| .TH TIMEMASTER 8 "January 2021" "linuxptp" |
| .SH NAME |
| |
| timemaster - run NTP with PTP as reference clocks |
| |
| .SH SYNOPSIS |
| |
| .B timemaster |
| [ |
| .B \-nmqv |
| ] [ |
| .BI \-l " print-level" |
| ] |
| .BI \-f " file" |
| |
| .SH DESCRIPTION |
| \fBtimemaster\fR is a program that uses \fBptp4l\fR and \fBphc2sys\fR in |
| combination with \fBchronyd\fR or \fBntpd\fR to synchronize the system clock to |
| NTP and PTP time sources. The PTP time is provided by \fBphc2sys\fR and |
| \fBptp4l\fR via SOCK reference clock to \fBchronyd\fR or SHM reference clock to |
| \fBntpd\fR, which can compare all time sources and use the best sources to |
| synchronize the system clock. |
| |
| On start, \fBtimemaster\fR reads a configuration file that specifies the NTP |
| and PTP time sources, checks which network interfaces have and share a PTP |
| hardware clock (PHC), generates configuration files for \fBptp4l\fR and |
| \fBchronyd\fR/\fBntpd\fR, and start the \fBptp4l\fR, \fBphc2sys\fR, |
| \fBchronyd\fR/\fBntpd\fR processes as needed. Then, it waits for a signal to |
| kill the processes, remove the generated configuration files and exit. |
| |
| .SH OPTIONS |
| |
| .TP |
| .BI \-f " file" |
| Specify the path to the \fBtimemaster\fR configuration file. |
| .TP |
| .BI \-n |
| Don't start the programs, only print their configuration files and the commands |
| that would be executed if this option wasn't specified. |
| .TP |
| .BI \-l " level" |
| Set the maximum syslog level of messages which should be printed or sent to |
| the system logger. The default value is 6 (LOG_INFO). |
| .TP |
| .B \-m |
| Print messages to the standard output. |
| .TP |
| .B \-q |
| Don't send messages to the system logger. |
| .TP |
| .B \-v |
| Print the software version and exit. |
| .TP |
| .BI \-h |
| Display a help message and exit. |
| |
| .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. |
| |
| Sections that can used in the configuration file and options that can be set in |
| them are described below. |
| |
| .SS [timemaster] |
| |
| .TP |
| .B ntp_program |
| Select which NTP implementation should be used. Possible values are |
| \fBchronyd\fR and \fBntpd\fR. The default value is \fBchronyd\fR. Limitations |
| of the implementations relevant to the timemaster configuration are listed in |
| \fBNOTES\fR. |
| |
| .TP |
| .B rundir |
| Specify the directory where should be generated \fBchronyd\fR, \fBntpd\fR and |
| \fBptp4l\fR configuration files and sockets. The directory will be created if |
| it doesn't exist. The default value is \fB/var/run/timemaster\fR. |
| |
| .TP |
| .B first_shm_segment |
| Specify the first number in a sequence of SHM segments that will be used by |
| \fBptp4l\fR and \fBphc2sys\fR. The default value is 0. Increasing the number |
| can be useful to avoid conflicts with time sources that are not started by |
| \fBtimemaster\fR, e.g. \fBgpsd\fR using segments number 0 and 1. |
| |
| .TP |
| .B restart_processes |
| Enable or disable restarting of processes started by \fBtimemaster\fR. If the |
| option is set to a non-zero value, all processes except \fBchronyd\fR and |
| \fBntpd\fR will be automatically restarted when terminated and \fBtimemaster\fR |
| is running for at least one second (i.e. the process did not terminate due to a |
| configuration error). If a process was terminated and is not started again, |
| \fBtimemaster\fR will kill the other processes and exit with a non-zero status. |
| The default value is 1 (enabled). |
| |
| .TP |
| .B use_vclocks |
| Enable or disable synchronization with virtual clocks. If enabled, |
| \fBtimemaster\fR will create virtual clocks running on top of physical clocks |
| needed by configured PTP domains. This enables hardware time stamping for |
| multiple \fBptp4l\fR instances using the same network interface. The default |
| value is -1, which enables the virtual clocks if running on Linux 5.18 or |
| later. |
| |
| .SS [ntp_server address] |
| |
| The \fBntp_server\fR section specifies an NTP server that should be used as a |
| time source. The address of the server is included in the name of the section. |
| |
| .TP |
| .B minpoll |
| .TQ |
| .B maxpoll |
| Specify the minimum and maximum NTP polling interval as powers of two in |
| seconds. The default values are 6 (64 seconds) and 10 (1024 seconds) |
| respectively. Shorter polling intervals usually improve the accuracy |
| significantly, but they should be used only when allowed by the operators of |
| the NTP service (public NTP servers generally don't allow too frequent |
| queries). If the NTP server is located on the same LAN, polling intervals |
| around 4 (16 seconds) might give best accuracy. |
| |
| .TP |
| .B iburst |
| Enable or disable sending a burst of NTP packets on start to speed up the |
| initial synchronization. Possible values are 1 and 0. The default value is 0 |
| (disabled). |
| |
| .TP |
| .B ntp_options |
| Specify extra options that should be added for this source to the \fBserver\fR |
| directive in the configuration file of the selected NTP implementation. No |
| extra options are added by default. |
| |
| .SS [ptp_domain number] |
| |
| The \fBptp_domain\fR section specifies a PTP domain that should be used as a |
| time source. The PTP domain number is included in the name of the section. The |
| \fBptp4l\fR instances are configured to run in the \fBclientOnly\fR mode. In |
| this section at least the \fBinterfaces\fR option needs to be set, other |
| options are optional. |
| |
| .TP |
| .B interfaces |
| Specify which network interfaces should be used for this PTP domain. A separate |
| \fBptp4l\fR instance will be started for each group of interfaces sharing the |
| same PHC and for each interface that supports only SW time stamping. HW time |
| stamping is enabled automatically. If an interface with HW time stamping is |
| specified also in other PTP domains and virtual clocks are disabled, only the |
| \fBptp4l\fR instance from the first PTP domain will be using HW time stamping. |
| |
| .TP |
| .B ntp_poll |
| Specify the polling interval of the SOCK/SHM reference clock reading samples |
| from \fBptp4l\fR or \fBphc2sys\fR. It's specified as a power of two in seconds. |
| The default value is 2 (4 seconds). |
| |
| .TP |
| .B phc2sys_poll |
| Specify the polling interval used by \fBphc2sys\fR to read a PTP clock |
| synchronized by \fBptp4l\fR and update the SOCK/SHM sample for |
| \fBchronyd\fR/\fBntpd\fR. It's specified as a power of two in seconds. The |
| default value is 0 (1 second). |
| |
| .TP |
| .B delay |
| Specify the maximum assumed roundtrip delay to the primary source of the time |
| in this PTP domain. This value is included in the distance used by |
| \fBchronyd\fR in the source selection algorithm to detect falsetickers and |
| assign weights for source combining. The default value is 1e\-4 (100 |
| microseconds). With \fBntpd\fR, the \fBtos mindist\fR command can be used to |
| set a limit with similar purpose globally for all time sources. |
| |
| .TP |
| .B ntp_options |
| Specify extra options that should be added for this source to the |
| \fBrefclock\fR or \fBserver\fR directives in the configuration file of the |
| selected NTP implementation. No extra options are added by default. |
| |
| .TP |
| .B ptp4l_option |
| Specify an extra \fBptp4l\fR option specific to this PTP domain that should be |
| added to the configuration files generated for \fBptp4l\fR. This option may be |
| used multiple times in one \fBptp_domain\fR section. |
| |
| .SS [chronyd] |
| |
| .TP |
| .B path |
| Specify the path to the \fBchronyd\fR binary. The default value is |
| \fBchronyd\fR to search for the binary in \fBPATH\fR. |
| |
| .TP |
| .B options |
| Specify extra options that should be added to the \fBchronyd\fR command line. |
| No extra options are added by default. |
| |
| .SS [chrony.conf] |
| |
| Settings specified in this section are copied directly to the configuration |
| file generated for \fBchronyd\fR. If this section is not present in the |
| \fBtimemaster\fR configuration file, the following setting will be added: |
| |
| .EX |
| makestep 1 3 |
| .EE |
| |
| This configures \fBchronyd\fR to step the system clock in the first three |
| updates if the offset is larger than 1 second. |
| |
| .SS [ntpd] |
| |
| .TP |
| .B path |
| Specify the path to the \fBntpd\fR binary. The default value is \fBntpd\fR to |
| search for the binary in \fBPATH\fR. |
| |
| .TP |
| .B options |
| Specify extra options that should be added to the \fBntpd\fR command line. No |
| extra options are added by default. |
| |
| .SS [ntp.conf] |
| |
| Settings specified in this section are copied directly to the configuration |
| file generated for \fBntpd\fR. If this section is not present in the |
| \fBtimemaster\fR configuration file, the following settings will be added: |
| |
| .EX |
| restrict default nomodify notrap nopeer noquery |
| restrict 127.0.0.1 |
| restrict ::1 |
| .EE |
| |
| This configures \fBntpd\fR to use safe default restrictions. |
| |
| .SS [phc2sys] |
| |
| .TP |
| .B path |
| Specify the path to the \fBphc2sys\fR binary. The default value is |
| \fBphc2sys\fR to search for the binary in \fBPATH\fR. |
| |
| .TP |
| .B options |
| Specify extra options that should be added to all \fBphc2sys\fR command lines. |
| By default, \fB\-l 5\fR is added to the command lines. |
| |
| .SS [ptp4l] |
| |
| .TP |
| .B path |
| Specify the path to the \fBptp4l\fR binary. The default value is \fBptp4l\fR to |
| search for the binary in \fBPATH\fR. |
| |
| .TP |
| .B options |
| Specify extra options that should be added to all \fBptp4l\fR command lines. By |
| default, \fB\-l 5\fR is added to the command lines. |
| |
| .SS [ptp4l.conf] |
| Settings specified in this section are copied directly to the global section of |
| the configuration files generated for all \fBptp4l\fR instances. There is no |
| default content of this section. |
| |
| Other sections (e.g. \fB[unicast_master_table]\fR) may be specified here, but |
| lines beginning with the bracket need to be prefixed with the \fB>\fR character |
| to prevent \fBtimemaster\fR from parsing it as a beginning of another section. |
| |
| .SH NOTES |
| For best accuracy, \fBchronyd\fR is usually preferred over \fBntpd\fR, it also |
| synchronizes the system clock faster. Both NTP implementations, however, have |
| some limitations that need to be considered before choosing the one to be used |
| in a given \fBtimemaster\fR configuration. |
| |
| The \fBchronyd\fR limitations are: |
| |
| .RS |
| In version 1.31 and older, the maximum number of reference clocks used at the |
| same time is 8. This limits the number of PHCs and interfaces using SW time |
| stamping that can be used for PTP. |
| |
| Using polling intervals (\fBminpoll\fR, \fBmaxpoll\fR, \fBntp_poll\fR options) |
| shorter than 2 (4 seconds) is not recommended with versions before 1.30. With |
| 1.30 and later values of 0 or 1 can be used for NTP sources and negative values |
| for PTP sources (\fBntp_poll\fR) to specify a subsecond interval. |
| .RE |
| |
| The \fBntpd\fR limitations are: |
| |
| .RS |
| In versions before 4.2.8p1, only the first two shared-memory segments created by |
| the \fBntpd\fR SHM refclock driver have owner-only access. Other segments |
| are created with world access, which allows any user on the system to write to |
| the segments and disrupt or take control over the synchronization of the clock. |
| In 4.2.8p1 the access was made configurable with the mode option, which is set |
| by \fBtimemaster\fR for owner-ownly access. |
| |
| The shortest polling interval for all sources is 3 (8 seconds). |
| |
| Nanosecond resolution in the SHM refclock driver is supported in version |
| 4.2.7p303 and later, older versions have only microsecond resolution. |
| .RE |
| |
| .SH EXAMPLES |
| |
| A minimal configuration file using one NTP source and two PTP sources would be: |
| |
| .EX |
| [ntp_server 10.1.1.1] |
| |
| [ptp_domain 0] |
| interfaces eth0 |
| |
| [ptp_domain 1] |
| interfaces eth1 |
| .EE |
| |
| A more complex example using all \fBtimemaster\fR options would be: |
| |
| .EX |
| [ntp_server 10.1.1.1] |
| minpoll 3 |
| maxpoll 4 |
| iburst 1 |
| ntp_options key 12 |
| |
| [ptp_domain 0] |
| interfaces eth0 eth1 |
| ntp_poll 0 |
| phc2sys_poll \-2 |
| delay 10e\-6 |
| ntp_options prefer |
| ptp4l_option clock_servo linreg |
| ptp4l_option delay_mechanism P2P |
| |
| [timemaster] |
| ntp_program chronyd |
| rundir /var/run/timemaster |
| first_shm_segment 1 |
| restart_processes 0 |
| use_vclocks 0 |
| |
| [chronyd] |
| path /usr/sbin/chronyd |
| options |
| |
| [chrony.conf] |
| makestep 1 3 |
| logchange 0.5 |
| rtcsync |
| driftfile /var/lib/chrony/drift |
| |
| [ntpd] |
| path /usr/sbin/ntpd |
| options \-u ntp:ntp |
| |
| [ntp.conf] |
| restrict default nomodify notrap nopeer noquery |
| restrict 127.0.0.1 |
| restrict ::1 |
| driftfile /var/lib/ntp/drift |
| |
| [phc2sys] |
| path /usr/sbin/phc2sys |
| options \-l 5 |
| |
| [ptp4l] |
| path /usr/sbin/ptp4l |
| options |
| |
| [ptp4l.conf] |
| logging_level 5 |
| .EE |
| |
| .SH SEE ALSO |
| |
| .BR chronyd (8), |
| .BR ntpd (8), |
| .BR phc2sys (8), |
| .BR ptp4l (8) |