phc2sys.8 - pub/scm/linux/kernel/git/bigeasy/linuxptp-hsr - Git at Google

 .TH PHC2SYS 8 "March 2024" "linuxptp"
 .SH NAME
 phc2sys \- synchronize two or more clocks

 .SH SYNOPSIS
 .B phc2sys \-a
 [
 .B \-r
 ] [
 .B \-r
 ] [
 .BI \-f " config-file"
 ] [ options ] [
 .I long-options
 ]
 .br
 .B phc2sys
 [
 .BI \-f " config-file"
 ] [
 .BI \-d " pps-device"
 ] [
 .BI \-s " device"
 ] [
 .BI \-c " device"
 ] [
 .BI \-O " offset"
 ] [
 .BI \-w
 ] [ options ] [
 .I long-options
 ]
 .I .\|.\|.


 .SH DESCRIPTION
 .B phc2sys
 is a program which synchronizes two or more clocks in the system. Typically,
 it is used to synchronize the system clock to a PTP hardware clock (PHC),
 which itself is synchronized by the
 .BR ptp4l (8)
 program.

 With the
 .B \-a
 option, the clocks to synchronize are fetched from the running
 .B ptp4l
 daemon and the direction of synchronization automatically follows changes of
 the PTP port states.

 Manual configuration is also possible. When using manual configuration, two
 synchronization modes are supported, one uses a pulse per second (PPS)
 signal provided by the source clock and the other mode reads time from the
 source clock directly. Some clocks can be used in both modes, the mode which
 will synchronize the time sink with better accuracy depends on hardware
 and driver implementation.

 .SH OPTIONS
 .TP
 .BI \-a
 Read the clocks to synchronize from running
 .B ptp4l
 and follow changes in the port states, adjusting the synchronization
 direction automatically. The system clock (CLOCK_REALTIME) is not
 synchronized, unless the
 .B \-r
 option is also specified.
 .TP
 .BI \-r
 Only valid together with the
 .B \-a
 option. Instructs
 .B phc2sys
 to also synchronize the system clock (CLOCK_REALTIME). By default, the
 system clock is not considered as a possible time source. If you want the
 system clock to be eligible to become a time source, specify the
 .B \-r
 option twice.
 .TP
 .BI \-f " config"
 Read configuration from the specified file. No configuration file is read by
 default.
 .TP
 .BI \-d " pps-device"
 Specify the PPS device of the source clock (e.g. /dev/pps0). With this option
 the PPS synchronization mode is used instead of the direct mode.  The
 matching PHC must be specified using the
 .B \-s
 command line option.
 This option can be used only with the system clock as the time sink. Not
 compatible with the
 .B \-a
 option.
 .TP
 .BI \-s " device"
 Specify the source clock by device (e.g. /dev/ptp0) or interface (e.g. eth0) or
 by name (e.g. CLOCK_REALTIME for the system clock). When this option is used
 together with the
 .B \-d
 option, the source clock is used only to correct the offset by whole number of
 seconds, which cannot be fixed with PPS alone. Not compatible with the
 .B \-a
 option. This option does not support bonded interface (e.g. bond0, team0). If
 .B ptp4l
 has a port on an active-backup bond or team interface, the
 .B \-a
 option can be used to track the active interface.
 .TP
 .BI \-i " interface"
 Performs the exact same function as
 .B \-s
 for compatibility reasons. Previously enabled specifying source clock by network
 interface. However, this can now be done using
 .B \-s
 and this option is no longer necessary. As such it has been deprecated, and
 should no longer be used.
 .TP
 .BI \-c " device"
 Specify the time sink by device (e.g. /dev/ptp1) or interface (e.g. eth1) or
 by name. If used together with the
 .B \-a
 option, it is an additional sink clock added to the clocks provided by the
 first ptp4l instance (if
 .B \-z
 is specified multiple times). Duplicated clocks are allowed. The default is
 CLOCK_REALTIME (the system clock). This option may be given up to 128 times.
 .TP
 .BI \-E " servo"
 Specify which clock servo should be used. Valid values are pi for a PI
 controller, linreg for an adaptive controller using linear regression, and
 ntpshm and refclock_sock for the NTP SHM and chrony SOCK reference clocks
 respectively to allow another process to synchronize the local clock.
 The default is pi.
 .TP
 .BI \-P " kp"
 Specify the proportional constant of the PI controller. The default is 0.7.
 .TP
 .BI \-I " ki"
 Specify the integral constant of the PI controller. The default is 0.3.
 .TP
 .BI \-S " step"
 Specify the step threshold of the servo. It is the maximum offset that
 the servo corrects by changing the clock frequency instead of stepping the
 clock. The clock is stepped on start regardless of the option if the offset is
 larger than 20 microseconds (unless the
 .BI \-F
 option is used). It's specified in seconds. The value of 0.0 disables stepping
 after the start. The default is 0.0.
 .TP
 .BI \-F " step"
 Specify the step threshold applied only on the first update. It is the maximum
 offset that is corrected by changing the clock frequency. It's specified in
 seconds. The value of 0.0 disables stepping on start. The default is 0.00002
 (20 microseconds).
 .TP
 .BI \-R " update-rate"
 Specify the time sink update rate when running in the direct synchronization
 mode. The default is 1 per second.
 .TP
 .BI \-N " phc-num"
 Specify the number of source clock readings used for each time sink update.
 Only the fastest reading is used to update the clock.  This is useful to
 minimize the error caused by random delays in scheduling and bus utilization.
 The default is 5.
 .TP
 .BI \-O " offset"
 Specify the offset between the sink and source times in seconds. If not
 specified, the offset will be set according to the currentUtcOffset value
 obtained from ptp4l and the direction of synchronization, assuming the system
 clock is keeping time in UTC and all used PHCs keep time in TAI. Not
 compatible with the
 .B \-a
 option.  See
 .SM
 .B TIME SCALE USAGE
 below.
 .TP
 .BI \-L " freq-limit"
 The maximum allowed frequency offset between uncorrected clock and the system
 monotonic clock in parts per billion (ppb). This is used as a sanity check of
 the synchronized clock. When a larger offset is measured, a warning message
 will be printed and the servo will be reset. When set to 0, the sanity check is
 disabled. The default is 200000000 (20%).
 .TP
 .BI \-M " segment"
 The number of the SHM segment used by ntpshm servo.
 The default is 0.
 .TP
 .BI \-u " summary-updates"
 Specify the number of clock updates included in summary statistics. The
 statistics include offset root mean square (RMS), maximum absolute offset,
 frequency offset mean and standard deviation, and mean of the delay in clock
 readings and standard deviation. The units are nanoseconds and parts per
 billion (ppb). If zero, the individual samples are printed instead of the
 statistics. The messages are printed at the LOG_INFO level.
 The default is 0 (disabled).
 .TP
 .B \-w
 Wait until ptp4l is in a synchronized state. If the
 .B \-O
 option is not used, also keep the offset between the sink and source
 times updated according to the currentUtcOffset value obtained from ptp4l and
 the direction of the clock synchronization. Not compatible with the
 .B \-a
 option.
 .TP
 .BI \-n " domain-number"
 Specify the domain number used by ptp4l. This option can be used up to 16 times
 to specify different domain numbers for different sockets specified by the
 .B \-z
 option. The domain numbers are assigned according to the order of the options
 on the command line.
 The default is 0.
 .TP
 .B \-x
 When a leap second is announced, don't apply it in the kernel by stepping the
 clock, but let the servo correct the one-second offset slowly by changing the
 clock frequency (unless the
 .B \-S
 option is used).
 .TP
 .BI \-z " uds-address"
 Specifies the address of the server's UNIX domain socket. This option can be
 used up to 16 times in the automatic mode to synchronize clocks between multiple
 .B ptp4l
 instances.
 The default is /var/run/ptp/ptp4l.
 .TP
 .BI \-l " print-level"
 Set the maximum syslog level of messages which should be printed or sent to
 the system logger. The default is 6 (LOG_INFO).
 .TP
 .BI \-t " message-tag"
 Specify the tag which is added to all messages printed to the standard output
 or system log. The default is an empty string.
 .TP
 .B \-m
 Print messages to the standard output.
 .TP
 .B \-q
 Don't send messages to the system logger.
 .TP
 .BI \-h
 Display a help message.
 .TP
 .B \-v
 Prints the software version and exits.

 .SH LONG OPTIONS

 Each and every configuration file option (see below in section
 .BR FILE\ OPTIONS)
 may also appear
 as a "long" style command line argument.  For example, the transportSpecific
 option may be set using either of these two forms:

 .RS
 \f(CW\-\-transportSpecific 1   \-\-transportSpecific=1\fP
 .RE

 Option values given on the command line override values in the global
 section of the configuration file (which, in turn overrides default
 values).

 .SH CONFIGURATION FILE

 The configuration file is divided into sections. Each section starts with a
 line containing its name enclosed in brackets and it follows with settings.
 Each setting is placed on a separate line, it contains the name of the
 option and the value separated by whitespace characters. Empty lines and lines
 starting with # are ignored.

 The global section (indicated as
 .BR [global] )
 sets the program options. This is the only used option.

 .SH FILE OPTIONS

 .TP
 .B active_key_id
 Used in conjunction with \fBspp\fR and \fBsa_file\fR directives to
 specify which key from the \fBspp\fR defined Security Association
 should be used for outbound icv calculations. All Security Assocations
 are read from the file specified by \fBsa_file\fR. Requires \fBspp\fR
 and \fBsa_file\fR directives. Must be in the range of 1 to 2^32-1,
 inclusive. The default is 0 (disabled).

 .TP
 .B clock_servo
 The servo which is used to synchronize the local clock. Valid values
 are "pi" for a PI controller, "linreg" for an adaptive controller using
 linear regression, "ntpshm" for the NTP SHM reference clock to allow
 another process to synchronize the local clock (the SHM segment number
 is set to the domain number), and "nullf" for a servo that always dials
 frequency offset zero (for use in SyncE nodes). The default is "pi."
 Same as option
 .B \-E
 (see above).

 .TP
 .B domainNumber
 Specify the domain number used by phc2sys. The default is 0. Same as option
 .B \-n
 (see above).

 .TP
 .B first_step_threshold
 Specify the step threshold applied only on the first update. It is the
 maximum offset that is corrected by adjusting clock. It's specified in
 seconds. The value of 0.0 disables stepping on start. The default is
 0.00002 (20 microseconds).
 Same as option
 .B \-F
 (see above).

 .TP
 .B free-running
 Don't adjust the sink clock if enabled. The default is 0 (disabled).

 .TP
 .B kernel_leap
 When a leap second is announced, let the kernel apply it by stepping the
 clock instead of correcting the one-second offset with servo, which would
 correct the one-second offset slowly by changing the clock frequency
 (unless the step_threshold option is set to correct such offset by
 stepping). Relevant only with software time stamping. The default is 1
 (enabled). Same as option
 .B \-x
 (see above).

 .TP
 .B logging_level
 The maximum logging level of messages which should be printed.
 The default is 6 (LOG_INFO). Same as option
 .B \-l
 (see above).

 .TP
 .B message_tag
 The tag which is added to all messages printed to the standard output
 or system log. If the tag contains the string "{level}", it will be replaced
 with the log level of the message as a number.
 The default is an empty string (which cannot be set in
 the configuration file as the option requires an argument).
 Same as option
 .B \-t
 (see above).

 .TP
 .B ntpshm_segment
 The number of the SHM segment used by ntpshm servo.  The default is 0.
 Same as option
 .B \-M
 (see above).

 .TP
 .B pi_integral_const
 Specifies the integral constant of the PI controller.
 Same as option
 .B \-I
 (see above).

 .TP
 .B pi_proportional_const
 Specifies the proportional constant of the PI controller.
 Same as option
 .B \-P
 (see above).

 .TP
 .B refclock_sock_address
 The address of the UNIX domain socket to be used by the refclock_sock servo.
 The default is /var/run/refclock.ptp.sock.

 .TP
 .B sa_file
 Specifies the location of the file containing Security Associations used
 for immediate security processing of the Authentication TLV in support of
 the optional security mechanism defined in ieee1588-2019 ch 14.16. See
 \fBSECURITY ASSOCIATION OPTIONS\fR for more info on file contents.
 The default is an empty string. (disabled).

 .TP
 .B sanity_freq_limit
 The maximum allowed frequency offset between uncorrected clock and the
 system monotonic clock in parts per billion (ppb). This is used as a
 sanity check of the synchronized clock. When a larger offset is measured,
 a warning message will be printed and the servo will be reset. When set
 to 0, the sanity check is disabled. The default is 200000000 (20%).
 Same as option
 .B \-L
 (see above).

 .TP
 .B step_threshold
 Specifies the step threshold of the servo. It is the maximum offset that the
 servo corrects by changing the clock frequency (phase when using nullf servo)
 instead of stepping the clock. The clock is stepped on start regardless of the
 option if the offset is larger than 20 microseconds (unless the -F option is
 used). It's specified in seconds. The value of 0.0 disables stepping after the
 start. The default is 0.0.
 Same as option
 .B \-S
 (see above).

 .TP
 .B spp
 Specifies the security parameters pointer for the desired security association
 to be used for authentication tlv support. If specified, the port owning the
 spp will attempt to attach (outbound) and check (inbound) authentication tlvs
 for all messages in accordance to the corresponding security association
 sourced via the \fBsa_file\fR directive. Not compatible with one step ports.
 Must be in the range of -1 to 255, inclusive. The default is -1 (disabled).

 .TP
 .B transportSpecific
 The transport specific field. Must be in the range 0 to 255.
 The default is 0.

 .TP
 .B uds_address
 Specifies the address of the server's UNIX domain socket. The default
 is /var/run/ptp/ptp4l
 Same as option
 .B \-z
 (see above).

 .TP
 .B use_syslog
 Print messages to the system log if enabled.  The default is 1 (enabled).
 Related to option
 .B \-q
 (see above).

 .TP
 .B verbose
 Print messages to the standard output if enabled.  The default is 0 (disabled).
 Related to option
 .B \-m
 (see above).

 .SH TIME SCALE USAGE

 .B Ptp4l
 uses either PTP time scale or UTC (Coordinated Universal Time) time
 scale.  PTP time scale is continuous and shifted against UTC by a few tens of
 seconds as PTP time scale does not apply leap seconds.

 In hardware time stamping mode,
 .B ptp4l
 announces use of PTP time scale and PHC
 is used for the stamps.  That means PHC must follow PTP time scale while system
 clock follows UTC.  Time offset between these two is maintained by
 .BR phc2sys .

 .B Phc2sys
 acquires the offset value either by reading it from ptp4l when
 .B \-a
 or
 .B \-w
 is in effect or from command line when
 .B \-O
 is supplied.  Failure to maintain the correct offset can result in the
 local system clock being offset some whole number of seconds from the
 domain server's clock when in client mode, or incorect PTP time
 announced to the network in case the host is the domain server.

 .SH EXAMPLES

 Synchronize time automatically according to the current
 .B ptp4l
 state, synchronizing the system clock to the remote server.

 .RS
 \f(CWphc2sys \-a \-r\fP
 .RE

 Same as above, but when the host becomes the domain server, synchronize time
 in the domain to its system clock.

 .RS
 \f(CWphc2sys \-a \-rr\fP
 .RE

 Same as above, in an IEEE 802.1AS domain.

 .RS
 \f(CWphc2sys \-a \-rr --transportSpecific=1\fP
 .RE

 The host is a domain server, PTP clock is synchronized to system clock and the
 time offset is obtained from
 .BR ptp4l .
 .B Phc2sys
 waits for
 .B ptp4l
 to get at least one port in server or client mode before starting the
 synchronization.

 .RS
 \f(CWphc2sys \-c /dev/ptp0 \-s CLOCK_REALTIME \-w\fP
 .RE

 Same as above, time offset is provided on command line and
 .B phc2sys
 does not wait for
 .BR ptp4l .

 .RS
 \f(CWphc2sys \-c /dev/ptp0 \-s CLOCK_REALTIME \-O 37\fP
 .RE

 The host is in client mode, system clock is synchronized from PTP clock,
 .B phc2sys
 waits for
 .B ptp4l
 and the offset is set automatically.

 .RS
 \f(CWphc2sys \-s /dev/ptp0 \-w\fP
 .RE

 Same as above, PTP clock id is read from the network interface, the offset is
 provided on command line
 .B phc2sys
 does not wait.

 .RS
 \f(CWphc2sys \-s eth0 \-O \-37\fP
 .RE

 .SH WARNING

 Be cautious when the same configuration file is used for both ptp4l and phc2sys.
 Keep in mind, that values specified in the configuration file take precedence
 over their default values. If a certain option, which is common to ptp4l and
 phc2sys, is specified to a non-default value in the configuration file
 (p.e., for ptp4l), then this non-default value applies also for phc2sys. This
 might be not what is expected.

 It is recommended to use seperate configuration files for ptp4l and
 phc2sys in order to avoid any unexpected behavior.

 .SH SEE ALSO
 .BR ptp4l (8)
	.TH PHC2SYS 8 "March 2024" "linuxptp"
	.SH NAME
	phc2sys \- synchronize two or more clocks

	.SH SYNOPSIS
	.B phc2sys \-a
	[
	.B \-r
	] [
	.B \-r
	] [
	.BI \-f " config-file"
	] [ options ] [
	.I long-options
	]
	.br
	.B phc2sys
	[
	.BI \-f " config-file"
	] [
	.BI \-d " pps-device"
	] [
	.BI \-s " device"
	] [
	.BI \-c " device"
	] [
	.BI \-O " offset"
	] [
	.BI \-w
	] [ options ] [
	.I long-options
	]
	.I .\\|.\\|.


	.SH DESCRIPTION
	.B phc2sys
	is a program which synchronizes two or more clocks in the system. Typically,
	it is used to synchronize the system clock to a PTP hardware clock (PHC),
	which itself is synchronized by the
	.BR ptp4l (8)
	program.

	With the
	.B \-a
	option, the clocks to synchronize are fetched from the running
	.B ptp4l
	daemon and the direction of synchronization automatically follows changes of
	the PTP port states.

	Manual configuration is also possible. When using manual configuration, two
	synchronization modes are supported, one uses a pulse per second (PPS)
	signal provided by the source clock and the other mode reads time from the
	source clock directly. Some clocks can be used in both modes, the mode which
	will synchronize the time sink with better accuracy depends on hardware
	and driver implementation.

	.SH OPTIONS
	.TP
	.BI \-a
	Read the clocks to synchronize from running
	.B ptp4l
	and follow changes in the port states, adjusting the synchronization
	direction automatically. The system clock (CLOCK_REALTIME) is not
	synchronized, unless the
	.B \-r
	option is also specified.
	.TP
	.BI \-r
	Only valid together with the
	.B \-a
	option. Instructs
	.B phc2sys
	to also synchronize the system clock (CLOCK_REALTIME). By default, the
	system clock is not considered as a possible time source. If you want the
	system clock to be eligible to become a time source, specify the
	.B \-r
	option twice.
	.TP
	.BI \-f " config"
	Read configuration from the specified file. No configuration file is read by
	default.
	.TP
	.BI \-d " pps-device"
	Specify the PPS device of the source clock (e.g. /dev/pps0). With this option
	the PPS synchronization mode is used instead of the direct mode. The
	matching PHC must be specified using the
	.B \-s
	command line option.
	This option can be used only with the system clock as the time sink. Not
	compatible with the
	.B \-a
	option.
	.TP
	.BI \-s " device"
	Specify the source clock by device (e.g. /dev/ptp0) or interface (e.g. eth0) or
	by name (e.g. CLOCK_REALTIME for the system clock). When this option is used
	together with the
	.B \-d
	option, the source clock is used only to correct the offset by whole number of
	seconds, which cannot be fixed with PPS alone. Not compatible with the
	.B \-a
	option. This option does not support bonded interface (e.g. bond0, team0). If
	.B ptp4l
	has a port on an active-backup bond or team interface, the
	.B \-a
	option can be used to track the active interface.
	.TP
	.BI \-i " interface"
	Performs the exact same function as
	.B \-s
	for compatibility reasons. Previously enabled specifying source clock by network
	interface. However, this can now be done using
	.B \-s
	and this option is no longer necessary. As such it has been deprecated, and
	should no longer be used.
	.TP
	.BI \-c " device"
	Specify the time sink by device (e.g. /dev/ptp1) or interface (e.g. eth1) or
	by name. If used together with the
	.B \-a
	option, it is an additional sink clock added to the clocks provided by the
	first ptp4l instance (if
	.B \-z
	is specified multiple times). Duplicated clocks are allowed. The default is
	CLOCK_REALTIME (the system clock). This option may be given up to 128 times.
	.TP
	.BI \-E " servo"
	Specify which clock servo should be used. Valid values are pi for a PI
	controller, linreg for an adaptive controller using linear regression, and
	ntpshm and refclock_sock for the NTP SHM and chrony SOCK reference clocks
	respectively to allow another process to synchronize the local clock.
	The default is pi.
	.TP
	.BI \-P " kp"
	Specify the proportional constant of the PI controller. The default is 0.7.
	.TP
	.BI \-I " ki"
	Specify the integral constant of the PI controller. The default is 0.3.
	.TP
	.BI \-S " step"
	Specify the step threshold of the servo. It is the maximum offset that
	the servo corrects by changing the clock frequency instead of stepping the
	clock. The clock is stepped on start regardless of the option if the offset is
	larger than 20 microseconds (unless the
	.BI \-F
	option is used). It's specified in seconds. The value of 0.0 disables stepping
	after the start. The default is 0.0.
	.TP
	.BI \-F " step"
	Specify the step threshold applied only on the first update. It is the maximum
	offset that is corrected by changing the clock frequency. It's specified in
	seconds. The value of 0.0 disables stepping on start. The default is 0.00002
	(20 microseconds).
	.TP
	.BI \-R " update-rate"
	Specify the time sink update rate when running in the direct synchronization
	mode. The default is 1 per second.
	.TP
	.BI \-N " phc-num"
	Specify the number of source clock readings used for each time sink update.
	Only the fastest reading is used to update the clock. This is useful to
	minimize the error caused by random delays in scheduling and bus utilization.
	The default is 5.
	.TP
	.BI \-O " offset"
	Specify the offset between the sink and source times in seconds. If not
	specified, the offset will be set according to the currentUtcOffset value
	obtained from ptp4l and the direction of synchronization, assuming the system
	clock is keeping time in UTC and all used PHCs keep time in TAI. Not
	compatible with the
	.B \-a
	option. See
	.SM
	.B TIME SCALE USAGE
	below.
	.TP
	.BI \-L " freq-limit"
	The maximum allowed frequency offset between uncorrected clock and the system
	monotonic clock in parts per billion (ppb). This is used as a sanity check of
	the synchronized clock. When a larger offset is measured, a warning message
	will be printed and the servo will be reset. When set to 0, the sanity check is
	disabled. The default is 200000000 (20%).
	.TP
	.BI \-M " segment"
	The number of the SHM segment used by ntpshm servo.
	The default is 0.
	.TP
	.BI \-u " summary-updates"
	Specify the number of clock updates included in summary statistics. The
	statistics include offset root mean square (RMS), maximum absolute offset,
	frequency offset mean and standard deviation, and mean of the delay in clock
	readings and standard deviation. The units are nanoseconds and parts per
	billion (ppb). If zero, the individual samples are printed instead of the
	statistics. The messages are printed at the LOG_INFO level.
	The default is 0 (disabled).
	.TP
	.B \-w
	Wait until ptp4l is in a synchronized state. If the
	.B \-O
	option is not used, also keep the offset between the sink and source
	times updated according to the currentUtcOffset value obtained from ptp4l and
	the direction of the clock synchronization. Not compatible with the
	.B \-a
	option.
	.TP
	.BI \-n " domain-number"
	Specify the domain number used by ptp4l. This option can be used up to 16 times
	to specify different domain numbers for different sockets specified by the
	.B \-z
	option. The domain numbers are assigned according to the order of the options
	on the command line.
	The default is 0.
	.TP
	.B \-x
	When a leap second is announced, don't apply it in the kernel by stepping the
	clock, but let the servo correct the one-second offset slowly by changing the
	clock frequency (unless the
	.B \-S
	option is used).
	.TP
	.BI \-z " uds-address"
	Specifies the address of the server's UNIX domain socket. This option can be
	used up to 16 times in the automatic mode to synchronize clocks between multiple
	.B ptp4l
	instances.
	The default is /var/run/ptp/ptp4l.
	.TP
	.BI \-l " print-level"
	Set the maximum syslog level of messages which should be printed or sent to
	the system logger. The default is 6 (LOG_INFO).
	.TP
	.BI \-t " message-tag"
	Specify the tag which is added to all messages printed to the standard output
	or system log. The default is an empty string.
	.TP
	.B \-m
	Print messages to the standard output.
	.TP
	.B \-q
	Don't send messages to the system logger.
	.TP
	.BI \-h
	Display a help message.
	.TP
	.B \-v
	Prints the software version and exits.

	.SH LONG OPTIONS

	Each and every configuration file option (see below in section
	.BR FILE\ OPTIONS)
	may also appear
	as a "long" style command line argument. For example, the transportSpecific
	option may be set using either of these two forms:

	.RS
	\f(CW\-\-transportSpecific 1 \-\-transportSpecific=1\fP
	.RE

	Option values given on the command line override values in the global
	section of the configuration file (which, in turn overrides default
	values).

	.SH CONFIGURATION FILE

	The configuration file is divided into sections. Each section starts with a
	line containing its name enclosed in brackets and it follows with settings.
	Each setting is placed on a separate line, it contains the name of the
	option and the value separated by whitespace characters. Empty lines and lines
	starting with # are ignored.

	The global section (indicated as
	.BR [global] )
	sets the program options. This is the only used option.

	.SH FILE OPTIONS

	.TP
	.B active_key_id
	Used in conjunction with \fBspp\fR and \fBsa_file\fR directives to
	specify which key from the \fBspp\fR defined Security Association
	should be used for outbound icv calculations. All Security Assocations
	are read from the file specified by \fBsa_file\fR. Requires \fBspp\fR
	and \fBsa_file\fR directives. Must be in the range of 1 to 2^32-1,
	inclusive. The default is 0 (disabled).

	.TP
	.B clock_servo
	The servo which is used to synchronize the local clock. Valid values
	are "pi" for a PI controller, "linreg" for an adaptive controller using
	linear regression, "ntpshm" for the NTP SHM reference clock to allow
	another process to synchronize the local clock (the SHM segment number
	is set to the domain number), and "nullf" for a servo that always dials
	frequency offset zero (for use in SyncE nodes). The default is "pi."
	Same as option
	.B \-E
	(see above).

	.TP
	.B domainNumber
	Specify the domain number used by phc2sys. The default is 0. Same as option
	.B \-n
	(see above).

	.TP
	.B first_step_threshold
	Specify the step threshold applied only on the first update. It is the
	maximum offset that is corrected by adjusting clock. It's specified in
	seconds. The value of 0.0 disables stepping on start. The default is
	0.00002 (20 microseconds).
	Same as option
	.B \-F
	(see above).

	.TP
	.B free-running
	Don't adjust the sink clock if enabled. The default is 0 (disabled).

	.TP
	.B kernel_leap
	When a leap second is announced, let the kernel apply it by stepping the
	clock instead of correcting the one-second offset with servo, which would
	correct the one-second offset slowly by changing the clock frequency
	(unless the step_threshold option is set to correct such offset by
	stepping). Relevant only with software time stamping. The default is 1
	(enabled). Same as option
	.B \-x
	(see above).

	.TP
	.B logging_level
	The maximum logging level of messages which should be printed.
	The default is 6 (LOG_INFO). Same as option
	.B \-l
	(see above).

	.TP
	.B message_tag
	The tag which is added to all messages printed to the standard output
	or system log. If the tag contains the string "{level}", it will be replaced
	with the log level of the message as a number.
	The default is an empty string (which cannot be set in
	the configuration file as the option requires an argument).
	Same as option
	.B \-t
	(see above).

	.TP
	.B ntpshm_segment
	The number of the SHM segment used by ntpshm servo. The default is 0.
	Same as option
	.B \-M
	(see above).

	.TP
	.B pi_integral_const
	Specifies the integral constant of the PI controller.
	Same as option
	.B \-I
	(see above).

	.TP
	.B pi_proportional_const
	Specifies the proportional constant of the PI controller.
	Same as option
	.B \-P
	(see above).

	.TP
	.B refclock_sock_address
	The address of the UNIX domain socket to be used by the refclock_sock servo.
	The default is /var/run/refclock.ptp.sock.

	.TP
	.B sa_file
	Specifies the location of the file containing Security Associations used
	for immediate security processing of the Authentication TLV in support of
	the optional security mechanism defined in ieee1588-2019 ch 14.16. See
	\fBSECURITY ASSOCIATION OPTIONS\fR for more info on file contents.
	The default is an empty string. (disabled).

	.TP
	.B sanity_freq_limit
	The maximum allowed frequency offset between uncorrected clock and the
	system monotonic clock in parts per billion (ppb). This is used as a
	sanity check of the synchronized clock. When a larger offset is measured,
	a warning message will be printed and the servo will be reset. When set
	to 0, the sanity check is disabled. The default is 200000000 (20%).
	Same as option
	.B \-L
	(see above).

	.TP
	.B step_threshold
	Specifies the step threshold of the servo. It is the maximum offset that the
	servo corrects by changing the clock frequency (phase when using nullf servo)
	instead of stepping the clock. The clock is stepped on start regardless of the
	option if the offset is larger than 20 microseconds (unless the -F option is
	used). It's specified in seconds. The value of 0.0 disables stepping after the
	start. The default is 0.0.
	Same as option
	.B \-S
	(see above).

	.TP
	.B spp
	Specifies the security parameters pointer for the desired security association
	to be used for authentication tlv support. If specified, the port owning the
	spp will attempt to attach (outbound) and check (inbound) authentication tlvs
	for all messages in accordance to the corresponding security association
	sourced via the \fBsa_file\fR directive. Not compatible with one step ports.
	Must be in the range of -1 to 255, inclusive. The default is -1 (disabled).

	.TP
	.B transportSpecific
	The transport specific field. Must be in the range 0 to 255.
	The default is 0.

	.TP
	.B uds_address
	Specifies the address of the server's UNIX domain socket. The default
	is /var/run/ptp/ptp4l
	Same as option
	.B \-z
	(see above).

	.TP
	.B use_syslog
	Print messages to the system log if enabled. The default is 1 (enabled).
	Related to option
	.B \-q
	(see above).

	.TP
	.B verbose
	Print messages to the standard output if enabled. The default is 0 (disabled).
	Related to option
	.B \-m
	(see above).

	.SH TIME SCALE USAGE

	.B Ptp4l
	uses either PTP time scale or UTC (Coordinated Universal Time) time
	scale. PTP time scale is continuous and shifted against UTC by a few tens of
	seconds as PTP time scale does not apply leap seconds.

	In hardware time stamping mode,
	.B ptp4l
	announces use of PTP time scale and PHC
	is used for the stamps. That means PHC must follow PTP time scale while system
	clock follows UTC. Time offset between these two is maintained by
	.BR phc2sys .

	.B Phc2sys
	acquires the offset value either by reading it from ptp4l when
	.B \-a
	or
	.B \-w
	is in effect or from command line when
	.B \-O
	is supplied. Failure to maintain the correct offset can result in the
	local system clock being offset some whole number of seconds from the
	domain server's clock when in client mode, or incorect PTP time
	announced to the network in case the host is the domain server.

	.SH EXAMPLES

	Synchronize time automatically according to the current
	.B ptp4l
	state, synchronizing the system clock to the remote server.

	.RS
	\f(CWphc2sys \-a \-r\fP
	.RE

	Same as above, but when the host becomes the domain server, synchronize time
	in the domain to its system clock.

	.RS
	\f(CWphc2sys \-a \-rr\fP
	.RE

	Same as above, in an IEEE 802.1AS domain.

	.RS
	\f(CWphc2sys \-a \-rr --transportSpecific=1\fP
	.RE

	The host is a domain server, PTP clock is synchronized to system clock and the
	time offset is obtained from
	.BR ptp4l .
	.B Phc2sys
	waits for
	.B ptp4l
	to get at least one port in server or client mode before starting the
	synchronization.

	.RS
	\f(CWphc2sys \-c /dev/ptp0 \-s CLOCK_REALTIME \-w\fP
	.RE

	Same as above, time offset is provided on command line and
	.B phc2sys
	does not wait for
	.BR ptp4l .

	.RS
	\f(CWphc2sys \-c /dev/ptp0 \-s CLOCK_REALTIME \-O 37\fP
	.RE

	The host is in client mode, system clock is synchronized from PTP clock,
	.B phc2sys
	waits for
	.B ptp4l
	and the offset is set automatically.

	.RS
	\f(CWphc2sys \-s /dev/ptp0 \-w\fP
	.RE

	Same as above, PTP clock id is read from the network interface, the offset is
	provided on command line
	.B phc2sys
	does not wait.

	.RS
	\f(CWphc2sys \-s eth0 \-O \-37\fP
	.RE

	.SH WARNING

	Be cautious when the same configuration file is used for both ptp4l and phc2sys.
	Keep in mind, that values specified in the configuration file take precedence
	over their default values. If a certain option, which is common to ptp4l and
	phc2sys, is specified to a non-default value in the configuration file
	(p.e., for ptp4l), then this non-default value applies also for phc2sys. This
	might be not what is expected.

	It is recommended to use seperate configuration files for ptp4l and
	phc2sys in order to avoid any unexpected behavior.

	.SH SEE ALSO
	.BR ptp4l (8)