1TIMEMASTER(8)               System Manager's Manual              TIMEMASTER(8)
2
3
4

NAME

6       timemaster - run NTP with PTP as reference clocks
7
8

SYNOPSIS

10       timemaster [ -nmqv ] [ -l print-level ] -f file
11
12

DESCRIPTION

14       timemaster is a program that uses ptp4l and phc2sys in combination with
15       chronyd or ntpd to synchronize the system clock to  NTP  and  PTP  time
16       sources.  The  PTP time is provided by phc2sys and ptp4l via SHM refer‐
17       ence clocks to chronyd/ntpd, which can compare all time sources and use
18       the best sources to synchronize the system clock.
19
20       On  start, timemaster reads a configuration file that specifies the NTP
21       and PTP time sources, checks which network interfaces have and share  a
22       PTP  hardware  clock (PHC), generates configuration files for ptp4l and
23       chronyd/ntpd, and start the ptp4l, phc2sys, chronyd/ntpd  processes  as
24       needed.  Then,  it waits for a signal to kill the processes, remove the
25       generated configuration files and exit.
26
27

OPTIONS

29       -f file
30              Specify the path to the timemaster configuration file.
31
32       -n     Don't start the programs, only print their  configuration  files
33              and  the  commands  that would be executed if this option wasn't
34              specified.
35
36       -l level
37              Set the maximum syslog level of messages which should be printed
38              or sent to the system logger. The default value is 6 (LOG_INFO).
39
40       -m     Print messages to the standard output.
41
42       -q     Don't send messages to the system logger.
43
44       -v     Print the software version and exit.
45
46       -h     Display a help message and exit.
47
48

CONFIGURATION FILE

