Provided by: linuxptp_1.8-1ubuntu0.1_amd64 
NAME
timemaster - run NTP with PTP as reference clocks
SYNOPSIS
timemaster [ -nmqv ] [ -l print-level ] -f file
DESCRIPTION
timemaster is a program that uses ptp4l and phc2sys in combination with chronyd or ntpd to synchronize
the system clock to NTP and PTP time sources. The PTP time is provided by phc2sys and ptp4l via SHM
reference clocks to chronyd/ntpd, which can compare all time sources and use the best sources to
synchronize the system clock.
On start, timemaster 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 ptp4l and
chronyd/ntpd, and start the ptp4l, phc2sys, chronyd/ntpd processes as needed. Then, it waits for a signal
to kill the processes, remove the generated configuration files and exit.
OPTIONS
-f file
Specify the path to the timemaster configuration file.
-n Don't start the programs, only print their configuration files and the commands that would be
executed if this option wasn't specified.
-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).
-m Print messages to the standard output.
-q Don't send messages to the system logger.
-v Print the software version and exit.
-h Display a help message and exit.
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.
[timemaster]
ntp_program
Select which NTP implementation should be used. Possible values are chronyd and ntpd. The default
value is chronyd. Limitations of the implementations relevant to the timemaster configuration are
listed in NOTES.
rundir Specify the directory where should be generated chronyd, ntpd and ptp4l configuration files and
sockets. The directory will be created if it doesn't exist. The default value is
/var/run/timemaster.
first_shm_segment
Specify the first number in a sequence of SHM segments that will be used by ptp4l and phc2sys. The
default value is 0. Increasing the number can be useful to avoid conflicts with time sources that
are not started by timemaster, e.g. gpsd using segments number 0 and 1.
[ntp_server address]
The ntp_server 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.
minpoll
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.
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).
ntp_options
Specify extra options that should be added for this source to the server directive in the
configuration file of the selected NTP implementation. No extra options are added by default.
[ptp_domain number]
The ptp_domain 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 ptp4l instances are configured to run in the slaveOnly mode.
In this section at least the interfaces option needs to be set, other options are optional.
interfaces
Specify which network interfaces should be used for this PTP domain. A separate ptp4l 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, only the ptp4l instance from the first PTP
domain will be using HW time stamping.
ntp_poll
Specify the polling interval of the NTP SHM reference clock reading samples from ptp4l or phc2sys.
It's specified as a power of two in seconds. The default value is 2 (4 seconds).
phc2sys_poll
Specify the polling interval used by phc2sys to read a PTP clock synchronized by ptp4l and update
the SHM sample for chronyd/ntpd. It's specified as a power of two in seconds. The default value is
0 (1 second).
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 chronyd in the source selection algorithm to detect
falsetickers and assign weights for source combining. The default value is 1e-4 (100
microseconds). With ntpd, the tos mindist command can be used to set a limit with similar purpose
globally for all time sources.
ntp_options
Specify extra options that should be added for this source to the refclock or server directives in
the configuration file of the selected NTP implementation. No extra options are added by default.
ptp4l_option
Specify an extra ptp4l option specific to this PTP domain that should be added to the
configuration files generated for ptp4l. This option may be used multiple times in one ptp_domain
section.
[chronyd]
path Specify the path to the chronyd binary. The default value is chronyd to search for the binary in
PATH.
options
Specify extra options that should be added to the chronyd command line. No extra options are
added by default.
[chrony.conf]
Settings specified in this section are copied directly to the configuration file generated for chronyd.
If this section is not present in the timemaster configuration file, the following setting will be added:
makestep 1 3
This configures chronyd to step the system clock in the first three updates if the offset is larger than
1 second.
[ntpd]
path Specify the path to the ntpd binary. The default value is ntpd to search for the binary in PATH.
options
Specify extra options that should be added to the ntpd command line. No extra options are added by
default.
[ntp.conf]
Settings specified in this section are copied directly to the configuration file generated for ntpd. If
this section is not present in the timemaster configuration file, the following settings will be added:
restrict default nomodify notrap nopeer noquery
restrict 127.0.0.1
restrict ::1
This configures ntpd to use safe default restrictions.
[phc2sys]
path Specify the path to the phc2sys binary. The default value is phc2sys to search for the binary in
PATH.
options
Specify extra options that should be added to all phc2sys command lines. By default, -l 5 is
added to the command lines.
[ptp4l]
path Specify the path to the ptp4l binary. The default value is ptp4l to search for the binary in PATH.
options
Specify extra options that should be added to all ptp4l command lines. By default, -l 5 is added
to the command lines.
[ptp4l.conf]
Settings specified in this section are copied directly to the configuration files generated for all ptp4l
instances. There is no default content of this section.
NOTES
For best accuracy, chronyd is usually preferred over ntpd, 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 timemaster configuration.
The chronyd limitations are:
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 (minpoll, maxpoll, ntp_poll 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 (ntp_poll) to specify a subsecond interval.
The ntpd limitations are:
In versions before 4.2.8p1, only the first two shared-memory segments created by the ntpd 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 timemaster 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.
EXAMPLES
A minimal configuration file using one NTP source and two PTP sources would be:
[ntp_server 10.1.1.1]
[ptp_domain 0]
interfaces eth0
[ptp_domain 1]
interfaces eth1
A more complex example using all timemaster options would be:
[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
[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
SEE ALSO
chronyd(8), ntpd(8), phc2sys(8), ptp4l(8)