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 SOCK refer‐
17 ence clock to chronyd or SHM reference clock to ntpd, which can compare
18 all time sources and use the best sources to synchronize the system
19 clock.
20 On start, timemaster reads a configuration file that specifies the NTP
22 and PTP time sources, checks which network interfaces have and share a
23 PTP hardware clock (PHC), generates configuration files for ptp4l and
24 chronyd/ntpd, and start the ptp4l, phc2sys, chronyd/ntpd processes as
25 needed. Then, it waits for a signal to kill the processes, remove the
26 generated configuration files and exit.
27
30 -f file
31 Specify the path to the timemaster configuration file.
32 -n Don't start the programs, only print their configuration files
34 and the commands that would be executed if this option wasn't
35 specified.
36 -l level
38 Set the maximum syslog level of messages which should be printed
39 or sent to the system logger. The default value is 6 (LOG_INFO).
40 -m Print messages to the standard output.
42 -q Don't send messages to the system logger.
44 -v Print the software version and exit.
46 -h Display a help message and exit.
48
51 The configuration file is divided into sections. Each section starts
52 with a line containing its name enclosed in brackets and it follows
53 with settings. Each setting is placed on a separate line, it contains
54 the name of the option and the value separated by whitespace charac‐
55 ters. Empty lines and lines starting with # are ignored.
56 Sections that can used in the configuration file and options that can
58 be set in them are described below.
59 [timemaster]
62 ntp_program
63 Select which NTP implementation should be used. Possible values
64 are chronyd and ntpd. The default value is chronyd. Limitations
65 of the implementations relevant to the timemaster configuration
66 are listed in NOTES.
67 rundir Specify the directory where should be generated chronyd, ntpd
70 and ptp4l configuration files and sockets. The directory will be
71 created if it doesn't exist. The default value is
72 /var/run/timemaster.
73 first_shm_segment
76 Specify the first number in a sequence of SHM segments that will
77 be used by ptp4l and phc2sys. The default value is 0. Increasing
78 the number can be useful to avoid conflicts with time sources
79 that are not started by timemaster, e.g. gpsd using segments
80 number 0 and 1.
81 restart_processes
84 Enable or disable restarting of processes started by timemaster.
85 If the option is set to a non-zero value, all processes except
86 chronyd and ntpd will be automatically restarted when terminated
87 and timemaster is running for at least one second (i.e. the
88 process did not terminate due to a configuration error). If a
89 process was terminated and is not started again, timemaster will
90 kill the other processes and exit with a non-zero status. The
91 default value is 1 (enabled).
92 use_vclocks
95 Enable or disable synchronization with virtual clocks. If en‐
96 abled, timemaster will create virtual clocks running on top of
97 physical clocks needed by configured PTP domains. This enables
98 hardware time stamping for multiple ptp4l instances using the
99 same network interface. The default value is -1, which enables
100 the virtual clocks if running on Linux 5.18 or later.
101 [ntp_server address]
104 The ntp_server section specifies an NTP server that should be used as a
105 time source. The address of the server is included in the name of the
106 section.
107 minpoll
110 maxpoll
111 Specify the minimum and maximum NTP polling interval as powers
112 of two in seconds. The default values are 6 (64 seconds) and 10
113 (1024 seconds) respectively. Shorter polling intervals usually
114 improve the accuracy significantly, but they should be used only
115 when allowed by the operators of the NTP service (public NTP
116 servers generally don't allow too frequent queries). If the NTP
117 server is located on the same LAN, polling intervals around 4
118 (16 seconds) might give best accuracy.
119 iburst Enable or disable sending a burst of NTP packets on start to
122 speed up the initial synchronization. Possible values are 1 and
123 0. The default value is 0 (disabled).
124 ntp_options
127 Specify extra options that should be added for this source to
128 the server directive in the configuration file of the selected
129 NTP implementation. No extra options are added by default.
130 [ptp_domain number]
133 The ptp_domain section specifies a PTP domain that should be used as a
134 time source. The PTP domain number is included in the name of the sec‐
135 tion. The ptp4l instances are configured to run in the clientOnly mode.
136 In this section at least the interfaces option needs to be set, other
137 options are optional.
138 interfaces
141 Specify which network interfaces should be used for this PTP do‐
142 main. A separate ptp4l instance will be started for each group
143 of interfaces sharing the same PHC and for each interface that
144 supports only SW time stamping. HW time stamping is enabled au‐
145 tomatically. If an interface with HW time stamping is specified
146 also in other PTP domains and virtual clocks are disabled, only
147 the ptp4l instance from the first PTP domain will be using HW
148 time stamping.
149 ntp_poll
152 Specify the polling interval of the SOCK/SHM reference clock
153 reading samples from ptp4l or phc2sys. It's specified as a power
154 of two in seconds. The default value is 2 (4 seconds).
155 phc2sys_poll
158 Specify the polling interval used by phc2sys to read a PTP clock
159 synchronized by ptp4l and update the SOCK/SHM sample for
160 chronyd/ntpd. It's specified as a power of two in seconds. The
161 default value is 0 (1 second).
162 delay Specify the maximum assumed roundtrip delay to the primary
165 source of the time in this PTP domain. This value is included in
166 the distance used by chronyd in the source selection algorithm
167 to detect falsetickers and assign weights for source combining.
168 The default value is 1e-4 (100 microseconds). With ntpd, the tos
169 mindist command can be used to set a limit with similar purpose
170 globally for all time sources.
171 ntp_options
174 Specify extra options that should be added for this source to
175 the refclock or server directives in the configuration file of
176 the selected NTP implementation. No extra options are added by
177 default.
178 ptp4l_option
181 Specify an extra ptp4l option specific to this PTP domain that
182 should be added to the configuration files generated for ptp4l.
183 This option may be used multiple times in one ptp_domain sec‐
184 tion.
185 [chronyd]
188 path Specify the path to the chronyd binary. The default value is
189 chronyd to search for the binary in PATH.
190 options
193 Specify extra options that should be added to the chronyd com‐
194 mand line. No extra options are added by default.
195 [chrony.conf]
198 Settings specified in this section are copied directly to the configu‐
199 ration file generated for chronyd. If this section is not present in
200 the timemaster configuration file, the following setting will be added:
201 makestep 1 3
203 This configures chronyd to step the system clock in the first three up‐
205 dates if the offset is larger than 1 second.
206 [ntpd]
209 path Specify the path to the ntpd binary. The default value is ntpd
210 to search for the binary in PATH.
211 options
214 Specify extra options that should be added to the ntpd command
215 line. No extra options are added by default.
216 [ntp.conf]
219 Settings specified in this section are copied directly to the configu‐
220 ration file generated for ntpd. If this section is not present in the
221 timemaster configuration file, the following settings will be added:
222 restrict default nomodify notrap nopeer noquery
224 restrict 127.0.0.1
225 restrict ::1
226 This configures ntpd to use safe default restrictions.
228 [phc2sys]
231 path Specify the path to the phc2sys binary. The default value is
232 phc2sys to search for the binary in PATH.
233 options
236 Specify extra options that should be added to all phc2sys com‐
237 mand lines. By default, -l 5 is added to the command lines.
238 [ptp4l]
241 path Specify the path to the ptp4l binary. The default value is ptp4l
242 to search for the binary in PATH.
243 options
246 Specify extra options that should be added to all ptp4l command
247 lines. By default, -l 5 is added to the command lines.
248 [ptp4l.conf]
251 Settings specified in this section are copied directly to the global
252 section of the configuration files generated for all ptp4l instances.
253 There is no default content of this section.
254 Other sections (e.g. [unicast_master_table]) may be specified here, but
256 lines beginning with the bracket need to be prefixed with the > charac‐
257 ter to prevent timemaster from parsing it as a beginning of another
258 section.
259
262 For best accuracy, chronyd is usually preferred over ntpd, it also syn‐
263 chronizes the system clock faster. Both NTP implementations, however,
264 have some limitations that need to be considered before choosing the
265 one to be used in a given timemaster configuration.
266 The chronyd limitations are:
268 In version 1.31 and older, the maximum number of reference
270 clocks used at the same time is 8. This limits the number of
271 PHCs and interfaces using SW time stamping that can be used for
272 PTP.
273 Using polling intervals (minpoll, maxpoll, ntp_poll options)
275 shorter than 2 (4 seconds) is not recommended with versions be‐
276 fore 1.30. With 1.30 and later values of 0 or 1 can be used for
277 NTP sources and negative values for PTP sources (ntp_poll) to
278 specify a subsecond interval.
279 The ntpd limitations are:
281 In versions before 4.2.8p1, only the first two shared-memory
283 segments created by the ntpd SHM refclock driver have owner-only
284 access. Other segments are created with world access, which al‐
285 lows any user on the system to write to the segments and disrupt
286 or take control over the synchronization of the clock. In
287 4.2.8p1 the access was made configurable with the mode option,
288 which is set by timemaster for owner-ownly access.
289 The shortest polling interval for all sources is 3 (8 seconds).
291 Nanosecond resolution in the SHM refclock driver is supported in
293 version 4.2.7p303 and later, older versions have only microsec‐
294 ond resolution.
295
298 A minimal configuration file using one NTP source and two PTP sources
299 would be:
300 [ntp_server 10.1.1.1]
302 [ptp_domain 0]
304 interfaces eth0
305 [ptp_domain 1]
307 interfaces eth1
308 A more complex example using all timemaster options would be:
310 [ntp_server 10.1.1.1]
312 minpoll 3
313 maxpoll 4
314 iburst 1
315 ntp_options key 12
316 [ptp_domain 0]
318 interfaces eth0 eth1
319 ntp_poll 0
320 phc2sys_poll -2
321 delay 10e-6
322 ntp_options prefer
323 ptp4l_option clock_servo linreg
324 ptp4l_option delay_mechanism P2P
325 [timemaster]
327 ntp_program chronyd
328 rundir /var/run/timemaster
329 first_shm_segment 1
330 restart_processes 0
331 use_vclocks 0
332 [chronyd]
334 path /usr/sbin/chronyd
335 options
336 [chrony.conf]
338 makestep 1 3
339 logchange 0.5
340 rtcsync
341 driftfile /var/lib/chrony/drift
342 [ntpd]
344 path /usr/sbin/ntpd
345 options -u ntp:ntp
346 [ntp.conf]
348 restrict default nomodify notrap nopeer noquery
349 restrict 127.0.0.1
350 restrict ::1
351 driftfile /var/lib/ntp/drift
352 [phc2sys]
354 path /usr/sbin/phc2sys
355 options -l 5
356 [ptp4l]
358 path /usr/sbin/ptp4l
359 options
360 [ptp4l.conf]
362 logging_level 5
363
366 chronyd(8), ntpd(8), phc2sys(8), ptp4l(8)
367linuxptp January 2021 TIMEMASTER(8)