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. 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 are not case-sensitive. Generally, the directives can occur
19 in any order in the file and if a directive is specified multiple
20 times, only the last one will be effective. Exceptions are noted in the
21 descriptions.
22 The configuration directives can also be specified directly on the
24 chronyd command line. In this case each argument is parsed as a new
25 line and the configuration file is ignored.
26 While the number of supported directives is large, only a few of them
28 are typically needed. See the EXAMPLES section for configuration in
29 typical operating scenarios.
30 The configuration file might contain comment lines. A comment line is
32 any line that starts with zero or more spaces followed by any one of
33 the following characters: !, ;, #, %. Any line with this format will be
34 ignored.
35
37 Time sources
38 server hostname [option]...
39 The server directive specifies an NTP server which can be used as a
40 time source. The client-server relationship is strictly
41 hierarchical: a client might synchronise its system time to that of
42 the server, but the server’s system time will never be influenced
43 by that of a client.
44 This directive can be used multiple times to specify multiple
46 servers.
47 The directive is immediately followed by either the name of the
49 server, or its IP address. It supports the following options:
50 minpoll poll
52 This option specifies the minimum interval between requests
53 sent to the server as a power of 2 in seconds. For example,
54 minpoll 5 would mean that the polling interval should not drop
55 below 32 seconds. The default is 6 (64 seconds), the minimum is
56 -6 (1/64th of a second), and the maximum is 24 (6 months). Note
57 that intervals shorter than 6 (64 seconds) should generally not
58 be used with public servers on the Internet, because it might
59 be considered abuse. A sub-second interval will be enabled only
60 when the server is reachable and the round-trip delay is
61 shorter than 10 milliseconds, i.e. the server should be in a
62 local network.
63 maxpoll poll
65 This option specifies the maximum interval between requests
66 sent to the server as a power of 2 in seconds. For example,
67 maxpoll 9 indicates that the polling interval should stay at or
68 below 9 (512 seconds). The default is 10 (1024 seconds), the
69 minimum is -6 (1/64th of a second), and the maximum is 24 (6
70 months).
71 iburst
73 With this option, chronyd will start with a burst of 4-8
74 requests in order to make the first update of the clock sooner.
75 It will also repeat the burst every time the source is switched
76 from the offline state to online with the online command in
77 chronyc.
78 burst
80 With this option, chronyd will send a burst of up to 4 requests
81 when it cannot get a good measurement from the server. The
82 number of requests in the burst is limited by the current
83 polling interval to keep the average interval at or above the
84 minimum interval, i.e. the current interval needs to be at
85 least two times longer than the minimum interval in order to
86 allow a burst with two requests.
87 key ID
89 The NTP protocol supports a message authentication code (MAC)
90 to prevent computers having their system time upset by rogue
91 packets being sent to them. The MAC is generated as a function
92 of a key specified in the key file, which is specified by the
93 keyfile directive.
94 The key option specifies which key (with an ID in the range 1
96 through 2^32-1) should chronyd use to authenticate requests
97 sent to the server and verify its responses. The server must
98 have the same key for this number configured, otherwise no
99 relationship between the computers will be possible.
100 If the server is running ntpd and the output size of the hash
102 function used by the key is longer than 160 bits (e.g. SHA256),
103 the version option needs to be set to 4 for compatibility.
104 nts
106 This option enables authentication using the Network Time
107 Security (NTS) mechanism. Unlike with the key option, the
108 server and client do not need to share a key in a key file. NTS
109 has a Key Establishment (NTS-KE) protocol using the Transport
110 Layer Security (TLS) protocol to get the keys and cookies
111 required by NTS for authentication of NTP packets.
112 maxdelay delay
114 chronyd uses the network round-trip delay to the server to
115 determine how accurate a particular measurement is likely to
116 be. Long round-trip delays indicate that the request, or the
117 response, or both were delayed. If only one of the messages was
118 delayed the measurement error is likely to be substantial.
119 For small variations in the round-trip delay, chronyd uses a
121 weighting scheme when processing the measurements. However,
122 beyond a certain level of delay the measurements are likely to
123 be so corrupted as to be useless. (This is particularly so on
124 dial-up or other slow links, where a long delay probably
125 indicates a highly asymmetric delay caused by the response
126 waiting behind a lot of packets related to a download of some
127 sort).
128 If the user knows that round trip delays above a certain level
130 should cause the measurement to be ignored, this level can be
131 defined with the maxdelay option. For example, maxdelay 0.3
132 would indicate that measurements with a round-trip delay of 0.3
133 seconds or more should be ignored. The default value is 3
134 seconds and the maximum value is 1000 seconds.
135 maxdelayratio ratio
137 This option is similar to the maxdelay option above. chronyd
138 keeps a record of the minimum round-trip delay amongst the
139 previous measurements that it has buffered. If a measurement
140 has a round trip delay that is greater than the maxdelayratio
141 times the minimum delay, it will be rejected.
142 maxdelaydevratio ratio
144 If a measurement has a ratio of the increase in the round-trip
145 delay from the minimum delay amongst the previous measurements
146 to the standard deviation of the previous measurements that is
147 greater than the specified ratio, it will be rejected. The
148 default is 10.0.
149 mindelay delay
151 This option specifies a fixed minimum round-trip delay to be
152 used instead of the minimum amongst the previous measurements.
153 This can be useful in networks with static configuration to
154 improve the stability of corrections for asymmetric jitter,
155 weighting of the measurements, and the maxdelayratio and
156 maxdelaydevratio tests. The value should be set accurately in
157 order to have a positive effect on the synchronisation.
158 asymmetry ratio
160 This option specifies the asymmetry of the network jitter on
161 the path to the source, which is used to correct the measured
162 offset according to the delay. The asymmetry can be between
163 -0.5 and +0.5. A negative value means the delay of packets sent
164 to the source is more variable than the delay of packets sent
165 from the source back. By default, chronyd estimates the
166 asymmetry automatically.
167 offset offset
169 This option specifies a correction (in seconds) which will be
170 applied to offsets measured with this source. It’s particularly
171 useful to compensate for a known asymmetry in network delay or
172 timestamping errors. For example, if packets sent to the source
173 were on average delayed by 100 microseconds more than packets
174 sent from the source back, the correction would be -0.00005
175 (-50 microseconds). The default is 0.0.
176 minsamples samples
178 Set the minimum number of samples kept for this source. This
179 overrides the minsamples directive.
180 maxsamples samples
182 Set the maximum number of samples kept for this source. This
183 overrides the maxsamples directive.
184 filter samples
186 This option enables a median filter to reduce noise in NTP
187 measurements. The filter will reduce the specified number of
188 samples to a single sample. It is intended to be used with very
189 short polling intervals in local networks where it is
190 acceptable to generate a lot of NTP traffic.
191 offline
193 If the server will not be reachable when chronyd is started,
194 the offline option can be specified. chronyd will not try to
195 poll the server until it is enabled to do so (by using the
196 online command in chronyc).
197 auto_offline
199 With this option, the server will be assumed to have gone
200 offline when sending a request fails, e.g. due to a missing
201 route to the network. This option avoids the need to run the
202 offline command from chronyc when disconnecting the network
203 link. (It will still be necessary to use the online command
204 when the link has been established, to enable measurements to
205 start.)
206 prefer
208 Prefer this source over sources without the prefer option.
209 noselect
211 Never select this source. This is particularly useful for
212 monitoring.
213 trust
215 Assume time from this source is always true. It can be rejected
216 as a falseticker in the source selection only if another source
217 with this option does not agree with it.
218 require
220 Require that at least one of the sources specified with this
221 option is selectable (i.e. recently reachable and not a
222 falseticker) before updating the clock. Together with the trust
223 option this might be useful to allow a trusted authenticated
224 source to be safely combined with unauthenticated sources in
225 order to improve the accuracy of the clock. They can be
226 selected and used for synchronisation only if they agree with
227 the trusted and required source.
228 xleave
230 This option enables the interleaved mode of NTP. It enables the
231 server to respond with more accurate transmit timestamps (e.g.
232 kernel or hardware timestamps), which cannot be contained in
233 the transmitted packet itself and need to refer to a previous
234 packet instead. This can significantly improve the accuracy and
235 stability of the measurements.
236 The interleaved mode is compatible with servers that support
238 only the basic mode. Note that even servers that support the
239 interleaved mode might respond in the basic mode as the
240 interleaved mode requires the servers to keep some state for
241 each client and the state might be dropped when there are too
242 many clients (e.g. clientloglimit is too small), or it might be
243 overwritten by other clients that have the same IP address
244 (e.g. computers behind NAT or someone sending requests with a
245 spoofed source address).
246 The xleave option can be combined with the presend option in
248 order to shorten the interval in which the server has to keep
249 the state to be able to respond in the interleaved mode.
250 polltarget target
252 Target number of measurements to use for the regression
253 algorithm which chronyd will try to maintain by adjusting the
254 polling interval between minpoll and maxpoll. A higher target
255 makes chronyd prefer shorter polling intervals. The default is
256 8 and a useful range is from 6 to 60.
257 port port
259 This option allows the UDP port on which the server understands
260 NTP requests to be specified. For normal servers this option
261 should not be required (the default is 123, the standard NTP
262 port).
263 ntsport port
265 This option specifies the TCP port on which the server is
266 listening for NTS-KE connections when the nts option is
267 enabled. The default is 4460.
268 presend poll
270 If the timing measurements being made by chronyd are the only
271 network data passing between two computers, you might find that
272 some measurements are badly skewed due to either the client or
273 the server having to do an ARP lookup on the other party prior
274 to transmitting a packet. This is more of a problem with long
275 sampling intervals, which might be similar in duration to the
276 lifetime of entries in the ARP caches of the machines.
277 In order to avoid this problem, the presend option can be used.
279 It takes a single integer argument, which is the smallest
280 polling interval for which an extra pair of NTP packets will be
281 exchanged between the client and the server prior to the actual
282 measurement. For example, with the following option included in
283 a server directive:
284 presend 9
286 when the polling interval is 512 seconds or more, an extra NTP
288 client packet will be sent to the server a short time (2
289 seconds) before making the actual measurement.
290 If the presend option is used together with the xleave option,
292 chronyd will send two extra packets instead of one.
293 minstratum stratum
295 When the synchronisation source is selected from available
296 sources, sources with lower stratum are normally slightly
297 preferred. This option can be used to increase stratum of the
298 source to the specified minimum, so chronyd will avoid
299 selecting that source. This is useful with low stratum sources
300 that are known to be unreliable or inaccurate and which should
301 be used only when other sources are unreachable.
302 version version
304 This option sets the NTP version of packets sent to the server.
305 This can be useful when the server runs an old NTP
306 implementation that does not respond to requests using a newer
307 version. The default version depends on whether a key is
308 specified by the key option and which authentication hash
309 function the key is using. If the output size of the hash
310 function is longer than 160 bits, the default version is 3 for
311 compatibility with older chronyd servers. Otherwise, the
312 default version is 4.
313 pool name [option]...
315 The syntax of this directive is similar to that for the server
316 directive, except that it is used to specify a pool of NTP servers
317 rather than a single NTP server. The pool name is expected to
318 resolve to multiple addresses which might change over time.
319 This directive can be used multiple times to specify multiple
321 pools.
322 All options valid in the server directive can be used in this
324 directive too. There is one option specific to the pool directive:
325 maxsources sources
327 This option sets the desired number of sources to be used from
328 the pool. chronyd will repeatedly try to resolve the name until
329 it gets this number of sources responding to requests. The
330 default value is 4 and the maximum value is 16.
331 When an NTP source is unreachable, marked as a falseticker, or has
334 a distance larger than the limit set by the maxdistance directive,
335 chronyd will try to replace the source with a newly resolved
336 address of the name.
337 An example of the pool directive is
339 pool pool.ntp.org iburst maxsources 3
341 peer hostname [option]...
343 The syntax of this directive is identical to that for the server
344 directive, except that it specifies a symmetric association with an
345 NTP peer instead of a client/server association with an NTP server.
346 A single symmetric association allows the peers to be both servers
347 and clients to each other. This is mainly useful when the NTP
348 implementation of the peer (e.g. ntpd) supports ephemeral symmetric
349 associations and does not need to be configured with an address of
350 this host. chronyd does not support ephemeral associations.
351 This directive can be used multiple times to specify multiple
353 peers.
354 The following options of the server directive do not work in the
356 peer directive: iburst, burst, nts, presend.
357 When using the xleave option, both peers must support and have
359 enabled the interleaved mode, otherwise the synchronisation will
360 work in one direction only. When a key is specified by the key
361 option to enable authentication, both peers must use the same key
362 and the same key number.
363 Note that the symmetric mode is less secure than the client/server
365 mode. A denial-of-service attack is possible on unauthenticated
366 symmetric associations, i.e. when the peer was specified without
367 the key option. An attacker who does not see network traffic
368 between two hosts, but knows that they are peering with each other,
369 can periodically send them unauthenticated packets with spoofed
370 source addresses in order to disrupt their NTP state and prevent
371 them from synchronising to each other. When the association is
372 authenticated, an attacker who does see the network traffic, but
373 cannot prevent the packets from reaching the other host, can still
374 disrupt the state by replaying old packets. The attacker has
375 effectively the same power as a man-in-the-middle attacker. A
376 partial protection against this attack is implemented in chronyd,
377 which can protect the peers if they are using the same polling
378 interval and they never sent an authenticated packet with a
379 timestamp from future, but it should not be relied on as it is
380 difficult to ensure the conditions are met. If two hosts should be
381 able to synchronise to each other in both directions, it is
382 recommended to use two separate client/server associations
383 (specified by the server directive on both hosts) instead.
384 initstepslew step-threshold [hostname]...
386 In normal operation, chronyd slews the time when it needs to adjust
387 the system clock. For example, to correct a system clock which is 1
388 second slow, chronyd slightly increases the amount by which the
389 system clock is advanced on each clock interrupt, until the error
390 is removed. Note that at no time does time run backwards with this
391 method.
392 On most Unix systems it is not desirable to step the system clock,
394 because many programs rely on time advancing monotonically
395 forwards.
396 When the chronyd daemon is initially started, it is possible that
398 the system clock is considerably in error. Attempting to correct
399 such an error by slewing might not be sensible, since it might take
400 several hours to correct the error by this means.
401 The purpose of the initstepslew directive is to allow chronyd to
403 make a rapid measurement of the system clock error at boot time,
404 and to correct the system clock by stepping before normal operation
405 begins. Since this would normally be performed only at an
406 appropriate point in the system boot sequence, no other software
407 should be adversely affected by the step.
408 If the correction required is less than a specified threshold, a
410 slew is used instead. This makes it safer to restart chronyd whilst
411 the system is in normal operation.
412 The initstepslew directive takes a threshold and a list of NTP
414 servers as arguments. Each of the servers is rapidly polled several
415 times, and a majority voting mechanism used to find the most likely
416 range of system clock error that is present. A step or slew is
417 applied to the system clock to correct this error. chronyd then
418 enters its normal operating mode.
419 An example of the use of the directive is:
421 initstepslew 30 foo.example.net bar.example.net
423 where 2 NTP servers are used to make the measurement. The 30
425 indicates that if the system’s error is found to be 30 seconds or
426 less, a slew will be used to correct it; if the error is above 30
427 seconds, a step will be used.
428 The initstepslew directive can also be used in an isolated LAN
430 environment, where the clocks are set manually. The most stable
431 computer is chosen as the master, and the other computers are
432 slaved to it. If each of the slaves is configured with the local
433 directive, the master can be set up with an initstepslew directive
434 which references some or all of the slaves. Then, if the master
435 machine has to be rebooted, the slaves can be relied on to act
436 analogously to a flywheel and preserve the time for a short period
437 while the master completes its reboot.
438 The initstepslew directive is functionally similar to a combination
440 of the makestep and server directives with the iburst option. The
441 main difference is that the initstepslew servers are used only
442 before normal operation begins and that the foreground chronyd
443 process waits for initstepslew to finish before exiting. This is
444 useful to prevent programs started in the boot sequence after
445 chronyd from reading the clock before it has been stepped.
446 refclock driver parameter[:option]... [option]...
448 The refclock directive specifies a hardware reference clock to be
449 used as a time source. It has two mandatory parameters, a driver
450 name and a driver-specific parameter. The two parameters are
451 followed by zero or more refclock options. Some drivers have
452 special options, which can be appended to the driver-specific
453 parameter using the : character.
454 This directive can be used multiple times to specify multiple
456 reference clocks.
457 There are four drivers included in chronyd:
459 PPS
461 Driver for the kernel PPS (pulse per second) API. The parameter
462 is the path to the PPS device (typically /dev/pps?). As PPS
463 refclocks do not supply full time, another time source (e.g.
464 NTP server or non-PPS refclock) is needed to complete samples
465 from the PPS refclock. An alternative is to enable the local
466 directive to allow synchronisation with some unknown but
467 constant offset. The driver supports the following option:
468 clear
470 By default, the PPS refclock uses assert events (rising
471 edge) for synchronisation. With this option, it will use
472 clear events (falling edge) instead.
473 Examples:
476 refclock PPS /dev/pps0 lock NMEA refid GPS
478 refclock SHM 0 offset 0.5 delay 0.2 refid NMEA noselect
479 refclock PPS /dev/pps1:clear refid GPS2
480 SHM
482 NTP shared memory driver. This driver uses a shared memory
483 segment to receive samples from another process (e.g. gpsd).
484 The parameter is the number of the shared memory segment,
485 typically a small number like 0, 1, 2, or 3. The driver
486 supports the following option:
487 perm=mode
489 This option specifies the permissions of the shared memory
490 segment created by chronyd. They are specified as a numeric
491 mode. The default value is 0600 (read-write access for
492 owner only).
493 Examples:
497 refclock SHM 0 poll 3 refid GPS1
499 refclock SHM 1:perm=0644 refid GPS2
500 SOCK
502 Unix domain socket driver. It is similar to the SHM driver, but
503 samples are received from a Unix domain socket instead of
504 shared memory and the messages have a different format. The
505 parameter is the path to the socket, which chronyd creates on
506 start. An advantage over the SHM driver is that SOCK does not
507 require polling and it can receive PPS samples with incomplete
508 time. The format of the messages is described in the
509 refclock_sock.c file in the chrony source code.
510 An application which supports the SOCK protocol is the gpsd
512 daemon. The path where gpsd expects the socket to be created is
513 described in the gpsd(8) man page. For example:
514 refclock SOCK /var/run/chrony.ttyS0.sock
516 PHC
518 PTP hardware clock (PHC) driver. The parameter is the path to
519 the device of the PTP clock which should be used as a time
520 source. If the clock is kept in TAI instead of UTC (e.g. it is
521 synchronised by a PTP daemon), the current UTC-TAI offset needs
522 to be specified by the offset option. Alternatively, the pps
523 refclock option can be enabled to treat the PHC as a PPS
524 refclock, using only the sub-second offset for synchronisation.
525 The driver supports the following options:
526 nocrossts
528 This option disables use of precise cross timestamping.
529 extpps
531 This option enables a PPS mode in which the PTP clock is
532 timestamping pulses of an external PPS signal connected to
533 the clock. The clock does not need to be synchronised, but
534 another time source is needed to complete the PPS samples.
535 Note that some PTP clocks cannot be configured to timestamp
536 only assert or clear events, and it is necessary to use the
537 width option to filter wrong PPS samples.
538 pin=index
540 This option specifies the index of the pin to which is
541 connected the PPS signal. The default value is 0.
542 channel=index
544 This option specifies the index of the channel for the PPS
545 mode. The default value is 0.
546 clear
548 This option enables timestamping of clear events (falling
549 edge) instead of assert events (rising edge) in the PPS
550 mode. This may not work with some clocks.
551 Examples:
555 refclock PHC /dev/ptp0 poll 0 dpoll -2 offset -37
557 refclock PHC /dev/ptp1:nocrossts poll 3 pps
558 refclock PHC /dev/ptp2:extpps:pin=1 width 0.2 poll 2
559 The refclock directive supports the following options:
562 poll poll
564 Timestamps produced by refclock drivers are not used
565 immediately, but they are stored and processed by a median
566 filter in the polling interval specified by this option. This
567 is defined as a power of 2 and can be negative to specify a
568 sub-second interval. The default is 4 (16 seconds). A shorter
569 interval allows chronyd to react faster to changes in the
570 frequency of the system clock, but it might have a negative
571 effect on its accuracy if the samples have a lot of jitter.
572 dpoll dpoll
574 Some drivers do not listen for external events and try to
575 produce samples in their own polling interval. This is defined
576 as a power of 2 and can be negative to specify a sub-second
577 interval. The default is 0 (1 second).
578 refid refid
580 This option is used to specify the reference ID of the
581 refclock, as up to four ASCII characters. The default reference
582 ID is composed from the first three characters of the driver
583 name and the number of the refclock. Each refclock must have a
584 unique reference ID.
585 lock refid
587 This option can be used to lock a PPS refclock to another
588 refclock, which is specified by its reference ID. In this mode
589 received PPS samples are paired directly with raw samples from
590 the specified refclock.
591 rate rate
593 This option sets the rate of the pulses in the PPS signal (in
594 Hz). This option controls how the pulses will be completed with
595 real time. To actually receive more than one pulse per second,
596 a negative dpoll has to be specified (-3 for a 5Hz signal). The
597 default is 1.
598 maxlockage pulses
600 This option specifies in number of pulses how old can be
601 samples from the refclock specified by the lock option to be
602 paired with the pulses. Increasing this value is useful when
603 the samples are produced at a lower rate than the pulses. The
604 default is 2.
605 width width
607 This option specifies the width of the pulses (in seconds). It
608 is used to filter PPS samples when the driver provides samples
609 for both rising and falling edges. Note that it reduces the
610 maximum allowed error of the time source which completes the
611 PPS samples. If the duty cycle is configurable, 50% should be
612 preferred in order to maximise the allowed error.
613 pps
615 This options forces chronyd to treat any refclock (e.g. SHM or
616 PHC) as a PPS refclock. This can be useful when the refclock
617 provides time with a variable offset of a whole number of
618 seconds (e.g. it uses TAI instead of UTC). Another time source
619 is needed to complete samples from the refclock.
620 offset offset
622 This option can be used to compensate for a constant error. The
623 specified offset (in seconds) is applied to all samples
624 produced by the reference clock. The default is 0.0.
625 delay delay
627 This option sets the NTP delay of the source (in seconds). Half
628 of this value is included in the maximum assumed error which is
629 used in the source selection algorithm. Increasing the delay is
630 useful to avoid having no majority in the source selection or
631 to make it prefer other sources. The default is 1e-9 (1
632 nanosecond).
633 stratum stratum
635 This option sets the NTP stratum of the refclock. This can be
636 useful when the refclock provides time with a stratum other
637 than 0. The default is 0.
638 precision precision
640 This option sets the precision of the reference clock (in
641 seconds). The default value is the estimated precision of the
642 system clock.
643 maxdispersion dispersion
645 Maximum allowed dispersion for filtered samples (in seconds).
646 Samples with larger estimated dispersion are ignored. By
647 default, this limit is disabled.
648 filter samples
650 This option sets the length of the median filter which is used
651 to reduce the noise in the measurements. With each poll about
652 40 percent of the stored samples are discarded and one final
653 sample is calculated as an average of the remaining samples. If
654 the length is 4 or more, at least 4 samples have to be
655 collected between polls. For lengths below 4, the filter has to
656 be full. The default is 64.
657 prefer
659 Prefer this source over sources without the prefer option.
660 noselect
662 Never select this source. This is useful for monitoring or with
663 sources which are not very accurate, but are locked with a PPS
664 refclock.
665 trust
667 Assume time from this source is always true. It can be rejected
668 as a falseticker in the source selection only if another source
669 with this option does not agree with it.
670 require
672 Require that at least one of the sources specified with this
673 option is selectable (i.e. recently reachable and not a
674 falseticker) before updating the clock. Together with the trust
675 option this can be useful to allow a trusted, but not very
676 precise, reference clock to be safely combined with
677 unauthenticated NTP sources in order to improve the accuracy of
678 the clock. They can be selected and used for synchronisation
679 only if they agree with the trusted and required source.
680 tai
682 This option indicates that the reference clock keeps time in
683 TAI instead of UTC and that chronyd should correct its offset
684 by the current TAI-UTC offset. The leapsectz directive must be
685 used with this option and the database must be kept up to date
686 in order for this correction to work as expected. This option
687 does not make sense with PPS refclocks.
688 minsamples samples
690 Set the minimum number of samples kept for this source. This
691 overrides the minsamples directive.
692 maxsamples samples
694 Set the maximum number of samples kept for this source. This
695 overrides the maxsamples directive.
696 manual
698 The manual directive enables support at run-time for the settime
699 command in chronyc. If no manual directive is included, any attempt
700 to use the settime command in chronyc will be met with an error
701 message.
702 Note that the settime command can be enabled at run-time using the
704 manual command in chronyc. (The idea of the two commands is that
705 the manual command controls the manual clock driver’s behaviour,
706 whereas the settime command allows samples of manually entered time
707 to be provided.)
708 acquisitionport port
710 By default, chronyd as an NTP client opens a new socket for each
711 request with the source port chosen randomly by the operating
712 system. The acquisitionport directive can be used to specify the
713 source port and use only one socket (per IPv4 or IPv6 address
714 family) for all configured servers. This can be useful for getting
715 through some firewalls. It should not be used if not necessary as
716 there is a small impact on security of the client. If set to 0, the
717 source port of the permanent socket will be chosen randomly by the
718 operating system.
719 It can be set to the same port as is used by the NTP server (which
721 can be configured with the port directive) to use only one socket
722 for all NTP packets.
723 An example of the acquisitionport directive is:
725 acquisitionport 1123
727 This would change the source port used for client requests to UDP
729 port 1123. You could then persuade the firewall administrator to
730 open that port.
731 bindacqaddress address
733 The bindacqaddress directive specifies a local IP address to which
734 chronyd will bind its NTP and NTS-KE client sockets. The syntax is
735 similar to the bindaddress and bindcmdaddress directives.
736 For each of the IPv4 and IPv6 protocols, only one bindacqaddress
738 directive can be specified.
739 bindacqdevice interface
741 The bindacqdevice directive binds the client sockets to a network
742 device specified by the interface name. This can be useful when the
743 local address is dynamic, or to enable an NTP source specified with
744 a link-local IPv6 address. This directive can specify only one
745 interface and it is supported on Linux only.
746 An example of the directive is:
748 bindacqdevice eth0
750 dscp point
752 The dscp directive sets the Differentiated Services Code Point
753 (DSCP) in transmitted NTP packets to the specified value. It can
754 improve stability of NTP measurements in local networks where
755 switches or routers are configured to prioritise forwarding of
756 packets with specific DSCP values. The default value is 0 and the
757 maximum value is 63.
758 An example of the directive (setting the Expedited Forwarding
760 class) is:
761 dscp 46
763 dumpdir directory
765 To compute the rate of gain or loss of time, chronyd has to store a
766 measurement history for each of the time sources it uses.
767 All supported systems, with the exception of macOS 10.12 and
769 earlier, have operating system support for setting the rate of gain
770 or loss to compensate for known errors. (On macOS 10.12 and
771 earlier, chronyd must simulate such a capability by periodically
772 slewing the system clock forwards or backwards by a suitable amount
773 to compensate for the error built up since the previous slew.)
774 For such systems, it is possible to save the measurement history
776 across restarts of chronyd (assuming no changes are made to the
777 system clock behaviour whilst it is not running). The dumpdir
778 directive defines the directory where the measurement histories are
779 saved when chronyd exits, or the dump command in chronyc is issued.
780 If the directory does not exist, it will be created automatically.
782 An example of the directive is:
784 dumpdir /run/chrony
786 A source whose IP address is 1.2.3.4 would have its measurement
788 history saved in the file /run/chrony/1.2.3.4.dat. History of
789 reference clocks is saved to files named by their reference ID in
790 form of refid:XXXXXXXX.dat.
791 maxsamples samples
793 The maxsamples directive sets the default maximum number of samples
794 that chronyd should keep for each source. This setting can be
795 overridden for individual sources in the server and refclock
796 directives. The default value is 0, which disables the configurable
797 limit. The useful range is 4 to 64.
798 As a special case, setting maxsamples to 1 disables frequency
800 tracking in order to make the sources immediately selectable with
801 only one sample. This can be useful when chronyd is started with
802 the -q or -Q option.
803 minsamples samples
805 The minsamples directive sets the default minimum number of samples
806 that chronyd should keep for each source. This setting can be
807 overridden for individual sources in the server and refclock
808 directives. The default value is 6. The useful range is 4 to 64.
809 Forcing chronyd to keep more samples than it would normally keep
811 reduces noise in the estimated frequency and offset, but slows down
812 the response to changes in the frequency and offset of the clock.
813 The offsets in the tracking and sourcestats reports (and the
814 tracking.log and statistics.log files) may be smaller than the
815 actual offsets.
816 ntsdumpdir directory
818 This directive specifies a directory for the client to save NTS
819 cookies it received from the server in order to avoid making an
820 NTS-KE request when chronyd is started again. The cookies are saved
821 separately for each NTP source in files named by the IP address of
822 the NTS-KE server (e.g. 1.2.3.4.nts). By default, the client does
823 not save the cookies.
824 If the directory does not exist, it will be created automatically.
826 An example of the directive is:
828 ntsdumpdir /var/lib/chrony
830 This directory is used also by the NTS server to save keys.
832 ntsrefresh interval
834 This directive specifies the maximum interval between NTS-KE
835 handshakes (in seconds) in order to refresh the keys authenticating
836 NTP packets. The default value is 2419200 (4 weeks).
837 ntstrustedcerts file
839 This directive specifies a file containing certificates (in the PEM
840 format) of trusted certificate authorities (CA) that should be used
841 to verify certificates of NTS servers in addition to the system’s
842 default trusted CAs (if the nosystemcert directive is not present).
843 nosystemcert
845 This directive disables the system’s default trusted CAs.
846 nocerttimecheck limit
848 This directive disables the checks of the activation and expiration
849 times of certificates for the specified number of clock updates. It
850 allows the NTS authentication mechanism to be used on computers
851 which start with wrong time (e.g. due to not having an RTC or
852 backup battery). Disabling the time checks has important security
853 implications, e.g. if an NTP server was ever compromised, its
854 certificate could be used in an attack after the expiration time.
855 The default value is 0, which means the time checks are always
856 enabled.
857 An example of the directive is:
859 nocerttimecheck 1
861 This would disable the time checks until the clock is updated for
863 the first time, assuming the first update corrects the clock and
864 later checks can work with correct time.
865 Source selection
867 authselectmode mode
868 NTP sources can be specified with the key or nts option to enable
869 authentication to limit the impact of man-in-the-middle attacks.
870 The attackers can drop or delay NTP packets (up to the maxdelay and
871 maxdistance limits), but they cannot modify the timestamps
872 contained in the packets. The attack can cause only a limited slew
873 or step, and also cause the clock to run faster or slower than real
874 time (up to double of the maxdrift limit).
875 When authentication is enabled for an NTP source, it is important
877 to disable unauthenticated NTP sources which could be exploited in
878 the attack, e.g. if they are not reachable only over a trusted
879 network. Alternatively, the source selection can be configured with
880 the require and trust options to synchronise to the unauthenticated
881 sources only if they agree with the authenticated sources and might
882 have a positive impact on the accuracy of the clock. Note that in
883 this case the impact of the attack is higher. The attackers cannot
884 cause an arbitrarily large step or slew, but they have more control
885 over the frequency of the clock and can cause chronyd to report
886 false information, e.g. a significantly smaller root delay and
887 dispersion.
888 This directive determines the default selection options for
890 authenticated and unauthenticated sources in order to simplify the
891 configuration with the configuration file and chronyc commands. It
892 sets a policy for authentication.
893 Sources specified with the noselect option are ignored (not counted
895 as either authenticated or unauthenticated), and they always have
896 only the selection options specified in the configuration.
897 There are four modes:
899 require
901 Authentication is strictly required for NTP sources in this
902 mode. If any unauthenticated NTP sources are specified, they
903 will automatically get the noselect option to prevent them from
904 being selected for synchronisation.
905 prefer
907 In this mode, authentication is optional and preferred. If it
908 is enabled for at least one NTP source, all unauthenticated NTP
909 sources will get the noselect option.
910 mix
912 In this mode, authentication is optional and synchronisation to
913 a mix of authenticated and unauthenticated NTP sources is
914 allowed. If both authenticated and unauthenticated NTP sources
915 are specified, all authenticated NTP sources and reference
916 clocks will get the require and trust options to prevent
917 synchronisation to unauthenticated NTP sources if they do not
918 agree with a majority of the authenticated sources and
919 reference clocks. This is the default mode.
920 ignore
922 In this mode, authentication is ignored in the source
923 selection. All sources will have only the selection options
924 that were specified in the configuration file, or chronyc
925 command. This was the behaviour of chronyd in versions before
926 4.0.
927 As an example, the following configuration using the default mix
931 mode:
932 server foo.example.net nts
934 server bar.example.net nts
935 server baz.example.net
936 refclock SHM 0
937 is equivalent to the following configuration using the ignore mode:
939 authselectmode ignore
941 server foo.example.net nts require trust
942 server bar.example.net nts require trust
943 server baz.example.net
944 refclock SHM 0 require trust
945 combinelimit limit
947 When chronyd has multiple sources available for synchronisation, it
948 has to select one source as the synchronisation source. The
949 measured offsets and frequencies of the system clock relative to
950 the other sources, however, can be combined with the selected
951 source to improve the accuracy of the system clock.
952 The combinelimit directive limits which sources are included in the
954 combining algorithm. Their synchronisation distance has to be
955 shorter than the distance of the selected source multiplied by the
956 value of the limit. Also, their measured frequencies have to be
957 close to the frequency of the selected source. If the selected
958 source was specified with the prefer option, it can be combined
959 only with other sources specified with this option.
960 By default, the limit is 3. Setting the limit to 0 effectively
962 disables the source combining algorithm and only the selected
963 source will be used to control the system clock.
964 maxdistance distance
966 The maxdistance directive sets the maximum allowed root distance of
967 the sources to not be rejected by the source selection algorithm.
968 The distance includes the accumulated dispersion, which might be
969 large when the source is no longer synchronised, and half of the
970 total round-trip delay to the primary source.
971 By default, the maximum root distance is 3 seconds.
973 Setting maxdistance to a larger value can be useful to allow
975 synchronisation with a server that only has a very infrequent
976 connection to its sources and can accumulate a large dispersion
977 between updates of its clock.
978 maxjitter jitter
980 The maxjitter directive sets the maximum allowed jitter of the
981 sources to not be rejected by the source selection algorithm. This
982 prevents synchronisation with sources that have a small root
983 distance, but their time is too variable.
984 By default, the maximum jitter is 1 second.
986 minsources sources
988 The minsources directive sets the minimum number of sources that
989 need to be considered as selectable in the source selection
990 algorithm before the local clock is updated. The default value is
991 1.
992 Setting this option to a larger number can be used to improve the
994 reliability. More sources will have to agree with each other and
995 the clock will not be updated when only one source (which could be
996 serving incorrect time) is reachable.
997 reselectdist distance
999 When chronyd selects a synchronisation source from available
1000 sources, it will prefer the one with the shortest synchronisation
1001 distance. However, to avoid frequent reselecting when there are
1002 sources with similar distance, a fixed distance is added to the
1003 distance for sources that are currently not selected. This can be
1004 set with the reselectdist directive. By default, the distance is
1005 100 microseconds.
1006 stratumweight distance
1008 The stratumweight directive sets how much distance should be added
1009 per stratum to the synchronisation distance when chronyd selects
1010 the synchronisation source from available sources.
1011 By default, the weight is 0.001 seconds. This means that the
1013 stratum of the sources in the selection process matters only when
1014 the differences between the distances are in milliseconds.
1015 System clock
1017 clockprecision precision
1018 The clockprecision directive specifies the precision of the system
1019 clock (in seconds). It is used by chronyd to estimate the minimum
1020 noise in NTP measurements and randomise low-order bits of
1021 timestamps in NTP responses. By default, the precision is measured
1022 on start as the minimum time to read the clock.
1023 The measured value works well in most cases. However, it generally
1025 overestimates the precision and it can be sensitive to the CPU
1026 speed, which can change over time to save power. In some cases with
1027 a high-precision clocksource (e.g. the Time Stamp Counter of the
1028 CPU) and hardware timestamping, setting the precision on the server
1029 to a smaller value can improve stability of clients' NTP
1030 measurements. The server’s precision is reported on clients by the
1031 ntpdata command.
1032 An example setting the precision to 8 nanoseconds is:
1034 clockprecision 8e-9
1036 corrtimeratio ratio
1038 When chronyd is slewing the system clock to correct an offset, the
1039 rate at which it is slewing adds to the frequency error of the
1040 clock. On all supported systems, with the exception of macOS 12 and
1041 earlier, this rate can be controlled.
1042 The corrtimeratio directive sets the ratio between the duration in
1044 which the clock is slewed for an average correction according to
1045 the source history and the interval in which the corrections are
1046 done (usually the NTP polling interval). Corrections larger than
1047 the average take less time and smaller corrections take more time,
1048 the amount of the correction and the correction time are inversely
1049 proportional.
1050 Increasing corrtimeratio improves the overall frequency error of
1052 the system clock, but increases the overall time error as the
1053 corrections take longer.
1054 By default, the ratio is set to 3, the time accuracy of the clock
1056 is preferred over its frequency accuracy.
1057 The maximum allowed slew rate can be set by the maxslewrate
1059 directive. The current remaining correction is shown in the
1060 tracking report as the System time value.
1061 driftfile file
1063 One of the main activities of the chronyd program is to work out
1064 the rate at which the system clock gains or loses time relative to
1065 real time.
1066 Whenever chronyd computes a new value of the gain or loss rate, it
1068 is desirable to record it somewhere. This allows chronyd to begin
1069 compensating the system clock at that rate whenever it is
1070 restarted, even before it has had a chance to obtain an equally
1071 good estimate of the rate during the new run. (This process can
1072 take many minutes, at least.)
1073 The driftfile directive allows a file to be specified into which
1075 chronyd can store the rate information. Two parameters are recorded
1076 in the file. The first is the rate at which the system clock gains
1077 or loses time, expressed in parts per million, with gains positive.
1078 Therefore, a value of 100.0 indicates that when the system clock
1079 has advanced by a second, it has gained 100 microseconds in reality
1080 (so the true time has only advanced by 999900 microseconds). The
1081 second is an estimate of the error bound around the first value in
1082 which the true rate actually lies.
1083 An example of the driftfile directive is:
1085 driftfile /var/lib/chrony/drift
1087 fallbackdrift min-interval max-interval
1089 Fallback drifts are long-term averages of the system clock drift
1090 calculated over exponentially increasing intervals. They are used
1091 to avoid quickly drifting away from true time when the clock was
1092 not updated for a longer period of time and there was a short-term
1093 deviation in the drift before the updates stopped.
1094 The directive specifies the minimum and maximum interval since the
1096 last clock update to switch between fallback drifts. They are
1097 defined as a power of 2 (in seconds). The syntax is as follows:
1098 fallbackdrift 16 19
1100 In this example, the minimum interval is 16 (18 hours) and the
1102 maximum interval is 19 (6 days). The system clock frequency will be
1103 set to the first fallback 18 hours after last clock update, to the
1104 second after 36 hours, and so on. This might be a good setting to
1105 cover frequency changes due to daily and weekly temperature
1106 fluctuations. When the frequency is set to a fallback, the state of
1107 the clock will change to ‘Not synchronised’.
1108 By default (or if the specified maximum or minimum is 0), no
1110 fallbacks are used and the clock frequency changes only with new
1111 measurements from NTP sources, reference clocks, or manual input.
1112 leapsecmode mode
1114 A leap second is an adjustment that is occasionally applied to UTC
1115 to keep it close to the mean solar time. When a leap second is
1116 inserted, the last day of June or December has an extra second
1117 23:59:60.
1118 For computer clocks that is a problem. The Unix time is defined as
1120 number of seconds since 00:00:00 UTC on 1 January 1970 without leap
1121 seconds. The system clock cannot have time 23:59:60, every minute
1122 has 60 seconds and every day has 86400 seconds by definition. The
1123 inserted leap second is skipped and the clock is suddenly ahead of
1124 UTC by one second. The leapsecmode directive selects how that error
1125 is corrected. There are four options:
1126 system
1128 When inserting a leap second, the kernel steps the system clock
1129 backwards by one second when the clock gets to 00:00:00 UTC.
1130 When deleting a leap second, it steps forward by one second
1131 when the clock gets to 23:59:59 UTC. This is the default mode
1132 when the system driver supports leap seconds (i.e. all
1133 supported systems with the exception of macOS 12 and earlier).
1134 step
1136 This is similar to the system mode, except the clock is stepped
1137 by chronyd instead of the kernel. It can be useful to avoid
1138 bugs in the kernel code that would be executed in the system
1139 mode. This is the default mode when the system driver does not
1140 support leap seconds.
1141 slew
1143 The clock is corrected by slewing started at 00:00:00 UTC when
1144 a leap second is inserted or 23:59:59 UTC when a leap second is
1145 deleted. This might be preferred over the system and step modes
1146 when applications running on the system are sensitive to jumps
1147 in the system time and it is acceptable that the clock will be
1148 off for a longer time. On Linux with the default maxslewrate
1149 value the correction takes 12 seconds.
1150 ignore
1152 No correction is applied to the clock for the leap second. The
1153 clock will be corrected later in normal operation when new
1154 measurements are made and the estimated offset includes the one
1155 second error.
1156 When serving time to NTP clients that cannot be configured to
1160 correct their clocks for a leap second by slewing, or to clients
1161 that would correct at slightly different rates when it is necessary
1162 to keep them close together, the slew mode can be combined with the
1163 smoothtime directive to enable a server leap smear.
1164 When smearing a leap second, the leap status is suppressed on the
1166 server and the served time is corrected slowly by slewing instead
1167 of stepping. The clients do not need any special configuration as
1168 they do not know there is any leap second and they follow the
1169 server time which eventually brings them back to UTC. Care must be
1170 taken to ensure they use only NTP servers which smear the leap
1171 second in exactly the same way for synchronisation.
1172 This feature must be used carefully, because the server is
1174 intentionally not serving its best estimate of the true time.
1175 A recommended configuration to enable a server leap smear is:
1177 leapsecmode slew
1179 maxslewrate 1000
1180 smoothtime 400 0.001024 leaponly
1181 The first directive is necessary to disable the clock step which
1183 would reset the smoothing process. The second directive limits the
1184 slewing rate of the local clock to 1000 ppm, which improves the
1185 stability of the smoothing process when the local correction starts
1186 and ends. The third directive enables the server time smoothing
1187 process. It will start when the clock gets to 00:00:00 UTC and it
1188 will take 62500 seconds (about 17.36 hours) to finish. The
1189 frequency offset will be changing by 0.001024 ppm per second and
1190 will reach a maximum of 32 ppm in 31250 seconds. The leaponly
1191 option makes the duration of the leap smear constant and allows the
1192 clients to safely synchronise with multiple identically configured
1193 leap smearing servers.
1194 The duration of the leap smear can be calculated from the specified
1196 wander as
1197 duration = sqrt(4 / wander)
1199 leapsectz timezone
1201 This directive specifies a timezone in the system tz database which
1202 chronyd can use to determine when will the next leap second occur
1203 and what is the current offset between TAI and UTC. It will
1204 periodically check if 23:59:59 and 23:59:60 are valid times in the
1205 timezone. This typically works with the right/UTC timezone.
1206 When a leap second is announced, the timezone needs to be updated
1208 at least 12 hours before the leap second. It is not necessary to
1209 restart chronyd.
1210 This directive is useful with reference clocks and other time
1212 sources which do not announce leap seconds, or announce them too
1213 late for an NTP server to forward them to its own clients. Clients
1214 of leap smearing servers must not use this directive.
1215 It is also useful when the system clock is required to have correct
1217 TAI-UTC offset. Note that the offset is set only when leap seconds
1218 are handled by the kernel, i.e. leapsecmode is set to system.
1219 The specified timezone is not used as an exclusive source of
1221 information about leap seconds. If a majority of time sources
1222 announce on the last day of June or December that a leap second
1223 should be inserted or deleted, it will be accepted even if it is
1224 not included in the timezone.
1225 An example of the directive is:
1227 leapsectz right/UTC
1229 The following shell command verifies that the timezone contains
1231 leap seconds and can be used with this directive:
1232 $ TZ=right/UTC date -d 'Dec 31 2008 23:59:60'
1234 Wed Dec 31 23:59:60 UTC 2008
1235 makestep threshold limit
1237 Normally chronyd will cause the system to gradually correct any
1238 time offset, by slowing down or speeding up the clock as required.
1239 In certain situations, the system clock might be so far adrift that
1240 this slewing process would take a very long time to correct the
1241 system clock.
1242 This directive forces chronyd to step the system clock if the
1244 adjustment is larger than a threshold value, but only if there were
1245 no more clock updates since chronyd was started than a specified
1246 limit (a negative value can be used to disable the limit).
1247 This is particularly useful when using reference clocks, because
1249 the initstepslew directive works only with NTP sources.
1250 An example of the use of this directive is:
1252 makestep 0.1 3
1254 This would step the system clock if the adjustment is larger than
1256 0.1 seconds, but only in the first three clock updates.
1257 maxchange offset start ignore
1259 This directive sets the maximum allowed offset corrected on a clock
1260 update. The check is performed only after the specified number of
1261 updates to allow a large initial adjustment of the system clock.
1262 When an offset larger than the specified maximum occurs, it will be
1263 ignored for the specified number of times and then chronyd will
1264 give up and exit (a negative value can be used to never exit). In
1265 both cases a message is sent to syslog.
1266 An example of the use of this directive is:
1268 maxchange 1000 1 2
1270 After the first clock update, chronyd will check the offset on
1272 every clock update, it will ignore two adjustments larger than 1000
1273 seconds and exit on another one.
1274 maxclockerror error-in-ppm
1276 The maxclockerror directive sets the maximum assumed frequency
1277 error that the system clock can gain on its own between clock
1278 updates. It describes the stability of the clock.
1279 By default, the maximum error is 1 ppm.
1281 Typical values for error-in-ppm might be 10 for a low quality clock
1283 and 0.1 for a high quality clock using a temperature compensated
1284 crystal oscillator.
1285 maxdrift drift-in-ppm
1287 This directive specifies the maximum assumed drift (frequency
1288 error) of the system clock. It limits the frequency adjustment that
1289 chronyd is allowed to use to correct the measured drift. It is an
1290 additional limit to the maximum adjustment that can be set by the
1291 system driver (100000 ppm on Linux, 500 ppm on FreeBSD, NetBSD, and
1292 macOS 10.13+, 32500 ppm on Solaris).
1293 By default, the maximum assumed drift is 500000 ppm, i.e. the
1295 adjustment is limited by the system driver rather than this
1296 directive.
1297 maxupdateskew skew-in-ppm
1299 One of chronyd’s tasks is to work out how fast or slow the
1300 computer’s clock runs relative to its reference sources. In
1301 addition, it computes an estimate of the error bounds around the
1302 estimated value.
1303 If the range of error is too large, it probably indicates that the
1305 measurements have not settled down yet, and that the estimated gain
1306 or loss rate is not very reliable.
1307 The maxupdateskew directive sets the threshold for determining
1309 whether an estimate might be so unreliable that it should not be
1310 used. By default, the threshold is 1000 ppm.
1311 Typical values for skew-in-ppm might be 100 for a dial-up
1313 connection to servers over a phone line, and 5 or 10 for a computer
1314 on a LAN.
1315 It should be noted that this is not the only means of protection
1317 against using unreliable estimates. At all times, chronyd keeps
1318 track of both the estimated gain or loss rate, and the error bound
1319 on the estimate. When a new estimate is generated following another
1320 measurement from one of the sources, a weighted combination
1321 algorithm is used to update the master estimate. So if chronyd has
1322 an existing highly-reliable master estimate and a new estimate is
1323 generated which has large error bounds, the existing master
1324 estimate will dominate in the new master estimate.
1325 maxslewrate rate-in-ppm
1327 The maxslewrate directive sets the maximum rate at which chronyd is
1328 allowed to slew the time. It limits the slew rate controlled by the
1329 correction time ratio (which can be set by the corrtimeratio
1330 directive) and is effective only on systems where chronyd is able
1331 to control the rate (i.e. all supported systems with the exception
1332 of macOS 12 or earlier).
1333 For each system there is a maximum frequency offset of the clock
1335 that can be set by the driver. On Linux it is 100000 ppm, on
1336 FreeBSD, NetBSD and macOS 10.13+ it is 5000 ppm, and on Solaris it
1337 is 32500 ppm. Also, due to a kernel limitation, setting maxslewrate
1338 on FreeBSD, NetBSD, macOS 10.13+ to a value between 500 ppm and
1339 5000 ppm will effectively set it to 500 ppm.
1340 In early beta releases of macOS 13 this capability is disabled
1342 because of a system kernel bug. When the kernel bug is fixed,
1343 chronyd will detect this and re-enable the capability (see above
1344 limitations) with no recompilation required.
1345 By default, the maximum slew rate is set to 83333.333 ppm (one
1347 twelfth).
1348 tempcomp file interval T0 k0 k1 k2, tempcomp file interval points-file
1350 Normally, changes in the rate of drift of the system clock are
1351 caused mainly by changes in the temperature of the crystal
1352 oscillator on the motherboard.
1353 If there are temperature measurements available from a sensor close
1355 to the oscillator, the tempcomp directive can be used to compensate
1356 for the changes in the temperature and improve the stability and
1357 accuracy of the clock.
1358 The result depends on many factors, including the resolution of the
1360 sensor, the amount of noise in the measurements, the polling
1361 interval of the time source, the compensation update interval, how
1362 well the compensation is specified, and how close the sensor is to
1363 the oscillator. When it is working well, the frequency reported in
1364 the tracking.log file is more stable and the maximum reached offset
1365 is smaller.
1366 There are two forms of the directive. The first one has six
1368 parameters: a path to the file containing the current temperature
1369 from the sensor (in text format), the compensation update interval
1370 (in seconds), and temperature coefficients T0, k0, k1, k2.
1371 The frequency compensation is calculated (in ppm) as
1373 comp = k0 + (T - T0) * k1 + (T - T0)^2 * k2
1375 The result has to be between -10 ppm and 10 ppm, otherwise the
1377 measurement is considered invalid and will be ignored. The k0
1378 coefficient can be adjusted to keep the compensation in that range.
1379 An example of the use is:
1381 tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 26000 0.0 0.000183 0.0
1383 The measured temperature will be read from the file in the Linux
1385 sysfs filesystem every 30 seconds. When the temperature is 26000
1386 (26 degrees Celsius), the frequency correction will be zero. When
1387 it is 27000 (27 degrees Celsius), the clock will be set to run
1388 faster by 0.183 ppm, etc.
1389 The second form has three parameters: the path to the sensor file,
1391 the update interval, and a path to a file containing a list of
1392 (temperature, compensation) points, from which the compensation is
1393 linearly interpolated or extrapolated.
1394 An example is:
1396 tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 /etc/chrony.tempcomp
1398 where the /etc/chrony.tempcomp file could have
1400 20000 1.0
1402 21000 0.64
1403 22000 0.36
1404 23000 0.16
1405 24000 0.04
1406 25000 0.0
1407 26000 0.04
1408 27000 0.16
1409 28000 0.36
1410 29000 0.64
1411 30000 1.0
1412 Valid measurements with corresponding compensations are logged to
1414 the tempcomp.log file if enabled by the log tempcomp directive.
1415 NTP server
1417 allow [all] [subnet]
1418 The allow directive is used to designate a particular subnet from
1419 which NTP clients are allowed to access the computer as an NTP
1420 server. It also controls access of NTS-KE clients when NTS is
1421 enabled on the server.
1422 The default is that no clients are allowed access, i.e. chronyd
1424 operates purely as an NTP client. If the allow directive is used,
1425 chronyd will be both a client of its servers, and a server to other
1426 clients.
1427 This directive can be used multiple times.
1429 Examples of the use of the directive are as follows:
1431 allow 1.2.3.4
1433 allow 1.2
1434 allow 3.4.5
1435 allow 6.7.8/22
1436 allow 6.7.8.9/22
1437 allow 2001:db8::/32
1438 allow 0/0
1439 allow ::/0
1440 allow
1441 The first directive allows a node with IPv4 address 1.2.3.4 to be
1443 an NTP client of this computer. The second directive allows any
1444 node with an IPv4 address of the form 1.2.x.y (with x and y
1445 arbitrary) to be an NTP client of this computer. Likewise, the
1446 third directive allows any node with an IPv4 address of the form
1447 3.4.5.x to have client NTP access. The fourth and fifth forms allow
1448 access from any node with an IPv4 address of the form 6.7.8.x,
1449 6.7.9.x, 6.7.10.x or 6.7.11.x (with x arbitrary), i.e. the value 22
1450 is the number of bits defining the specified subnet. In the fifth
1451 form, the final byte is ignored. The sixth form is used for IPv6
1452 addresses. The seventh and eighth forms allow access by any IPv4
1453 and IPv6 node respectively. The ninth forms allows access by any
1454 node (IPv4 or IPv6).
1455 A second form of the directive, allow all, has a greater effect,
1457 depending on the ordering of directives in the configuration file.
1458 To illustrate the effect, consider the two examples:
1459 allow 1.2.3.4
1461 deny 1.2.3
1462 allow 1.2
1463 and
1465 allow 1.2.3.4
1467 deny 1.2.3
1468 allow all 1.2
1469 In the first example, the effect is the same regardless of what
1471 order the three directives are given in. So the 1.2.x.y subnet is
1472 allowed access, except for the 1.2.3.x subnet, which is denied
1473 access, however the host 1.2.3.4 is allowed access.
1474 In the second example, the allow all 1.2 directives overrides the
1476 effect of any previous directive relating to a subnet within the
1477 specified subnet. Within a configuration file this capability is
1478 probably rather moot; however, it is of greater use for
1479 reconfiguration at run-time via chronyc with the allow all command.
1480 The directive allows a hostname to be specified instead of an IP
1482 address, but the name must be resolvable when chronyd is started
1483 (i.e. chronyd needs to be started when the network is already up
1484 and DNS is working).
1485 Note, if the initstepslew directive is used in the configuration
1487 file, each of the computers listed in that directive must allow
1488 client access by this computer for it to work.
1489 deny [all] [subnet]
1491 This is similar to the allow directive, except that it denies NTP
1492 and NTS-KE client access to a particular subnet or host, rather
1493 than allowing it.
1494 The syntax is identical and the directive can be used multiple
1496 times too.
1497 There is also a deny all directive with similar behaviour to the
1499 allow all directive.
1500 bindaddress address
1502 The bindaddress directive binds the sockets on which chronyd
1503 listens for NTP and NTS-KE requests to a local address of the
1504 computer. On systems other than Linux, the address of the computer
1505 needs to be already configured when chronyd is started.
1506 An example of the use of the directive is:
1508 bindaddress 192.168.1.1
1510 Currently, for each of the IPv4 and IPv6 protocols, only one
1512 bindaddress directive can be specified. Therefore, it is not useful
1513 on computers which should serve NTP on multiple network interfaces.
1514 binddevice interface
1516 The binddevice directive binds the NTP and NTS-KE server sockets to
1517 a network device specified by the interface name. This directive
1518 can specify only one interface and it is supported on Linux only.
1519 An example of the directive is:
1521 binddevice eth0
1523 broadcast interval address [port]
1525 The broadcast directive is used to declare a broadcast address to
1526 which chronyd should send packets in the NTP broadcast mode (i.e.
1527 make chronyd act as a broadcast server). Broadcast clients on that
1528 subnet will be able to synchronise.
1529 This directive can be used multiple times to specify multiple
1531 addresses.
1532 The syntax is as follows:
1534 broadcast 30 192.168.1.255
1536 broadcast 60 192.168.2.255 12123
1537 broadcast 60 ff02::101
1538 In the first example, the destination port defaults to UDP port 123
1540 (the normal NTP port). In the second example, the destination port
1541 is specified as 12123. The first parameter in each case (30 or 60
1542 respectively) is the interval in seconds between broadcast packets
1543 being sent. The second parameter in each case is the broadcast
1544 address to send the packet to. This should correspond to the
1545 broadcast address of one of the network interfaces on the computer
1546 where chronyd is running.
1547 You can have more than 1 broadcast directive if you have more than
1549 1 network interface onto which you want to send NTP broadcast
1550 packets.
1551 chronyd itself cannot act as a broadcast client; it must always be
1553 configured as a point-to-point client by defining specific NTP
1554 servers and peers. This broadcast server feature is intended for
1555 providing a time source to other NTP implementations.
1556 If ntpd is used as the broadcast client, it will try to measure the
1558 round-trip delay between the server and client with normal client
1559 mode packets. Thus, the broadcast subnet should also be the subject
1560 of an allow directive.
1561 clientloglimit limit
1563 This directive specifies the maximum amount of memory that chronyd
1564 is allowed to allocate for logging of client accesses and the state
1565 that chronyd as an NTP server needs to support the interleaved mode
1566 for its clients. The default limit is 524288 bytes, which is
1567 sufficient for monitoring about four thousand clients at the same
1568 time.
1569 In older chrony versions if the limit was set to 0, the memory
1571 allocation was unlimited.
1572 An example of the use of this directive is:
1574 clientloglimit 1048576
1576 noclientlog
1578 This directive, which takes no arguments, specifies that client
1579 accesses are not to be logged. Normally they are logged, allowing
1580 statistics to be reported using the clients command in chronyc.
1581 This option also effectively disables server support for the NTP
1582 interleaved mode.
1583 local [option]...
1585 The local directive enables a local reference mode, which allows
1586 chronyd operating as an NTP server to appear synchronised to real
1587 time (from the viewpoint of clients polling it), even when it was
1588 never synchronised or the last update of the clock happened a long
1589 time ago.
1590 This directive is normally used in an isolated network, where
1592 computers are required to be synchronised to one another, but not
1593 necessarily to real time. The server can be kept vaguely in line
1594 with real time by manual input.
1595 The local directive has the following options:
1597 stratum stratum
1599 This option sets the stratum of the server which will be
1600 reported to clients when the local reference is active. The
1601 specified value is in the range 1 through 15, and the default
1602 value is 10. It should be larger than the maximum expected
1603 stratum in the network when external NTP servers are
1604 accessible.
1605 Stratum 1 indicates a computer that has a true real-time
1607 reference directly connected to it (e.g. GPS, atomic clock,
1608 etc.), such computers are expected to be very close to real
1609 time. Stratum 2 computers are those which have a stratum 1
1610 server; stratum 3 computers have a stratum 2 server and so on.
1611 A value of 10 indicates that the clock is so many hops away
1612 from a reference clock that its time is fairly unreliable.
1613 distance distance
1615 This option sets the threshold for the root distance which will
1616 activate the local reference. If chronyd was synchronised to
1617 some source, the local reference will not be activated until
1618 its root distance reaches the specified value (the rate at
1619 which the distance is increasing depends on how well the clock
1620 was tracking the source). The default value is 1 second.
1621 The current root distance can be calculated from root delay and
1623 root dispersion (reported by the tracking command in chronyc)
1624 as:
1625 distance = delay / 2 + dispersion
1627 orphan
1629 This option enables a special ‘orphan’ mode, where sources with
1630 stratum equal to the local stratum are assumed to not serve
1631 real time. They are ignored unless no other source is
1632 selectable and their reference IDs are smaller than the local
1633 reference ID.
1634 This allows multiple servers in the network to use the same
1636 local configuration and to be synchronised to one another,
1637 without confusing clients that poll more than one server. Each
1638 server needs to be configured to poll all other servers with
1639 the local directive. This ensures only the server with the
1640 smallest reference ID has the local reference active and others
1641 are synchronised to it. If that server stops responding, the
1642 server with the second smallest reference ID will take over
1643 when its local reference mode activates (root distance reaches
1644 the threshold configured by the distance option).
1645 The orphan mode is compatible with the ntpd’s orphan mode
1647 (enabled by the tos orphan command).
1648 An example of the directive is:
1652 local stratum 10 orphan distance 0.1
1654 ntpsigndsocket directory
1656 This directive specifies the location of the Samba ntp_signd socket
1657 when it is running as a Domain Controller (DC). If chronyd is
1658 compiled with this feature, responses to MS-SNTP clients will be
1659 signed by the smbd daemon.
1660 Note that MS-SNTP requests are not authenticated and any client
1662 that is allowed to access the server by the allow directive, or the
1663 allow command in chronyc, can get an MS-SNTP response signed with a
1664 trust account’s password and try to crack the password in a
1665 brute-force attack. Access to the server should be carefully
1666 controlled.
1667 An example of the directive is:
1669 ntpsigndsocket /var/lib/samba/ntp_signd
1671 ntsport port
1673 This directive specifies the TCP port on which chronyd will provide
1674 the NTS Key Establishment (NTS-KE) service. The default port is
1675 4460.
1676 The port will be open only when a certificate and key is specified
1678 by the ntsservercert and ntsserverkey directives.
1679 ntsservercert file
1681 This directive specifies a file containing a certificate in the PEM
1682 format for chronyd to operate as an NTS server.
1683 ntsserverkey file
1685 This directive specifies a file containing a private key in the PEM
1686 format for chronyd to operate as an NTS server.
1687 ntsprocesses processes
1689 This directive specifies how many helper processes will chronyd
1690 operating as an NTS server start for handling client NTS-KE
1691 requests in order to improve performance with multi-core CPUs and
1692 multithreading. If set to 0, no helper process will be started and
1693 all NTS-KE requests will be handled by the main chronyd process.
1694 The default value is 1.
1695 maxntsconnections connections
1697 This directive specifies the maximum number of concurrent NTS-KE
1698 connections per process that the NTS server will accept. The
1699 default value is 100.
1700 ntsdumpdir directory
1702 This directive specifies a directory where chronyd operating as an
1703 NTS server can save the keys which encrypt NTS cookies provided to
1704 clients. The keys are saved to a single file named ntskeys. When
1705 chronyd is restarted, reloading the keys allows the clients to
1706 continue using old cookies and avoids a storm of NTS-KE requests.
1707 By default, the server does not save the keys.
1708 An example of the directive is:
1710 ntsdumpdir /var/lib/chrony
1712 This directory is used also by the NTS client to save NTS cookies.
1714 ntsntpserver hostname
1716 This directive specifies the hostname or address of the NTP
1717 server(s) which is provided in the NTS-KE response to the clients.
1718 It allows the NTS-KE server to be separated from the NTP server.
1719 However, the servers need to share the keys, i.e. external key
1720 management needs to be enabled by setting ntsrotate to 0. By
1721 default, no hostname or address is provided to the clients, which
1722 means they should use the same server for NTS-KE and NTP.
1723 ntsrotate interval
1725 This directive specifies the rotation interval (in seconds) of the
1726 server key which encrypts the NTS cookies. New keys are generated
1727 automatically from the /dev/urandom device. The server keeps two
1728 previous keys to give the clients time to get new cookies encrypted
1729 by the latest key. The interval is measured as the server’s
1730 operating time, i.e. the actual interval can be longer if chronyd
1731 is not running continuously. The default interval is 604800 seconds
1732 (1 week).
1733 The automatic rotation of the keys can be disabled by setting
1735 ntsrotate to 0. In this case the keys are assumed to be managed
1736 externally. chronyd will not save the keys to the ntskeys file and
1737 will reload the keys from the file when the rekey command is issued
1738 in chronyc. The file can be periodically copied from another server
1739 running chronyd (which does not have ntsrotate set to 0) in order
1740 to have one or more servers dedicated to NTS-KE. The NTS-KE servers
1741 need to be configured with the ntsntpname directive to point the
1742 clients to the right NTP server.
1743 An example of the directive is:
1745 ntsrotate 2592000
1747 port port
1749 This option allows you to configure the port on which chronyd will
1750 listen for NTP requests. The port will be open only when an address
1751 is allowed by the allow directive or the allow command in chronyc,
1752 an NTP peer is configured, or the broadcast server mode is enabled.
1753 The default value is 123, the standard NTP port. If set to 0,
1755 chronyd will never open the server port and will operate strictly
1756 in a client-only mode. The source port used in NTP client requests
1757 can be set by the acquisitionport directive.
1758 ratelimit [option]...
1760 This directive enables response rate limiting for NTP packets. Its
1761 purpose is to reduce network traffic with misconfigured or broken
1762 NTP clients that are polling the server too frequently. The limits
1763 are applied to individual IP addresses. If multiple clients share
1764 one IP address (e.g. multiple hosts behind NAT), the sum of their
1765 traffic will be limited. If a client that increases its polling
1766 rate when it does not receive a reply is detected, its rate
1767 limiting will be temporarily suspended to avoid increasing the
1768 overall amount of traffic. The maximum number of IP addresses which
1769 can be monitored at the same time depends on the memory limit set
1770 by the clientloglimit directive.
1771 The ratelimit directive supports a number of options (which can be
1773 defined in any order):
1774 interval
1776 This option sets the minimum interval between responses. It is
1777 defined as a power of 2 in seconds. The default value is 3 (8
1778 seconds). The minimum value is -19 (524288 packets per second)
1779 and the maximum value is 12 (one packet per 4096 seconds). Note
1780 that with values below -4 the rate limiting is coarse
1781 (responses are allowed in bursts, even if the interval between
1782 them is shorter than the specified interval).
1783 burst
1785 This option sets the maximum number of responses that can be
1786 sent in a burst, temporarily exceeding the limit specified by
1787 the interval option. This is useful for clients that make rapid
1788 measurements on start (e.g. chronyd with the iburst option).
1789 The default value is 8. The minimum value is 1 and the maximum
1790 value is 255.
1791 leak
1793 This option sets the rate at which responses are randomly
1794 allowed even if the limits specified by the interval and burst
1795 options are exceeded. This is necessary to prevent an attacker
1796 who is sending requests with a spoofed source address from
1797 completely blocking responses to that address. The leak rate is
1798 defined as a power of 1/2 and it is 2 by default, i.e. on
1799 average at least every fourth request has a response. The
1800 minimum value is 1 and the maximum value is 4.
1801 An example use of the directive is:
1805 ratelimit interval 1 burst 16
1807 This would reduce the response rate for IP addresses sending
1809 packets on average more than once per 2 seconds, or sending packets
1810 in bursts of more than 16 packets, by up to 75% (with default leak
1811 of 2).
1812 ntsratelimit [option]...
1814 This directive enables rate limiting of NTS-KE requests. It is
1815 similar to the ratelimit directive, except the default interval is
1816 6 (1 connection per 64 seconds).
1817 An example of the use of the directive is:
1819 ntsratelimit interval 3 burst 1
1821 smoothtime max-freq max-wander [leaponly]
1823 The smoothtime directive can be used to enable smoothing of the
1824 time that chronyd serves to its clients to make it easier for them
1825 to track it and keep their clocks close together even when large
1826 offset or frequency corrections are applied to the server’s clock,
1827 for example after being offline for a longer time.
1828 BE WARNED: The server is intentionally not serving its best
1830 estimate of the true time. If a large offset has been accumulated,
1831 it can take a very long time to smooth it out. This directive
1832 should be used only when the clients are not configured to also
1833 poll another NTP server, because they could reject this server as a
1834 falseticker or fail to select a source completely.
1835 The smoothing process is implemented with a quadratic spline
1837 function with two or three pieces. It is independent from any
1838 slewing applied to the local system clock, but the accumulated
1839 offset and frequency will be reset when the clock is corrected by
1840 stepping, e.g. by the makestep directive or the makestep command in
1841 chronyc. The process can be reset without stepping the clock by the
1842 smoothtime reset command.
1843 The first two arguments of the directive are the maximum frequency
1845 offset of the smoothed time to the tracked NTP time (in ppm) and
1846 the maximum rate at which the frequency offset is allowed to change
1847 (in ppm per second). leaponly is an optional third argument which
1848 enables a mode where only leap seconds are smoothed out and normal
1849 offset and frequency changes are ignored. The leaponly option is
1850 useful in a combination with the leapsecmode slew directive to
1851 allow the clients to use multiple time smoothing servers safely.
1852 The smoothing process is activated automatically when 1/10000 of
1854 the estimated skew of the local clock falls below the maximum rate
1855 of frequency change. It can be also activated manually by the
1856 smoothtime activate command, which is particularly useful when the
1857 clock is synchronised only with manual input and the skew is always
1858 larger than the threshold. The smoothing command can be used to
1859 monitor the process.
1860 An example suitable for clients using ntpd and 1024 second polling
1862 interval could be:
1863 smoothtime 400 0.001
1865 An example suitable for clients using chronyd on Linux could be:
1867 smoothtime 50000 0.01
1869 Command and monitoring access
1871 bindcmdaddress address
1872 The bindcmdaddress directive specifies a local IP address to which
1873 chronyd will bind the UDP socket listening for monitoring command
1874 packets (issued by chronyc). On systems other than Linux, the
1875 address of the interface needs to be already configured when
1876 chronyd is started.
1877 This directive can also change the path of the Unix domain command
1879 socket, which is used by chronyc to send configuration commands.
1880 The socket must be in a directory that is accessible only by the
1881 root or chrony user. The directory will be created on start if it
1882 does not exist. The compiled-in default path of the socket is
1883 /run/chrony/chronyd.sock. The socket can be disabled by setting the
1884 path to /.
1885 By default, chronyd binds the UDP sockets to the addresses
1887 127.0.0.1 and ::1 (i.e. the loopback interface). This blocks all
1888 access except from localhost. To listen for command packets on all
1889 interfaces, you can add the lines:
1890 bindcmdaddress 0.0.0.0
1892 bindcmdaddress ::
1893 to the configuration file.
1895 For each of the IPv4, IPv6, and Unix domain protocols, only one
1897 bindcmdaddress directive can be specified.
1898 An example that sets the path of the Unix domain command socket is:
1900 bindcmdaddress /var/run/chrony/chronyd.sock
1902 bindcmddevice interface
1904 The bindcmddevice directive binds the UDP command sockets to a
1905 network device specified by the interface name. This directive can
1906 specify only one interface and it is supported on Linux only.
1907 An example of the directive is:
1909 bindcmddevice eth0
1911 cmdallow [all] [subnet]
1913 This is similar to the allow directive, except that it allows
1914 monitoring access (rather than NTP client access) to a particular
1915 subnet or host. (By ‘monitoring access’ is meant that chronyc can
1916 be run on those hosts and retrieve monitoring data from chronyd on
1917 this computer.)
1918 The syntax is identical to the allow directive.
1920 There is also a cmdallow all directive with similar behaviour to
1922 the allow all directive (but applying to monitoring access in this
1923 case, of course).
1924 Note that chronyd has to be configured with the bindcmdaddress
1926 directive to not listen only on the loopback interface to actually
1927 allow remote access.
1928 cmddeny [all] [subnet]
1930 This is similar to the cmdallow directive, except that it denies
1931 monitoring access to a particular subnet or host, rather than
1932 allowing it.
1933 The syntax is identical.
1935 There is also a cmddeny all directive with similar behaviour to the
1937 cmdallow all directive.
1938 cmdport port
1940 The cmdport directive allows the port that is used for run-time
1941 monitoring (via the chronyc program) to be altered from its default
1942 (323). If set to 0, chronyd will not open the port, this is useful
1943 to disable chronyc access from the Internet. (It does not disable
1944 the Unix domain command socket.)
1945 An example shows the syntax:
1947 cmdport 257
1949 This would make chronyd use UDP 257 as its command port. (chronyc
1951 would need to be run with the -p 257 switch to inter-operate
1952 correctly.)
1953 cmdratelimit [option]...
1955 This directive enables response rate limiting for command packets.
1956 It is similar to the ratelimit directive, except responses to
1957 localhost are never limited and the default interval is -4 (16
1958 packets per second).
1959 An example of the use of the directive is:
1961 cmdratelimit interval 2
1963 Real-time clock (RTC)
1965 hwclockfile file
1966 The hwclockfile directive sets the location of the adjtime file
1967 which is used by the hwclock program on Linux. chronyd parses the
1968 file to find out if the RTC keeps local time or UTC. It overrides
1969 the rtconutc directive.
1970 The compiled-in default value is '/etc/adjtime'.
1972 An example of the directive is:
1974 hwclockfile /etc/adjtime
1976 rtcautotrim threshold
1978 The rtcautotrim directive is used to keep the RTC close to the
1979 system clock automatically. When the system clock is synchronised
1980 and the estimated error between the two clocks is larger than the
1981 specified threshold, chronyd will trim the RTC as if the trimrtc
1982 command in chronyc was issued. The trimming operation is accurate
1983 to only about 1 second, which is the minimum effective threshold.
1984 This directive is effective only with the rtcfile directive.
1986 An example of the use of this directive is:
1988 rtcautotrim 30
1990 This would set the threshold error to 30 seconds.
1992 rtcdevice device
1994 The rtcdevice directive sets the path to the device file for
1995 accessing the RTC. The default path is /dev/rtc.
1996 rtcfile file
1998 The rtcfile directive defines the name of the file in which chronyd
1999 can save parameters associated with tracking the accuracy of the
2000 RTC.
2001 An example of the directive is:
2003 rtcfile /var/lib/chrony/rtc
2005 chronyd saves information in this file when it exits and when the
2007 writertc command is issued in chronyc. The information saved is the
2008 RTC’s error at some epoch, that epoch (in seconds since January 1
2009 1970), and the rate at which the RTC gains or loses time.
2010 So far, the support for real-time clocks is limited; their code is
2012 even more system-specific than the rest of the software. You can
2013 only use the RTC facilities (the rtcfile directive and the -s
2014 command-line option to chronyd) if the following three conditions
2015 apply:
2016 1. You are running Linux.
2018 2. The kernel is compiled with extended real-time clock support
2020 (i.e. the /dev/rtc device is capable of doing useful things).
2021 3. You do not have other applications that need to make use of
2023 /dev/rtc at all.
2024 rtconutc
2026 chronyd assumes by default that the RTC keeps local time (including
2027 any daylight saving changes). This is convenient on PCs running
2028 Linux which are dual-booted with Windows.
2029 If you keep the RTC on local time and your computer is off when
2031 daylight saving (summer time) starts or ends, the computer’s system
2032 time will be one hour in error when you next boot and start
2033 chronyd.
2034 An alternative is for the RTC to keep Universal Coordinated Time
2036 (UTC). This does not suffer from the 1 hour problem when daylight
2037 saving starts or ends.
2038 If the rtconutc directive appears, it means the RTC is required to
2040 keep UTC. The directive takes no arguments. It is equivalent to
2041 specifying the -u switch to the Linux hwclock program.
2042 Note that this setting is overridden by the hwclockfile file and is
2044 not relevant for the rtcsync directive.
2045 rtcsync
2047 The rtcsync directive enables a mode where the system time is
2048 periodically copied to the RTC and chronyd does not try to track
2049 its drift. This directive cannot be used with the rtcfile
2050 directive.
2051 On Linux, the RTC copy is performed by the kernel every 11 minutes.
2053 On macOS, chronyd will perform the RTC copy every 60 minutes when
2055 the system clock is in a synchronised state.
2056 On other systems this directive does nothing.
2058 Logging
2060 log [option]...
2061 The log directive indicates that certain information is to be
2062 logged. The log files are written to the directory specified by the
2063 logdir directive. A banner is periodically written to the files to
2064 indicate the meanings of the columns.
2065 rawmeasurements
2067 This option logs the raw NTP measurements and related
2068 information to a file called measurements.log. An entry is made
2069 for each packet received from the source. This can be useful
2070 when debugging a problem. An example line (which actually
2071 appears as a single line in the file) from the log file is
2072 shown below.
2073 2016-11-09 05:40:50 203.0.113.15 N 2 111 111 1111 10 10 1.0 \
2075 -4.966e-03 2.296e-01 1.577e-05 1.615e-01 7.446e-03 CB00717B 4B D K
2076 The columns are as follows (the quantities in square brackets
2078 are the values from the example line above):
2079 1. Date [2015-10-13]
2081 2. Hour:Minute:Second. Note that the date-time pair is
2083 expressed in UTC, not the local time zone. [05:40:50]
2084 3. IP address of server or peer from which measurement came
2086 [203.0.113.15]
2087 4. Leap status (N means normal, + means that the last minute
2089 of the current month has 61 seconds, - means that the last
2090 minute of the month has 59 seconds, ? means the remote
2091 computer is not currently synchronised.) [N]
2092 5. Stratum of remote computer. [2]
2094 6. RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111]
2096 7. RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111]
2098 8. Tests for maximum delay, maximum delay ratio and maximum
2100 delay dev ratio, against defined parameters, and a test for
2101 synchronisation loop (1=pass, 0=fail) [1111]
2102 9. Local poll [10]
2104 10. Remote poll [10]
2106 11. ‘Score’ (an internal score within each polling level used
2108 to decide when to increase or decrease the polling level.
2109 This is adjusted based on number of measurements currently
2110 being used for the regression algorithm). [1.0]
2111 12. The estimated local clock error (theta in RFC 5905).
2113 Positive indicates that the local clock is slow of the
2114 remote source. [-4.966e-03]
2115 13. The peer delay (delta in RFC 5905). [2.296e-01]
2117 14. The peer dispersion (epsilon in RFC 5905). [1.577e-05]
2119 15. The root delay (DELTA in RFC 5905). [1.615e-01]
2121 16. The root dispersion (EPSILON in RFC 5905). [7.446e-03]
2123 17. Reference ID of the server’s source as a hexadecimal
2125 number. [CB00717B]
2126 18. NTP mode of the received packet (1=active peer, 2=passive
2128 peer, 4=server, B=basic, I=interleaved). [4B]
2129 19. Source of the local transmit timestamp (D=daemon,
2131 K=kernel, H=hardware). [D]
2132 20. Source of the local receive timestamp (D=daemon, K=kernel,
2134 H=hardware). [K]
2135 measurements
2137 This option is identical to the rawmeasurements option, except
2138 it logs only valid measurements from synchronised sources, i.e.
2139 measurements which passed the RFC 5905 tests 1 through 7. This
2140 can be useful for producing graphs of the source’s performance.
2141 statistics
2143 This option logs information about the regression processing to
2144 a file called statistics.log. An example line (which actually
2145 appears as a single line in the file) from the log file is
2146 shown below.
2147 2016-08-10 05:40:50 203.0.113.15 6.261e-03 -3.247e-03 \
2149 2.220e-03 1.874e-06 1.080e-06 7.8e-02 16 0 8 0.00
2150 The columns are as follows (the quantities in square brackets
2152 are the values from the example line above):
2153 1. Date [2015-07-22]
2155 2. Hour:Minute:Second. Note that the date-time pair is
2157 expressed in UTC, not the local time zone. [05:40:50]
2158 3. IP address of server or peer from which measurement comes
2160 [203.0.113.15]
2161 4. The estimated standard deviation of the measurements from
2163 the source (in seconds). [6.261e-03]
2164 5. The estimated offset of the source (in seconds, positive
2166 means the local clock is estimated to be fast, in this
2167 case). [-3.247e-03]
2168 6. The estimated standard deviation of the offset estimate (in
2170 seconds). [2.220e-03]
2171 7. The estimated rate at which the local clock is gaining or
2173 losing time relative to the source (in seconds per second,
2174 positive means the local clock is gaining). This is
2175 relative to the compensation currently being applied to the
2176 local clock, not to the local clock without any
2177 compensation. [1.874e-06]
2178 8. The estimated error in the rate value (in seconds per
2180 second). [1.080e-06].
2181 9. The ratio of |old_rate - new_rate| / old_rate_error. Large
2183 values indicate the statistics are not modelling the source
2184 very well. [7.8e-02]
2185 10. The number of measurements currently being used for the
2187 regression algorithm. [16]
2188 11. The new starting index (the oldest sample has index 0;
2190 this is the method used to prune old samples when it no
2191 longer looks like the measurements fit a linear model). [0,
2192 i.e. no samples discarded this time]
2193 12. The number of runs. The number of runs of regression
2195 residuals with the same sign is computed. If this is too
2196 small it indicates that the measurements are no longer
2197 represented well by a linear model and that some older
2198 samples need to be discarded. The number of runs for the
2199 data that is being retained is tabulated. Values of
2200 approximately half the number of samples are expected. [8]
2201 13. The estimated or configured asymmetry of network jitter on
2203 the path to the source which was used to correct the
2204 measured offsets. The asymmetry can be between -0.5 and
2205 +0.5. A negative value means the delay of packets sent to
2206 the source is more variable than the delay of packets sent
2207 from the source back. [0.00, i.e. no correction for
2208 asymmetry]
2209 tracking
2211 This option logs changes to the estimate of the system’s gain
2212 or loss rate, and any slews made, to a file called
2213 tracking.log. An example line (which actually appears as a
2214 single line in the file) from the log file is shown below.
2215 2017-08-22 13:22:36 203.0.113.15 2 -3.541 0.075 -8.621e-06 N \
2217 2 2.940e-03 -2.084e-04 1.534e-02 3.472e-04 8.304e-03
2218 The columns are as follows (the quantities in square brackets
2220 are the values from the example line above) :
2221 1. Date [2017-08-22]
2223 2. Hour:Minute:Second. Note that the date-time pair is
2225 expressed in UTC, not the local time zone. [13:22:36]
2226 3. The IP address of the server or peer to which the local
2228 system is synchronised. [203.0.113.15]
2229 4. The stratum of the local system. [2]
2231 5. The local system frequency (in ppm, positive means the
2233 local system runs fast of UTC). [-3.541]
2234 6. The error bounds on the frequency (in ppm). [0.075]
2236 7. The estimated local offset at the epoch, which is normally
2238 corrected by slewing the local clock (in seconds, positive
2239 indicates the clock is fast of UTC). [-8.621e-06]
2240 8. Leap status (N means normal, + means that the last minute
2242 of this month has 61 seconds, - means that the last minute
2243 of the month has 59 seconds, ? means the clock is not
2244 currently synchronised.) [N]
2245 9. The number of combined sources. [2]
2247 10. The estimated standard deviation of the combined offset
2249 (in seconds). [2.940e-03]
2250 11. The remaining offset correction from the previous update
2252 (in seconds, positive means the system clock is slow of
2253 UTC). [-2.084e-04]
2254 12. The total of the network path delays to the reference
2256 clock to which the local clock is ultimately synchronised
2257 (in seconds). [1.534e-02]
2258 13. The total dispersion accumulated through all the servers
2260 back to the reference clock to which the local clock is
2261 ultimately synchronised (in seconds). [3.472e-04]
2262 14. The maximum estimated error of the system clock in the
2264 interval since the previous update (in seconds). It
2265 includes the offset, remaining offset correction, root
2266 delay, and dispersion from the previous update with the
2267 dispersion which accumulated in the interval. [8.304e-03]
2268 rtc
2270 This option logs information about the system’s real-time
2271 clock. An example line (which actually appears as a single line
2272 in the file) from the rtc.log file is shown below.
2273 2015-07-22 05:40:50 -0.037360 1 -0.037434\
2275 -37.948 12 5 120
2276 The columns are as follows (the quantities in square brackets
2278 are the values from the example line above):
2279 1. Date [2015-07-22]
2281 2. Hour:Minute:Second. Note that the date-time pair is
2283 expressed in UTC, not the local time zone. [05:40:50]
2284 3. The measured offset between the RTC and the system clock in
2286 seconds. Positive indicates that the RTC is fast of the
2287 system time [-0.037360].
2288 4. Flag indicating whether the regression has produced valid
2290 coefficients. (1 for yes, 0 for no). [1]
2291 5. Offset at the current time predicted by the regression
2293 process. A large difference between this value and the
2294 measured offset tends to indicate that the measurement is
2295 an outlier with a serious measurement error. [-0.037434]
2296 6. The rate at which the RTC is losing or gaining time
2298 relative to the system clock. In ppm, with positive
2299 indicating that the RTC is gaining time. [-37.948]
2300 7. The number of measurements used in the regression. [12]
2302 8. The number of runs of regression residuals of the same
2304 sign. Low values indicate that a straight line is no longer
2305 a good model of the measured data and that older
2306 measurements should be discarded. [5]
2307 9. The measurement interval used prior to the measurement
2309 being made (in seconds). [120]
2310 refclocks
2312 This option logs the raw and filtered reference clock
2313 measurements to a file called refclocks.log. An example line
2314 (which actually appears as a single line in the file) from the
2315 log file is shown below.
2316 2009-11-30 14:33:27.000000 PPS2 7 N 1 4.900000e-07 -6.741777e-07 1.000e-06
2318 The columns are as follows (the quantities in square brackets
2320 are the values from the example line above):
2321 1. Date [2009-11-30]
2323 2. Hour:Minute:Second.Microsecond. Note that the date-time
2325 pair is expressed in UTC, not the local time zone.
2326 [14:33:27.000000]
2327 3. Reference ID of the reference clock from which the
2329 measurement came. [PPS2]
2330 4. Sequence number of driver poll within one polling interval
2332 for raw samples, or - for filtered samples. [7]
2333 5. Leap status (N means normal, + means that the last minute
2335 of the current month has 61 seconds, - means that the last
2336 minute of the month has 59 seconds). [N]
2337 6. Flag indicating whether the sample comes from PPS source.
2339 (1 for yes, 0 for no, or - for filtered sample). [1]
2340 7. Local clock error measured by reference clock driver, or -
2342 for filtered sample. [4.900000e-07]
2343 8. Local clock error with applied corrections. Positive
2345 indicates that the local clock is slow. [-6.741777e-07]
2346 9. Assumed dispersion of the sample. [1.000e-06]
2348 tempcomp
2350 This option logs the temperature measurements and system rate
2351 compensations to a file called tempcomp.log. An example line
2352 (which actually appears as a single line in the file) from the
2353 log file is shown below.
2354 2015-04-19 10:39:48 2.8000e+04 3.6600e-01
2356 The columns are as follows (the quantities in square brackets
2358 are the values from the example line above):
2359 1. Date [2015-04-19]
2361 2. Hour:Minute:Second. Note that the date-time pair is
2363 expressed in UTC, not the local time zone. [10:39:48]
2364 3. Temperature read from the sensor. [2.8000e+04]
2366 4. Applied compensation in ppm, positive means the system
2368 clock is running faster than it would be without the
2369 compensation. [3.6600e-01]
2370 An example of the directive is:
2373 log measurements statistics tracking
2375 logbanner entries
2377 A banner is periodically written to the log files enabled by the
2378 log directive to indicate the meanings of the columns.
2379 The logbanner directive specifies after how many entries in the log
2381 file should be the banner written. The default is 32, and 0 can be
2382 used to disable it entirely.
2383 logchange threshold
2385 This directive sets the threshold for the adjustment of the system
2386 clock that will generate a syslog message. Clock errors detected
2387 via NTP packets, reference clocks, or timestamps entered via the
2388 settime command of chronyc are logged.
2389 By default, the threshold is 1 second.
2391 An example of the use is:
2393 logchange 0.1
2395 which would cause a syslog message to be generated if a system
2397 clock error of over 0.1 seconds starts to be compensated.
2398 logdir directory
2400 This directive specifies the directory for writing log files
2401 enabled by the log directive. If the directory does not exist, it
2402 will be created automatically.
2403 An example of the use of this directive is:
2405 logdir /var/log/chrony
2407 mailonchange email threshold
2409 This directive defines an email address to which mail should be
2410 sent if chronyd applies a correction exceeding a particular
2411 threshold to the system clock.
2412 An example of the use of this directive is:
2414 mailonchange root@localhost 0.5
2416 This would send a mail message to root if a change of more than 0.5
2418 seconds were applied to the system clock.
2419 This directive cannot be used when a system call filter is enabled
2421 by the -F option as the chronyd process will not be allowed to fork
2422 and execute the sendmail binary.
2423 Miscellaneous
2425 confdir directory...
2426 The confdir directive includes configuration files with the .conf
2427 suffix from a directory. The files are included in the
2428 lexicographical order of the file names.
2429 Multiple directories (up to 10) can be specified with a single
2431 confdir directive. In this case, if multiple directories contain a
2432 file with the same name, only the first file in the order of the
2433 specified directories will be included. This enables a fragmented
2434 configuration where existing fragments can be replaced by adding
2435 files to a different directory.
2436 This directive can be used multiple times.
2438 An example of the directive is:
2440 confdir /etc/chrony.d
2442 sourcedir directory...
2444 The sourcedir directive is identical to the confdir directive,
2445 except the configuration files have the .sources suffix, they can
2446 only specify NTP sources (i.e. use the server, pool, and peer
2447 directive), and can be reloaded by the reload sources command in
2448 chronyc. It is particularly useful with dynamic sources like NTP
2449 servers received from a DHCP server, which can be written to a file
2450 specific to the network interface by a networking script.
2451 This directive can be used multiple times.
2453 An example of the directive is:
2455 sourcedir /var/run/chrony-dhcp
2457 include pattern
2459 The include directive includes a configuration file, or multiple
2460 configuration files if a wildcard pattern is specified. Unlike with
2461 the confdir directive, the full name of the files needs to be
2462 specified and at least one file is required to exist.
2463 This directive can be used multiple times.
2465 An example of the directive is:
2467 include /etc/chrony.d/*.conf
2469 hwtimestamp interface [option]...
2471 This directive enables hardware timestamping of NTP packets sent to
2472 and received from the specified network interface. The network
2473 interface controller (NIC) uses its own clock to accurately
2474 timestamp the actual transmissions and receptions, avoiding
2475 processing and queueing delays in the kernel, network driver, and
2476 hardware. This can significantly improve the accuracy of the
2477 timestamps and the measured offset, which is used for
2478 synchronisation of the system clock. In order to get the best
2479 results, both sides receiving and sending NTP packets (i.e. server
2480 and client, or two peers) need to use HW timestamping. If the
2481 server or peer supports the interleaved mode, it needs to be
2482 enabled by the xleave option in the server or the peer directive.
2483 This directive is supported on Linux 3.19 and newer. The NIC must
2485 support HW timestamping, which can be verified with the ethtool -T
2486 command. The list of capabilities should include
2487 SOF_TIMESTAMPING_RAW_HARDWARE, SOF_TIMESTAMPING_TX_HARDWARE, and
2488 SOF_TIMESTAMPING_RX_HARDWARE. Receive filter HWTSTAMP_FILTER_ALL,
2489 or HWTSTAMP_FILTER_NTP_ALL, is necessary for timestamping of
2490 received packets. Timestamping of packets received from bridged and
2491 bonded interfaces is supported on Linux 4.13 and newer. When
2492 chronyd is running, no other process (e.g. a PTP daemon) should be
2493 working with the NIC clock.
2494 If the kernel supports software timestamping, it will be enabled
2496 for all interfaces. The source of timestamps (i.e. hardware,
2497 kernel, or daemon) is indicated in the measurements.log file if
2498 enabled by the log measurements directive, and the ntpdata report
2499 in chronyc.
2500 This directive can be used multiple times to enable HW timestamping
2502 on multiple interfaces. If the specified interface is *, chronyd
2503 will try to enable HW timestamping on all available interfaces.
2504 The hwtimestamp directive has the following options:
2506 minpoll poll
2508 This option specifies the minimum interval between readings of
2509 the NIC clock. It’s defined as a power of two. It should
2510 correspond to the minimum polling interval of all NTP sources
2511 and the minimum expected polling interval of NTP clients. The
2512 default value is 0 (1 second) and the minimum value is -6
2513 (1/64th of a second).
2514 minsamples samples
2516 This option specifies the minimum number of readings kept for
2517 tracking of the NIC clock. The default value is 2.
2518 maxsamples samples
2520 This option specifies the maximum number of readings kept for
2521 tracking of the NIC clock. The default value is 16.
2522 precision precision
2524 This option specifies the assumed precision of reading of the
2525 NIC clock. The default value is 100e-9 (100 nanoseconds).
2526 txcomp compensation
2528 This option specifies the difference in seconds between the
2529 actual transmission time at the physical layer and the reported
2530 transmit timestamp. This value will be added to transmit
2531 timestamps obtained from the NIC. The default value is 0.
2532 rxcomp compensation
2534 This option specifies the difference in seconds between the
2535 reported receive timestamp and the actual reception time at the
2536 physical layer. This value will be subtracted from receive
2537 timestamps obtained from the NIC. The default value is 0.
2538 nocrossts
2540 Some hardware can precisely cross timestamp the NIC clock with
2541 the system clock. This option disables the use of the cross
2542 timestamping.
2543 rxfilter filter
2545 This option selects the receive timestamping filter. The filter
2546 can be one of the following:
2547 all
2549 Enables timestamping of all received packets.
2550 ntp
2552 Enables timestamping of received NTP packets.
2553 none
2555 Disables timestamping of received packets.
2556 The most specific filter for timestamping NTP packets which is
2559 supported by the NIC is selected by default. Some NICs can
2560 timestamp only PTP packets, which limits the selection to the
2561 none filter. Forcing timestamping of all packets with the all
2562 filter when the NIC supports both all and ntp filters can be
2563 useful when packets are received from or on a non-standard UDP
2564 port (e.g. specified by the port directive).
2565 Examples of the directive are:
2569 hwtimestamp eth0
2571 hwtimestamp eth1 txcomp 300e-9 rxcomp 645e-9
2572 hwtimestamp *
2573 keyfile file
2575 This directive is used to specify the location of the file
2576 containing symmetric keys which are shared between NTP servers and
2577 clients, or peers, in order to authenticate NTP packets with a
2578 message authentication code (MAC) using a cryptographic hash
2579 function or cipher.
2580 The format of the directive is shown in the example below:
2582 keyfile /etc/chrony.keys
2584 The argument is simply the name of the file containing the ID-key
2586 pairs. The format of the file is shown below:
2587 10 tulip
2589 11 hyacinth
2590 20 MD5 ASCII:crocus
2591 25 SHA1 HEX:933F62BE1D604E68A81B557F18CFA200483F5B70
2592 30 AES128 HEX:7EA62AE64D190114D46D5A082F948EC1
2593 31 AES256 HEX:37DDCBC67BB902BCB8E995977FAB4D2B5642F5B32EBCEEE421921D97E5CBFE39
2594 ...
2595 Each line consists of an ID, optional type, and key.
2597 The ID can be any positive integer in the range 1 through 2^32-1.
2599 The type is a name of a cryptographic hash function or cipher which
2601 is used to generate and verify the MAC. The default type is MD5,
2602 which is always supported. If chronyd was built with enabled
2603 support for hashing using a crypto library (nettle, nss, or
2604 libtomcrypt), the following functions are available: MD5, SHA1,
2605 SHA256, SHA384, SHA512. Depending on which library and version is
2606 chronyd using, some of the following hash functions and ciphers may
2607 also be available: SHA3-224, SHA3-256, SHA3-384, SHA3-512, TIGER,
2608 WHIRLPOOL, AES128, AES256.
2609 The key can be specified as a string of ASCII characters not
2611 containing white space with an optional ASCII: prefix, or as a
2612 hexadecimal number with the HEX: prefix. The maximum length of the
2613 line is 2047 characters. If the type is a cipher, the length of the
2614 key must match the cipher (i.e. 128 bits for AES128 and 256 bits
2615 for AES256).
2616 It is recommended to use randomly generated keys, specified in the
2618 hexadecimal format, which are at least 128 bits long (i.e. they
2619 have at least 32 characters after the HEX: prefix). chronyd will
2620 log a warning to syslog on start if a source is specified in the
2621 configuration file with a key shorter than 80 bits.
2622 The recommended key types are AES ciphers and SHA3 hash functions.
2624 MD5 should be avoided unless no other type is supported on the
2625 server and client, or peers.
2626 The keygen command of chronyc can be used to generate random keys
2628 for the key file. By default, it generates 160-bit MD5 or SHA1
2629 keys.
2630 For security reasons, the file should be readable only by root and
2632 the user under which chronyd is normally running (to allow chronyd
2633 to re-read the file when the rekey command is issued by chronyc).
2634 lock_all
2636 The lock_all directive will lock chronyd into RAM so that it will
2637 never be paged out. This mode is supported on Linux, FreeBSD,
2638 NetBSD, and Solaris. This directive uses the POSIX mlockall()
2639 system call to prevent chronyd from ever being swapped out. This
2640 should result in lower and more consistent latency. It should not
2641 have significant impact on performance as chronyd’s memory usage is
2642 modest. The mlockall(2) man page has more details.
2643 pidfile file
2645 Unless chronyd is started with the -Q option, it writes its process
2646 ID (PID) to a file, and checks this file on startup to see if
2647 another chronyd might already be running on the system. By default,
2648 the file used is /run/chrony/chronyd.pid. The pidfile directive
2649 allows the name to be changed, e.g.:
2650 pidfile /run/chronyd.pid
2652 sched_priority priority
2654 On Linux, FreeBSD, NetBSD, and Solaris, the sched_priority
2655 directive will select the SCHED_FIFO real-time scheduler at the
2656 specified priority (which must be between 0 and 100). On macOS,
2657 this option must have either a value of 0 (the default) to disable
2658 the thread time constraint policy or 1 for the policy to be
2659 enabled.
2660 On systems other than macOS, this directive uses the
2662 pthread_setschedparam() system call to instruct the kernel to use
2663 the SCHED_FIFO first-in, first-out real-time scheduling policy for
2664 chronyd with the specified priority. This means that whenever
2665 chronyd is ready to run it will run, interrupting whatever else is
2666 running unless it is a higher priority real-time process. This
2667 should not impact performance as chronyd resource requirements are
2668 modest, but it should result in lower and more consistent latency
2669 since chronyd will not need to wait for the scheduler to get around
2670 to running it. You should not use this unless you really need it.
2671 The pthread_setschedparam(3) man page has more details.
2672 On macOS, this directive uses the thread_policy_set() kernel call
2674 to specify real-time scheduling. As noted above, you should not use
2675 this directive unless you really need it.
2676 user user
2678 The user directive sets the name of the system user to which
2679 chronyd will switch after start in order to drop root privileges.
2680 On Linux, chronyd needs to be compiled with support for the libcap
2682 library. On macOS, FreeBSD, NetBSD and Solaris chronyd forks into
2683 two processes. The child process retains root privileges, but can
2684 only perform a very limited range of privileged system calls on
2685 behalf of the parent.
2686 The compiled-in default value is chrony.
2688
2690 NTP client with permanent connection to NTP servers
2691 This section shows how to configure chronyd for computers that are
2692 connected to the Internet (or to any network containing true NTP
2693 servers which ultimately derive their time from a reference clock)
2694 permanently or most of the time.
2695 To operate in this mode, you will need to know the names of the NTP
2697 servers you want to use. You might be able to find names of suitable
2698 servers by one of the following methods:
2699 · Your institution might already operate servers on its network.
2701 Contact your system administrator to find out.
2702 · Your ISP probably has one or more NTP servers available for its
2704 customers.
2705 · Somewhere under the NTP homepage there is a list of public stratum
2707 1 and stratum 2 servers. You should find one or more servers that
2708 are near to you. Check that their access policy allows you to use
2709 their facilities.
2710 · Use public servers from the pool.ntp.org
2712 <https://www.pool.ntp.org/> project.
2713 Assuming that your NTP servers are called foo.example.net,
2715 bar.example.net and baz.example.net, your chrony.conf file could
2716 contain as a minimum:
2717 server foo.example.net
2719 server bar.example.net
2720 server baz.example.net
2721 However, you will probably want to include some of the other
2723 directives. The driftfile, makestep and rtcsync might be particularly
2724 useful. Also, the iburst option of the server directive is useful to
2725 speed up the initial synchronisation. The smallest useful configuration
2726 file would look something like:
2727 server foo.example.net iburst
2729 server bar.example.net iburst
2730 server baz.example.net iburst
2731 driftfile /var/lib/chrony/drift
2732 makestep 1.0 3
2733 rtcsync
2734 When using a pool of NTP servers (one name is used for multiple servers
2736 which might change over time), it is better to specify them with the
2737 pool directive instead of multiple server directives. The configuration
2738 file could in this case look like:
2739 pool pool.ntp.org iburst
2741 driftfile /var/lib/chrony/drift
2742 makestep 1.0 3
2743 rtcsync
2744 If the servers (or pool) support the Network Time Security (NTS)
2746 authentication mechanism and chronyd is compiled with NTS support, the
2747 nts option will enable a secure synchronisation to the servers. The
2748 configuration file could look like:
2749 server foo.example.net iburst nts
2751 server bar.example.net iburst nts
2752 server baz.example.net iburst nts
2753 driftfile /var/lib/chrony/drift
2754 makestep 1.0 3
2755 rtcsync
2756 NTP client with infrequent connection to NTP servers
2758 This section shows how to configure chronyd for computers that have
2759 occasional connections to NTP servers. In this case, you will need some
2760 additional configuration to tell chronyd when the connection goes up
2761 and down. This saves the program from continuously trying to poll the
2762 servers when they are inaccessible.
2763 Again, assuming that your NTP servers are called foo.example.net,
2765 bar.example.net and baz.example.net, your chrony.conf file would now
2766 contain:
2767 server foo.example.net offline
2769 server bar.example.net offline
2770 server baz.example.net offline
2771 driftfile /var/lib/chrony/drift
2772 makestep 1.0 3
2773 rtcsync
2774 The offline keyword indicates that the servers start in an offline
2776 state, and that they should not be contacted until chronyd receives
2777 notification from chronyc that the link to the Internet is present. To
2778 tell chronyd when to start and finish sampling the servers, the online
2779 and offline commands of chronyc need to be used.
2780 To give an example of their use, assuming that pppd is the program
2782 being used to connect to the Internet and that chronyc has been
2783 installed at /usr/bin/chronyc, the script /etc/ppp/ip-up would include:
2784 /usr/bin/chronyc online
2786 and the script /etc/ppp/ip-down would include:
2788 /usr/bin/chronyc offline
2790 chronyd’s polling of the servers would now only occur whilst the
2792 machine is actually connected to the Internet.
2793 Isolated networks
2795 This section shows how to configure chronyd for computers that never
2796 have network connectivity to any computer which ultimately derives its
2797 time from a reference clock.
2798 In this situation, one computer is selected to be the master
2800 timeserver. The other computers are either direct clients of the
2801 master, or clients of clients.
2802 The local directive enables a local reference mode, which allows
2804 chronyd to appear synchronised even when it is not.
2805 The rate value in the master’s drift file needs to be set to the
2807 average rate at which the master gains or loses time. chronyd includes
2808 support for this, in the form of the manual directive and the settime
2809 command in the chronyc program.
2810 If the master is rebooted, chronyd can re-read the drift rate from the
2812 drift file. However, the master has no accurate estimate of the current
2813 time. To get around this, the system can be configured so that the
2814 master can initially set itself to a ‘majority-vote’ of selected
2815 clients' times; this allows the clients to ‘flywheel’ the master while
2816 it is rebooting.
2817 The smoothtime directive is useful when the clocks of the clients need
2819 to stay close together when the local time is adjusted by the settime
2820 command. The smoothing process needs to be activated by the smoothtime
2821 activate command when the local time is ready to be served. After that
2822 point, any adjustments will be smoothed out.
2823 A typical configuration file for the master (called master) might be
2825 (assuming the clients and the master are in the 192.168.165.x subnet):
2826 initstepslew 1 client1 client3 client6
2828 driftfile /var/lib/chrony/drift
2829 local stratum 8
2830 manual
2831 allow 192.168.165.0/24
2832 smoothtime 400 0.01
2833 rtcsync
2834 For the clients that have to resynchronise the master when it restarts,
2836 the configuration file might be:
2837 server master iburst
2839 driftfile /var/lib/chrony/drift
2840 allow 192.168.165.0/24
2841 makestep 1.0 3
2842 rtcsync
2843 The rest of the clients would be the same, except that the allow
2845 directive is not required.
2846 If there is no suitable computer to be designated as the master, or
2848 there is a requirement to keep the clients synchronised even when it
2849 fails, the orphan option of the local directive enables a special mode
2850 where the master is selected from multiple computers automatically.
2851 They all need to use the same local configuration and poll one another.
2852 The server with the smallest reference ID (which is based on its IP
2853 address) will take the role of the master and others will be
2854 synchronised to it. When it fails, the server with the second smallest
2855 reference ID will take over and so on.
2856 A configuration file for the first server might be (assuming there are
2858 three servers called master1, master2, and master3):
2859 initstepslew 1 master2 master3
2861 server master2
2862 server master3
2863 driftfile /var/lib/chrony/drift
2864 local stratum 8 orphan
2865 manual
2866 allow 192.168.165.0/24
2867 rtcsync
2868 The other servers would be the same, except the hostnames in the
2870 initstepslew and server directives would be modified to specify the
2871 other servers. Their clients might be configured to poll all three
2872 servers.
2873 RTC tracking
2875 This section considers a computer which has occasional connections to
2876 the Internet and is turned off between ‘sessions’. In this case,
2877 chronyd relies on the computer’s RTC to maintain the time between the
2878 periods when it is powered up. It assumes that Linux is run exclusively
2879 on the computer. Dual-boot systems might work; it depends what (if
2880 anything) the other system does to the RTC. On 2.6 and later kernels,
2881 if your motherboard has a HPET, you will need to enable the
2882 HPET_EMULATE_RTC option in your kernel configuration. Otherwise,
2883 chronyd will not be able to interact with the RTC device and will give
2884 up using it.
2885 When the computer is connected to the Internet, chronyd has access to
2887 external NTP servers which it makes measurements from. These
2888 measurements are saved, and straight-line fits are performed on them to
2889 provide an estimate of the computer’s time error and rate of gaining or
2890 losing time.
2891 When the computer is taken offline from the Internet, the best estimate
2893 of the gain or loss rate is used to free-run the computer until it next
2894 goes online.
2895 Whilst the computer is running, chronyd makes measurements of the RTC
2897 (via the /dev/rtc interface, which must be compiled into the kernel).
2898 An estimate is made of the RTC error at a particular RTC second, and
2899 the rate at which the RTC gains or loses time relative to true time.
2900 When the computer is powered down, the measurement histories for all
2902 the NTP servers are saved to files, and the RTC tracking information is
2903 also saved to a file (if the rtcfile directive has been specified).
2904 These pieces of information are also saved if the dump and writertc
2905 commands respectively are issued through chronyc.
2906 When the computer is rebooted, chronyd reads the current RTC time and
2908 the RTC information saved at the last shutdown. This information is
2909 used to set the system clock to the best estimate of what its time
2910 would have been now, had it been left running continuously. The
2911 measurement histories for the servers are then reloaded.
2912 The next time the computer goes online, the previous sessions'
2914 measurements can contribute to the line-fitting process, which gives a
2915 much better estimate of the computer’s gain or loss rate.
2916 One problem with saving the measurements and RTC data when the machine
2918 is shut down is what happens if there is a power failure; the most
2919 recent data will not be saved. Although chronyd is robust enough to
2920 cope with this, some performance might be lost. (The main danger arises
2921 if the RTC has been changed during the session, with the trimrtc
2922 command in chronyc. Because of this, trimrtc will make sure that a
2923 meaningful RTC file is saved after the change is completed).
2924 The easiest protection against power failure is to put the dump and
2926 writertc commands in the same place as the offline command is issued to
2927 take chronyd offline; because chronyd free-runs between online
2928 sessions, no parameters will change significantly between going offline
2929 from the Internet and any power failure.
2930 A final point regards computers which are left running for extended
2932 periods and where it is desired to spin down the hard disc when it is
2933 not in use (e.g. when not accessed for 15 minutes). chronyd has been
2934 planned so it supports such operation; this is the reason why the RTC
2935 tracking parameters are not saved to disc after every update, but only
2936 when the user requests such a write, or during the shutdown sequence.
2937 The only other facility that will generate periodic writes to the disc
2938 is the log rtc facility in the configuration file; this option should
2939 not be used if you want your disc to spin down.
2940 To illustrate how a computer might be configured for this case, example
2942 configuration files are shown.
2943 For the chrony.conf file, the following can be used as an example.
2945 server foo.example.net maxdelay 0.4 offline
2947 server bar.example.net maxdelay 0.4 offline
2948 server baz.example.net maxdelay 0.4 offline
2949 logdir /var/log/chrony
2950 log statistics measurements tracking
2951 driftfile /var/lib/chrony/drift
2952 makestep 1.0 3
2953 maxupdateskew 100.0
2954 dumpdir /var/lib/chrony
2955 rtcfile /var/lib/chrony/rtc
2956 pppd is used for connecting to the Internet. This runs two scripts
2958 /etc/ppp/ip-up and /etc/ppp/ip-down when the link goes online and
2959 offline respectively.
2960 The relevant part of the /etc/ppp/ip-up file is:
2962 /usr/bin/chronyc online
2964 and the relevant part of the /etc/ppp/ip-down script is:
2966 /usr/bin/chronyc -m offline dump writertc
2968 chronyd is started during the boot sequence with the -r and -s options.
2970 It might need to be started before any software that depends on the
2971 system clock not jumping or moving backwards, depending on the
2972 directives in chronyd’s configuration file.
2973 For the system shutdown, chronyd should receive a SIGTERM several
2975 seconds before the final SIGKILL; the SIGTERM causes the measurement
2976 histories and RTC information to be saved.
2977 Public NTP server
2979 chronyd can be configured to operate as a public NTP server, e.g. to
2980 join the pool.ntp.org <https://www.pool.ntp.org/en/join.html> project.
2981 The configuration is similar to the NTP client with permanent
2982 connection, except it needs to allow client access from all addresses.
2983 It is recommended to find at least four good servers (e.g. from the
2984 pool, or on the NTP homepage). If the server has a hardware reference
2985 clock (e.g. a GPS receiver), it can be specified by the refclock
2986 directive.
2987 The amount of memory used for logging client accesses can be increased
2989 in order to enable clients to use the interleaved mode even when the
2990 server has a large number of clients, and better support rate limiting
2991 if it is enabled by the ratelimit directive. The system timezone
2992 database, if it is kept up to date and includes the right/UTC timezone,
2993 can be used as a reliable source to determine when a leap second will
2994 be applied to UTC. The -r option with the dumpdir directive shortens
2995 the time in which chronyd will not be able to serve time to its clients
2996 when it needs to be restarted (e.g. after upgrading to a newer version,
2997 or a change in the configuration).
2998 The configuration file could look like:
3000 server foo.example.net iburst
3002 server bar.example.net iburst
3003 server baz.example.net iburst
3004 server qux.example.net iburst
3005 makestep 1.0 3
3006 rtcsync
3007 allow
3008 clientloglimit 100000000
3009 leapsectz right/UTC
3010 driftfile /var/lib/chrony/drift
3011 dumpdir /run/chrony
3012
3014 chronyc(1), chronyd(8)
3015
3017 For instructions on how to report bugs, please visit
3018 https://chrony.tuxfamily.org/.
3019
3021 chrony was written by Richard Curnow, Miroslav Lichvar, and others.
3022chrony 4.0 2020-10-07 CHRONY.CONF(5)