Provided by: linuxptp_1.6-1_amd64 bug

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.

   [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).

   [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.

       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

       [ptp_domain 0]
       interfaces eth0 eth1
       ntp_poll 0
       phc2sys_poll -2
       delay 10e-6
       ptp4l_option clock_servo linreg
       ptp4l_option delay_mechanism P2P

       [timemaster]
       ntp_program chronyd
       rundir /var/run/timemaster

       [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)