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