1CHRONY.CONF(5) Configuration Files CHRONY.CONF(5)
2
3
4
6 chrony.conf - chronyd configuration file
7
9 chrony.conf
10
12 This file configures the chronyd daemon. The compiled-in location is
13 /etc/chrony.conf, but other locations can be specified on the chronyd
14 command line with the -f option.
15
16 Each directive in the configuration file is placed on a separate line.
17 The following sections describe each of the directives in turn. The
18 directives can occur in any order in the file and they are not
19 case-sensitive.
20
21 The configuration directives can also be specified directly on the
22 chronyd command line. In this case each argument is parsed as a new
23 line and the configuration file is ignored.
24
25 While the number of supported directives is large, only a few of them
26 are typically needed. See the EXAMPLES section for configuration in
27 typical operating scenarios.
28
29 The configuration file might contain comment lines. A comment line is
30 any line that starts with zero or more spaces followed by any one of
31 the following characters: !, ;, #, %. Any line with this format will be
32 ignored.
33
35 Time sources
36 server hostname [option]...
37 The server directive specifies an NTP server which can be used as a
38 time source. The client-server relationship is strictly
39 hierarchical: a client might synchronise its system time to that of
40 the server, but the server’s system time will never be influenced
41 by that of a client.
42
43 The server directive is immediately followed by either the name of
44 the server, or its IP address. The server directive supports the
45 following options:
46
47 minpoll poll
48 Although chronyd will trim the rate at which it samples the
49 server during normal operation, the user might want to
50 constrain the minimum polling interval. This is always defined
51 as a power of 2, so minpoll 5 would mean that the polling
52 interval cannot drop below 32 seconds. The default is 6 (64
53 seconds), the minimum is -4 (1/16th of a second), and the
54 maximum is 24 (6 months). Note that intervals shorter than 6
55 (64 seconds) should generally not be used with public servers
56 on the Internet, because it might be considered abuse.
57
58 maxpoll poll
59 In a similar way, the user might want to constrain the maximum
60 polling interval. Again this is specified as a power of 2,
61 maxpoll 9 indicates that the polling interval must stay at or
62 below 512 seconds. The default is 10 (1024 seconds), the
63 minimum is 0 (1 second), and the maximum is 24 (6 months).
64
65 iburst
66 If this option is set, the interval between the first four
67 polls will be 2 seconds instead of minpoll. This is useful to
68 quickly get the first update of the clock after chronyd is
69 started.
70
71 key id
72 The NTP protocol supports the inclusion of checksums in the
73 packets, to prevent computers having their system time upset by
74 rogue packets being sent to them. The checksums are generated
75 as a function of a password, using the cryptographic hash
76 function set in the key file, which is specified by the keyfile
77 directive.
78
79 If the key option is present, chronyd will attempt to use
80 authenticated packets when communicating with this server. The
81 key number used will be the single argument to the key option
82 (an unsigned integer in the range 1 through 2^32-1). The server
83 must have the same password for this key number configured,
84 otherwise no relationship between the computers will be
85 possible.
86
87 maxdelay delay
88 chronyd uses the network round-trip delay to the server to
89 determine how accurate a particular measurement is likely to
90 be. Long round-trip delays indicate that the request, or the
91 response, or both were delayed. If only one of the messages was
92 delayed the measurement error is likely to be substantial.
93
94 For small variations in the round-trip delay, chronyd uses a
95 weighting scheme when processing the measurements. However,
96 beyond a certain level of delay the measurements are likely to
97 be so corrupted as to be useless. (This is particularly so on
98 dial-up or other slow links, where a long delay probably
99 indicates a highly asymmetric delay caused by the response
100 waiting behind a lot of packets related to a download of some
101 sort).
102
103 If the user knows that round trip delays above a certain level
104 should cause the measurement to be ignored, this level can be
105 defined with the maxdelay option. For example, maxdelay 0.3
106 would indicate that measurements with a round-trip delay of 0.3
107 seconds or more should be ignored. The default value is 3
108 seconds and the maximum value is 1000 seconds.
109
110 maxdelayratio ratio
111 This option is similar to the maxdelay option above. chronyd
112 keeps a record of the minimum round-trip delay amongst the
113 previous measurements that it has buffered. If a measurement
114 has a round trip delay that is greater than the maxdelayratio
115 times the minimum delay, it will be rejected.
116
117 maxdelaydevratio ratio
118 If a measurement has a ratio of the increase in the round-trip
119 delay from the minimum delay amongst the previous measurements
120 to the standard deviation of the previous measurements that is
121 greater than the specified ratio, it will be rejected. The
122 default is 10.0.
123
124 mindelay delay
125 This options specifies a fixed minimum round-trip delay to be
126 used instead of the minimum amongst the previous measurements.
127 This can be useful in networks with static configuration to
128 improve the stability of corrections for asymmetric jitter,
129 weighting of the measurements, and the maxdelayratio and
130 maxdelaydevratio tests. The value should be set accurately in
131 order to have a positive effect on the synchronisation.
132
133 asymmetry ratio
134 This options specifies the asymmetry of the network jitter on
135 the path to the source, which is used to correct the measured
136 offset according to the delay. The asymmetry can be between
137 -0.5 and +0.5. A negative value means the delay of packets sent
138 to the source is more variable than the delay of packets sent
139 from the source back. By default, chronyd estimates the
140 asymmetry automatically.
141
142 offset offset
143 This option specifies a correction (in seconds) which will be
144 applied to offsets measured with this source. It’s particularly
145 useful to compensate for a known asymmetry in network delay or
146 timestamping errors. For example, if packets sent to the source
147 were on average delayed by 100 microseconds more than packets
148 sent from the source back, the correction would be -0.00005
149 (-50 microseconds). The default is 0.0.
150
151 minsamples samples
152 Set the minimum number of samples kept for this source. This
153 overrides the minsamples directive.
154
155 maxsamples samples
156 Set the maximum number of samples kept for this source. This
157 overrides the maxsamples directive.
158
159 offline
160 If the server will not be reachable when chronyd is started,
161 the offline option can be specified. chronyd will not try to
162 poll the server until it is enabled to do so (by using the
163 online command in chronyc).
164
165 auto_offline
166 If this option is set, the server will be assumed to have gone
167 offline when 2 requests have been sent to it without receiving
168 a response. This option avoids the need to run the offline
169 command from chronyc when disconnecting the network link. (It
170 will still be necessary to use the online command when the link
171 has been established, to enable measurements to start.)
172
173 prefer
174 Prefer this source over sources without prefer option.
175
176 noselect
177 Never select this source. This is particularly useful for
178 monitoring.
179
180 trust
181 Assume time from this source is always true. It can be rejected
182 as a falseticker in the source selection only if another source
183 with this option does not agree with it.
184
185 require
186 Require that at least one of the sources specified with this
187 option is selectable (i.e. recently reachable and not a
188 falseticker) before updating the clock. Together with the trust
189 option this might be useful to allow a trusted authenticated
190 source to be safely combined with unauthenticated sources in
191 order to improve the accuracy of the clock. They can be
192 selected and used for synchronisation only if they agree with
193 the trusted and required source.
194
195 xleave
196 This option enables an interleaved mode which allows the server
197 or the peer to send transmit timestamps captured after the
198 actual transmission (e.g. when the server or the peer is
199 running chronyd with software (kernel) or hardware
200 timestamping). This can significantly improve the accuracy of
201 the measurements.
202
203 The interleaved mode is compatible with servers that support
204 only the basic mode, but peers must both support and have
205 enabled the interleaved mode, otherwise the synchronisation
206 will work only in one direction. Note that even servers that
207 support the interleaved mode might respond in the basic mode as
208 the interleaved mode requires the servers to keep some state
209 for each client and the state might be dropped when there are
210 too many clients (e.g. clientloglimit is too small), or it
211 might be overwritten by other clients that have the same IP
212 address (e.g. computers behind NAT or someone sending requests
213 with a spoofed source address).
214
215 The xleave option can be combined with the presend option in
216 order to shorten the interval in which the server has to keep
217 the state to be able to respond in the interleaved mode.
218
219 polltarget target
220 Target number of measurements to use for the regression
221 algorithm which chronyd will try to maintain by adjusting the
222 polling interval between minpoll and maxpoll. A higher target
223 makes chronyd prefer shorter polling intervals. The default is
224 8 and a useful range is from 6 to 60.
225
226 port port
227 This option allows the UDP port on which the server understands
228 NTP requests to be specified. For normal servers this option
229 should not be required (the default is 123, the standard NTP
230 port).
231
232 presend poll
233 If the timing measurements being made by chronyd are the only
234 network data passing between two computers, you might find that
235 some measurements are badly skewed due to either the client or
236 the server having to do an ARP lookup on the other party prior
237 to transmitting a packet. This is more of a problem with long
238 sampling intervals, which might be similar in duration to the
239 lifetime of entries in the ARP caches of the machines.
240
241 In order to avoid this problem, the presend option can be used.
242 It takes a single integer argument, which is the smallest
243 polling interval for which an extra pair of NTP packets will be
244 exchanged between the client and the server prior to the actual
245 measurement. For example, with the following option included in
246 a server directive:
247
248 presend 9
249
250 when the polling interval is 512 seconds or more, an extra NTP
251 client packet will be sent to the server a short time (2
252 seconds) before making the actual measurement.
253
254 The presend option cannot be used in the peer directive. If it
255 is used with the xleave option, chronyd will send two extra
256 packets instead of one.
257
258 minstratum stratum
259 When the synchronisation source is selected from available
260 sources, sources with lower stratum are normally slightly
261 preferred. This option can be used to increase stratum of the
262 source to the specified minimum, so chronyd will avoid
263 selecting that source. This is useful with low stratum sources
264 that are known to be unreliable or inaccurate and which should
265 be used only when other sources are unreachable.
266
267 version version
268 This option sets the NTP version of packets sent to the server.
269 This can be useful when the server runs an old NTP
270 implementation that does not respond to requests using a newer
271 version. The default version depends on whether a key is
272 specified by the key option and which authentication hash
273 function the key is using. If the output size of the hash
274 function is longer than 160 bits, the default version is 3 for
275 compatibility with older chronyd servers. Otherwise, the
276 default version is 4.
277
278 pool name [option]...
279 The syntax of this directive is similar to that for the server
280 directive, except that it is used to specify a pool of NTP servers
281 rather than a single NTP server. The pool name is expected to
282 resolve to multiple addresses which might change over time.
283
284 All options valid in the server directive can be used in this
285 directive too. There is one option specific to the pool directive:
286 maxsources sets the maximum number of sources that can be used from
287 the pool, the default value is 4.
288
289 On start, when the pool name is resolved, chronyd will add up to 16
290 sources, one for each resolved address. When the number of sources
291 from which at least one valid reply was received reaches the number
292 specified by the maxsources option, the other sources will be
293 removed. When a pool source is unreachable, marked as a
294 falseticker, or has a distance larger than the limit set by the
295 maxdistance directive, chronyd will try to replace the source with
296 a newly resolved address from the pool.
297
298 An example of the pool directive is
299
300 pool pool.ntp.org iburst maxsources 3
301
302 peer hostname [option]...
303 The syntax of this directive is identical to that for the server
304 directive, except that it specifies a symmetric association with an
305 NTP peer instead of a client/server association with an NTP server.
306 A single symmetric association allows the peers to be both servers
307 and clients to each other. This is mainly useful when the NTP
308 implementation of the peer (e.g. ntpd) supports ephemeral symmetric
309 associations and does not need to be configured with an address of
310 this host. chronyd does not support ephemeral associations.
311
312 When a key is specified by the key option to enable authentication,
313 both peers must use the same key and the same key number.
314
315 Note that the symmetric mode is less secure than the client/server
316 mode. A denial-of-service attack is possible on unauthenticated
317 symmetric associations, i.e. when the peer was specified without
318 the key option. An attacker who does not see network traffic
319 between two hosts, but knows that they are peering with each other,
320 can periodically send them unauthenticated packets with spoofed
321 source addresses in order to disrupt their NTP state and prevent
322 them from synchronising to each other. When the association is
323 authenticated, an attacker who does see the network traffic, but
324 cannot prevent the packets from reaching the other host, can still
325 disrupt the state by replaying old packets. The attacker has
326 effectively the same power as a man-in-the-middle attacker. A
327 partial protection against this attack is implemented in chronyd,
328 which can protect the peers if they are using the same polling
329 interval and they never sent an authenticated packet with a
330 timestamp from future, but it should not be relied on as it is
331 difficult to ensure the conditions are met. If two hosts should be
332 able to synchronise to each other in both directions, it is
333 recommended to use two separate client/server associations
334 (specified by the server directive on both hosts) instead.
335
336 initstepslew step-threshold [hostname]...
337 In normal operation, chronyd slews the time when it needs to adjust
338 the system clock. For example, to correct a system clock which is 1
339 second slow, chronyd slightly increases the amount by which the
340 system clock is advanced on each clock interrupt, until the error
341 is removed. Note that at no time does time run backwards with this
342 method.
343
344 On most Unix systems it is not desirable to step the system clock,
345 because many programs rely on time advancing monotonically
346 forwards.
347
348 When the chronyd daemon is initially started, it is possible that
349 the system clock is considerably in error. Attempting to correct
350 such an error by slewing might not be sensible, since it might take
351 several hours to correct the error by this means.
352
353 The purpose of the initstepslew directive is to allow chronyd to
354 make a rapid measurement of the system clock error at boot time,
355 and to correct the system clock by stepping before normal operation
356 begins. Since this would normally be performed only at an
357 appropriate point in the system boot sequence, no other software
358 should be adversely affected by the step.
359
360 If the correction required is less than a specified threshold, a
361 slew is used instead. This makes it safer to restart chronyd whilst
362 the system is in normal operation.
363
364 The initstepslew directive takes a threshold and a list of NTP
365 servers as arguments. Each of the servers is rapidly polled several
366 times, and a majority voting mechanism used to find the most likely
367 range of system clock error that is present. A step or slew is
368 applied to the system clock to correct this error. chronyd then
369 enters its normal operating mode.
370
371 An example of the use of the directive is:
372
373 initstepslew 30 foo.example.net bar.example.net
374
375 where 2 NTP servers are used to make the measurement. The 30
376 indicates that if the system’s error is found to be 30 seconds or
377 less, a slew will be used to correct it; if the error is above 30
378 seconds, a step will be used.
379
380 The initstepslew directive can also be used in an isolated LAN
381 environment, where the clocks are set manually. The most stable
382 computer is chosen as the master, and the other computers are
383 slaved to it. If each of the slaves is configured with the local
384 directive, the master can be set up with an initstepslew directive
385 which references some or all of the slaves. Then, if the master
386 machine has to be rebooted, the slaves can be relied on to act
387 analogously to a flywheel and preserve the time for a short period
388 while the master completes its reboot.
389
390 The initstepslew directive is functionally similar to a combination
391 of the makestep and server directives with the iburst option. The
392 main difference is that the initstepslew servers are used only
393 before normal operation begins and that the foreground chronyd
394 process waits for initstepslew to finish before exiting. This is
395 useful to prevent programs started in the boot sequence after
396 chronyd from reading the clock before it has been stepped.
397
398 refclock driver parameter[:option,...] [option]...
399 The refclock directive specifies a hardware reference clock to be
400 used as a time source. It has two mandatory parameters, a driver
401 name and a driver-specific parameter. The two parameters are
402 followed by zero or more refclock options. Some drivers have
403 special options, which can be appended to the driver-specific
404 parameter (separated by the : and , characters).
405
406 There are four drivers included in chronyd:
407
408 PPS
409 Driver for the kernel PPS (pulse per second) API. The parameter
410 is the path to the PPS device (typically /dev/pps?). As PPS
411 refclocks do not supply full time, another time source (e.g.
412 NTP server or non-PPS refclock) is needed to complete samples
413 from the PPS refclock. An alternative is to enable the local
414 directive to allow synchronisation with some unknown but
415 constant offset. The driver supports the following option:
416
417 clear
418 By default, the PPS refclock uses assert events (rising
419 edge) for synchronisation. With this option, it will use
420 clear events (falling edge) instead.
421
422
423 Examples:
424
425 refclock PPS /dev/pps0 lock NMEA refid GPS
426 refclock SHM 0 offset 0.5 delay 0.2 refid NMEA noselect
427 refclock PPS /dev/pps1:clear refid GPS2
428
429 SHM
430 NTP shared memory driver. This driver uses a shared memory
431 segment to receive samples from another process (e.g. gpsd).
432 The parameter is the number of the shared memory segment,
433 typically a small number like 0, 1, 2, or 3. The driver
434 supports the following option:
435
436 perm=mode
437 This option specifies the permissions of the shared memory
438 segment created by chronyd. They are specified as a numeric
439 mode. The default value is 0600 (read-write access for
440 owner only).
441
442
443
444 Examples:
445
446 refclock SHM 0 poll 3 refid GPS1
447 refclock SHM 1:perm=0644 refid GPS2
448
449 SOCK
450 Unix domain socket driver. It is similar to the SHM driver, but
451 samples are received from a Unix domain socket instead of
452 shared memory and the messages have a different format. The
453 parameter is the path to the socket, which chronyd creates on
454 start. An advantage over the SHM driver is that SOCK does not
455 require polling and it can receive PPS samples with incomplete
456 time. The format of the messages is described in the
457 refclock_sock.c file in the chrony source code.
458
459 An application which supports the SOCK protocol is the gpsd
460 daemon. The path where gpsd expects the socket to be created is
461 described in the gpsd(8) man page. For example:
462
463 refclock SOCK /var/run/chrony.ttyS0.sock
464
465 PHC
466 PTP hardware clock (PHC) driver. The parameter is the path to
467 the device of the PTP clock which should be used as a time
468 source. If the clock is kept in TAI instead of UTC (e.g. it is
469 synchronised by a PTP daemon), the current UTC-TAI offset needs
470 to be specified by the offset option. Alternatively, the pps
471 refclock option can be enabled to treat the PHC as a PPS
472 refclock, using only the sub-second offset for synchronisation.
473 The driver supports the following options:
474
475 nocrossts
476 This option disables use of precise cross timestamping.
477
478 extpps
479 This option enables a PPS mode in which the PTP clock is
480 timestamping pulses of an external PPS signal connected to
481 the clock. The clock does not need to be synchronised, but
482 another time source is needed to complete the PPS samples.
483 Note that some PTP clocks cannot be configured to timestamp
484 only assert or clear events, and it is necessary to use the
485 width option to filter wrong PPS samples.
486
487 pin=index
488 This option specifies the index of the pin to which is
489 connected the PPS signal. The default value is 0.
490
491 channel=index
492 This option specifies the index of the channel for the PPS
493 mode. The default value is 0.
494
495 clear
496 This option enables timestamping of clear events (falling
497 edge) instead of assert events (rising edge) in the PPS
498 mode. This may not work with some clocks.
499
500
501
502 Examples:
503
504 refclock PHC /dev/ptp0 poll 0 dpoll -2 offset -37
505 refclock PHC /dev/ptp1:nocrossts poll 3 pps
506 refclock PHC /dev/ptp2:extpps,pin=1 width 0.2 poll 2
507
508
509 The refclock directive supports the following options:
510
511 poll poll
512 Timestamps produced by refclock drivers are not used
513 immediately, but they are stored and processed by a median
514 filter in the polling interval specified by this option. This
515 is defined as a power of 2 and can be negative to specify a
516 sub-second interval. The default is 4 (16 seconds). A shorter
517 interval allows chronyd to react faster to changes in the
518 frequency of the system clock, but it might have a negative
519 effect on its accuracy if the samples have a lot of jitter.
520
521 dpoll dpoll
522 Some drivers do not listen for external events and try to
523 produce samples in their own polling interval. This is defined
524 as a power of 2 and can be negative to specify a sub-second
525 interval. The default is 0 (1 second).
526
527 refid refid
528 This option is used to specify the reference ID of the
529 refclock, as up to four ASCII characters. The default reference
530 ID is composed from the first three characters of the driver
531 name and the number of the refclock. Each refclock must have a
532 unique reference ID.
533
534 lock refid
535 This option can be used to lock a PPS refclock to another
536 refclock, which is specified by its reference ID. In this mode
537 received PPS samples are paired directly with raw samples from
538 the specified refclock.
539
540 rate rate
541 This option sets the rate of the pulses in the PPS signal (in
542 Hz). This option controls how the pulses will be completed with
543 real time. To actually receive more than one pulse per second,
544 a negative dpoll has to be specified (-3 for a 5Hz signal). The
545 default is 1.
546
547 maxlockage pulses
548 This option specifies in number of pulses how old can be
549 samples from the refclock specified by the lock option to be
550 paired with the pulses. Increasing this value is useful when
551 the samples are produced at a lower rate than the pulses. The
552 default is 2.
553
554 width width
555 This option specifies the width of the pulses (in seconds). It
556 is used to filter PPS samples when the driver provides samples
557 for both rising and falling edges. Note that it reduces the
558 maximum allowed error of the time source which completes the
559 PPS samples. If the duty cycle is configurable, 50% should be
560 preferred in order to maximise the allowed error.
561
562 pps
563 This options forces chronyd to treat any refclock (e.g. SHM or
564 PHC) as a PPS refclock. This can be useful when the refclock
565 provides time with a variable offset of a whole number of
566 seconds (e.g. it uses TAI instead of UTC). Another time source
567 is needed to complete samples from the refclock.
568
569 offset offset
570 This option can be used to compensate for a constant error. The
571 specified offset (in seconds) is applied to all samples
572 produced by the reference clock. The default is 0.0.
573
574 delay delay
575 This option sets the NTP delay of the source (in seconds). Half
576 of this value is included in the maximum assumed error which is
577 used in the source selection algorithm. Increasing the delay is
578 useful to avoid having no majority in the source selection or
579 to make it prefer other sources. The default is 1e-9 (1
580 nanosecond).
581
582 precision precision
583 This option sets the precision of the reference clock (in
584 seconds). The default value is the estimated precision of the
585 system clock.
586
587 maxdispersion dispersion
588 Maximum allowed dispersion for filtered samples (in seconds).
589 Samples with larger estimated dispersion are ignored. By
590 default, this limit is disabled.
591
592 filter samples
593 This option sets the length of the median filter which is used
594 to reduce the noise in the measurements. With each poll about
595 40 percent of the stored samples are discarded and one final
596 sample is calculated as an average of the remaining samples. If
597 the length is 4 or more, at least 4 samples have to be
598 collected between polls. For lengths below 4, the filter has to
599 be full. The default is 64.
600
601 prefer
602 Prefer this source over sources without the prefer option.
603
604 noselect
605 Never select this source. This is useful for monitoring or with
606 sources which are not very accurate, but are locked with a PPS
607 refclock.
608
609 trust
610 Assume time from this source is always true. It can be rejected
611 as a falseticker in the source selection only if another source
612 with this option does not agree with it.
613
614 require
615 Require that at least one of the sources specified with this
616 option is selectable (i.e. recently reachable and not a
617 falseticker) before updating the clock. Together with the trust
618 option this can be useful to allow a trusted, but not very
619 precise, reference clock to be safely combined with
620 unauthenticated NTP sources in order to improve the accuracy of
621 the clock. They can be selected and used for synchronisation
622 only if they agree with the trusted and required source.
623
624 minsamples samples
625 Set the minimum number of samples kept for this source. This
626 overrides the minsamples directive.
627
628 maxsamples samples
629 Set the maximum number of samples kept for this source. This
630 overrides the maxsamples directive.
631
632 manual
633 The manual directive enables support at run-time for the settime
634 command in chronyc. If no manual directive is included, any attempt
635 to use the settime command in chronyc will be met with an error
636 message.
637
638 Note that the settime command can be enabled at run-time using the
639 manual command in chronyc. (The idea of the two commands is that
640 the manual command controls the manual clock driver’s behaviour,
641 whereas the settime command allows samples of manually entered time
642 to be provided.)
643
644 acquisitionport port
645 By default, chronyd uses a separate client socket for each
646 configured server and their source port is chosen arbitrarily by
647 the operating system. However, you can use the acquisitionport
648 directive to explicitly specify a port and use only one socket (per
649 IPv4 or IPv6 address family) for all configured servers. This can
650 be useful for getting through some firewalls. If set to 0, the
651 source port of the socket will be chosen arbitrarily.
652
653 It can be set to the same port as is used by the NTP server (which
654 can be configured with the port directive) to use only one socket
655 for all NTP packets.
656
657 An example of the acquisitionport directive is:
658
659 acquisitionport 1123
660
661 This would change the source port used for client requests to UDP
662 port 1123. You could then persuade the firewall administrator to
663 open that port.
664
665 bindacqaddress address
666 The bindacqaddress directive sets the network interface to which
667 chronyd will bind its NTP client sockets. The syntax is similar to
668 the bindaddress and bindcmdaddress directives.
669
670 For each of the IPv4 and IPv6 protocols, only one bindacqaddress
671 directive can be specified.
672
673 dumpdir directory
674 To compute the rate of gain or loss of time, chronyd has to store a
675 measurement history for each of the time sources it uses.
676
677 All supported systems, with the exception of macOS 10.12 and
678 earlier, have operating system support for setting the rate of gain
679 or loss to compensate for known errors. (On macOS 10.12 and
680 earlier, chronyd must simulate such a capability by periodically
681 slewing the system clock forwards or backwards by a suitable amount
682 to compensate for the error built up since the previous slew.)
683
684 For such systems, it is possible to save the measurement history
685 across restarts of chronyd (assuming no changes are made to the
686 system clock behaviour whilst it is not running). The dumpdir
687 directive defines the directory where the measurement histories are
688 saved when chronyd exits, or the dump command in chronyc is issued.
689
690 An example of the directive is:
691
692 dumpdir /var/run/chrony
693
694 A source whose IP address is 1.2.3.4 would have its measurement
695 history saved in the file /var/run/chrony/1.2.3.4.dat. History of
696 reference clocks is saved to files named by their reference ID in
697 form of refid:XXXXXXXX.dat.
698
699 maxsamples samples
700 The maxsamples directive sets the default maximum number of samples
701 that chronyd should keep for each source. This setting can be
702 overridden for individual sources in the server and refclock
703 directives. The default value is 0, which disables the configurable
704 limit. The useful range is 4 to 64.
705
706 minsamples samples
707 The minsamples directive sets the default minimum number of samples
708 that chronyd should keep for each source. This setting can be
709 overridden for individual sources in the server and refclock
710 directives. The default value is 6. The useful range is 4 to 64.
711
712 Source selection
713 combinelimit limit
714 When chronyd has multiple sources available for synchronisation, it
715 has to select one source as the synchronisation source. The
716 measured offsets and frequencies of the system clock relative to
717 the other sources, however, can be combined with the selected
718 source to improve the accuracy of the system clock.
719
720 The combinelimit directive limits which sources are included in the
721 combining algorithm. Their synchronisation distance has to be
722 shorter than the distance of the selected source multiplied by the
723 value of the limit. Also, their measured frequencies have to be
724 close to the frequency of the selected source.
725
726 By default, the limit is 3. Setting the limit to 0 effectively
727 disables the source combining algorithm and only the selected
728 source will be used to control the system clock.
729
730 maxdistance distance
731 The maxdistance directive sets the maximum allowed root distance of
732 the sources to not be rejected by the source selection algorithm.
733 The distance includes the accumulated dispersion, which might be
734 large when the source is no longer synchronised, and half of the
735 total round-trip delay to the primary source.
736
737 By default, the maximum root distance is 3 seconds.
738
739 Setting maxdistance to a larger value can be useful to allow
740 synchronisation with a server that only has a very infrequent
741 connection to its sources and can accumulate a large dispersion
742 between updates of its clock.
743
744 maxjitter jitter
745 The maxjitter directive sets the maximum allowed jitter of the
746 sources to not be rejected by the source selection algorithm. This
747 prevents synchronisation with sources that have a small root
748 distance, but their time is too variable.
749
750 By default, the maximum jitter is 1 second.
751
752 minsources sources
753 The minsources directive sets the minimum number of sources that
754 need to be considered as selectable in the source selection
755 algorithm before the local clock is updated. The default value is
756 1.
757
758 Setting this option to a larger number can be used to improve the
759 reliability. More sources will have to agree with each other and
760 the clock will not be updated when only one source (which could be
761 serving incorrect time) is reachable.
762
763 reselectdist distance
764 When chronyd selects a synchronisation source from available
765 sources, it will prefer the one with the shortest synchronisation
766 distance. However, to avoid frequent reselecting when there are
767 sources with similar distance, a fixed distance is added to the
768 distance for sources that are currently not selected. This can be
769 set with the reselectdist directive. By default, the distance is
770 100 microseconds.
771
772 stratumweight distance
773 The stratumweight directive sets how much distance should be added
774 per stratum to the synchronisation distance when chronyd selects
775 the synchronisation source from available sources.
776
777 By default, the weight is 0.001 seconds. This means that the
778 stratum of the sources in the selection process matters only when
779 the differences between the distances are in milliseconds.
780
781 System clock
782 corrtimeratio ratio
783 When chronyd is slewing the system clock to correct an offset, the
784 rate at which it is slewing adds to the frequency error of the
785 clock. On all supported systems, with the exception of macOS 12 and
786 earlier, this rate can be controlled.
787
788 The corrtimeratio directive sets the ratio between the duration in
789 which the clock is slewed for an average correction according to
790 the source history and the interval in which the corrections are
791 done (usually the NTP polling interval). Corrections larger than
792 the average take less time and smaller corrections take more time,
793 the amount of the correction and the correction time are inversely
794 proportional.
795
796 Increasing corrtimeratio improves the overall frequency error of
797 the system clock, but increases the overall time error as the
798 corrections take longer.
799
800 By default, the ratio is set to 3, the time accuracy of the clock
801 is preferred over its frequency accuracy.
802
803 The maximum allowed slew rate can be set by the maxslewrate
804 directive. The current remaining correction is shown in the
805 tracking report as the System time value.
806
807 driftfile file
808 One of the main activities of the chronyd program is to work out
809 the rate at which the system clock gains or loses time relative to
810 real time.
811
812 Whenever chronyd computes a new value of the gain or loss rate, it
813 is desirable to record it somewhere. This allows chronyd to begin
814 compensating the system clock at that rate whenever it is
815 restarted, even before it has had a chance to obtain an equally
816 good estimate of the rate during the new run. (This process can
817 take many minutes, at least.)
818
819 The driftfile directive allows a file to be specified into which
820 chronyd can store the rate information. Two parameters are recorded
821 in the file. The first is the rate at which the system clock gains
822 or loses time, expressed in parts per million, with gains positive.
823 Therefore, a value of 100.0 indicates that when the system clock
824 has advanced by a second, it has gained 100 microseconds in reality
825 (so the true time has only advanced by 999900 microseconds). The
826 second is an estimate of the error bound around the first value in
827 which the true rate actually lies.
828
829 An example of the driftfile directive is:
830
831 driftfile /var/lib/chrony/drift
832
833 fallbackdrift min-interval max-interval
834 Fallback drifts are long-term averages of the system clock drift
835 calculated over exponentially increasing intervals. They are used
836 when the clock is no longer synchronised to avoid quickly drifting
837 away from true time if there was a short-term deviation in the
838 drift before the synchronisation was lost.
839
840 The directive specifies the minimum and maximum interval since the
841 last clock update to switch between fallback drifts. They are
842 defined as a power of 2 (in seconds). The syntax is as follows:
843
844 fallbackdrift 16 19
845
846 In this example, the minimum interval is 16 (18 hours) and the
847 maximum interval is 19 (6 days). The system clock frequency will be
848 set to the first fallback 18 hours after last clock update, to the
849 second after 36 hours, etc. This might be a good setting to cover
850 daily and weekly temperature fluctuations.
851
852 By default (or if the specified maximum or minimum is 0), no
853 fallbacks are used and the clock frequency changes only with new
854 measurements from NTP sources, reference clocks, or manual input.
855
856 leapsecmode mode
857 A leap second is an adjustment that is occasionally applied to UTC
858 to keep it close to the mean solar time. When a leap second is
859 inserted, the last day of June or December has an extra second
860 23:59:60.
861
862 For computer clocks that is a problem. The Unix time is defined as
863 number of seconds since 00:00:00 UTC on 1 January 1970 without leap
864 seconds. The system clock cannot have time 23:59:60, every minute
865 has 60 seconds and every day has 86400 seconds by definition. The
866 inserted leap second is skipped and the clock is suddenly ahead of
867 UTC by one second. The leapsecmode directive selects how that error
868 is corrected. There are four options:
869
870 system
871 When inserting a leap second, the kernel steps the system clock
872 backwards by one second when the clock gets to 00:00:00 UTC.
873 When deleting a leap second, it steps forward by one second
874 when the clock gets to 23:59:59 UTC. This is the default mode
875 when the system driver supports leap seconds (i.e. all
876 supported systems with the exception of macOS 12 and earlier).
877
878 step
879 This is similar to the system mode, except the clock is stepped
880 by chronyd instead of the kernel. It can be useful to avoid
881 bugs in the kernel code that would be executed in the system
882 mode. This is the default mode when the system driver does not
883 support leap seconds.
884
885 slew
886 The clock is corrected by slewing started at 00:00:00 UTC when
887 a leap second is inserted or 23:59:59 UTC when a leap second is
888 deleted. This might be preferred over the system and step modes
889 when applications running on the system are sensitive to jumps
890 in the system time and it is acceptable that the clock will be
891 off for a longer time. On Linux with the default maxslewrate
892 value the correction takes 12 seconds.
893
894 ignore
895 No correction is applied to the clock for the leap second. The
896 clock will be corrected later in normal operation when new
897 measurements are made and the estimated offset includes the one
898 second error.
899
900
901
902 When serving time to NTP clients that cannot be configured to
903 correct their clocks for a leap second by slewing, or to clients
904 that would correct at slightly different rates when it is necessary
905 to keep them close together, the slew mode can be combined with the
906 smoothtime directive to enable a server leap smear.
907
908 When smearing a leap second, the leap status is suppressed on the
909 server and the served time is corrected slowly be slewing instead
910 of stepping. The clients do not need any special configuration as
911 they do not know there is any leap second and they follow the
912 server time which eventually brings them back to UTC. Care must be
913 taken to ensure they use only NTP servers which smear the leap
914 second in exactly the same way for synchronisation.
915
916 This feature must be used carefully, because the server is
917 intentionally not serving its best estimate of the true time.
918
919 A recommended configuration to enable a server leap smear is:
920
921 leapsecmode slew
922 maxslewrate 1000
923 smoothtime 400 0.001 leaponly
924
925 The first directive is necessary to disable the clock step which
926 would reset the smoothing process. The second directive limits the
927 slewing rate of the local clock to 1000 ppm, which improves the
928 stability of the smoothing process when the local correction starts
929 and ends. The third directive enables the server time smoothing
930 process. It will start when the clock gets to 00:00:00 UTC and it
931 will take 17 hours 34 minutes to finish. The frequency offset will
932 be changing by 0.001 ppm per second and will reach a maximum of
933 31.623 ppm. The leaponly option makes the duration of the leap
934 smear constant and allows the clients to safely synchronise with
935 multiple identically configured leap smearing servers.
936
937 leapsectz timezone
938 This directive specifies a timezone in the system tz database which
939 chronyd can use to determine when will the next leap second occur
940 and what is the current offset between TAI and UTC. It will
941 periodically check if 23:59:59 and 23:59:60 are valid times in the
942 timezone. This typically works with the right/UTC timezone.
943
944 When a leap second is announced, the timezone needs to be updated
945 at least 12 hours before the leap second. It is not necessary to
946 restart chronyd.
947
948 This directive is useful with reference clocks and other time
949 sources which do not announce leap seconds, or announce them too
950 late for an NTP server to forward them to its own clients. Clients
951 of leap smearing servers must not use this directive.
952
953 It is also useful when the system clock is required to have correct
954 TAI-UTC offset. Note that the offset is set only when leap seconds
955 are handled by the kernel, i.e. leapsecmode is set to system.
956
957 An example of the directive is:
958
959 leapsectz right/UTC
960
961 The following shell command verifies that the timezone contains
962 leap seconds and can be used with this directive:
963
964 $ TZ=right/UTC date -d 'Dec 31 2008 23:59:60'
965 Wed Dec 31 23:59:60 UTC 2008
966
967 makestep threshold limit
968 Normally chronyd will cause the system to gradually correct any
969 time offset, by slowing down or speeding up the clock as required.
970 In certain situations, the system clock might be so far adrift that
971 this slewing process would take a very long time to correct the
972 system clock.
973
974 This directive forces chronyd to step the system clock if the
975 adjustment is larger than a threshold value, but only if there were
976 no more clock updates since chronyd was started than a specified
977 limit (a negative value can be used to disable the limit).
978
979 This is particularly useful when using reference clocks, because
980 the initstepslew directive works only with NTP sources.
981
982 An example of the use of this directive is:
983
984 makestep 0.1 3
985
986 This would step the system clock if the adjustment is larger than
987 0.1 seconds, but only in the first three clock updates.
988
989 maxchange offset start ignore
990 This directive sets the maximum allowed offset corrected on a clock
991 update. The check is performed only after the specified number of
992 updates to allow a large initial adjustment of the system clock.
993 When an offset larger than the specified maximum occurs, it will be
994 ignored for the specified number of times and then chronyd will
995 give up and exit (a negative value can be used to never exit). In
996 both cases a message is sent to syslog.
997
998 An example of the use of this directive is:
999
1000 maxchange 1000 1 2
1001
1002 After the first clock update, chronyd will check the offset on
1003 every clock update, it will ignore two adjustments larger than 1000
1004 seconds and exit on another one.
1005
1006 maxclockerror error-in-ppm
1007 The maxclockerror directive sets the maximum assumed frequency
1008 error that the system clock can gain on its own between clock
1009 updates. It describes the stability of the clock.
1010
1011 By default, the maximum error is 1 ppm.
1012
1013 Typical values for error-in-ppm might be 10 for a low quality clock
1014 and 0.1 for a high quality clock using a temperature compensated
1015 crystal oscillator.
1016
1017 maxdrift drift-in-ppm
1018 This directive specifies the maximum assumed drift (frequency
1019 error) of the system clock. It limits the frequency adjustment that
1020 chronyd is allowed to use to correct the measured drift. It is an
1021 additional limit to the maximum adjustment that can be set by the
1022 system driver (100000 ppm on Linux, 500 ppm on FreeBSD, NetBSD, and
1023 macOS 10.13+, 32500 ppm on Solaris).
1024
1025 By default, the maximum assumed drift is 500000 ppm, i.e. the
1026 adjustment is limited by the system driver rather than this
1027 directive.
1028
1029 maxupdateskew skew-in-ppm
1030 One of chronyd’s tasks is to work out how fast or slow the
1031 computer’s clock runs relative to its reference sources. In
1032 addition, it computes an estimate of the error bounds around the
1033 estimated value.
1034
1035 If the range of error is too large, it probably indicates that the
1036 measurements have not settled down yet, and that the estimated gain
1037 or loss rate is not very reliable.
1038
1039 The maxupdateskew directive sets the threshold for determining
1040 whether an estimate might be so unreliable that it should not be
1041 used. By default, the threshold is 1000 ppm.
1042
1043 Typical values for skew-in-ppm might be 100 for a dial-up
1044 connection to servers over a phone line, and 5 or 10 for a computer
1045 on a LAN.
1046
1047 It should be noted that this is not the only means of protection
1048 against using unreliable estimates. At all times, chronyd keeps
1049 track of both the estimated gain or loss rate, and the error bound
1050 on the estimate. When a new estimate is generated following another
1051 measurement from one of the sources, a weighted combination
1052 algorithm is used to update the master estimate. So if chronyd has
1053 an existing highly-reliable master estimate and a new estimate is
1054 generated which has large error bounds, the existing master
1055 estimate will dominate in the new master estimate.
1056
1057 maxslewrate rate-in-ppm
1058 The maxslewrate directive sets the maximum rate at which chronyd is
1059 allowed to slew the time. It limits the slew rate controlled by the
1060 correction time ratio (which can be set by the corrtimeratio
1061 directive) and is effective only on systems where chronyd is able
1062 to control the rate (i.e. all supported systems with the exception
1063 of macOS 12 or earlier).
1064
1065 For each system there is a maximum frequency offset of the clock
1066 that can be set by the driver. On Linux it is 100000 ppm, on
1067 FreeBSD, NetBSD and macOS 10.13+ it is 5000 ppm, and on Solaris it
1068 is 32500 ppm. Also, due to a kernel limitation, setting maxslewrate
1069 on FreeBSD, NetBSD, macOS 10.13+ to a value between 500 ppm and
1070 5000 ppm will effectively set it to 500 ppm.
1071
1072 In early beta releases of macOS 13 this capability is disabled
1073 because of a system kernel bug. When the kernel bug is fixed,
1074 chronyd will detect this and re-enable the capability (see above
1075 limitations) with no recompilation required.
1076
1077 By default, the maximum slew rate is set to 83333.333 ppm (one
1078 twelfth).
1079
1080 tempcomp file interval T0 k0 k1 k2, tempcomp file interval points-file
1081 Normally, changes in the rate of drift of the system clock are
1082 caused mainly by changes in the temperature of the crystal
1083 oscillator on the motherboard.
1084
1085 If there are temperature measurements available from a sensor close
1086 to the oscillator, the tempcomp directive can be used to compensate
1087 for the changes in the temperature and improve the stability and
1088 accuracy of the clock.
1089
1090 The result depends on many factors, including the resolution of the
1091 sensor, the amount of noise in the measurements, the polling
1092 interval of the time source, the compensation update interval, how
1093 well the compensation is specified, and how close the sensor is to
1094 the oscillator. When it is working well, the frequency reported in
1095 the tracking.log file is more stable and the maximum reached offset
1096 is smaller.
1097
1098 There are two forms of the directive. The first one has six
1099 parameters: a path to the file containing the current temperature
1100 from the sensor (in text format), the compensation update interval
1101 (in seconds), and temperature coefficients T0, k0, k1, k2.
1102
1103 The frequency compensation is calculated (in ppm) as
1104
1105 k0 + (T - T0) * k1 + (T - T0)^2 * k2
1106
1107 The result has to be between -10 ppm and 10 ppm, otherwise the
1108 measurement is considered invalid and will be ignored. The k0
1109 coefficient can be adjusted to keep the compensation in that range.
1110
1111 An example of the use is:
1112
1113 tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 26000 0.0 0.000183 0.0
1114
1115 The measured temperature will be read from the file in the Linux
1116 sysfs filesystem every 30 seconds. When the temperature is 26000
1117 (26 degrees Celsius), the frequency correction will be zero. When
1118 it is 27000 (27 degrees Celsius), the clock will be set to run
1119 faster by 0.183 ppm, etc.
1120
1121 The second form has three parameters: the path to the sensor file,
1122 the update interval, and a path to a file containing a list of
1123 (temperature, compensation) points, from which the compensation is
1124 linearly interpolated or extrapolated.
1125
1126 An example is:
1127
1128 tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 /etc/chrony.tempcomp
1129
1130 where the /etc/chrony.tempcomp file could have
1131
1132 20000 1.0
1133 21000 0.64
1134 22000 0.36
1135 23000 0.16
1136 24000 0.04
1137 25000 0.0
1138 26000 0.04
1139 27000 0.16
1140 28000 0.36
1141 29000 0.64
1142 30000 1.0
1143
1144 Valid measurements with corresponding compensations are logged to
1145 the tempcomp.log file if enabled by the log tempcomp directive.
1146
1147 NTP server
1148 allow [all] [subnet]
1149 The allow directive is used to designate a particular subnet from
1150 which NTP clients are allowed to access the computer as an NTP
1151 server.
1152
1153 The default is that no clients are allowed access, i.e. chronyd
1154 operates purely as an NTP client. If the allow directive is used,
1155 chronyd will be both a client of its servers, and a server to other
1156 clients.
1157
1158 Examples of the use of the directive are as follows:
1159
1160 allow 1.2.3.4
1161 allow 1.2
1162 allow 3.4.5
1163 allow 6.7.8/22
1164 allow 6.7.8.9/22
1165 allow 2001:db8::/32
1166 allow 0/0
1167 allow ::/0
1168 allow
1169
1170 The first directive allows a node with IPv4 address 1.2.3.4 to be
1171 an NTP client of this computer. The second directive allows any
1172 node with an IPv4 address of the form 1.2.x.y (with x and y
1173 arbitrary) to be an NTP client of this computer. Likewise, the
1174 third directive allows any node with an IPv4 address of the form
1175 3.4.5.x to have client NTP access. The fourth and fifth forms allow
1176 access from any node with an IPv4 address of the form 6.7.8.x,
1177 6.7.9.x, 6.7.10.x or 6.7.11.x (with x arbitrary), i.e. the value 22
1178 is the number of bits defining the specified subnet. In the fifth
1179 form, the final byte is ignored. The sixth form is used for IPv6
1180 addresses. The seventh and eighth forms allow access by any IPv4
1181 and IPv6 node respectively. The ninth forms allows access by any
1182 node (IPv4 or IPv6).
1183
1184 A second form of the directive, allow all, has a greater effect,
1185 depending on the ordering of directives in the configuration file.
1186 To illustrate the effect, consider the two examples:
1187
1188 allow 1.2.3.4
1189 deny 1.2.3
1190 allow 1.2
1191
1192 and
1193
1194 allow 1.2.3.4
1195 deny 1.2.3
1196 allow all 1.2
1197
1198 In the first example, the effect is the same regardless of what
1199 order the three directives are given in. So the 1.2.x.y subnet is
1200 allowed access, except for the 1.2.3.x subnet, which is denied
1201 access, however the host 1.2.3.4 is allowed access.
1202
1203 In the second example, the allow all 1.2 directives overrides the
1204 effect of any previous directive relating to a subnet within the
1205 specified subnet. Within a configuration file this capability is
1206 probably rather moot; however, it is of greater use for
1207 reconfiguration at run-time via chronyc with the allow all command.
1208
1209 The directive allows a hostname to be specified instead of an IP
1210 address, but the name must be resolvable when chronyd is started
1211 (i.e. chronyd needs to be started when the network is already up
1212 and DNS is working).
1213
1214 Note, if the initstepslew directive is used in the configuration
1215 file, each of the computers listed in that directive must allow
1216 client access by this computer for it to work.
1217
1218 deny [all] [subnet]
1219 This is similar to the allow directive, except that it denies NTP
1220 client access to a particular subnet or host, rather than allowing
1221 it.
1222
1223 The syntax is identical.
1224
1225 There is also a deny all directive with similar behaviour to the
1226 allow all directive.
1227
1228 bindaddress address
1229 The bindaddress directive binds the socket on which chronyd listens
1230 for NTP requests to a local address of the computer. On systems
1231 other than Linux, the address of the computer needs to be already
1232 configured when chronyd is started.
1233
1234 An example of the use of the directive is:
1235
1236 bindaddress 192.168.1.1
1237
1238 Currently, for each of the IPv4 and IPv6 protocols, only one
1239 bindaddress directive can be specified. Therefore, it is not useful
1240 on computers which should serve NTP on multiple network interfaces.
1241
1242 broadcast interval address [port]
1243 The broadcast directive is used to declare a broadcast address to
1244 which chronyd should send packets in the NTP broadcast mode (i.e.
1245 make chronyd act as a broadcast server). Broadcast clients on that
1246 subnet will be able to synchronise.
1247
1248 The syntax is as follows:
1249
1250 broadcast 30 192.168.1.255
1251 broadcast 60 192.168.2.255 12123
1252 broadcast 60 ff02::101
1253
1254 In the first example, the destination port defaults to UDP port 123
1255 (the normal NTP port). In the second example, the destination port
1256 is specified as 12123. The first parameter in each case (30 or 60
1257 respectively) is the interval in seconds between broadcast packets
1258 being sent. The second parameter in each case is the broadcast
1259 address to send the packet to. This should correspond to the
1260 broadcast address of one of the network interfaces on the computer
1261 where chronyd is running.
1262
1263 You can have more than 1 broadcast directive if you have more than
1264 1 network interface onto which you want to send NTP broadcast
1265 packets.
1266
1267 chronyd itself cannot act as a broadcast client; it must always be
1268 configured as a point-to-point client by defining specific NTP
1269 servers and peers. This broadcast server feature is intended for
1270 providing a time source to other NTP implementations.
1271
1272 If ntpd is used as the broadcast client, it will try to measure the
1273 round-trip delay between the server and client with normal client
1274 mode packets. Thus, the broadcast subnet should also be the subject
1275 of an allow directive.
1276
1277 clientloglimit limit
1278 This directive specifies the maximum amount of memory that chronyd
1279 is allowed to allocate for logging of client accesses and the state
1280 that chronyd as an NTP server needs to support the interleaved mode
1281 for its clients. The default limit is 524288 bytes, which is
1282 sufficient for monitoring about four thousand clients at the same
1283 time.
1284
1285 In older chrony versions if the limit was set to 0, the memory
1286 allocation was unlimited.
1287
1288 An example of the use of this directive is:
1289
1290 clientloglimit 1048576
1291
1292 noclientlog
1293 This directive, which takes no arguments, specifies that client
1294 accesses are not to be logged. Normally they are logged, allowing
1295 statistics to be reported using the clients command in chronyc.
1296 This option also effectively disables server support for the NTP
1297 interleaved mode.
1298
1299 local [option]...
1300 The local directive enables a local reference mode, which allows
1301 chronyd operating as an NTP server to appear synchronised to real
1302 time (from the viewpoint of clients polling it), even when it was
1303 never synchronised or the last update of the clock happened a long
1304 time ago.
1305
1306 This directive is normally used in an isolated network, where
1307 computers are required to be synchronised to one another, but not
1308 necessarily to real time. The server can be kept vaguely in line
1309 with real time by manual input.
1310
1311 The local directive has the following options:
1312
1313 stratum stratum
1314 This option sets the stratum of the server which will be
1315 reported to clients when the local reference is active. The
1316 specified value is in the range 1 through 15, and the default
1317 value is 10. It should be larger than the maximum expected
1318 stratum in the network when external NTP servers are
1319 accessible.
1320
1321 Stratum 1 indicates a computer that has a true real-time
1322 reference directly connected to it (e.g. GPS, atomic clock,
1323 etc.), such computers are expected to be very close to real
1324 time. Stratum 2 computers are those which have a stratum 1
1325 server; stratum 3 computers have a stratum 2 server and so on.
1326 A value of 10 indicates that the clock is so many hops away
1327 from a reference clock that its time is fairly unreliable.
1328
1329 distance distance
1330 This option sets the threshold for the root distance which will
1331 activate the local reference. If chronyd was synchronised to
1332 some source, the local reference will not be activated until
1333 its root distance reaches the specified value (the rate at
1334 which the distance is increasing depends on how well the clock
1335 was tracking the source). The default value is 1 second.
1336
1337 The current root distance can be calculated from root delay and
1338 root dispersion (reported by the tracking command in chronyc)
1339 as:
1340
1341 distance = delay / 2 + dispersion
1342
1343 orphan
1344 This option enables a special ‘orphan’ mode, where sources with
1345 stratum equal to the local stratum are assumed to not serve
1346 real time. They are ignored unless no other source is
1347 selectable and their reference IDs are smaller than the local
1348 reference ID.
1349
1350 This allows multiple servers in the network to use the same
1351 local configuration and to be synchronised to one another,
1352 without confusing clients that poll more than one server. Each
1353 server needs to be configured to poll all other servers with
1354 the local directive. This ensures only the server with the
1355 smallest reference ID has the local reference active and others
1356 are synchronised to it. When that server fails, another will
1357 take over.
1358
1359 The orphan mode is compatible with the ntpd’s orphan mode
1360 (enabled by the tos orphan command).
1361
1362
1363
1364 An example of the directive is:
1365
1366 local stratum 10 orphan
1367
1368 ntpsigndsocket directory
1369 This directive specifies the location of the Samba ntp_signd socket
1370 when it is running as a Domain Controller (DC). If chronyd is
1371 compiled with this feature, responses to MS-SNTP clients will be
1372 signed by the smbd daemon.
1373
1374 Note that MS-SNTP requests are not authenticated and any client
1375 that is allowed to access the server by the allow directive, or the
1376 allow command in chronyc, can get an MS-SNTP response signed with a
1377 trust account’s password and try to crack the password in a
1378 brute-force attack. Access to the server should be carefully
1379 controlled.
1380
1381 An example of the directive is:
1382
1383 ntpsigndsocket /var/lib/samba/ntp_signd
1384
1385 port port
1386 This option allows you to configure the port on which chronyd will
1387 listen for NTP requests. The port will be open only when an address
1388 is allowed by the allow directive or the allow command in chronyc,
1389 an NTP peer is configured, or the broadcast server mode is enabled.
1390
1391 The default value is 123, the standard NTP port. If set to 0,
1392 chronyd will never open the server port and will operate strictly
1393 in a client-only mode. The source port used in NTP client requests
1394 can be set by the acquisitionport directive.
1395
1396 ratelimit [option]...
1397 This directive enables response rate limiting for NTP packets. Its
1398 purpose is to reduce network traffic with misconfigured or broken
1399 NTP clients that are polling the server too frequently. The limits
1400 are applied to individual IP addresses. If multiple clients share
1401 one IP address (e.g. multiple hosts behind NAT), the sum of their
1402 traffic will be limited. If a client that increases its polling
1403 rate when it does not receive a reply is detected, its rate
1404 limiting will be temporarily suspended to avoid increasing the
1405 overall amount of traffic. The maximum number of IP addresses which
1406 can be monitored at the same time depends on the memory limit set
1407 by the clientloglimit directive.
1408
1409 The ratelimit directive supports a number of options (which can be
1410 defined in any order):
1411
1412 interval
1413 This option sets the minimum interval between responses. It is
1414 defined as a power of 2 in seconds. The default value is 3 (8
1415 seconds). The minimum value is -19 (524288 packets per second)
1416 and the maximum value is 12 (one packet per 4096 seconds). Note
1417 that with values below -4 the rate limiting is coarse
1418 (responses are allowed in bursts, even if the interval between
1419 them is shorter than the specified interval).
1420
1421 burst
1422 This option sets the maximum number of responses that can be
1423 sent in a burst, temporarily exceeding the limit specified by
1424 the interval option. This is useful for clients that make rapid
1425 measurements on start (e.g. chronyd with the iburst option).
1426 The default value is 8. The minimum value is 1 and the maximum
1427 value is 255.
1428
1429 leak
1430 This option sets the rate at which responses are randomly
1431 allowed even if the limits specified by the interval and burst
1432 options are exceeded. This is necessary to prevent an attacker
1433 who is sending requests with a spoofed source address from
1434 completely blocking responses to that address. The leak rate is
1435 defined as a power of 1/2 and it is 2 by default, i.e. on
1436 average at least every fourth request has a response. The
1437 minimum value is 1 and the maximum value is 4.
1438
1439
1440
1441 An example use of the directive is:
1442
1443 ratelimit interval 1 burst 16
1444
1445 This would reduce the response rate for IP addresses sending
1446 packets on average more than once per 2 seconds, or sending packets
1447 in bursts of more than 16 packets, by up to 75% (with default leak
1448 of 2).
1449
1450 smoothtime max-freq max-wander [leaponly]
1451 The smoothtime directive can be used to enable smoothing of the
1452 time that chronyd serves to its clients to make it easier for them
1453 to track it and keep their clocks close together even when large
1454 offset or frequency corrections are applied to the server’s clock,
1455 for example after being offline for a longer time.
1456
1457 BE WARNED: The server is intentionally not serving its best
1458 estimate of the true time. If a large offset has been accumulated,
1459 it can take a very long time to smooth it out. This directive
1460 should be used only when the clients are not configured to also
1461 poll another NTP server, because they could reject this server as a
1462 falseticker or fail to select a source completely.
1463
1464 The smoothing process is implemented with a quadratic spline
1465 function with two or three pieces. It is independent from any
1466 slewing applied to the local system clock, but the accumulated
1467 offset and frequency will be reset when the clock is corrected by
1468 stepping, e.g. by the makestep directive or the makestep command in
1469 chronyc. The process can be reset without stepping the clock by the
1470 smoothtime reset command.
1471
1472 The first two arguments of the directive are the maximum frequency
1473 offset of the smoothed time to the tracked NTP time (in ppm) and
1474 the maximum rate at which the frequency offset is allowed to change
1475 (in ppm per second). leaponly is an optional third argument which
1476 enables a mode where only leap seconds are smoothed out and normal
1477 offset and frequency changes are ignored. The leaponly option is
1478 useful in a combination with the leapsecmode slew directive to
1479 allow the clients to use multiple time smoothing servers safely.
1480
1481 The smoothing process is activated automatically when 1/10000 of
1482 the estimated skew of the local clock falls below the maximum rate
1483 of frequency change. It can be also activated manually by the
1484 smoothtime activate command, which is particularly useful when the
1485 clock is synchronised only with manual input and the skew is always
1486 larger than the threshold. The smoothing command can be used to
1487 monitor the process.
1488
1489 An example suitable for clients using ntpd and 1024 second polling
1490 interval could be:
1491
1492 smoothtime 400 0.001
1493
1494 An example suitable for clients using chronyd on Linux could be:
1495
1496 smoothtime 50000 0.01
1497
1498 Command and monitoring access
1499 bindcmdaddress address
1500 The bindcmdaddress directive allows you to specify an IP address of
1501 an interface on which chronyd will listen for monitoring command
1502 packets (issued by chronyc). On systems other than Linux, the
1503 address of the interface needs to be already configured when
1504 chronyd is started.
1505
1506 This directive can also change the path of the Unix domain command
1507 socket, which is used by chronyc to send configuration commands.
1508 The socket must be in a directory that is accessible only by the
1509 root or chrony user. The directory will be created on start if it
1510 does not exist. The compiled-in default path of the socket is
1511 /var/run/chrony/chronyd.sock. The socket can be disabled by setting
1512 the path to /.
1513
1514 By default, chronyd binds to the loopback interface (with addresses
1515 127.0.0.1 and ::1). This blocks all access except from localhost.
1516 To listen for command packets on all interfaces, you can add the
1517 lines:
1518
1519 bindcmdaddress 0.0.0.0
1520 bindcmdaddress ::
1521
1522 to the configuration file.
1523
1524 For each of the IPv4, IPv6, and Unix domain protocols, only one
1525 bindcmdaddress directive can be specified.
1526
1527 An example that sets the path of the Unix domain command socket is:
1528
1529 bindcmdaddress /var/run/chrony/chronyd.sock
1530
1531 cmdallow [all] [subnet]
1532 This is similar to the allow directive, except that it allows
1533 monitoring access (rather than NTP client access) to a particular
1534 subnet or host. (By ‘monitoring access’ is meant that chronyc can
1535 be run on those hosts and retrieve monitoring data from chronyd on
1536 this computer.)
1537
1538 The syntax is identical to the allow directive.
1539
1540 There is also a cmdallow all directive with similar behaviour to
1541 the allow all directive (but applying to monitoring access in this
1542 case, of course).
1543
1544 Note that chronyd has to be configured with the bindcmdaddress
1545 directive to not listen only on the loopback interface to actually
1546 allow remote access.
1547
1548 cmddeny [all] [subnet]
1549 This is similar to the cmdallow directive, except that it denies
1550 monitoring access to a particular subnet or host, rather than
1551 allowing it.
1552
1553 The syntax is identical.
1554
1555 There is also a cmddeny all directive with similar behaviour to the
1556 cmdallow all directive.
1557
1558 cmdport port
1559 The cmdport directive allows the port that is used for run-time
1560 monitoring (via the chronyc program) to be altered from its default
1561 (323). If set to 0, chronyd will not open the port, this is useful
1562 to disable chronyc access from the Internet. (It does not disable
1563 the Unix domain command socket.)
1564
1565 An example shows the syntax:
1566
1567 cmdport 257
1568
1569 This would make chronyd use UDP 257 as its command port. (chronyc
1570 would need to be run with the -p 257 switch to inter-operate
1571 correctly.)
1572
1573 cmdratelimit [option]...
1574 This directive enables response rate limiting for command packets.
1575 It is similar to the ratelimit directive, except responses to
1576 localhost are never limited and the default interval is -4 (16
1577 packets per second).
1578
1579 An example of the use of the directive is:
1580
1581 cmdratelimit interval 2
1582
1583 Real-time clock (RTC)
1584 hwclockfile file
1585 The hwclockfile directive sets the location of the adjtime file
1586 which is used by the hwclock program on Linux. chronyd parses the
1587 file to find out if the RTC keeps local time or UTC. It overrides
1588 the rtconutc directive.
1589
1590 The compiled-in default value is '/etc/adjtime'.
1591
1592 An example of the directive is:
1593
1594 hwclockfile /etc/adjtime
1595
1596 rtcautotrim threshold
1597 The rtcautotrim directive is used to keep the RTC close to the
1598 system clock automatically. When the system clock is synchronised
1599 and the estimated error between the two clocks is larger than the
1600 specified threshold, chronyd will trim the RTC as if the trimrtc
1601 command in chronyc was issued.
1602
1603 This directive is effective only with the rtcfile directive.
1604
1605 An example of the use of this directive is:
1606
1607 rtcautotrim 30
1608
1609 This would set the threshold error to 30 seconds.
1610
1611 rtcdevice device
1612 The rtcdevice directive sets the path to the device file for
1613 accessing the RTC. The default path is /dev/rtc.
1614
1615 rtcfile file
1616 The rtcfile directive defines the name of the file in which chronyd
1617 can save parameters associated with tracking the accuracy of the
1618 RTC.
1619
1620 An example of the directive is:
1621
1622 rtcfile /var/lib/chrony/rtc
1623
1624 chronyd saves information in this file when it exits and when the
1625 writertc command is issued in chronyc. The information saved is the
1626 RTC’s error at some epoch, that epoch (in seconds since January 1
1627 1970), and the rate at which the RTC gains or loses time.
1628
1629 So far, the support for real-time clocks is limited; their code is
1630 even more system-specific than the rest of the software. You can
1631 only use the RTC facilities (the rtcfile directive and the -s
1632 command-line option to chronyd) if the following three conditions
1633 apply:
1634
1635 1. You are running Linux.
1636
1637 2. The kernel is compiled with extended real-time clock support
1638 (i.e. the /dev/rtc device is capable of doing useful things).
1639
1640 3. You do not have other applications that need to make use of
1641 /dev/rtc at all.
1642
1643 rtconutc
1644 chronyd assumes by default that the RTC keeps local time (including
1645 any daylight saving changes). This is convenient on PCs running
1646 Linux which are dual-booted with Windows.
1647
1648 If you keep the RTC on local time and your computer is off when
1649 daylight saving (summer time) starts or ends, the computer’s system
1650 time will be one hour in error when you next boot and start
1651 chronyd.
1652
1653 An alternative is for the RTC to keep Universal Coordinated Time
1654 (UTC). This does not suffer from the 1 hour problem when daylight
1655 saving starts or ends.
1656
1657 If the rtconutc directive appears, it means the RTC is required to
1658 keep UTC. The directive takes no arguments. It is equivalent to
1659 specifying the -u switch to the Linux hwclock program.
1660
1661 Note that this setting is overridden when the hwclockfile directive
1662 is specified.
1663
1664 rtcsync
1665 The rtcsync directive enables a mode where the system time is
1666 periodically copied to the RTC and chronyd does not try to track
1667 its drift. This directive cannot be used with the rtcfile
1668 directive.
1669
1670 On Linux, the RTC copy is performed by the kernel every 11 minutes.
1671
1672 On macOS, chronyd will perform the RTC copy every 60 minutes when
1673 the system clock is in a synchronised state.
1674
1675 On other systems this directive does nothing.
1676
1677 Logging
1678 log [option]...
1679 The log directive indicates that certain information is to be
1680 logged. The log files are written to the directory specified by the
1681 logdir directive. A banner is periodically written to the files to
1682 indicate the meanings of the columns.
1683
1684 rawmeasurements
1685 This option logs the raw NTP measurements and related
1686 information to a file called measurements.log. An entry is made
1687 for each packet received from the source. This can be useful
1688 when debugging a problem. An example line (which actually
1689 appears as a single line in the file) from the log file is
1690 shown below.
1691
1692 2016-11-09 05:40:50 203.0.113.15 N 2 111 111 1111 10 10 1.0 \
1693 -4.966e-03 2.296e-01 1.577e-05 1.615e-01 7.446e-03 CB00717B 4B D K
1694
1695 The columns are as follows (the quantities in square brackets
1696 are the values from the example line above):
1697
1698 1. Date [2015-10-13]
1699
1700 2. Hour:Minute:Second. Note that the date-time pair is
1701 expressed in UTC, not the local time zone. [05:40:50]
1702
1703 3. IP address of server or peer from which measurement came
1704 [203.0.113.15]
1705
1706 4. Leap status (N means normal, + means that the last minute
1707 of the current month has 61 seconds, - means that the last
1708 minute of the month has 59 seconds, ? means the remote
1709 computer is not currently synchronised.) [N]
1710
1711 5. Stratum of remote computer. [2]
1712
1713 6. RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111]
1714
1715 7. RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111]
1716
1717 8. Tests for maximum delay, maximum delay ratio and maximum
1718 delay dev ratio, against defined parameters, and a test for
1719 synchronisation loop (1=pass, 0=fail) [1111]
1720
1721 9. Local poll [10]
1722
1723 10. Remote poll [10]
1724
1725 11. ‘Score’ (an internal score within each polling level used
1726 to decide when to increase or decrease the polling level.
1727 This is adjusted based on number of measurements currently
1728 being used for the regression algorithm). [1.0]
1729
1730 12. The estimated local clock error (theta in RFC 5905).
1731 Positive indicates that the local clock is slow of the
1732 remote source. [-4.966e-03]
1733
1734 13. The peer delay (delta in RFC 5905). [2.296e-01]
1735
1736 14. The peer dispersion (epsilon in RFC 5905). [1.577e-05]
1737
1738 15. The root delay (DELTA in RFC 5905). [1.615e-01]
1739
1740 16. The root dispersion (EPSILON in RFC 5905). [7.446e-03]
1741
1742 17. Reference ID of the server’s source as a hexadecimal
1743 number. [CB00717B]
1744
1745 18. NTP mode of the received packet (1=active peer, 2=passive
1746 peer, 4=server, B=basic, I=interleaved). [4B]
1747
1748 19. Source of the local transmit timestamp (D=daemon,
1749 K=kernel, H=hardware). [D]
1750
1751 20. Source of the local receive timestamp (D=daemon, K=kernel,
1752 H=hardware). [K]
1753
1754 measurements
1755 This option is identical to the rawmeasurements option, except
1756 it logs only valid measurements from synchronised sources, i.e.
1757 measurements which passed the RFC 5905 tests 1 through 7. This
1758 can be useful for producing graphs of the source’s performance.
1759
1760 statistics
1761 This option logs information about the regression processing to
1762 a file called statistics.log. An example line (which actually
1763 appears as a single line in the file) from the log file is
1764 shown below.
1765
1766 2016-08-10 05:40:50 203.0.113.15 6.261e-03 -3.247e-03 \
1767 2.220e-03 1.874e-06 1.080e-06 7.8e-02 16 0 8 0.00
1768
1769 The columns are as follows (the quantities in square brackets
1770 are the values from the example line above):
1771
1772 1. Date [2015-07-22]
1773
1774 2. Hour:Minute:Second. Note that the date-time pair is
1775 expressed in UTC, not the local time zone. [05:40:50]
1776
1777 3. IP address of server or peer from which measurement comes
1778 [203.0.113.15]
1779
1780 4. The estimated standard deviation of the measurements from
1781 the source (in seconds). [6.261e-03]
1782
1783 5. The estimated offset of the source (in seconds, positive
1784 means the local clock is estimated to be fast, in this
1785 case). [-3.247e-03]
1786
1787 6. The estimated standard deviation of the offset estimate (in
1788 seconds). [2.220e-03]
1789
1790 7. The estimated rate at which the local clock is gaining or
1791 losing time relative to the source (in seconds per second,
1792 positive means the local clock is gaining). This is
1793 relative to the compensation currently being applied to the
1794 local clock, not to the local clock without any
1795 compensation. [1.874e-06]
1796
1797 8. The estimated error in the rate value (in seconds per
1798 second). [1.080e-06].
1799
1800 9. The ratio of |old_rate - new_rate| / old_rate_error. Large
1801 values indicate the statistics are not modelling the source
1802 very well. [7.8e-02]
1803
1804 10. The number of measurements currently being used for the
1805 regression algorithm. [16]
1806
1807 11. The new starting index (the oldest sample has index 0;
1808 this is the method used to prune old samples when it no
1809 longer looks like the measurements fit a linear model). [0,
1810 i.e. no samples discarded this time]
1811
1812 12. The number of runs. The number of runs of regression
1813 residuals with the same sign is computed. If this is too
1814 small it indicates that the measurements are no longer
1815 represented well by a linear model and that some older
1816 samples need to be discarded. The number of runs for the
1817 data that is being retained is tabulated. Values of
1818 approximately half the number of samples are expected. [8]
1819
1820 13. The estimated or configured asymmetry of network jitter on
1821 the path to the source which was used to correct the
1822 measured offsets. The asymmetry can be between -0.5 and
1823 +0.5. A negative value means the delay of packets sent to
1824 the source is more variable than the delay of packets sent
1825 from the source back. [0.00, i.e. no correction for
1826 asymmetry]
1827
1828 tracking
1829 This option logs changes to the estimate of the system’s gain
1830 or loss rate, and any slews made, to a file called
1831 tracking.log. An example line (which actually appears as a
1832 single line in the file) from the log file is shown below.
1833
1834 2017-08-22 13:22:36 203.0.113.15 2 -3.541 0.075 -8.621e-06 N \
1835 2 2.940e-03 -2.084e-04 1.534e-02 3.472e-04 8.304e-03
1836
1837 The columns are as follows (the quantities in square brackets
1838 are the values from the example line above) :
1839
1840 1. Date [2017-08-22]
1841
1842 2. Hour:Minute:Second. Note that the date-time pair is
1843 expressed in UTC, not the local time zone. [13:22:36]
1844
1845 3. The IP address of the server or peer to which the local
1846 system is synchronised. [203.0.113.15]
1847
1848 4. The stratum of the local system. [2]
1849
1850 5. The local system frequency (in ppm, positive means the
1851 local system runs fast of UTC). [-3.541]
1852
1853 6. The error bounds on the frequency (in ppm). [0.075]
1854
1855 7. The estimated local offset at the epoch, which is normally
1856 corrected by slewing the local clock (in seconds, positive
1857 indicates the clock is fast of UTC). [-8.621e-06]
1858
1859 8. Leap status (N means normal, + means that the last minute
1860 of this month has 61 seconds, - means that the last minute
1861 of the month has 59 seconds, ? means the clock is not
1862 currently synchronised.) [N]
1863
1864 9. The number of combined sources. [2]
1865
1866 10. The estimated standard deviation of the combined offset
1867 (in seconds). [2.940e-03]
1868
1869 11. The remaining offset correction from the previous update
1870 (in seconds, positive means the system clock is slow of
1871 UTC). [-2.084e-04]
1872
1873 12. The total of the network path delays to the reference
1874 clock to which the local clock is ultimately synchronised
1875 (in seconds). [1.534e-02]
1876
1877 13. The total dispersion accumulated through all the servers
1878 back to the reference clock to which the local clock is
1879 ultimately synchronised (in seconds). [3.472e-04]
1880
1881 14. The maximum estimated error of the system clock in the
1882 interval since the previous update (in seconds). It
1883 includes the offset, remaining offset correction, root
1884 delay, and dispersion from the previous update with the
1885 dispersion which accumulated in the interval. [8.304e-03]
1886
1887 rtc
1888 This option logs information about the system’s real-time
1889 clock. An example line (which actually appears as a single line
1890 in the file) from the rtc.log file is shown below.
1891
1892 2015-07-22 05:40:50 -0.037360 1 -0.037434\
1893 -37.948 12 5 120
1894
1895 The columns are as follows (the quantities in square brackets
1896 are the values from the example line above):
1897
1898 1. Date [2015-07-22]
1899
1900 2. Hour:Minute:Second. Note that the date-time pair is
1901 expressed in UTC, not the local time zone. [05:40:50]
1902
1903 3. The measured offset between the RTC and the system clock in
1904 seconds. Positive indicates that the RTC is fast of the
1905 system time [-0.037360].
1906
1907 4. Flag indicating whether the regression has produced valid
1908 coefficients. (1 for yes, 0 for no). [1]
1909
1910 5. Offset at the current time predicted by the regression
1911 process. A large difference between this value and the
1912 measured offset tends to indicate that the measurement is
1913 an outlier with a serious measurement error. [-0.037434]
1914
1915 6. The rate at which the RTC is losing or gaining time
1916 relative to the system clock. In ppm, with positive
1917 indicating that the RTC is gaining time. [-37.948]
1918
1919 7. The number of measurements used in the regression. [12]
1920
1921 8. The number of runs of regression residuals of the same
1922 sign. Low values indicate that a straight line is no longer
1923 a good model of the measured data and that older
1924 measurements should be discarded. [5]
1925
1926 9. The measurement interval used prior to the measurement
1927 being made (in seconds). [120]
1928
1929 refclocks
1930 This option logs the raw and filtered reference clock
1931 measurements to a file called refclocks.log. An example line
1932 (which actually appears as a single line in the file) from the
1933 log file is shown below.
1934
1935 2009-11-30 14:33:27.000000 PPS2 7 N 1 4.900000e-07 -6.741777e-07 1.000e-06
1936
1937 The columns are as follows (the quantities in square brackets
1938 are the values from the example line above):
1939
1940 1. Date [2009-11-30]
1941
1942 2. Hour:Minute:Second.Microsecond. Note that the date-time
1943 pair is expressed in UTC, not the local time zone.
1944 [14:33:27.000000]
1945
1946 3. Reference ID of the reference clock from which the
1947 measurement came. [PPS2]
1948
1949 4. Sequence number of driver poll within one polling interval
1950 for raw samples, or - for filtered samples. [7]
1951
1952 5. Leap status (N means normal, + means that the last minute
1953 of the current month has 61 seconds, - means that the last
1954 minute of the month has 59 seconds). [N]
1955
1956 6. Flag indicating whether the sample comes from PPS source.
1957 (1 for yes, 0 for no, or - for filtered sample). [1]
1958
1959 7. Local clock error measured by reference clock driver, or -
1960 for filtered sample. [4.900000e-07]
1961
1962 8. Local clock error with applied corrections. Positive
1963 indicates that the local clock is slow. [-6.741777e-07]
1964
1965 9. Assumed dispersion of the sample. [1.000e-06]
1966
1967 tempcomp
1968 This option logs the temperature measurements and system rate
1969 compensations to a file called tempcomp.log. An example line
1970 (which actually appears as a single line in the file) from the
1971 log file is shown below.
1972
1973 2015-04-19 10:39:48 2.8000e+04 3.6600e-01
1974
1975 The columns are as follows (the quantities in square brackets
1976 are the values from the example line above):
1977
1978 1. Date [2015-04-19]
1979
1980 2. Hour:Minute:Second. Note that the date-time pair is
1981 expressed in UTC, not the local time zone. [10:39:48]
1982
1983 3. Temperature read from the sensor. [2.8000e+04]
1984
1985 4. Applied compensation in ppm, positive means the system
1986 clock is running faster than it would be without the
1987 compensation. [3.6600e-01]
1988
1989
1990 An example of the directive is:
1991
1992 log measurements statistics tracking
1993
1994 logbanner entries
1995 A banner is periodically written to the log files enabled by the
1996 log directive to indicate the meanings of the columns.
1997
1998 The logbanner directive specifies after how many entries in the log
1999 file should be the banner written. The default is 32, and 0 can be
2000 used to disable it entirely.
2001
2002 logchange threshold
2003 This directive sets the threshold for the adjustment of the system
2004 clock that will generate a syslog message. Clock errors detected
2005 via NTP packets, reference clocks, or timestamps entered via the
2006 settime command of chronyc are logged.
2007
2008 By default, the threshold is 1 second.
2009
2010 An example of the use is:
2011
2012 logchange 0.1
2013
2014 which would cause a syslog message to be generated if a system
2015 clock error of over 0.1 seconds starts to be compensated.
2016
2017 logdir directory
2018 This directive allows the directory where log files are written to
2019 be specified.
2020
2021 An example of the use of this directive is:
2022
2023 logdir /var/log/chrony
2024
2025 mailonchange email threshold
2026 This directive defines an email address to which mail should be
2027 sent if chronyd applies a correction exceeding a particular
2028 threshold to the system clock.
2029
2030 An example of the use of this directive is:
2031
2032 mailonchange root@localhost 0.5
2033
2034 This would send a mail message to root if a change of more than 0.5
2035 seconds were applied to the system clock.
2036
2037 This directive cannot be used when a system call filter is enabled
2038 by the -F option as the chronyd process will not be allowed to fork
2039 and execute the sendmail binary.
2040
2041 Miscellaneous
2042 hwtimestamp interface [option]...
2043 This directive enables hardware timestamping of NTP packets sent to
2044 and received from the specified network interface. The network
2045 interface controller (NIC) uses its own clock to accurately
2046 timestamp the actual transmissions and receptions, avoiding
2047 processing and queueing delays in the kernel, network driver, and
2048 hardware. This can significantly improve the accuracy of the
2049 timestamps and the measured offset, which is used for
2050 synchronisation of the system clock. In order to get the best
2051 results, both sides receiving and sending NTP packets (i.e. server
2052 and client, or two peers) need to use HW timestamping. If the
2053 server or peer supports the interleaved mode, it needs to be
2054 enabled by the xleave option in the server or the peer directive.
2055
2056 This directive is supported on Linux. The NIC must support HW
2057 timestamping, which can be verified with the ethtool -T command.
2058 The list of capabilities should include
2059 SOF_TIMESTAMPING_RAW_HARDWARE, SOF_TIMESTAMPING_TX_HARDWARE, and
2060 SOF_TIMESTAMPING_RX_HARDWARE. Receive filter HWTSTAMP_FILTER_ALL,
2061 or HWTSTAMP_FILTER_NTP_ALL, is necessary for timestamping of
2062 received packets. When chronyd is running, no other process (e.g. a
2063 PTP daemon) should be working with the NIC clock.
2064
2065 If the kernel supports software timestamping, it will be enabled
2066 for all interfaces. The source of timestamps (i.e. hardware,
2067 kernel, or daemon) is indicated in the measurements.log file if
2068 enabled by the log measurements directive, and the ntpdata report
2069 in chronyc.
2070
2071 If the specified interface is *, chronyd will try to enable HW
2072 timestamping on all available interfaces.
2073
2074 The hwtimestamp directive has the following options:
2075
2076 minpoll poll
2077 This option specifies the minimum interval between readings of
2078 the NIC clock. It’s defined as a power of two. It should
2079 correspond to the minimum polling interval of all NTP sources
2080 and the minimum expected polling interval of NTP clients. The
2081 default value is 0 (1 second) and the minimum value is -6
2082 (1/64th of a second).
2083
2084 precision precision
2085 This option specifies the assumed precision of reading of the
2086 NIC clock. The default value is 100e-9 (100 nanoseconds).
2087
2088 txcomp compensation
2089 This option specifies the difference in seconds between the
2090 actual transmission time at the physical layer and the reported
2091 transmit timestamp. This value will be added to transmit
2092 timestamps obtained from the NIC. The default value is 0.
2093
2094 rxcomp compensation
2095 This option specifies the difference in seconds between the
2096 reported receive timestamp and the actual reception time at the
2097 physical layer. This value will be subtracted from receive
2098 timestamps obtained from the NIC. The default value is 0.
2099
2100 nocrossts
2101 Some hardware can precisely cross timestamp the NIC clock with
2102 the system clock. This option disables the use of the cross
2103 timestamping.
2104
2105 rxfilter filter
2106 This option selects the receive timestamping filter. The filter
2107 can be one of the following:
2108
2109 all
2110 Enables timestamping of all received packets.
2111
2112 ntp
2113 Enables timestamping of received NTP packets.
2114
2115 none
2116 Disables timestamping of received packets.
2117
2118
2119 The most specific filter for timestamping NTP packets which is
2120 supported by the NIC is selected by default. Some NICs can
2121 timestamp only PTP packets, which limits the selection to the
2122 none filter. Forcing timestamping of all packets with the all
2123 filter when the NIC supports both all and ntp filters can be
2124 useful when packets are received from or on a non-standard UDP
2125 port (e.g. specified by the port directive).
2126
2127
2128
2129 Examples of the directive are:
2130
2131 hwtimestamp eth0
2132 hwtimestamp eth1 txcomp 300e-9 rxcomp 645e-9
2133 hwtimestamp *
2134
2135 include pattern
2136 The include directive includes a configuration file or multiple
2137 configuration files if a wildcard pattern is specified. This can be
2138 useful when maintaining configuration on multiple hosts to keep the
2139 differences in separate files.
2140
2141 An example of the directive is:
2142
2143 include /etc/chrony.d/*.conf
2144
2145 keyfile file
2146 This directive is used to specify the location of the file
2147 containing ID-key pairs for authentication of NTP packets.
2148
2149 The format of the directive is shown in the example below:
2150
2151 keyfile /etc/chrony.keys
2152
2153 The argument is simply the name of the file containing the ID-key
2154 pairs. The format of the file is shown below:
2155
2156 10 tulip
2157 11 hyacinth
2158 20 MD5 ASCII:crocus
2159 25 SHA1 HEX:1dc764e0791b11fa67efc7ecbc4b0d73f68a070c
2160 ...
2161
2162 Each line consists of an ID, name of an authentication hash
2163 function (optional), and a password. The ID can be any unsigned
2164 integer in the range 1 through 2^32-1. The default hash function is
2165 MD5. Depending on how chronyd was compiled, other supported
2166 functions might be SHA1, SHA256, SHA384, SHA512, RMD128, RMD160,
2167 RMD256, RMD320, TIGER, and WHIRLPOOL. The password can be specified
2168 as a string of characters not containing white space with an
2169 optional ASCII: prefix, or as a hexadecimal number with the HEX:
2170 prefix. The maximum length of the line is 2047 characters.
2171
2172 The password is used with the hash function to generate and verify
2173 a message authentication code (MAC) in NTP packets. It is
2174 recommended to use SHA1, or stronger, hash function with random
2175 passwords specified in the hexadecimal format that have at least
2176 128 bits. chronyd will log a warning to syslog on start if a source
2177 is specified in the configuration file with a key that has password
2178 shorter than 80 bits.
2179
2180 The keygen command of chronyc can be used to generate random keys
2181 for the key file. By default, it generates 160-bit MD5 or SHA1
2182 keys.
2183
2184 lock_all
2185 The lock_all directive will lock chronyd into RAM so that it will
2186 never be paged out. This mode is only supported on Linux. This
2187 directive uses the Linux mlockall() system call to prevent chronyd
2188 from ever being swapped out. This should result in lower and more
2189 consistent latency. It should not have significant impact on
2190 performance as chronyd’s memory usage is modest. The mlockall(2)
2191 man page has more details.
2192
2193 pidfile file
2194 chronyd always writes its process ID (PID) to a file, and checks
2195 this file on startup to see if another chronyd might already be
2196 running on the system. By default, the file used is
2197 /var/run/chronyd.pid. The pidfile directive allows the name to be
2198 changed, e.g.:
2199
2200 pidfile /run/chronyd.pid
2201
2202 sched_priority priority
2203 On Linux, the sched_priority directive will select the SCHED_FIFO
2204 real-time scheduler at the specified priority (which must be
2205 between 0 and 100). On macOS, this option must have either a value
2206 of 0 (the default) to disable the thread time constraint policy or
2207 1 for the policy to be enabled. Other systems do not support this
2208 option.
2209
2210 On Linux, this directive uses the sched_setscheduler() system call
2211 to instruct the kernel to use the SCHED_FIFO first-in, first-out
2212 real-time scheduling policy for chronyd with the specified
2213 priority. This means that whenever chronyd is ready to run it will
2214 run, interrupting whatever else is running unless it is a higher
2215 priority real-time process. This should not impact performance as
2216 chronyd resource requirements are modest, but it should result in
2217 lower and more consistent latency since chronyd will not need to
2218 wait for the scheduler to get around to running it. You should not
2219 use this unless you really need it. The sched_setscheduler(2) man
2220 page has more details.
2221
2222 On macOS, this directive uses the thread_policy_set() kernel call
2223 to specify real-time scheduling. As noted for Linux, you should not
2224 use this directive unless you really need it.
2225
2226 user user
2227 The user directive sets the name of the system user to which
2228 chronyd will switch after start in order to drop root privileges.
2229
2230 On Linux, chronyd needs to be compiled with support for the libcap
2231 library. On macOS, FreeBSD, NetBSD and Solaris chronyd forks into
2232 two processes. The child process retains root privileges, but can
2233 only perform a very limited range of privileged system calls on
2234 behalf of the parent.
2235
2236 The compiled-in default value is chrony.
2237
2239 NTP client with permanent connection to NTP servers
2240 This section shows how to configure chronyd for computers that are
2241 connected to the Internet (or to any network containing true NTP
2242 servers which ultimately derive their time from a reference clock)
2243 permanently or most of the time.
2244
2245 To operate in this mode, you will need to know the names of the NTP
2246 servers you want to use. You might be able to find names of suitable
2247 servers by one of the following methods:
2248
2249 · Your institution might already operate servers on its network.
2250 Contact your system administrator to find out.
2251
2252 · Your ISP probably has one or more NTP servers available for its
2253 customers.
2254
2255 · Somewhere under the NTP homepage there is a list of public stratum
2256 1 and stratum 2 servers. You should find one or more servers that
2257 are near to you. Check that their access policy allows you to use
2258 their facilities.
2259
2260 · Use public servers from the pool.ntp.org <http://www.pool.ntp.org/>
2261 project.
2262
2263 Assuming that your NTP servers are called foo.example.net,
2264 bar.example.net and baz.example.net, your chrony.conf file could
2265 contain as a minimum:
2266
2267 server foo.example.net
2268 server bar.example.net
2269 server baz.example.net
2270
2271 However, you will probably want to include some of the other
2272 directives. The driftfile, makestep and rtcsync might be particularly
2273 useful. Also, the iburst option of the server directive is useful to
2274 speed up the initial synchronisation. The smallest useful configuration
2275 file would look something like:
2276
2277 server foo.example.net iburst
2278 server bar.example.net iburst
2279 server baz.example.net iburst
2280 driftfile /var/lib/chrony/drift
2281 makestep 1.0 3
2282 rtcsync
2283
2284 When using a pool of NTP servers (one name is used for multiple servers
2285 which might change over time), it is better to specify them with the
2286 pool directive instead of multiple server directives. The configuration
2287 file could in this case look like:
2288
2289 pool pool.ntp.org iburst
2290 driftfile /var/lib/chrony/drift
2291 makestep 1.0 3
2292 rtcsync
2293
2294 NTP client with infrequent connection to NTP servers
2295 This section shows how to configure chronyd for computers that have
2296 occasional connections to NTP servers. In this case, you will need some
2297 additional configuration to tell chronyd when the connection goes up
2298 and down. This saves the program from continuously trying to poll the
2299 servers when they are inaccessible.
2300
2301 Again, assuming that your NTP servers are called foo.example.net,
2302 bar.example.net and baz.example.net, your chrony.conf file would now
2303 contain:
2304
2305 server foo.example.net offline
2306 server bar.example.net offline
2307 server baz.example.net offline
2308 driftfile /var/lib/chrony/drift
2309 makestep 1.0 3
2310 rtcsync
2311
2312 The offline keyword indicates that the servers start in an offline
2313 state, and that they should not be contacted until chronyd receives
2314 notification from chronyc that the link to the Internet is present. To
2315 tell chronyd when to start and finish sampling the servers, the online
2316 and offline commands of chronyc need to be used.
2317
2318 To give an example of their use, assuming that pppd is the program
2319 being used to connect to the Internet and that chronyc has been
2320 installed at /usr/bin/chronyc, the script /etc/ppp/ip-up would include:
2321
2322 /usr/bin/chronyc online
2323
2324 and the script /etc/ppp/ip-down would include:
2325
2326 /usr/bin/chronyc offline
2327
2328 chronyd’s polling of the servers would now only occur whilst the
2329 machine is actually connected to the Internet.
2330
2331 Isolated networks
2332 This section shows how to configure chronyd for computers that never
2333 have network conectivity to any computer which ultimately derives its
2334 time from a reference clock.
2335
2336 In this situation, one computer is selected to be the master
2337 timeserver. The other computers are either direct clients of the
2338 master, or clients of clients.
2339
2340 The local directive enables a local reference mode, which allows
2341 chronyd to appear synchronised even when it is not.
2342
2343 The rate value in the master’s drift file needs to be set to the
2344 average rate at which the master gains or loses time. chronyd includes
2345 support for this, in the form of the manual directive and the settime
2346 command in the chronyc program.
2347
2348 If the master is rebooted, chronyd can re-read the drift rate from the
2349 drift file. However, the master has no accurate estimate of the current
2350 time. To get around this, the system can be configured so that the
2351 master can initially set itself to a ‘majority-vote’ of selected
2352 clients' times; this allows the clients to ‘flywheel’ the master while
2353 it is rebooting.
2354
2355 The smoothtime directive is useful when the clocks of the clients need
2356 to stay close together when the local time is adjusted by the settime
2357 command. The smoothing process needs to be activated by the smoothtime
2358 activate command when the local time is ready to be served. After that
2359 point, any adjustments will be smoothed out.
2360
2361 A typical configuration file for the master (called master) might be
2362 (assuming the clients and the master are in the 192.168.165.x subnet):
2363
2364 initstepslew 1 client1 client3 client6
2365 driftfile /var/lib/chrony/drift
2366 local stratum 8
2367 manual
2368 allow 192.168.165.0/24
2369 smoothtime 400 0.01
2370 rtcsync
2371
2372 For the clients that have to resynchronise the master when it restarts,
2373 the configuration file might be:
2374
2375 server master iburst
2376 driftfile /var/lib/chrony/drift
2377 allow 192.168.165.0/24
2378 makestep 1.0 3
2379 rtcsync
2380
2381 The rest of the clients would be the same, except that the allow
2382 directive is not required.
2383
2384 If there is no suitable computer to be designated as the master, or
2385 there is a requirement to keep the clients synchronised even when it
2386 fails, the orphan option of the local directive enables a special mode
2387 where the master is selected from multiple computers automatically.
2388 They all need to use the same local configuration and poll one another.
2389 The server with the smallest reference ID (which is based on its IP
2390 address) will take the role of the master and others will be
2391 synchronised to it. When it fails, the server with the second smallest
2392 reference ID will take over and so on.
2393
2394 A configuration file for the first server might be (assuming there are
2395 three servers called master1, master2, and master3):
2396
2397 initstepslew 1 master2 master3
2398 server master2
2399 server master3
2400 driftfile /var/lib/chrony/drift
2401 local stratum 8 orphan
2402 manual
2403 allow 192.168.165.0/24
2404 rtcsync
2405
2406 The other servers would be the same, except the hostnames in the
2407 initstepslew and server directives would be modified to specify the
2408 other servers. Their clients might be configured to poll all three
2409 servers.
2410
2411 RTC tracking
2412 This section considers a computer which has occasional connections to
2413 the Internet and is turned off between ‘sessions’. In this case,
2414 chronyd relies on the computer’s RTC to maintain the time between the
2415 periods when it is powered up. It assumes that Linux is run exclusively
2416 on the computer. Dual-boot systems might work; it depends what (if
2417 anything) the other system does to the RTC. On 2.6 and later kernels,
2418 if your motherboard has a HPET, you will need to enable the
2419 HPET_EMULATE_RTC option in your kernel configuration. Otherwise,
2420 chronyd will not be able to interact with the RTC device and will give
2421 up using it.
2422
2423 When the computer is connected to the Internet, chronyd has access to
2424 external NTP servers which it makes measurements from. These
2425 measurements are saved, and straight-line fits are performed on them to
2426 provide an estimate of the computer’s time error and rate of gaining or
2427 losing time.
2428
2429 When the computer is taken offline from the Internet, the best estimate
2430 of the gain or loss rate is used to free-run the computer until it next
2431 goes online.
2432
2433 Whilst the computer is running, chronyd makes measurements of the RTC
2434 (via the /dev/rtc interface, which must be compiled into the kernel).
2435 An estimate is made of the RTC error at a particular RTC second, and
2436 the rate at which the RTC gains or loses time relative to true time.
2437
2438 When the computer is powered down, the measurement histories for all
2439 the NTP servers are saved to files, and the RTC tracking information is
2440 also saved to a file (if the rtcfile directive has been specified).
2441 These pieces of information are also saved if the dump and writertc
2442 commands respectively are issued through chronyc.
2443
2444 When the computer is rebooted, chronyd reads the current RTC time and
2445 the RTC information saved at the last shutdown. This information is
2446 used to set the system clock to the best estimate of what its time
2447 would have been now, had it been left running continuously. The
2448 measurement histories for the servers are then reloaded.
2449
2450 The next time the computer goes online, the previous sessions'
2451 measurements can contribute to the line-fitting process, which gives a
2452 much better estimate of the computer’s gain or loss rate.
2453
2454 One problem with saving the measurements and RTC data when the machine
2455 is shut down is what happens if there is a power failure; the most
2456 recent data will not be saved. Although chronyd is robust enough to
2457 cope with this, some performance might be lost. (The main danger arises
2458 if the RTC has been changed during the session, with the trimrtc
2459 command in chronyc. Because of this, trimrtc will make sure that a
2460 meaningful RTC file is saved after the change is completed).
2461
2462 The easiest protection against power failure is to put the dump and
2463 writertc commands in the same place as the offline command is issued to
2464 take chronyd offline; because chronyd free-runs between online
2465 sessions, no parameters will change significantly between going offline
2466 from the Internet and any power failure.
2467
2468 A final point regards computers which are left running for extended
2469 periods and where it is desired to spin down the hard disc when it is
2470 not in use (e.g. when not accessed for 15 minutes). chronyd has been
2471 planned so it supports such operation; this is the reason why the RTC
2472 tracking parameters are not saved to disc after every update, but only
2473 when the user requests such a write, or during the shutdown sequence.
2474 The only other facility that will generate periodic writes to the disc
2475 is the log rtc facility in the configuration file; this option should
2476 not be used if you want your disc to spin down.
2477
2478 To illustrate how a computer might be configured for this case, example
2479 configuration files are shown.
2480
2481 For the chrony.conf file, the following can be used as an example.
2482
2483 server foo.example.net maxdelay 0.4 offline
2484 server bar.example.net maxdelay 0.4 offline
2485 server baz.example.net maxdelay 0.4 offline
2486 logdir /var/log/chrony
2487 log statistics measurements tracking
2488 driftfile /var/lib/chrony/drift
2489 makestep 1.0 3
2490 maxupdateskew 100.0
2491 dumpdir /var/lib/chrony
2492 rtcfile /var/lib/chrony/rtc
2493
2494 pppd is used for connecting to the Internet. This runs two scripts
2495 /etc/ppp/ip-up and /etc/ppp/ip-down when the link goes online and
2496 offline respectively.
2497
2498 The relevant part of the /etc/ppp/ip-up file is:
2499
2500 /usr/bin/chronyc online
2501
2502 and the relevant part of the /etc/ppp/ip-down script is:
2503
2504 /usr/bin/chronyc -m offline dump writertc
2505
2506 chronyd is started during the boot sequence with the -r and -s options.
2507 It might need to be started before any software that depends on the
2508 system clock not jumping or moving backwards, depending on the
2509 directives in chronyd’s configuration file.
2510
2511 For the system shutdown, chronyd should receive a SIGTERM several
2512 seconds before the final SIGKILL; the SIGTERM causes the measurement
2513 histories and RTC information to be saved.
2514
2515 Public NTP server
2516 chronyd can be configured to operate as a public NTP server, e.g. to
2517 join the pool.ntp.org <http://www.pool.ntp.org/en/join.html> project.
2518 The configuration is similar to the NTP client with permanent
2519 connection, except it needs to allow client access from all addresses.
2520 It is recommended to find at least four good servers (e.g. from the
2521 pool, or on the NTP homepage). If the server has a hardware reference
2522 clock (e.g. a GPS receiver), it can be specified by the refclock
2523 directive.
2524
2525 The amount of memory used for logging client accesses can be increased
2526 in order to enable clients to use the interleaved mode even when the
2527 server has a large number of clients, and better support rate limiting
2528 if it is enabled by the ratelimit directive. The system timezone
2529 database, if it is kept up to date and includes the right/UTC timezone,
2530 can be used as a reliable source to determine when a leap second will
2531 be applied to UTC. The -r option with the dumpdir directive shortens
2532 the time in which chronyd will not be able to serve time to its clients
2533 when it needs to be restarted (e.g. after upgrading to a newer version,
2534 or a change in the configuration).
2535
2536 The configuration file could look like:
2537
2538 server foo.example.net iburst
2539 server bar.example.net iburst
2540 server baz.example.net iburst
2541 server qux.example.net iburst
2542 makestep 1.0 3
2543 rtcsync
2544 allow
2545 clientloglimit 100000000
2546 leapsectz right/UTC
2547 driftfile /var/lib/chrony/drift
2548 dumpdir /var/run/chrony
2549
2551 chronyc(1), chronyd(8)
2552
2554 For instructions on how to report bugs, please visit <https://
2555 chrony.tuxfamily.org/>.
2556
2558 chrony was written by Richard Curnow, Miroslav Lichvar, and others.
2559
2560
2561
2562chrony 3.2 2017-09-15 CHRONY.CONF(5)