50       The  configuration  file  is divided into sections. Each section starts
51       with a line containing its name enclosed in  brackets  and  it  follows
52       with  settings.  Each setting is placed on a separate line, it contains
53       the name of the option and the value separated  by  whitespace  charac‐
54       ters. Empty lines and lines starting with # are ignored.
55
56       Sections  that  can used in the configuration file and options that can
57       be set in them are described below.
58
59
60   [timemaster]
61       ntp_program
62              Select which NTP implementation should be used. Possible  values
63              are  chronyd and ntpd. The default value is chronyd. Limitations
64              of the implementations relevant to the timemaster  configuration
65              are listed in NOTES.
66
67
68       rundir Specify  the  directory  where should be generated chronyd, ntpd
69              and ptp4l configuration files and sockets. The directory will be
70              created   if   it   doesn't   exist.   The   default   value  is
71              /var/run/timemaster.
72
73
74       first_shm_segment
75              Specify the first number in a sequence of SHM segments that will
76              be used by ptp4l and phc2sys. The default value is 0. Increasing
77              the number can be useful to avoid conflicts  with  time  sources
78              that  are  not  started  by timemaster, e.g. gpsd using segments
79              number 0 and 1.
80
81
82       restart_processes
83              Enable or disable restarting of processes started by timemaster.
84              If  the  option is set to a non-zero value, all processes except
85              chronyd and ntpd will be automatically restarted when terminated
86              and  timemaster  is  running  for  at least one second (i.e. the
87              process did not terminate due to a configuration  error).  If  a
88              process was terminated and is not started again, timemaster will
89              kill the other processes and exit with a non-zero  status.   The
90              default value is 1 (enabled).
91
92
93   [ntp_server address]
94       The ntp_server section specifies an NTP server that should be used as a
95       time source. The address of the server is included in the name  of  the
96       section.
97
98
99       minpoll
100       maxpoll
101              Specify  the  minimum and maximum NTP polling interval as powers
102              of two in seconds. The default values are 6 (64 seconds) and  10
103              (1024  seconds)  respectively. Shorter polling intervals usually
104              improve the accuracy significantly, but they should be used only
105              when  allowed  by  the  operators of the NTP service (public NTP
106              servers generally don't allow too frequent queries). If the  NTP
107              server  is  located  on the same LAN, polling intervals around 4
108              (16 seconds) might give best accuracy.
109
110
111       iburst Enable or disable sending a burst of NTP  packets  on  start  to
112              speed  up the initial synchronization. Possible values are 1 and
113              0. The default value is 0 (disabled).
114
115
116       ntp_options
117              Specify extra options that should be added for  this  source  to
118              the  server  directive in the configuration file of the selected
119              NTP implementation. No extra options are added by default.
120
121
122   [ptp_domain number]
123       The ptp_domain section specifies a PTP domain that should be used as  a
124       time  source. The PTP domain number is included in the name of the sec‐
125       tion. The ptp4l instances are configured to run in the slaveOnly  mode.
126       In  this  section at least the interfaces option needs to be set, other
127       options are optional.
128
129
130       interfaces
131              Specify which network interfaces should be  used  for  this  PTP
132              domain. A separate ptp4l instance will be started for each group
133              of interfaces sharing the same PHC and for each  interface  that
134              supports  only  SW  time  stamping.  HW time stamping is enabled
135              automatically. If an interface with HW time stamping  is  speci‐
136              fied also in other PTP domains, only the ptp4l instance from the
137              first PTP domain will be using HW time stamping.
138
139
140       ntp_poll
141              Specify the polling interval of  the  NTP  SHM  reference  clock
142              reading samples from ptp4l or phc2sys. It's specified as a power
143              of two in seconds.  The default value is 2 (4 seconds).
144
145
146       phc2sys_poll
147              Specify the polling interval used by phc2sys to read a PTP clock
148              synchronized   by   ptp4l   and   update   the  SHM  sample  for
149              chronyd/ntpd. It's specified as a power of two in  seconds.  The
150              default value is 0 (1 second).
151
152
153       delay  Specify  the  maximum  assumed  roundtrip  delay  to the primary
154              source of the time in this PTP domain. This value is included in
155              the  distance  used by chronyd in the source selection algorithm
156              to detect falsetickers and assign weights for source  combining.
157              The default value is 1e-4 (100 microseconds). With ntpd, the tos
158              mindist command can be used to set a limit with similar  purpose
159              globally for all time sources.
160
161
162       ntp_options
163              Specify  extra  options  that should be added for this source to
164              the refclock or server directives in the configuration  file  of
165              the  selected  NTP implementation. No extra options are added by
166              default.
167
168
169       ptp4l_option
170              Specify an extra ptp4l option specific to this PTP  domain  that
171              should  be added to the configuration files generated for ptp4l.
172              This option may be used multiple times in  one  ptp_domain  sec‐
173              tion.
174
175
176   [chronyd]
177       path   Specify  the  path  to  the chronyd binary. The default value is
178              chronyd to search for the binary in PATH.
179
180
181       options
182              Specify extra options that should be added to the  chronyd  com‐
183              mand line.  No extra options are added by default.
184
185
186   [chrony.conf]
187       Settings  specified in this section are copied directly to the configu‐
188       ration file generated for chronyd. If this section is  not  present  in
189       the timemaster configuration file, the following setting will be added:
190
191       makestep 1 3
192
193       This  configures  chronyd  to  step the system clock in the first three
194       updates if the offset is larger than 1 second.
195
196
197   [ntpd]
198       path   Specify the path to the ntpd binary. The default value  is  ntpd
199              to search for the binary in PATH.
200
201
202       options
203              Specify  extra  options that should be added to the ntpd command
204              line. No extra options are added by default.
205
206
207   [ntp.conf]
208       Settings specified in this section are copied directly to the  configu‐
209       ration  file  generated for ntpd. If this section is not present in the
210       timemaster configuration file, the following settings will be added:
211
212       restrict default nomodify notrap nopeer noquery
213       restrict 127.0.0.1
214       restrict ::1
215
216       This configures ntpd to use safe default restrictions.
217
218
219   [phc2sys]
220       path   Specify the path to the phc2sys binary.  The  default  value  is
221              phc2sys to search for the binary in PATH.
222
223
224       options
225              Specify  extra  options that should be added to all phc2sys com‐
226              mand lines.  By default, -l 5 is added to the command lines.
227
228
229   [ptp4l]
230       path   Specify the path to the ptp4l binary. The default value is ptp4l
231              to search for the binary in PATH.
232
233
234       options
235              Specify  extra options that should be added to all ptp4l command
236              lines. By default, -l 5 is added to the command lines.
237
238
239   [ptp4l.conf]
240       Settings specified in this section are copied directly  to  the  global
241       section  of  the configuration files generated for all ptp4l instances.
242       There is no default content of this section.
243
244       Other sections (e.g. [unicast_master_table]) may be specified here, but
245       lines beginning with the bracket need to be prefixed with the > charac‐
246       ter to prevent timemaster from parsing it as  a  beginning  of  another
247       section.
248
249

NOTES

251       For best accuracy, chronyd is usually preferred over ntpd, it also syn‐
252       chronizes the system clock faster. Both NTP  implementations,  however,
253       have  some  limitations  that need to be considered before choosing the
254       one to be used in a given timemaster configuration.
255
256       The chronyd limitations are:
257
258              In version 1.31 and  older,  the  maximum  number  of  reference
259              clocks  used  at  the  same time is 8. This limits the number of
260              PHCs and interfaces using SW time stamping that can be used  for
261              PTP.
262
263              Using  polling  intervals  (minpoll,  maxpoll, ntp_poll options)
264              shorter than 2 (4 seconds)  is  not  recommended  with  versions
265              before  1.30.  With  1.30 and later values of 0 or 1 can be used
266              for NTP sources and negative values for PTP  sources  (ntp_poll)
267              to specify a subsecond interval.
268
269       The ntpd limitations are:
270
271              In  versions  before  4.2.8p1,  only the first two shared-memory
272              segments created by the ntpd SHM refclock driver have owner-only
273              access.  Other  segments  are  created  with world access, which
274              allows any user on the system to write to the segments and  dis‐
275              rupt  or take control over the synchronization of the clock.  In
276              4.2.8p1 the access was made configurable with the  mode  option,
277              which is set by timemaster for owner-ownly access.
278
279              The shortest polling interval for all sources is 3 (8 seconds).
280
281              Nanosecond resolution in the SHM refclock driver is supported in
282              version 4.2.7p303 and later, older versions have only  microsec‐
283              ond resolution.
284
285

EXAMPLES

287       A  minimal  configuration file using one NTP source and two PTP sources
288       would be:
289
290       [ntp_server 10.1.1.1]
291
292       [ptp_domain 0]
293       interfaces eth0
294
295       [ptp_domain 1]
296       interfaces eth1
297
298       A more complex example using all timemaster options would be:
299
300       [ntp_server 10.1.1.1]
301       minpoll 3
302       maxpoll 4
303       iburst 1
304       ntp_options key 12
305
306       [ptp_domain 0]
307       interfaces eth0 eth1
308       ntp_poll 0
309       phc2sys_poll -2
310       delay 10e-6
311       ntp_options prefer
312       ptp4l_option clock_servo linreg
313       ptp4l_option delay_mechanism P2P
314
315       [timemaster]
316       ntp_program chronyd
317       rundir /var/run/timemaster
318       first_shm_segment 1
319       restart_processes 0
320
321       [chronyd]
322       path /usr/sbin/chronyd
323       options
324
325       [chrony.conf]
326       makestep 1 3
327       logchange 0.5
328       rtcsync
329       driftfile /var/lib/chrony/drift
330
331       [ntpd]
332       path /usr/sbin/ntpd
333       options -u ntp:ntp
334
335       [ntp.conf]
336       restrict default nomodify notrap nopeer noquery
337       restrict 127.0.0.1
338       restrict ::1
339       driftfile /var/lib/ntp/drift
340
341       [phc2sys]
342       path /usr/sbin/phc2sys
343       options -l 5
344
345       [ptp4l]
346       path /usr/sbin/ptp4l
347       options
348
349       [ptp4l.conf]
350       logging_level 5
351
352

SEE ALSO

354       chronyd(8), ntpd(8), phc2sys(8), ptp4l(8)
355
356
357
358linuxptp                         October 2014                    TIMEMASTER(8)
Impressum