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 [ntp_server address]
75 The ntp_server section specifies an NTP server that should be used as a
76 time source. The address of the server is included in the name of the
77 section.
78 minpoll
81 maxpoll
82 Specify the minimum and maximum NTP polling interval as powers
83 of two in seconds. The default values are 6 (64 seconds) and 10
84 (1024 seconds) respectively. Shorter polling intervals usually
85 improve the accuracy significantly, but they should be used only
86 when allowed by the operators of the NTP service (public NTP
87 servers generally don't allow too frequent queries). If the NTP
88 server is located on the same LAN, polling intervals around 4
89 (16 seconds) might give best accuracy.
90 iburst Enable or disable sending a burst of NTP packets on start to
93 speed up the initial synchronization. Possible values are 1 and
94 0. The default value is 0 (disabled).
95 [ptp_domain number]
98 The ptp_domain section specifies a PTP domain that should be used as a
99 time source. The PTP domain number is included in the name of the sec‐
100 tion. The ptp4l instances are configured to run in the slaveOnly mode.
101 In this section at least the interfaces option needs to be set, other
102 options are optional.
103 interfaces
106 Specify which network interfaces should be used for this PTP
107 domain. A separate ptp4l instance will be started for each group
108 of interfaces sharing the same PHC and for each interface that
109 supports only SW time stamping. HW time stamping is enabled
110 automatically. If an interface with HW time stamping is speci‐
111 fied also in other PTP domains, only the ptp4l instance from the
112 first PTP domain will be using HW time stamping.
113 ntp_poll
116 Specify the polling interval of the NTP SHM reference clock
117 reading samples from ptp4l or phc2sys. It's specified as a power
118 of two in seconds. The default value is 2 (4 seconds).
119 phc2sys_poll
122 Specify the polling interval used by phc2sys to read a PTP clock
123 synchronized by ptp4l and update the SHM sample for
124 chronyd/ntpd. It's specified as a power of two in seconds. The
125 default value is 0 (1 second).
126 delay Specify the maximum assumed roundtrip delay to the primary
129 source of the time in this PTP domain. This value is included in
130 the distance used by chronyd in the source selection algorithm
131 to detect falsetickers and assign weights for source combining.
132 The default value is 1e-4 (100 microseconds). With ntpd, the tos
133 mindist command can be used to set a limit with similar purpose
134 globally for all time sources.
135 ptp4l_option
138 Specify an extra ptp4l option specific to this PTP domain that
139 should be added to the configuration files generated for ptp4l.
140 This option may be used multiple times in one ptp_domain sec‐
141 tion.
142 [chronyd]
145 path Specify the path to the chronyd binary. The default value is
146 chronyd to search for the binary in PATH.
147 options
150 Specify extra options that should be added to the chronyd com‐
151 mand line. No extra options are added by default.
152 [chrony.conf]
155 Settings specified in this section are copied directly to the configu‐
156 ration file generated for chronyd. If this section is not present in
157 the timemaster configuration file, the following setting will be added:
158 makestep 1 3
160 This configures chronyd to step the system clock in the first three
162 updates if the offset is larger than 1 second.
163 [ntpd]
166 path Specify the path to the ntpd binary. The default value is ntpd
167 to search for the binary in PATH.
168 options
171 Specify extra options that should be added to the ntpd command
172 line. No extra options are added by default.
173 [ntp.conf]
176 Settings specified in this section are copied directly to the configu‐
177 ration file generated for ntpd. If this section is not present in the
178 timemaster configuration file, the following settings will be added:
179 restrict default nomodify notrap nopeer noquery
181 restrict 127.0.0.1
182 restrict ::1
183 This configures ntpd to use safe default restrictions.
185 [phc2sys]
188 path Specify the path to the phc2sys binary. The default value is
189 phc2sys to search for the binary in PATH.
190 options
193 Specify extra options that should be added to all phc2sys com‐
194 mand lines. By default, -l 5 is added to the command lines.
195 [ptp4l]
198 path Specify the path to the ptp4l binary. The default value is ptp4l
199 to search for the binary in PATH.
200 options
203 Specify extra options that should be added to all ptp4l command
204 lines. By default, -l 5 is added to the command lines.
205 [ptp4l.conf]
208 Settings specified in this section are copied directly to the configu‐
209 ration files generated for all ptp4l instances. There is no default
210 content of this section.
211
214 For best accuracy, chronyd is usually preferred over ntpd, it also syn‐
215 chronizes the system clock faster. Both NTP implementations, however,
216 have some limitations that need to be considered before choosing the
217 one to be used in a given timemaster configuration.
218 The chronyd limitations are:
220 In version 1.31 and older, the maximum number of reference
222 clocks used at the same time is 8. This limits the number of
223 PHCs and interfaces using SW time stamping that can be used for
224 PTP.
225 Using polling intervals (minpoll, maxpoll, ntp_poll options)
227 shorter than 2 (4 seconds) is not recommended with versions
228 before 1.30. With 1.30 and later values of 0 or 1 can be used
229 for NTP sources and negative values for PTP sources (ntp_poll)
230 to specify a subsecond interval.
231 The ntpd limitations are:
233 In versions before 4.2.8p1, only the first two shared-memory
235 segments created by the ntpd SHM refclock driver have owner-only
236 access. Other segments are created with world access, which
237 allows any user on the system to write to the segments and dis‐
238 rupt or take control over the synchronization of the clock. In
239 4.2.8p1 the access was made configurable with the mode option,
240 which is set by timemaster for owner-ownly access. (in Red Hat
241 Enterprise Linux 6 it is configurable in ntp-4.2.6p5-3.el6 and
242 later)
243 The shortest polling interval for all sources is 3 (8 seconds).
245 Nanosecond resolution in the SHM refclock driver is supported in
247 version 4.2.7p303 and later, older versions have only microsec‐
248 ond resolution. (in Red Hat Enterprise Linux 6 nanosecond reso‐
249 lution is supported in ntp-4.2.6p5-3.el6 and later)
250
253 A minimal configuration file using one NTP source and two PTP sources
254 would be:
255 [ntp_server 10.1.1.1]
257 [ptp_domain 0]
259 interfaces eth0
260 [ptp_domain 1]
262 interfaces eth1
263 A more complex example using all timemaster options would be:
265 [ntp_server 10.1.1.1]
267 minpoll 3
268 maxpoll 4
269 iburst 1
270 [ptp_domain 0]
272 interfaces eth0 eth1
273 ntp_poll 0
274 phc2sys_poll -2
275 delay 10e-6
276 ptp4l_option clock_servo linreg
277 ptp4l_option delay_mechanism P2P
278 [timemaster]
280 ntp_program chronyd
281 rundir /var/run/timemaster
282 [chronyd]
284 path /usr/sbin/chronyd
285 options
286 [chrony.conf]
288 makestep 1 3
289 logchange 0.5
290 rtcsync
291 driftfile /var/lib/chrony/drift
292 [ntpd]
294 path /usr/sbin/ntpd
295 options -u ntp:ntp
296 [ntp.conf]
298 restrict default nomodify notrap nopeer noquery
299 restrict 127.0.0.1
300 restrict ::1
301 driftfile /var/lib/ntp/drift
302 [phc2sys]
304 path /usr/sbin/phc2sys
305 options -l 5
306 [ptp4l]
308 path /usr/sbin/ptp4l
309 options
310 [ptp4l.conf]
312 logging_level 5
313
316 chronyd(8), ntpd(8), phc2sys(8), ptp4l(8)
317linuxptp October 2014 TIMEMASTER(8)