1TIMEMASTER(8) System Manager's Manual TIMEMASTER(8)
2
6 timemaster - run NTP with PTP as reference clocks
7
10 timemaster [ -nmqv ] [ -l print-level ] -f file
11
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 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
29 -f file
30 Specify the path to the timemaster configuration file.
31 -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 -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 -m Print messages to the standard output.
41 -q Don't send messages to the system logger.
43 -v Print the software version and exit.
45 -h Display a help message and exit.
47
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 Sections that can used in the configuration file and options that can
57 be set in them are described below.
58 [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 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 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 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 [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 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 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 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 [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 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 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 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 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 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 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 [chronyd]
177 path Specify the path to the chronyd binary. The default value is
178 chronyd to search for the binary in PATH.
179 options
182 Specify extra options that should be added to the chronyd com‐
183 mand line. No extra options are added by default.
184 [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 makestep 1 3
192 This configures chronyd to step the system clock in the first three
194 updates if the offset is larger than 1 second.
195 [ntpd]
198 path Specify the path to the ntpd binary. The default value is ntpd
199 to search for the binary in PATH.
200 options
203 Specify extra options that should be added to the ntpd command
204 line. No extra options are added by default.
205 [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 restrict default nomodify notrap nopeer noquery
213 restrict 127.0.0.1
214 restrict ::1
215 This configures ntpd to use safe default restrictions.
217 [phc2sys]
220 path Specify the path to the phc2sys binary. The default value is
221 phc2sys to search for the binary in PATH.
222 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 [ptp4l]
230 path Specify the path to the ptp4l binary. The default value is ptp4l
231 to search for the binary in PATH.
232 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 [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 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
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 The chronyd limitations are:
257 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 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 The ntpd limitations are:
270 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 The shortest polling interval for all sources is 3 (8 seconds).
280 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
287 A minimal configuration file using one NTP source and two PTP sources
288 would be:
289 [ntp_server 10.1.1.1]
291 [ptp_domain 0]
293 interfaces eth0
294 [ptp_domain 1]
296 interfaces eth1
297 A more complex example using all timemaster options would be:
299 [ntp_server 10.1.1.1]
301 minpoll 3
302 maxpoll 4
303 iburst 1
304 ntp_options key 12
305 [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 [timemaster]
316 ntp_program chronyd
317 rundir /var/run/timemaster
318 first_shm_segment 1
319 restart_processes 0
320 [chronyd]
322 path /usr/sbin/chronyd
323 options
324 [chrony.conf]
326 makestep 1 3
327 logchange 0.5
328 rtcsync
329 driftfile /var/lib/chrony/drift
330 [ntpd]
332 path /usr/sbin/ntpd
333 options -u ntp:ntp
334 [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 [phc2sys]
342 path /usr/sbin/phc2sys
343 options -l 5
344 [ptp4l]
346 path /usr/sbin/ptp4l
347 options
348 [ptp4l.conf]
350 logging_level 5
351
354 chronyd(8), ntpd(8), phc2sys(8), ptp4l(8)
355linuxptp October 2014 TIMEMASTER(8)