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