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  configu‐
241       ration  files  generated  for  all ptp4l instances. There is no default
242       content of this section.
243
244

NOTES

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

EXAMPLES

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

SEE ALSO

349       chronyd(8), ntpd(8), phc2sys(8), ptp4l(8)
350
351
352
353linuxptp                         October 2014                    TIMEMASTER(8)
Impressum