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 certset ID
114 This option specifies which set of trusted certificates should
115 be used to verify the server’s certificate when the nts option
116 is enabled. Sets of certificates can be specified with the
117 ntstrustedcerts directive. The default set is 0, which by
118 default contains certificates of the system’s default trusted
119 certificate authorities.
120 maxdelay delay
122 chronyd uses the network round-trip delay to the server to
123 determine how accurate a particular measurement is likely to
124 be. Long round-trip delays indicate that the request, or the
125 response, or both were delayed. If only one of the messages was
126 delayed the measurement error is likely to be substantial.
127 For small variations in the round-trip delay, chronyd uses a
129 weighting scheme when processing the measurements. However,
130 beyond a certain level of delay the measurements are likely to
131 be so corrupted as to be useless. (This is particularly so on
132 wireless networks and other slow links, where a long delay
133 probably indicates a highly asymmetric delay caused by the
134 response waiting behind a lot of packets related to a download
135 of some sort).
136 If the user knows that round trip delays above a certain level
138 should cause the measurement to be ignored, this level can be
139 defined with the maxdelay option. For example, maxdelay 0.3
140 would indicate that measurements with a round-trip delay of 0.3
141 seconds or more should be ignored. The default value is 3
142 seconds and the maximum value is 1000 seconds.
143 maxdelayratio ratio
145 This option is similar to the maxdelay option above. chronyd
146 keeps a record of the minimum round-trip delay amongst the
147 previous measurements that it has buffered. If a measurement
148 has a round trip delay that is greater than the specified ratio
149 times the minimum delay, it will be rejected.
150 maxdelaydevratio ratio
152 If a measurement has a ratio of the increase in the round-trip
153 delay from the minimum delay amongst the previous measurements
154 to the standard deviation of the previous measurements that is
155 greater than the specified ratio, it will be rejected. The
156 default is 10.0.
157 mindelay delay
159 This option specifies a fixed minimum round-trip delay to be
160 used instead of the minimum amongst the previous measurements.
161 This can be useful in networks with static configuration to
162 improve the stability of corrections for asymmetric jitter,
163 weighting of the measurements, and the maxdelayratio and
164 maxdelaydevratio tests. The value should be set accurately in
165 order to have a positive effect on the synchronisation.
166 asymmetry ratio
168 This option specifies the asymmetry of the network jitter on
169 the path to the source, which is used to correct the measured
170 offset according to the delay. The asymmetry can be between
171 -0.5 and +0.5. A negative value means the delay of packets sent
172 to the source is more variable than the delay of packets sent
173 from the source back. By default, chronyd estimates the
174 asymmetry automatically.
175 offset offset
177 This option specifies a correction (in seconds) which will be
178 applied to offsets measured with this source. It’s particularly
179 useful to compensate for a known asymmetry in network delay or
180 timestamping errors. For example, if packets sent to the source
181 were on average delayed by 100 microseconds more than packets
182 sent from the source back, the correction would be -0.00005
183 (-50 microseconds). The default is 0.0.
184 minsamples samples
186 Set the minimum number of samples kept for this source. This
187 overrides the minsamples directive.
188 maxsamples samples
190 Set the maximum number of samples kept for this source. This
191 overrides the maxsamples directive.
192 filter samples
194 This option enables a median filter to reduce noise in NTP
195 measurements. The filter will reduce the specified number of
196 samples to a single sample. It is intended to be used with very
197 short polling intervals in local networks where it is
198 acceptable to generate a lot of NTP traffic.
199 offline
201 If the server will not be reachable when chronyd is started,
202 the offline option can be specified. chronyd will not try to
203 poll the server until it is enabled to do so (by using the
204 online command in chronyc).
205 auto_offline
207 With this option, the server will be assumed to have gone
208 offline when sending a request fails, e.g. due to a missing
209 route to the network. This option avoids the need to run the
210 offline command from chronyc when disconnecting the network
211 link. (It will still be necessary to use the online command
212 when the link has been established, to enable measurements to
213 start.)
214 prefer
216 Prefer this source over sources without the prefer option.
217 noselect
219 Never select this source. This is particularly useful for
220 monitoring.
221 trust
223 Assume time from this source is always true. It can be rejected
224 as a falseticker in the source selection only if another source
225 with this option does not agree with it.
226 require
228 Require that at least one of the sources specified with this
229 option is selectable (i.e. recently reachable and not a
230 falseticker) before updating the clock. Together with the trust
231 option this might be useful to allow a trusted authenticated
232 source to be safely combined with unauthenticated sources in
233 order to improve the accuracy of the clock. They can be
234 selected and used for synchronisation only if they agree with
235 the trusted and required source.
236 xleave
238 This option enables the interleaved mode of NTP. It enables the
239 server to respond with more accurate transmit timestamps (e.g.
240 kernel or hardware timestamps), which cannot be contained in
241 the transmitted packet itself and need to refer to a previous
242 packet instead. This can significantly improve the accuracy and
243 stability of the measurements.
244 The interleaved mode is compatible with servers that support
246 only the basic mode. Note that even servers that support the
247 interleaved mode might respond in the basic mode as the
248 interleaved mode requires the servers to keep some state for
249 each client and the state might be dropped when there are too
250 many clients (e.g. clientloglimit is too small), or it might be
251 overwritten by other clients that have the same IP address
252 (e.g. computers behind NAT or someone sending requests with a
253 spoofed source address).
254 The xleave option can be combined with the presend option in
256 order to shorten the interval in which the server has to keep
257 the state to be able to respond in the interleaved mode.
258 polltarget target
260 Target number of measurements to use for the regression
261 algorithm which chronyd will try to maintain by adjusting the
262 polling interval between minpoll and maxpoll. A higher target
263 makes chronyd prefer shorter polling intervals. The default is
264 8 and a useful range is from 6 to 60.
265 port port
267 This option allows the UDP port on which the server understands
268 NTP requests to be specified. For normal servers this option
269 should not be required (the default is 123, the standard NTP
270 port).
271 ntsport port
273 This option specifies the TCP port on which the server is
274 listening for NTS-KE connections when the nts option is
275 enabled. The default is 4460.
276 presend poll
278 If the timing measurements being made by chronyd are the only
279 network data passing between two computers, you might find that
280 some measurements are badly skewed due to either the client or
281 the server having to do an ARP lookup on the other party prior
282 to transmitting a packet. This is more of a problem with long
283 sampling intervals, which might be similar in duration to the
284 lifetime of entries in the ARP caches of the machines.
285 In order to avoid this problem, the presend option can be used.
287 It takes a single integer argument, which is the smallest
288 polling interval for which an extra pair of NTP packets will be
289 exchanged between the client and the server prior to the actual
290 measurement. For example, with the following option included in
291 a server directive:
292 presend 9
294 when the polling interval is 512 seconds or more, an extra NTP
296 client packet will be sent to the server a short time (2
297 seconds) before making the actual measurement.
298 If the presend option is used together with the xleave option,
300 chronyd will send two extra packets instead of one.
301 minstratum stratum
303 When the synchronisation source is selected from available
304 sources, sources with lower stratum are normally slightly
305 preferred. This option can be used to increase stratum of the
306 source to the specified minimum, so chronyd will avoid
307 selecting that source. This is useful with low-stratum sources
308 that are known to be unreliable or inaccurate and which should
309 be used only when other sources are unreachable.
310 version version
312 This option sets the NTP version of packets sent to the server.
313 This can be useful when the server runs an old NTP
314 implementation that does not respond to requests using a newer
315 version. The default version depends on other options. If the
316 extfield or xleave option is used, the default version is 4. If
317 those options are not used and the key option specifies a key
318 using a hash function with output size longer than 160 bits
319 (e.g. SHA256), the default version is 3 for compatibility with
320 older chronyd servers. In other cases, the default version is
321 4.
322 copy
324 This option specifies that the server and client are closely
325 related, their configuration does not allow a synchronisation
326 loop to form between them, and the client is allowed to assume
327 the reference ID and stratum of the server. This is useful when
328 multiple instances of chronyd are running on one computer (e.g.
329 for security or performance reasons), one primarily operating
330 as a client to synchronise the system clock and other instances
331 started with the -x option to operate as NTP servers for other
332 computers with their NTP clocks synchronised to the first
333 instance.
334 extfield type
336 This option enables an NTPv4 extension field specified by its
337 type as a hexadecimal number. It will be included in requests
338 sent to the server and processed in received responses if the
339 server supports it. Note that some server implementations do
340 not respond to requests containing an unknown extension field
341 (chronyd as a server responded to such requests since version
342 2.0).
343 The following extension field can be enabled by this option:
345 F323
347 This is an experimental extension field for some
348 improvements that were proposed for the next version of the
349 NTP protocol (NTPv5). The field contains root delay and
350 dispersion in higher resolution and a monotonic receive
351 timestamp, which enables a frequency transfer between the
352 server and client. It can significantly improve stability
353 of the synchronization. Generally, it should be expected to
354 work only between servers and clients running the same
355 version of chronyd.
356 pool name [option]...
360 The syntax of this directive is similar to that for the server
361 directive, except that it is used to specify a pool of NTP servers
362 rather than a single NTP server. The pool name is expected to
363 resolve to multiple addresses which might change over time.
364 This directive can be used multiple times to specify multiple
366 pools.
367 All options valid in the server directive can be used in this
369 directive too. There is one option specific to the pool directive:
370 maxsources sources
372 This option sets the desired number of sources to be used from
373 the pool. chronyd will repeatedly try to resolve the name until
374 it gets this number of sources responding to requests. The
375 default value is 4 and the maximum value is 16.
376 When an NTP source is unreachable, marked as a falseticker, or has
379 a distance larger than the limit set by the maxdistance directive,
380 chronyd will try to replace the source with a newly resolved
381 address of the name.
382 An example of the pool directive is
384 pool pool.ntp.org iburst maxsources 3
386 peer hostname [option]...
388 The syntax of this directive is identical to that for the server
389 directive, except that it specifies a symmetric association with an
390 NTP peer instead of a client/server association with an NTP server.
391 A single symmetric association allows the peers to be both servers
392 and clients to each other. This is mainly useful when the NTP
393 implementation of the peer (e.g. ntpd) supports ephemeral symmetric
394 associations and does not need to be configured with an address of
395 this host. chronyd does not support ephemeral associations.
396 This directive can be used multiple times to specify multiple
398 peers.
399 The following options of the server directive do not work in the
401 peer directive: iburst, burst, nts, presend, copy.
402 When using the xleave option, both peers must support and have
404 enabled the interleaved mode, otherwise the synchronisation will
405 work in one direction only. When a key is specified by the key
406 option to enable authentication, both peers must use the same key
407 and the same key number.
408 Note that the symmetric mode is less secure than the client/server
410 mode. A denial-of-service attack is possible on unauthenticated
411 symmetric associations, i.e. when the peer was specified without
412 the key option. An attacker who does not see network traffic
413 between two hosts, but knows that they are peering with each other,
414 can periodically send them unauthenticated packets with spoofed
415 source addresses in order to disrupt their NTP state and prevent
416 them from synchronising to each other. When the association is
417 authenticated, an attacker who does see the network traffic, but
418 cannot prevent the packets from reaching the other host, can still
419 disrupt the state by replaying old packets. The attacker has
420 effectively the same power as a man-in-the-middle attacker. A
421 partial protection against this attack is implemented in chronyd,
422 which can protect the peers if they are using the same polling
423 interval and they never sent an authenticated packet with a
424 timestamp from future, but it should not be relied on as it is
425 difficult to ensure the conditions are met. If two hosts should be
426 able to synchronise to each other in both directions, it is
427 recommended to use two separate client/server associations
428 (specified by the server directive on both hosts) instead.
429 initstepslew step-threshold [hostname]...
431 (This directive is deprecated in favour of the makestep directive.)
432 The purpose of the initstepslew directive is to allow chronyd to
434 make a rapid measurement of the system clock error at boot time,
435 and to correct the system clock by stepping before normal operation
436 begins. Since this would normally be performed only at an
437 appropriate point in the system boot sequence, no other software
438 should be adversely affected by the step.
439 If the correction required is less than a specified threshold, a
441 slew is used instead. This makes it safer to restart chronyd whilst
442 the system is in normal operation.
443 The initstepslew directive takes a threshold and a list of NTP
445 servers as arguments. Each of the servers is rapidly polled several
446 times, and a majority voting mechanism used to find the most likely
447 range of system clock error that is present. A step or slew is
448 applied to the system clock to correct this error. chronyd then
449 enters its normal operating mode.
450 An example of the use of the directive is:
452 initstepslew 30 foo.example.net bar.example.net baz.example.net
454 where 3 NTP servers are used to make the measurement. The 30
456 indicates that if the system’s error is found to be 30 seconds or
457 less, a slew will be used to correct it; if the error is above 30
458 seconds, a step will be used.
459 The initstepslew directive can also be used in an isolated LAN
461 environment, where the clocks are set manually. The most stable
462 computer is chosen as the primary server and the other computers
463 are its clients. If each of the clients is configured with the
464 local directive, the server can be set up with an initstepslew
465 directive which references some or all of the clients. Then, if the
466 server machine has to be rebooted, the clients can be relied on to
467 act analogously to a flywheel and preserve the time for a short
468 period while the server completes its reboot.
469 The initstepslew directive is functionally similar to a combination
471 of the makestep and server directives with the iburst option. The
472 main difference is that the initstepslew servers are used only
473 before normal operation begins and that the foreground chronyd
474 process waits for initstepslew to finish before exiting. This
475 prevent programs started in the boot sequence after chronyd from
476 reading the clock before it has been stepped. With the makestep
477 directive, the waitsync command of chronyc can be used instead.
478 refclock driver parameter[:option]... [option]...
480 The refclock directive specifies a hardware reference clock to be
481 used as a time source. It has two mandatory parameters, a driver
482 name and a driver-specific parameter. The two parameters are
483 followed by zero or more refclock options. Some drivers have
484 special options, which can be appended to the driver-specific
485 parameter using the : character.
486 This directive can be used multiple times to specify multiple
488 reference clocks.
489 There are four drivers included in chronyd:
491 PPS
493 Driver for the kernel PPS (pulse per second) API. The parameter
494 is the path to the PPS device (typically /dev/pps?). As PPS
495 refclocks do not supply full time, another time source (e.g.
496 NTP server or non-PPS refclock) is needed to complete samples
497 from the PPS refclock. An alternative is to enable the local
498 directive to allow synchronisation with some unknown but
499 constant offset. The driver supports the following option:
500 clear
502 By default, the PPS refclock uses assert events (rising
503 edge) for synchronisation. With this option, it will use
504 clear events (falling edge) instead.
505 Examples:
508 refclock PPS /dev/pps0 lock NMEA refid GPS
510 refclock SHM 0 offset 0.5 delay 0.2 refid NMEA noselect
511 refclock PPS /dev/pps1:clear refid GPS2
512 SHM
514 NTP shared memory driver. This driver uses a shared memory
515 segment to receive samples from another process (e.g. gpsd).
516 The parameter is the number of the shared memory segment,
517 typically a small number like 0, 1, 2, or 3. The driver
518 supports the following option:
519 perm=mode
521 This option specifies the permissions of the shared memory
522 segment created by chronyd. They are specified as a numeric
523 mode. The default value is 0600 (read-write access for
524 owner only).
525 Examples:
529 refclock SHM 0 poll 3 refid GPS1
531 refclock SHM 1:perm=0644 refid GPS2
532 SOCK
534 Unix domain socket driver. It is similar to the SHM driver, but
535 samples are received from a Unix domain socket instead of
536 shared memory and the messages have a different format. The
537 parameter is the path to the socket, which chronyd creates on
538 start. An advantage over the SHM driver is that SOCK does not
539 require polling and it can receive PPS samples with incomplete
540 time. The format of the messages is described in the
541 refclock_sock.c file in the chrony source code.
542 An application which supports the SOCK protocol is the gpsd
544 daemon. The path where gpsd expects the socket to be created is
545 described in the gpsd(8) man page. For example:
546 refclock SOCK /var/run/chrony.ttyS0.sock
548 PHC
550 PTP hardware clock (PHC) driver. The parameter is the path to
551 the device of the PTP clock which should be used as a time
552 source. If the clock is kept in TAI instead of UTC (e.g. it is
553 synchronised by a PTP daemon), the current UTC-TAI offset needs
554 to be specified by the offset option. Alternatively, the pps
555 refclock option can be enabled to treat the PHC as a PPS
556 refclock, using only the sub-second offset for synchronisation.
557 The driver supports the following options:
558 nocrossts
560 This option disables use of precise cross timestamping.
561 extpps
563 This option enables a PPS mode in which the PTP clock is
564 timestamping pulses of an external PPS signal connected to
565 the clock. The clock does not need to be synchronised, but
566 another time source is needed to complete the PPS samples.
567 Note that some PTP clocks cannot be configured to timestamp
568 only assert or clear events, and it is necessary to use the
569 width option to filter wrong PPS samples.
570 pin=index
572 This option specifies the index of the pin to which is
573 connected the PPS signal. The default value is 0.
574 channel=index
576 This option specifies the index of the channel for the PPS
577 mode. The default value is 0.
578 clear
580 This option enables timestamping of clear events (falling
581 edge) instead of assert events (rising edge) in the PPS
582 mode. This may not work with some clocks.
583 Examples:
587 refclock PHC /dev/ptp0 poll 0 dpoll -2 offset -37
589 refclock PHC /dev/ptp1:nocrossts poll 3 pps
590 refclock PHC /dev/ptp2:extpps:pin=1 width 0.2 poll 2
591 The refclock directive supports the following options:
594 poll poll
596 Timestamps produced by refclock drivers are not used
597 immediately, but they are stored and processed by a median
598 filter in the polling interval specified by this option. This
599 is defined as a power of 2 and can be negative to specify a
600 sub-second interval. The default is 4 (16 seconds). A shorter
601 interval allows chronyd to react faster to changes in the
602 frequency of the system clock, but it might have a negative
603 effect on its accuracy if the samples have a lot of jitter.
604 dpoll dpoll
606 Some drivers do not listen for external events and try to
607 produce samples in their own polling interval. This is defined
608 as a power of 2 and can be negative to specify a sub-second
609 interval. The default is 0 (1 second).
610 refid refid
612 This option is used to specify the reference ID of the
613 refclock, as up to four ASCII characters. The default reference
614 ID is composed from the first three characters of the driver
615 name and the number of the refclock. Each refclock must have a
616 unique reference ID.
617 lock refid
619 This option can be used to lock a PPS refclock to another
620 refclock, which is specified by its reference ID. In this mode
621 received PPS samples are paired directly with raw samples from
622 the specified refclock.
623 rate rate
625 This option sets the rate of the pulses in the PPS signal (in
626 Hz). This option controls how the pulses will be completed with
627 real time. To actually receive more than one pulse per second,
628 a negative dpoll has to be specified (-3 for a 5Hz signal). The
629 default is 1.
630 maxlockage pulses
632 This option specifies in number of pulses how old can be
633 samples from the refclock specified by the lock option to be
634 paired with the pulses. Increasing this value is useful when
635 the samples are produced at a lower rate than the pulses. The
636 default is 2.
637 width width
639 This option specifies the width of the pulses (in seconds). It
640 is used to filter PPS samples when the driver provides samples
641 for both rising and falling edges. Note that it reduces the
642 maximum allowed error of the time source which completes the
643 PPS samples. If the duty cycle is configurable, 50% should be
644 preferred in order to maximise the allowed error.
645 pps
647 This options forces chronyd to treat any refclock (e.g. SHM or
648 PHC) as a PPS refclock. This can be useful when the refclock
649 provides time with a variable offset of a whole number of
650 seconds (e.g. it uses TAI instead of UTC). Another time source
651 is needed to complete samples from the refclock.
652 offset offset
654 This option can be used to compensate for a constant error. The
655 specified offset (in seconds) is applied to all samples
656 produced by the reference clock. The default is 0.0.
657 delay delay
659 This option sets the NTP delay of the source (in seconds). Half
660 of this value is included in the maximum assumed error which is
661 used in the source selection algorithm. Increasing the delay is
662 useful to avoid having no majority in the source selection or
663 to make it prefer other sources. The default is 1e-9 (1
664 nanosecond).
665 stratum stratum
667 This option sets the NTP stratum of the refclock. This can be
668 useful when the refclock provides time with a stratum other
669 than 0. The default is 0.
670 precision precision
672 This option sets the precision of the reference clock (in
673 seconds). The default value is the estimated precision of the
674 system clock.
675 maxdispersion dispersion
677 Maximum allowed dispersion for filtered samples (in seconds).
678 Samples with larger estimated dispersion are ignored. By
679 default, this limit is disabled.
680 filter samples
682 This option sets the length of the median filter which is used
683 to reduce the noise in the measurements. With each poll about
684 40 percent of the stored samples are discarded and one final
685 sample is calculated as an average of the remaining samples. If
686 the length is 4 or more, at least 4 samples have to be
687 collected between polls. For lengths below 4, the filter has to
688 be full. The default is 64.
689 prefer
691 Prefer this source over sources without the prefer option.
692 noselect
694 Never select this source. This is useful for monitoring or with
695 sources which are not very accurate, but are locked with a PPS
696 refclock.
697 trust
699 Assume time from this source is always true. It can be rejected
700 as a falseticker in the source selection only if another source
701 with this option does not agree with it.
702 require
704 Require that at least one of the sources specified with this
705 option is selectable (i.e. recently reachable and not a
706 falseticker) before updating the clock. Together with the trust
707 option this can be useful to allow a trusted, but not very
708 precise, reference clock to be safely combined with
709 unauthenticated NTP sources in order to improve the accuracy of
710 the clock. They can be selected and used for synchronisation
711 only if they agree with the trusted and required source.
712 tai
714 This option indicates that the reference clock keeps time in
715 TAI instead of UTC and that chronyd should correct its offset
716 by the current TAI-UTC offset. The leapsectz directive must be
717 used with this option and the database must be kept up to date
718 in order for this correction to work as expected. This option
719 does not make sense with PPS refclocks.
720 minsamples samples
722 Set the minimum number of samples kept for this source. This
723 overrides the minsamples directive.
724 maxsamples samples
726 Set the maximum number of samples kept for this source. This
727 overrides the maxsamples directive.
728 manual
730 The manual directive enables support at run-time for the settime
731 command in chronyc. If no manual directive is included, any attempt
732 to use the settime command in chronyc will be met with an error
733 message.
734 Note that the settime command can be enabled at run-time using the
736 manual command in chronyc. (The idea of the two commands is that
737 the manual command controls the manual clock driver’s behaviour,
738 whereas the settime command allows samples of manually entered time
739 to be provided.)
740 acquisitionport port
742 By default, chronyd as an NTP client opens a new socket for each
743 request with the source port chosen randomly by the operating
744 system. The acquisitionport directive can be used to specify the
745 source port and use only one socket (per IPv4 or IPv6 address
746 family) for all configured servers. This can be useful for getting
747 through some firewalls. It should not be used if not necessary as
748 there is a small impact on security of the client. If set to 0, the
749 source port of the permanent socket will be chosen randomly by the
750 operating system.
751 It can be set to the same port as is used by the NTP server (which
753 can be configured with the port directive) to use only one socket
754 for all NTP packets.
755 An example of the acquisitionport directive is:
757 acquisitionport 1123
759 This would change the source port used for client requests to UDP
761 port 1123. You could then persuade the firewall administrator to
762 open that port.
763 bindacqaddress address
765 The bindacqaddress directive specifies a local IP address to which
766 chronyd will bind its NTP and NTS-KE client sockets. The syntax is
767 similar to the bindaddress and bindcmdaddress directives.
768 For each of the IPv4 and IPv6 protocols, only one bindacqaddress
770 directive can be specified.
771 bindacqdevice interface
773 The bindacqdevice directive binds the client sockets to a network
774 device specified by the interface name. This can be useful when the
775 local address is dynamic, or to enable an NTP source specified with
776 a link-local IPv6 address. This directive can specify only one
777 interface and it is supported on Linux only.
778 An example of the directive is:
780 bindacqdevice eth0
782 dscp point
784 The dscp directive sets the Differentiated Services Code Point
785 (DSCP) in transmitted NTP packets to the specified value. It can
786 improve stability of NTP measurements in local networks where
787 switches or routers are configured to prioritise forwarding of
788 packets with specific DSCP values. The default value is 0 and the
789 maximum value is 63.
790 An example of the directive (setting the Expedited Forwarding
792 class) is:
793 dscp 46
795 dumpdir directory
797 To compute the rate of gain or loss of time, chronyd has to store a
798 measurement history for each of the time sources it uses.
799 All supported systems, with the exception of macOS 10.12 and
801 earlier, have operating system support for setting the rate of gain
802 or loss to compensate for known errors. (On macOS 10.12 and
803 earlier, chronyd must simulate such a capability by periodically
804 slewing the system clock forwards or backwards by a suitable amount
805 to compensate for the error built up since the previous slew.)
806 For such systems, it is possible to save the measurement history
808 across restarts of chronyd (assuming no changes are made to the
809 system clock behaviour whilst it is not running). The dumpdir
810 directive defines the directory where the measurement histories are
811 saved when chronyd exits, or the dump command in chronyc is issued.
812 If the directory does not exist, it will be created automatically.
814 The -r option of chronyd enables loading of the dump files on
816 start. All dump files found in the directory will be removed after
817 start, even if the -r option is not present.
818 An example of the directive is:
820 dumpdir /run/chrony
822 A source whose IP address is 1.2.3.4 would have its measurement
824 history saved in the file /run/chrony/1.2.3.4.dat. History of
825 reference clocks is saved to files named by their reference ID in
826 form of refid:XXXXXXXX.dat.
827 maxsamples samples
829 The maxsamples directive sets the default maximum number of samples
830 that chronyd should keep for each source. This setting can be
831 overridden for individual sources in the server and refclock
832 directives. The default value is 0, which disables the configurable
833 limit. The useful range is 4 to 64.
834 As a special case, setting maxsamples to 1 disables frequency
836 tracking in order to make the sources immediately selectable with
837 only one sample. This can be useful when chronyd is started with
838 the -q or -Q option.
839 minsamples samples
841 The minsamples directive sets the default minimum number of samples
842 that chronyd should keep for each source. This setting can be
843 overridden for individual sources in the server and refclock
844 directives. The default value is 6. The useful range is 4 to 64.
845 Forcing chronyd to keep more samples than it would normally keep
847 reduces noise in the estimated frequency and offset, but slows down
848 the response to changes in the frequency and offset of the clock.
849 The offsets in the tracking and sourcestats reports (and the
850 tracking.log and statistics.log files) may be smaller than the
851 actual offsets.
852 ntsdumpdir directory
854 This directive specifies a directory for the client to save NTS
855 cookies it received from the server in order to avoid making an
856 NTS-KE request when chronyd is started again. The cookies are saved
857 separately for each NTP source in files named by the IP address of
858 the NTS-KE server (e.g. 1.2.3.4.nts). By default, the client does
859 not save the cookies.
860 If the directory does not exist, it will be created automatically.
862 An example of the directive is:
864 ntsdumpdir /var/lib/chrony
866 This directory is used also by the NTS server to save keys.
868 ntsrefresh interval
870 This directive specifies the maximum interval between NTS-KE
871 handshakes (in seconds) in order to refresh the keys authenticating
872 NTP packets. The default value is 2419200 (4 weeks) and the maximum
873 value is 2^31-1 (68 years).
874 ntstrustedcerts [set-ID] file|directory
876 This directive specifies a file or directory containing
877 certificates (in the PEM format) of trusted certificate authorities
878 (CA) which can be used to verify certificates of NTS servers.
879 The optional set-ID argument is a number in the range 0 through
881 2^32-1, which selects the set of certificates where certificates
882 from the specified file or directory are added. The default ID is
883 0, which is a set containing the system’s default trusted CAs
884 (unless the nosystemcert directive is present). All other sets are
885 empty by default. A set of certificates can be selected for
886 verification of an NTS server by the certset option in the server
887 or pool directive.
888 This directive can be used multiple times to specify one or more
890 sets of trusted certificates, each containing certificates from one
891 or more files and/or directories.
892 It is not necessary to restart chronyd in order to reload the
894 certificates if they change (e.g. after a renewal).
895 An example is:
897 ntstrustedcerts /etc/pki/nts/foo.crt
899 ntstrustedcerts 1 /etc/pki/nts/bar.crt
900 ntstrustedcerts 1 /etc/pki/nts/baz.crt
901 ntstrustedcerts 2 /etc/pki/nts/qux.crt
902 nosystemcert
904 This directive disables the system’s default trusted CAs. Only
905 certificates specified by the ntstrustedcerts directive will be
906 trusted.
907 nocerttimecheck limit
909 This directive disables the checks of the activation and expiration
910 times of certificates for the specified number of clock updates. It
911 allows the NTS authentication mechanism to be used on computers
912 which start with wrong time (e.g. due to not having an RTC or
913 backup battery). Disabling the time checks has important security
914 implications and should be used only as a last resort, preferably
915 with a minimal number of trusted certificates. The default value is
916 0, which means the time checks are always enabled.
917 An example of the directive is:
919 nocerttimecheck 1
921 This would disable the time checks until the clock is updated for
923 the first time, assuming the first update corrects the clock and
924 later checks can work with correct time.
925 Source selection
927 authselectmode mode
928 NTP sources can be specified with the key or nts option to enable
929 authentication to limit the impact of man-in-the-middle attacks.
930 The attackers can drop or delay NTP packets (up to the maxdelay and
931 maxdistance limits), but they cannot modify the timestamps
932 contained in the packets. The attack can cause only a limited slew
933 or step, and also cause the clock to run faster or slower than real
934 time (up to double of the maxdrift limit).
935 When authentication is enabled for an NTP source, it is important
937 to disable unauthenticated NTP sources which could be exploited in
938 the attack, e.g. if they are not reachable only over a trusted
939 network. Alternatively, the source selection can be configured with
940 the require and trust options to synchronise to the unauthenticated
941 sources only if they agree with the authenticated sources and might
942 have a positive impact on the accuracy of the clock. Note that in
943 this case the impact of the attack is higher. The attackers cannot
944 cause an arbitrarily large step or slew, but they have more control
945 over the frequency of the clock and can cause chronyd to report
946 false information, e.g. a significantly smaller root delay and
947 dispersion.
948 This directive determines the default selection options for
950 authenticated and unauthenticated sources in order to simplify the
951 configuration with the configuration file and chronyc commands. It
952 sets a policy for authentication.
953 Sources specified with the noselect option are ignored (not counted
955 as either authenticated or unauthenticated), and they always have
956 only the selection options specified in the configuration.
957 There are four modes:
959 require
961 Authentication is strictly required for NTP sources in this
962 mode. If any unauthenticated NTP sources are specified, they
963 will automatically get the noselect option to prevent them from
964 being selected for synchronisation.
965 prefer
967 In this mode, authentication is optional and preferred. If it
968 is enabled for at least one NTP source, all unauthenticated NTP
969 sources will get the noselect option.
970 mix
972 In this mode, authentication is optional and synchronisation to
973 a mix of authenticated and unauthenticated NTP sources is
974 allowed. If both authenticated and unauthenticated NTP sources
975 are specified, all authenticated NTP sources and reference
976 clocks will get the require and trust options to prevent
977 synchronisation to unauthenticated NTP sources if they do not
978 agree with a majority of the authenticated sources and
979 reference clocks. This is the default mode.
980 ignore
982 In this mode, authentication is ignored in the source
983 selection. All sources will have only the selection options
984 that were specified in the configuration file, or chronyc
985 command. This was the behaviour of chronyd in versions before
986 4.0.
987 As an example, the following configuration using the default mix
991 mode:
992 server foo.example.net nts
994 server bar.example.net nts
995 server baz.example.net
996 refclock SHM 0
997 is equivalent to the following configuration using the ignore mode:
999 authselectmode ignore
1001 server foo.example.net nts require trust
1002 server bar.example.net nts require trust
1003 server baz.example.net
1004 refclock SHM 0 require trust
1005 combinelimit limit
1007 When chronyd has multiple sources available for synchronisation, it
1008 has to select one source as the synchronisation source. The
1009 measured offsets and frequencies of the system clock relative to
1010 the other sources, however, can be combined with the selected
1011 source to improve the accuracy of the system clock.
1012 The combinelimit directive limits which sources are included in the
1014 combining algorithm. Their synchronisation distance has to be
1015 shorter than the distance of the selected source multiplied by the
1016 value of the limit. Also, their measured frequencies have to be
1017 close to the frequency of the selected source. If the selected
1018 source was specified with the prefer option, it can be combined
1019 only with other sources specified with this option.
1020 By default, the limit is 3. Setting the limit to 0 effectively
1022 disables the source combining algorithm and only the selected
1023 source will be used to control the system clock.
1024 maxdistance distance
1026 The maxdistance directive sets the maximum root distance of a
1027 source to be acceptable for synchronisation of the clock. Sources
1028 that have a distance larger than the specified distance will be
1029 rejected. The distance estimates the maximum error of the source.
1030 It includes the root dispersion and half of the root delay
1031 (round-trip time) accumulated on the path to the primary source.
1032 By default, the maximum root distance is 3 seconds.
1034 Setting maxdistance to a larger value can be useful to allow
1036 synchronisation with a server that only has a very infrequent
1037 connection to its sources and can accumulate a large dispersion
1038 between updates of its clock.
1039 maxjitter jitter
1041 The maxjitter directive sets the maximum allowed jitter of the
1042 sources to not be rejected by the source selection algorithm. This
1043 prevents synchronisation with sources that have a small root
1044 distance, but their time is too variable.
1045 By default, the maximum jitter is 1 second.
1047 minsources sources
1049 The minsources directive sets the minimum number of sources that
1050 need to be considered as selectable in the source selection
1051 algorithm before the local clock is updated. The default value is
1052 1.
1053 Setting this option to a larger number can be used to improve the
1055 reliability. More sources will have to agree with each other and
1056 the clock will not be updated when only one source (which could be
1057 serving incorrect time) is reachable.
1058 reselectdist distance
1060 When chronyd selects a synchronisation source from available
1061 sources, it will prefer the one with the shortest synchronisation
1062 distance. However, to avoid frequent reselecting when there are
1063 sources with similar distance, a fixed distance is added to the
1064 distance for sources that are currently not selected. This can be
1065 set with the reselectdist directive. By default, the distance is
1066 100 microseconds.
1067 stratumweight distance
1069 The stratumweight directive sets how much distance should be added
1070 per stratum to the synchronisation distance when chronyd selects
1071 the synchronisation source from available sources.
1072 By default, the weight is 0.001 seconds. This means that the
1074 stratum of the sources in the selection process matters only when
1075 the differences between the distances are in milliseconds.
1076 System clock
1078 clockprecision precision
1079 The clockprecision directive specifies the precision of the system
1080 clock (in seconds). It is used by chronyd to estimate the minimum
1081 noise in NTP measurements and randomise low-order bits of
1082 timestamps in NTP responses. By default, the precision is measured
1083 on start as the minimum time to read the clock.
1084 The measured value works well in most cases. However, it generally
1086 overestimates the precision and it can be sensitive to the CPU
1087 speed, which can change over time to save power. In some cases with
1088 a high-precision clocksource (e.g. the Time Stamp Counter of the
1089 CPU) and hardware timestamping, setting the precision on the server
1090 to a smaller value can improve stability of clients' NTP
1091 measurements. The server’s precision is reported on clients by the
1092 ntpdata command.
1093 An example setting the precision to 8 nanoseconds is:
1095 clockprecision 8e-9
1097 corrtimeratio ratio
1099 When chronyd is slewing the system clock to correct an offset, the
1100 rate at which it is slewing adds to the frequency error of the
1101 clock. On all supported systems, with the exception of macOS 12 and
1102 earlier, this rate can be controlled.
1103 The corrtimeratio directive sets the ratio between the duration in
1105 which the clock is slewed for an average correction according to
1106 the source history and the interval in which the corrections are
1107 done (usually the NTP polling interval). Corrections larger than
1108 the average take less time and smaller corrections take more time,
1109 the amount of the correction and the correction time are inversely
1110 proportional.
1111 Increasing corrtimeratio improves the overall frequency error of
1113 the system clock, but increases the overall time error as the
1114 corrections take longer.
1115 By default, the ratio is set to 3, the time accuracy of the clock
1117 is preferred over its frequency accuracy.
1118 The maximum allowed slew rate can be set by the maxslewrate
1120 directive. The current remaining correction is shown in the
1121 tracking report as the System time value.
1122 driftfile file
1124 One of the main activities of the chronyd program is to work out
1125 the rate at which the system clock gains or loses time relative to
1126 real time.
1127 Whenever chronyd computes a new value of the gain or loss rate, it
1129 is desirable to record it somewhere. This allows chronyd to begin
1130 compensating the system clock at that rate whenever it is
1131 restarted, even before it has had a chance to obtain an equally
1132 good estimate of the rate during the new run. (This process can
1133 take many minutes, at least.)
1134 The driftfile directive allows a file to be specified into which
1136 chronyd can store the rate information. Two parameters are recorded
1137 in the file. The first is the rate at which the system clock gains
1138 or loses time, expressed in parts per million, with gains positive.
1139 Therefore, a value of 100.0 indicates that when the system clock
1140 has advanced by a second, it has gained 100 microseconds in reality
1141 (so the true time has only advanced by 999900 microseconds). The
1142 second is an estimate of the error bound around the first value in
1143 which the true rate actually lies.
1144 An example of the driftfile directive is:
1146 driftfile /var/lib/chrony/drift
1148 fallbackdrift min-interval max-interval
1150 Fallback drifts are long-term averages of the system clock drift
1151 calculated over exponentially increasing intervals. They are used
1152 to avoid quickly drifting away from true time when the clock was
1153 not updated for a longer period of time and there was a short-term
1154 deviation in the drift before the updates stopped.
1155 The directive specifies the minimum and maximum interval since the
1157 last clock update to switch between fallback drifts. They are
1158 defined as a power of 2 (in seconds). The syntax is as follows:
1159 fallbackdrift 16 19
1161 In this example, the minimum interval is 16 (18 hours) and the
1163 maximum interval is 19 (6 days). The system clock frequency will be
1164 set to the first fallback 18 hours after last clock update, to the
1165 second after 36 hours, and so on. This might be a good setting to
1166 cover frequency changes due to daily and weekly temperature
1167 fluctuations. When the frequency is set to a fallback, the state of
1168 the clock will change to ‘Not synchronised’.
1169 By default (or if the specified maximum or minimum is 0), no
1171 fallbacks are used and the clock frequency changes only with new
1172 measurements from NTP sources, reference clocks, or manual input.
1173 leapsecmode mode
1175 A leap second is an adjustment that is occasionally applied to UTC
1176 to keep it close to the mean solar time. When a leap second is
1177 inserted, the last day of June or December has an extra second
1178 23:59:60.
1179 For computer clocks that is a problem. The Unix time is defined as
1181 number of seconds since 00:00:00 UTC on 1 January 1970 without leap
1182 seconds. The system clock cannot have time 23:59:60, every minute
1183 has 60 seconds and every day has 86400 seconds by definition. The
1184 inserted leap second is skipped and the clock is suddenly ahead of
1185 UTC by one second. The leapsecmode directive selects how that error
1186 is corrected. There are four options:
1187 system
1189 When inserting a leap second, the kernel steps the system clock
1190 backwards by one second when the clock gets to 00:00:00 UTC.
1191 When deleting a leap second, it steps forward by one second
1192 when the clock gets to 23:59:59 UTC. This is the default mode
1193 when the system driver supports leap seconds (i.e. all
1194 supported systems with the exception of macOS 12 and earlier).
1195 step
1197 This is similar to the system mode, except the clock is stepped
1198 by chronyd instead of the kernel. It can be useful to avoid
1199 bugs in the kernel code that would be executed in the system
1200 mode. This is the default mode when the system driver does not
1201 support leap seconds.
1202 slew
1204 The clock is corrected by slewing started at 00:00:00 UTC when
1205 a leap second is inserted or 23:59:59 UTC when a leap second is
1206 deleted. This might be preferred over the system and step modes
1207 when applications running on the system are sensitive to jumps
1208 in the system time and it is acceptable that the clock will be
1209 off for a longer time. On Linux with the default maxslewrate
1210 value the correction takes 12 seconds.
1211 ignore
1213 No correction is applied to the clock for the leap second. The
1214 clock will be corrected later in normal operation when new
1215 measurements are made and the estimated offset includes the one
1216 second error. This option is particularly useful when multiple
1217 chronyd instances are running on the system, one controlling
1218 the system clock and others started with the -x option, which
1219 should rely on the first instance to correct the system clock
1220 and ignore it for the correction of their own NTP clock running
1221 on top of the system clock.
1222 When serving time to NTP clients that cannot be configured to
1226 correct their clocks for a leap second by slewing, or to clients
1227 that would correct at slightly different rates when it is necessary
1228 to keep them close together, the slew mode can be combined with the
1229 smoothtime directive to enable a server leap smear.
1230 When smearing a leap second, the leap status is suppressed on the
1232 server and the served time is corrected slowly by slewing instead
1233 of stepping. The clients do not need any special configuration as
1234 they do not know there is any leap second and they follow the
1235 server time which eventually brings them back to UTC. Care must be
1236 taken to ensure they use only NTP servers which smear the leap
1237 second in exactly the same way for synchronisation.
1238 This feature must be used carefully, because the server is
1240 intentionally not serving its best estimate of the true time.
1241 A recommended configuration to enable a server leap smear is:
1243 leapsecmode slew
1245 maxslewrate 1000
1246 smoothtime 400 0.001024 leaponly
1247 The first directive is necessary to disable the clock step which
1249 would reset the smoothing process. The second directive limits the
1250 slewing rate of the local clock to 1000 ppm, which improves the
1251 stability of the smoothing process when the local correction starts
1252 and ends. The third directive enables the server time smoothing
1253 process. It will start when the clock gets to 00:00:00 UTC and it
1254 will take 62500 seconds (about 17.36 hours) to finish. The
1255 frequency offset will be changing by 0.001024 ppm per second and
1256 will reach a maximum of 32 ppm in 31250 seconds. The leaponly
1257 option makes the duration of the leap smear constant and allows the
1258 clients to safely synchronise with multiple identically configured
1259 leap smearing servers.
1260 The duration of the leap smear can be calculated from the specified
1262 wander as
1263 duration = sqrt(4 / wander)
1265 leapsectz timezone
1267 This directive specifies a timezone in the system timezone database
1268 which chronyd can use to determine when will the next leap second
1269 occur and what is the current offset between TAI and UTC. It will
1270 periodically check if 23:59:59 and 23:59:60 are valid times in the
1271 timezone. This normally works with the right/UTC timezone.
1272 When a leap second is announced, the timezone needs to be updated
1274 at least 12 hours before the leap second. It is not necessary to
1275 restart chronyd.
1276 This directive is useful with reference clocks and other time
1278 sources which do not announce leap seconds, or announce them too
1279 late for an NTP server to forward them to its own clients. Clients
1280 of leap smearing servers must not use this directive.
1281 It is also useful when the system clock is required to have correct
1283 TAI-UTC offset. Note that the offset is set only when leap seconds
1284 are handled by the kernel, i.e. leapsecmode is set to system.
1285 The specified timezone is not used as an exclusive source of
1287 information about leap seconds. If a majority of time sources
1288 announce on the last day of June or December that a leap second
1289 should be inserted or deleted, it will be accepted even if it is
1290 not included in the timezone.
1291 An example of the directive is:
1293 leapsectz right/UTC
1295 The following shell command verifies that the timezone contains
1297 leap seconds and can be used with this directive:
1298 $ TZ=right/UTC date -d 'Dec 31 2008 23:59:60'
1300 Wed Dec 31 23:59:60 UTC 2008
1301 makestep threshold limit
1303 Normally chronyd will cause the system to gradually correct any
1304 time offset, by slowing down or speeding up the clock as required.
1305 In certain situations, e.g. when chronyd is initially started, the
1306 system clock might be so far adrift that this slewing process would
1307 take a very long time to correct the system clock.
1308 This directive forces chronyd to step the system clock if the
1310 adjustment is larger than a threshold value, but only if there were
1311 no more clock updates since chronyd was started than the specified
1312 limit. A negative value disables the limit.
1313 On most systems it is desirable to step the system clock only on
1315 boot, before starting programs that rely on time advancing
1316 monotonically forwards.
1317 An example of the use of this directive is:
1319 makestep 0.1 3
1321 This would step the system clock if the adjustment is larger than
1323 0.1 seconds, but only in the first three clock updates.
1324 maxchange offset start ignore
1326 This directive sets the maximum allowed offset corrected on a clock
1327 update. The check is performed only after the specified number of
1328 updates to allow a large initial adjustment of the system clock.
1329 When an offset larger than the specified maximum occurs, it will be
1330 ignored for the specified number of times and then chronyd will
1331 give up and exit (a negative value can be used to never exit). In
1332 both cases a message is sent to syslog.
1333 An example of the use of this directive is:
1335 maxchange 1000 1 2
1337 After the first clock update, chronyd will check the offset on
1339 every clock update, it will ignore two adjustments larger than 1000
1340 seconds and exit on another one.
1341 maxclockerror error-in-ppm
1343 The maxclockerror directive sets the maximum assumed frequency
1344 error that the system clock can gain on its own between clock
1345 updates. It describes the stability of the clock.
1346 By default, the maximum error is 1 ppm.
1348 Typical values for error-in-ppm might be 10 for a low quality clock
1350 and 0.1 for a high quality clock using a temperature compensated
1351 crystal oscillator.
1352 maxdrift drift-in-ppm
1354 This directive specifies the maximum assumed drift (frequency
1355 error) of the system clock. It limits the frequency adjustment that
1356 chronyd is allowed to use to correct the measured drift. It is an
1357 additional limit to the maximum adjustment that can be set by the
1358 system driver (100000 ppm on Linux, 500 ppm on FreeBSD, NetBSD, and
1359 macOS 10.13+, 32500 ppm on illumos).
1360 By default, the maximum assumed drift is 500000 ppm, i.e. the
1362 adjustment is limited by the system driver rather than this
1363 directive.
1364 maxupdateskew skew-in-ppm
1366 One of chronyd's tasks is to work out how fast or slow the
1367 computer’s clock runs relative to its reference sources. In
1368 addition, it computes an estimate of the error bounds around the
1369 estimated value.
1370 If the range of error is too large, it probably indicates that the
1372 measurements have not settled down yet, and that the estimated gain
1373 or loss rate is not very reliable.
1374 The maxupdateskew directive sets the threshold for determining
1376 whether an estimate might be so unreliable that it should not be
1377 used. By default, the threshold is 1000 ppm.
1378 Typical values for skew-in-ppm might be 100 for NTP sources polled
1380 over a wireless network, and 10 or smaller for sources on a local
1381 wired network.
1382 It should be noted that this is not the only means of protection
1384 against using unreliable estimates. At all times, chronyd keeps
1385 track of both the estimated gain or loss rate, and the error bound
1386 on the estimate. When a new estimate is generated following another
1387 measurement from one of the sources, a weighted combination
1388 algorithm is used to update the master estimate. So if chronyd has
1389 an existing highly-reliable master estimate and a new estimate is
1390 generated which has large error bounds, the existing master
1391 estimate will dominate in the new master estimate.
1392 maxslewrate rate-in-ppm
1394 The maxslewrate directive sets the maximum rate at which chronyd is
1395 allowed to slew the time. It limits the slew rate controlled by the
1396 correction time ratio (which can be set by the corrtimeratio
1397 directive) and is effective only on systems where chronyd is able
1398 to control the rate (i.e. all supported systems with the exception
1399 of macOS 12 or earlier).
1400 For each system there is a maximum frequency offset of the clock
1402 that can be set by the driver. On Linux it is 100000 ppm, on
1403 FreeBSD, NetBSD and macOS 10.13+ it is 5000 ppm, and on illumos it
1404 is 32500 ppm. Also, due to a kernel limitation, setting maxslewrate
1405 on FreeBSD, NetBSD, macOS 10.13+ to a value between 500 ppm and
1406 5000 ppm will effectively set it to 500 ppm.
1407 By default, the maximum slew rate is set to 83333.333 ppm (one
1409 twelfth).
1410 tempcomp file interval T0 k0 k1 k2, tempcomp file interval points-file
1412 Normally, changes in the rate of drift of the system clock are
1413 caused mainly by changes in the temperature of the crystal
1414 oscillator on the motherboard.
1415 If there are temperature measurements available from a sensor close
1417 to the oscillator, the tempcomp directive can be used to compensate
1418 for the changes in the temperature and improve the stability and
1419 accuracy of the clock.
1420 The result depends on many factors, including the resolution of the
1422 sensor, the amount of noise in the measurements, the polling
1423 interval of the time source, the compensation update interval, how
1424 well the compensation is specified, and how close the sensor is to
1425 the oscillator. When it is working well, the frequency reported in
1426 the tracking.log file is more stable and the maximum reached offset
1427 is smaller.
1428 There are two forms of the directive. The first one has six
1430 parameters: a path to the file containing the current temperature
1431 from the sensor (in text format), the compensation update interval
1432 (in seconds), and temperature coefficients T0, k0, k1, k2.
1433 The frequency compensation is calculated (in ppm) as
1435 comp = k0 + (T - T0) * k1 + (T - T0)^2 * k2
1437 The result has to be between -10 ppm and 10 ppm, otherwise the
1439 measurement is considered invalid and will be ignored. The k0
1440 coefficient can be adjusted to keep the compensation in that range.
1441 An example of the use is:
1443 tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 26000 0.0 0.000183 0.0
1445 The measured temperature will be read from the file in the Linux
1447 sysfs filesystem every 30 seconds. When the temperature is 26000
1448 (26 degrees Celsius), the frequency correction will be zero. When
1449 it is 27000 (27 degrees Celsius), the clock will be set to run
1450 faster by 0.183 ppm, etc.
1451 The second form has three parameters: the path to the sensor file,
1453 the update interval, and a path to a file containing a list of
1454 (temperature, compensation) points, from which the compensation is
1455 linearly interpolated or extrapolated.
1456 An example is:
1458 tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 /etc/chrony.tempcomp
1460 where the /etc/chrony.tempcomp file could have
1462 20000 1.0
1464 21000 0.64
1465 22000 0.36
1466 23000 0.16
1467 24000 0.04
1468 25000 0.0
1469 26000 0.04
1470 27000 0.16
1471 28000 0.36
1472 29000 0.64
1473 30000 1.0
1474 Valid measurements with corresponding compensations are logged to
1476 the tempcomp.log file if enabled by the log tempcomp directive.
1477 NTP server
1479 allow [all] [subnet]
1480 The allow directive is used to designate a particular subnet from
1481 which NTP clients are allowed to access the computer as an NTP
1482 server. It also controls access of NTS-KE clients when NTS is
1483 enabled on the server.
1484 The default is that no clients are allowed access, i.e. chronyd
1486 operates purely as an NTP client. If the allow directive is used,
1487 chronyd will be both a client of its servers, and a server to other
1488 clients.
1489 This directive can be used multiple times.
1491 Examples of the use of the directive are as follows:
1493 allow 1.2.3.4
1495 allow 3.4.5.0/24
1496 allow 3.4.5
1497 allow 2001:db8::/32
1498 allow 0/0
1499 allow ::/0
1500 allow
1501 The first directive allows access from an IPv4 address. The second
1503 directive allows access from all computers in an IPv4 subnet
1504 specified in the CIDR notation. The third directive specifies the
1505 same subnet using a simpler notation where the prefix length is
1506 determined by the number of dots. The fourth directive specifies an
1507 IPv6 subnet. The fifth and sixth directives allow access from all
1508 IPv4 and IPv6 addresses respectively. The seventh directive allows
1509 access from all addresses (both IPv4 or IPv6).
1510 A second form of the directive, allow all, has a greater effect,
1512 depending on the ordering of directives in the configuration file.
1513 To illustrate the effect, consider the two examples:
1514 allow 1.2.3.4
1516 deny 1.2.3.0/24
1517 allow 1.2.0.0/16
1518 and
1520 allow 1.2.3.4
1522 deny 1.2.3.0/24
1523 allow all 1.2.0.0/16
1524 In the first example, the effect is the same regardless of what
1526 order the three directives are given in. So the 1.2.0.0/16 subnet
1527 is allowed access, except for the 1.2.3.0/24 subnet, which is
1528 denied access, however the host 1.2.3.4 is allowed access.
1529 In the second example, the allow all 1.2.0.0/16 directive overrides
1531 the effect of any previous directive relating to a subnet within
1532 the specified subnet. Within a configuration file this capability
1533 is probably rather moot; however, it is of greater use for
1534 reconfiguration at run-time via chronyc with the allow all command.
1535 The rules are internally represented as a tree of tables with one
1537 level per four bits of the IPv4 or IPv6 address. The order of the
1538 allow and deny directives matters if they modify the same records
1539 of one table, i.e. if one subnet is included in the other subnet
1540 and their prefix lengths are at the same level. For example,
1541 1.2.3.0/28 and 1.2.3.0/29 are in different tables, but 1.2.3.0/25
1542 and 1.2.3.0/28 are in the same table. The configuration can be
1543 verified for individual addresses with the accheck command in
1544 chronyc.
1545 A hostname can be specified in the directives instead of the IP
1547 address, but the name must be resolvable when chronyd is started,
1548 i.e. the network is already up and DNS is working. If the hostname
1549 resolves to multiple addresses, only the first address (in the
1550 order returned by the system resolver) will be allowed or denied.
1551 Note, if the initstepslew directive is used in the configuration
1553 file, each of the computers listed in that directive must allow
1554 client access by this computer for it to work.
1555 deny [all] [subnet]
1557 This is similar to the allow directive, except that it denies NTP
1558 and NTS-KE client access to a particular subnet or host, rather
1559 than allowing it.
1560 The syntax is identical and the directive can be used multiple
1562 times too.
1563 There is also a deny all directive with similar behaviour to the
1565 allow all directive.
1566 bindaddress address
1568 The bindaddress directive binds the sockets on which chronyd
1569 listens for NTP and NTS-KE requests to a local address of the
1570 computer. On systems other than Linux, the address of the computer
1571 needs to be already configured when chronyd is started.
1572 An example of the use of the directive is:
1574 bindaddress 192.168.1.1
1576 Currently, for each of the IPv4 and IPv6 protocols, only one
1578 bindaddress directive can be specified. Therefore, it is not useful
1579 on computers which should serve NTP on multiple network interfaces.
1580 binddevice interface
1582 The binddevice directive binds the NTP and NTS-KE server sockets to
1583 a network device specified by the interface name. This directive
1584 can specify only one interface and it is supported on Linux only.
1585 An example of the directive is:
1587 binddevice eth0
1589 broadcast interval address [port]
1591 The broadcast directive is used to declare a broadcast address to
1592 which chronyd should send packets in the NTP broadcast mode (i.e.
1593 make chronyd act as a broadcast server). Broadcast clients on that
1594 subnet will be able to synchronise.
1595 This directive can be used multiple times to specify multiple
1597 addresses.
1598 The syntax is as follows:
1600 broadcast 32 192.168.1.255
1602 broadcast 64 192.168.2.255 12123
1603 broadcast 64 ff02::101
1604 In the first example, the destination port defaults to UDP port 123
1606 (the normal NTP port). In the second example, the destination port
1607 is specified as 12123. The first parameter in each case (32 or 64
1608 respectively) is the interval in seconds between broadcast packets
1609 being sent. The second parameter in each case is the broadcast
1610 address to send the packet to. This should correspond to the
1611 broadcast address of one of the network interfaces on the computer
1612 where chronyd is running.
1613 You can have more than 1 broadcast directive if you have more than
1615 1 network interface onto which you want to send NTP broadcast
1616 packets.
1617 chronyd itself cannot act as a broadcast client; it must always be
1619 configured as a point-to-point client by defining specific NTP
1620 servers and peers. This broadcast server feature is intended for
1621 providing a time source to other NTP implementations.
1622 If ntpd is used as the broadcast client, it will try to measure the
1624 round-trip delay between the server and client with normal client
1625 mode packets. Thus, the broadcast subnet should also be the subject
1626 of an allow directive.
1627 clientloglimit limit
1629 This directive specifies the maximum amount of memory that chronyd
1630 is allowed to allocate for logging of client accesses and the state
1631 that chronyd as an NTP server needs to support the interleaved mode
1632 for its clients. The default limit is 524288 bytes, which enables
1633 monitoring of up to 4096 IP addresses at the same time and holding
1634 NTP timestamps for up to 4096 clients using the interleaved mode
1635 (depending on uniformity of their polling interval). The number of
1636 addresses and timestamps is always a power of 2. The maximum
1637 effective value is 2147483648 (2 GB), which corresponds to 16777216
1638 addresses and timestamps.
1639 An example of the use of this directive is:
1641 clientloglimit 1048576
1643 noclientlog
1645 This directive, which takes no arguments, specifies that client
1646 accesses are not to be logged. Normally they are logged, allowing
1647 statistics to be reported using the clients command in chronyc.
1648 This option also effectively disables server support for the NTP
1649 interleaved mode.
1650 local [option]...
1652 The local directive enables a local reference mode, which allows
1653 chronyd operating as an NTP server to appear synchronised to real
1654 time (from the viewpoint of clients polling it), even when it was
1655 never synchronised or the last update of the clock happened a long
1656 time ago.
1657 This directive is normally used in an isolated network, where
1659 computers are required to be synchronised to one another, but not
1660 necessarily to real time. The server can be kept vaguely in line
1661 with real time by manual input.
1662 The local directive has the following options:
1664 stratum stratum
1666 This option sets the stratum of the server which will be
1667 reported to clients when the local reference is active. The
1668 specified value is in the range 1 through 15, and the default
1669 value is 10. It should be larger than the maximum expected
1670 stratum in the network when external NTP servers are
1671 accessible.
1672 Stratum 1 indicates a computer that has a true real-time
1674 reference directly connected to it (e.g. GPS, atomic clock,
1675 etc.), such computers are expected to be very close to real
1676 time. Stratum 2 computers are those which have a stratum 1
1677 server; stratum 3 computers have a stratum 2 server and so on.
1678 A value of 10 indicates that the clock is so many hops away
1679 from a reference clock that its time is fairly unreliable.
1680 distance distance
1682 This option sets the threshold for the root distance which will
1683 activate the local reference. If chronyd was synchronised to
1684 some source, the local reference will not be activated until
1685 its root distance reaches the specified value (the rate at
1686 which the distance is increasing depends on how well the clock
1687 was tracking the source). The default value is 1 second.
1688 The current root distance can be calculated from root delay and
1690 root dispersion (reported by the tracking command in chronyc)
1691 as:
1692 distance = delay / 2 + dispersion
1694 orphan
1696 This option enables a special ‘orphan’ mode, where sources with
1697 stratum equal to the local stratum are assumed to not serve
1698 real time. They are ignored unless no other source is
1699 selectable and their reference IDs are smaller than the local
1700 reference ID.
1701 This allows multiple servers in the network to use the same
1703 local configuration and to be synchronised to one another,
1704 without confusing clients that poll more than one server. Each
1705 server needs to be configured to poll all other servers with
1706 the local directive. This ensures only the server with the
1707 smallest reference ID has the local reference active and others
1708 are synchronised to it. If that server stops responding, the
1709 server with the second smallest reference ID will take over
1710 when its local reference mode activates (root distance reaches
1711 the threshold configured by the distance option).
1712 The orphan mode is compatible with the ntpd's orphan mode
1714 (enabled by the tos orphan command).
1715 An example of the directive is:
1719 local stratum 10 orphan distance 0.1
1721 ntpsigndsocket directory
1723 This directive specifies the location of the Samba ntp_signd socket
1724 when it is running as a Domain Controller (DC). If chronyd is
1725 compiled with this feature, responses to MS-SNTP clients will be
1726 signed by the smbd daemon.
1727 Note that MS-SNTP requests are not authenticated and any client
1729 that is allowed to access the server by the allow directive, or the
1730 allow command in chronyc, can get an MS-SNTP response signed with a
1731 trust account’s password and try to crack the password in a
1732 brute-force attack. Access to the server should be carefully
1733 controlled.
1734 An example of the directive is:
1736 ntpsigndsocket /var/lib/samba/ntp_signd
1738 ntsport port
1740 This directive specifies the TCP port on which chronyd will provide
1741 the NTS Key Establishment (NTS-KE) service. The default port is
1742 4460.
1743 The port will be open only when a certificate and key is specified
1745 by the ntsservercert and ntsserverkey directives.
1746 ntsservercert file
1748 This directive specifies a file containing a certificate in the PEM
1749 format for chronyd to operate as an NTS server. The file should
1750 also include any intermediate certificates that the clients will
1751 need to validate the server’s certificate. The file needs to be
1752 readable by the user under which chronyd is running after dropping
1753 root privileges.
1754 This directive can be used multiple times to specify multiple
1756 certificates for different names of the server.
1757 The files are loaded only once. chronyd needs to be restarted in
1759 order to load a renewed certificate. The ntsdumpdir and dumpdir
1760 directives with the -r option of chronyd are recommended for a
1761 near-seamless server operation.
1762 ntsserverkey file
1764 This directive specifies a file containing a private key in the PEM
1765 format for chronyd to operate as an NTS server. The file needs to
1766 be readable by the user under which chronyd is running after
1767 dropping root privileges. For security reasons, it should not be
1768 readable by other users.
1769 This directive can be used multiple times to specify multiple keys.
1771 The number of keys must be the same as the number of certificates
1772 and the corresponding files must be specified in the same order.
1773 ntsprocesses processes
1775 This directive specifies how many helper processes will chronyd
1776 operating as an NTS server start for handling client NTS-KE
1777 requests in order to improve performance with multi-core CPUs and
1778 multithreading. If set to 0, no helper process will be started and
1779 all NTS-KE requests will be handled by the main chronyd process.
1780 The default value is 1.
1781 maxntsconnections connections
1783 This directive specifies the maximum number of concurrent NTS-KE
1784 connections per process that the NTS server will accept. The
1785 default value is 100. The maximum practical value is half of the
1786 system FD_SETSIZE constant (usually 1024).
1787 ntsdumpdir directory
1789 This directive specifies a directory where chronyd operating as an
1790 NTS server can save the keys which encrypt NTS cookies provided to
1791 clients. The keys are saved to a single file named ntskeys. When
1792 chronyd is restarted, reloading the keys allows the clients to
1793 continue using old cookies and avoids a storm of NTS-KE requests.
1794 By default, the server does not save the keys.
1795 An example of the directive is:
1797 ntsdumpdir /var/lib/chrony
1799 This directory is used also by the NTS client to save NTS cookies.
1801 ntsntpserver hostname
1803 This directive specifies the hostname (as a fully qualified domain
1804 name) or address of the NTP server(s) which is provided in the
1805 NTS-KE response to the clients. It allows the NTS-KE server to be
1806 separated from the NTP server. However, the servers need to share
1807 the keys, i.e. external key management needs to be enabled by
1808 setting ntsrotate to 0. By default, no hostname or address is
1809 provided to the clients, which means they should use the same
1810 server for NTS-KE and NTP.
1811 ntsrotate interval
1813 This directive specifies the rotation interval (in seconds) of the
1814 server key which encrypts the NTS cookies. New keys are generated
1815 automatically from the /dev/urandom device. The server keeps two
1816 previous keys to give the clients time to get new cookies encrypted
1817 by the latest key. The interval is measured as the server’s
1818 operating time, i.e. the actual interval can be longer if chronyd
1819 is not running continuously. The default interval is 604800 seconds
1820 (1 week). The maximum value is 2^31-1 (68 years).
1821 The automatic rotation of the keys can be disabled by setting
1823 ntsrotate to 0. In this case the keys are assumed to be managed
1824 externally. chronyd will not save the keys to the ntskeys file and
1825 will reload the keys from the file when the rekey command is issued
1826 in chronyc. The file can be periodically copied from another server
1827 running chronyd (which does not have ntsrotate set to 0) in order
1828 to have one or more servers dedicated to NTS-KE. The NTS-KE servers
1829 need to be configured with the ntsntpserver directive to point the
1830 clients to the right NTP server.
1831 An example of the directive is:
1833 ntsrotate 2592000
1835 port port
1837 This option allows you to configure the port on which chronyd will
1838 listen for NTP requests. The port will be open only when an address
1839 is allowed by the allow directive or the allow command in chronyc,
1840 an NTP peer is configured, or the broadcast server mode is enabled.
1841 The default value is 123, the standard NTP port. If set to 0,
1843 chronyd will never open the server port and will operate strictly
1844 in a client-only mode. The source port used in NTP client requests
1845 can be set by the acquisitionport directive.
1846 ratelimit [option]...
1848 This directive enables response rate limiting for NTP packets. Its
1849 purpose is to reduce network traffic with misconfigured or broken
1850 NTP clients that are polling the server too frequently. The limits
1851 are applied to individual IP addresses. If multiple clients share
1852 one IP address (e.g. multiple hosts behind NAT), the sum of their
1853 traffic will be limited. If a client that increases its polling
1854 rate when it does not receive a reply is detected, its rate
1855 limiting will be temporarily suspended to avoid increasing the
1856 overall amount of traffic. The maximum number of IP addresses which
1857 can be monitored at the same time depends on the memory limit set
1858 by the clientloglimit directive.
1859 The ratelimit directive supports a number of options (which can be
1861 defined in any order):
1862 interval interval
1864 This option sets the minimum interval between responses. It is
1865 defined as a power of 2 in seconds. The default value is 3 (8
1866 seconds). The minimum value is -19 (524288 packets per second)
1867 and the maximum value is 12 (one packet per 4096 seconds). Note
1868 that with values below -4 the rate limiting is coarse
1869 (responses are allowed in bursts, even if the interval between
1870 them is shorter than the specified interval).
1871 burst responses
1873 This option sets the maximum number of responses that can be
1874 sent in a burst, temporarily exceeding the limit specified by
1875 the interval option. This is useful for clients that make rapid
1876 measurements on start (e.g. chronyd with the iburst option).
1877 The default value is 8. The minimum value is 1 and the maximum
1878 value is 255.
1879 leak rate
1881 This option sets the rate at which responses are randomly
1882 allowed even if the limits specified by the interval and burst
1883 options are exceeded. This is necessary to prevent an attacker
1884 who is sending requests with a spoofed source address from
1885 completely blocking responses to that address. The leak rate is
1886 defined as a power of 1/2 and it is 2 by default, i.e. on
1887 average at least every fourth request has a response. The
1888 minimum value is 1 and the maximum value is 4.
1889 An example use of the directive is:
1893 ratelimit interval 1 burst 16
1895 This would reduce the response rate for IP addresses sending
1897 packets on average more than once per 2 seconds, or sending packets
1898 in bursts of more than 16 packets, by up to 75% (with default leak
1899 of 2).
1900 ntsratelimit [option]...
1902 This directive enables rate limiting of NTS-KE requests. It is
1903 similar to the ratelimit directive, except the default interval is
1904 6 (1 connection per 64 seconds).
1905 An example of the use of the directive is:
1907 ntsratelimit interval 3 burst 1
1909 smoothtime max-freq max-wander [leaponly]
1911 The smoothtime directive can be used to enable smoothing of the
1912 time that chronyd serves to its clients to make it easier for them
1913 to track it and keep their clocks close together even when large
1914 offset or frequency corrections are applied to the server’s clock,
1915 for example after being offline for a longer time.
1916 BE WARNED: The server is intentionally not serving its best
1918 estimate of the true time. If a large offset has been accumulated,
1919 it can take a very long time to smooth it out. This directive
1920 should be used only when the clients are not configured to also
1921 poll another NTP server, because they could reject this server as a
1922 falseticker or fail to select a source completely.
1923 The smoothing process is implemented with a quadratic spline
1925 function with two or three pieces. It is independent from any
1926 slewing applied to the local system clock, but the accumulated
1927 offset and frequency will be reset when the clock is corrected by
1928 stepping, e.g. by the makestep directive or the makestep command in
1929 chronyc. The process can be reset without stepping the clock by the
1930 smoothtime reset command.
1931 The first two arguments of the directive are the maximum frequency
1933 offset of the smoothed time to the tracked NTP time (in ppm) and
1934 the maximum rate at which the frequency offset is allowed to change
1935 (in ppm per second). leaponly is an optional third argument which
1936 enables a mode where only leap seconds are smoothed out and normal
1937 offset and frequency changes are ignored. The leaponly option is
1938 useful in a combination with the leapsecmode slew directive to
1939 allow the clients to use multiple time smoothing servers safely.
1940 The smoothing process is activated automatically when 1/10000 of
1942 the estimated skew of the local clock falls below the maximum rate
1943 of frequency change. It can be also activated manually by the
1944 smoothtime activate command, which is particularly useful when the
1945 clock is synchronised only with manual input and the skew is always
1946 larger than the threshold. The smoothing command can be used to
1947 monitor the process.
1948 An example suitable for clients using ntpd and 1024 second polling
1950 interval could be:
1951 smoothtime 400 0.001
1953 An example suitable for clients using chronyd on Linux could be:
1955 smoothtime 50000 0.01
1957 Command and monitoring access
1959 bindcmdaddress address
1960 The bindcmdaddress directive specifies a local IP address to which
1961 chronyd will bind the UDP socket listening for monitoring command
1962 packets (issued by chronyc). On systems other than Linux, the
1963 address of the interface needs to be already configured when
1964 chronyd is started.
1965 This directive can also change the path of the Unix domain command
1967 socket, which is used by chronyc to send configuration commands.
1968 The socket must be in a directory that is accessible only by the
1969 root or chrony user. The directory will be created on start if it
1970 does not exist. The compiled-in default path of the socket is
1971 /run/chrony/chronyd.sock. The socket can be disabled by setting the
1972 path to /.
1973 By default, chronyd binds the UDP sockets to the addresses
1975 127.0.0.1 and ::1 (i.e. the loopback interface). This blocks all
1976 access except from localhost. To listen for command packets on all
1977 interfaces, you can add the lines:
1978 bindcmdaddress 0.0.0.0
1980 bindcmdaddress ::
1981 to the configuration file.
1983 For each of the IPv4, IPv6, and Unix domain protocols, only one
1985 bindcmdaddress directive can be specified.
1986 An example that sets the path of the Unix domain command socket is:
1988 bindcmdaddress /var/run/chrony/chronyd.sock
1990 bindcmddevice interface
1992 The bindcmddevice directive binds the UDP command sockets to a
1993 network device specified by the interface name. This directive can
1994 specify only one interface and it is supported on Linux only.
1995 An example of the directive is:
1997 bindcmddevice eth0
1999 cmdallow [all] [subnet]
2001 This is similar to the allow directive, except that it allows
2002 monitoring access (rather than NTP client access) to a particular
2003 subnet or host. (By ‘monitoring access’ is meant that chronyc can
2004 be run on those hosts and retrieve monitoring data from chronyd on
2005 this computer.)
2006 The syntax is identical to the allow directive.
2008 There is also a cmdallow all directive with similar behaviour to
2010 the allow all directive (but applying to monitoring access in this
2011 case, of course).
2012 Note that chronyd has to be configured with the bindcmdaddress
2014 directive to not listen only on the loopback interface to actually
2015 allow remote access.
2016 cmddeny [all] [subnet]
2018 This is similar to the cmdallow directive, except that it denies
2019 monitoring access to a particular subnet or host, rather than
2020 allowing it.
2021 The syntax is identical.
2023 There is also a cmddeny all directive with similar behaviour to the
2025 cmdallow all directive.
2026 cmdport port
2028 The cmdport directive allows the port that is used for run-time
2029 monitoring (via the chronyc program) to be altered from its default
2030 (323). If set to 0, chronyd will not open the port, this is useful
2031 to disable chronyc access from the Internet. (It does not disable
2032 the Unix domain command socket.)
2033 An example shows the syntax:
2035 cmdport 257
2037 This would make chronyd use UDP 257 as its command port. (chronyc
2039 would need to be run with the -p 257 switch to inter-operate
2040 correctly.)
2041 cmdratelimit [option]...
2043 This directive enables response rate limiting for command packets.
2044 It is similar to the ratelimit directive, except responses to
2045 localhost are never limited and the default interval is -4 (16
2046 packets per second).
2047 An example of the use of the directive is:
2049 cmdratelimit interval 2
2051 Real-time clock (RTC)
2053 hwclockfile file
2054 The hwclockfile directive sets the location of the adjtime file
2055 which is used by the hwclock program on Linux. chronyd parses the
2056 file to find out if the RTC keeps local time or UTC. It overrides
2057 the rtconutc directive.
2058 The compiled-in default value is '/etc/adjtime'.
2060 An example of the directive is:
2062 hwclockfile /etc/adjtime
2064 rtcautotrim threshold
2066 The rtcautotrim directive is used to keep the RTC close to the
2067 system clock automatically. When the system clock is synchronised
2068 and the estimated error between the two clocks is larger than the
2069 specified threshold, chronyd will trim the RTC as if the trimrtc
2070 command in chronyc was issued. The trimming operation is accurate
2071 to only about 1 second, which is the minimum effective threshold.
2072 This directive is effective only with the rtcfile directive.
2074 An example of the use of this directive is:
2076 rtcautotrim 30
2078 This would set the threshold error to 30 seconds.
2080 rtcdevice device
2082 The rtcdevice directive sets the path to the device file for
2083 accessing the RTC. The default path is /dev/rtc.
2084 rtcfile file
2086 The rtcfile directive defines the name of the file in which chronyd
2087 can save parameters associated with tracking the accuracy of the
2088 RTC.
2089 An example of the directive is:
2091 rtcfile /var/lib/chrony/rtc
2093 chronyd saves information in this file when it exits and when the
2095 writertc command is issued in chronyc. The information saved is the
2096 RTC’s error at some epoch, that epoch (in seconds since January 1
2097 1970), and the rate at which the RTC gains or loses time.
2098 So far, the support for real-time clocks is limited; their code is
2100 even more system-specific than the rest of the software. You can
2101 only use the RTC facilities (the rtcfile directive and the -s
2102 command-line option to chronyd) if the following three conditions
2103 apply:
2104 1. You are running Linux.
2106 2. The kernel is compiled with extended real-time clock support
2108 (i.e. the /dev/rtc device is capable of doing useful things).
2109 3. You do not have other applications that need to make use of
2111 /dev/rtc at all.
2112 rtconutc
2114 chronyd assumes by default that the RTC keeps local time (including
2115 any daylight saving changes). This is convenient on PCs running
2116 Linux which are dual-booted with Windows.
2117 If you keep the RTC on local time and your computer is off when
2119 daylight saving (summer time) starts or ends, the computer’s system
2120 time will be one hour in error when you next boot and start
2121 chronyd.
2122 An alternative is for the RTC to keep Universal Coordinated Time
2124 (UTC). This does not suffer from the 1 hour problem when daylight
2125 saving starts or ends.
2126 If the rtconutc directive appears, it means the RTC is required to
2128 keep UTC. The directive takes no arguments. It is equivalent to
2129 specifying the -u switch to the Linux hwclock program.
2130 Note that this setting is overridden by the hwclockfile file and is
2132 not relevant for the rtcsync directive.
2133 rtcsync
2135 The rtcsync directive enables a mode where the system time is
2136 periodically copied to the RTC and chronyd does not try to track
2137 its drift. This directive cannot be used with the rtcfile
2138 directive.
2139 On Linux, the RTC copy is performed by the kernel every 11 minutes.
2141 On macOS, chronyd will perform the RTC copy every 60 minutes when
2143 the system clock is in a synchronised state.
2144 On other systems this directive does nothing.
2146 Logging
2148 log [option]...
2149 The log directive indicates that certain information is to be
2150 logged. The log files are written to the directory specified by the
2151 logdir directive. A banner is periodically written to the files to
2152 indicate the meanings of the columns.
2153 rawmeasurements
2155 This option logs the raw NTP measurements and related
2156 information to a file called measurements.log. An entry is made
2157 for each packet received from the source. This can be useful
2158 when debugging a problem. An example line (which actually
2159 appears as a single line in the file) from the log file is
2160 shown below.
2161 2016-11-09 05:40:50 203.0.113.15 N 2 111 111 1111 10 10 1.0 \
2163 -4.966e-03 2.296e-01 1.577e-05 1.615e-01 7.446e-03 CB00717B 4B D K
2164 The columns are as follows (the quantities in square brackets
2166 are the values from the example line above):
2167 1. Date [2015-10-13]
2169 2. Hour:Minute:Second. Note that the date-time pair is
2171 expressed in UTC, not the local time zone. [05:40:50]
2172 3. IP address of server or peer from which measurement came
2174 [203.0.113.15]
2175 4. Leap status (N means normal, + means that the last minute
2177 of the current month has 61 seconds, - means that the last
2178 minute of the month has 59 seconds, ? means the remote
2179 computer is not currently synchronised.) [N]
2180 5. Stratum of remote computer. [2]
2182 6. RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111]
2184 7. RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111]
2186 8. Tests for maximum delay, maximum delay ratio and maximum
2188 delay dev ratio, against defined parameters, and a test for
2189 synchronisation loop (1=pass, 0=fail) [1111]
2190 9. Local poll [10]
2192 10. Remote poll [10]
2194 11. ‘Score’ (an internal score within each polling level used
2196 to decide when to increase or decrease the polling level.
2197 This is adjusted based on number of measurements currently
2198 being used for the regression algorithm). [1.0]
2199 12. The estimated local clock error (theta in RFC 5905).
2201 Positive indicates that the local clock is slow of the
2202 remote source. [-4.966e-03]
2203 13. The peer delay (delta in RFC 5905). [2.296e-01]
2205 14. The peer dispersion (epsilon in RFC 5905). [1.577e-05]
2207 15. The root delay (DELTA in RFC 5905). [1.615e-01]
2209 16. The root dispersion (EPSILON in RFC 5905). [7.446e-03]
2211 17. Reference ID of the server’s source as a hexadecimal
2213 number. [CB00717B]
2214 18. NTP mode of the received packet (1=active peer, 2=passive
2216 peer, 4=server, B=basic, I=interleaved). [4B]
2217 19. Source of the local transmit timestamp (D=daemon,
2219 K=kernel, H=hardware). [D]
2220 20. Source of the local receive timestamp (D=daemon, K=kernel,
2222 H=hardware). [K]
2223 measurements
2225 This option is identical to the rawmeasurements option, except
2226 it logs only valid measurements from synchronised sources, i.e.
2227 measurements which passed the RFC 5905 tests 1 through 7. This
2228 can be useful for producing graphs of the source’s performance.
2229 statistics
2231 This option logs information about the regression processing to
2232 a file called statistics.log. An example line (which actually
2233 appears as a single line in the file) from the log file is
2234 shown below.
2235 2016-08-10 05:40:50 203.0.113.15 6.261e-03 -3.247e-03 \
2237 2.220e-03 1.874e-06 1.080e-06 7.8e-02 16 0 8 0.00
2238 The columns are as follows (the quantities in square brackets
2240 are the values from the example line above):
2241 1. Date [2015-07-22]
2243 2. Hour:Minute:Second. Note that the date-time pair is
2245 expressed in UTC, not the local time zone. [05:40:50]
2246 3. IP address of server or peer from which measurement comes
2248 [203.0.113.15]
2249 4. The estimated standard deviation of the measurements from
2251 the source (in seconds). [6.261e-03]
2252 5. The estimated offset of the source (in seconds, positive
2254 means the local clock is estimated to be fast, in this
2255 case). [-3.247e-03]
2256 6. The estimated standard deviation of the offset estimate (in
2258 seconds). [2.220e-03]
2259 7. The estimated rate at which the local clock is gaining or
2261 losing time relative to the source (in seconds per second,
2262 positive means the local clock is gaining). This is
2263 relative to the compensation currently being applied to the
2264 local clock, not to the local clock without any
2265 compensation. [1.874e-06]
2266 8. The estimated error in the rate value (in seconds per
2268 second). [1.080e-06].
2269 9. The ratio of |old_rate - new_rate| / old_rate_error. Large
2271 values indicate the statistics are not modelling the source
2272 very well. [7.8e-02]
2273 10. The number of measurements currently being used for the
2275 regression algorithm. [16]
2276 11. The new starting index (the oldest sample has index 0;
2278 this is the method used to prune old samples when it no
2279 longer looks like the measurements fit a linear model). [0,
2280 i.e. no samples discarded this time]
2281 12. The number of runs. The number of runs of regression
2283 residuals with the same sign is computed. If this is too
2284 small it indicates that the measurements are no longer
2285 represented well by a linear model and that some older
2286 samples need to be discarded. The number of runs for the
2287 data that is being retained is tabulated. Values of
2288 approximately half the number of samples are expected. [8]
2289 13. The estimated or configured asymmetry of network jitter on
2291 the path to the source which was used to correct the
2292 measured offsets. The asymmetry can be between -0.5 and
2293 +0.5. A negative value means the delay of packets sent to
2294 the source is more variable than the delay of packets sent
2295 from the source back. [0.00, i.e. no correction for
2296 asymmetry]
2297 tracking
2299 This option logs changes to the estimate of the system’s gain
2300 or loss rate, and any slews made, to a file called
2301 tracking.log. An example line (which actually appears as a
2302 single line in the file) from the log file is shown below.
2303 2017-08-22 13:22:36 203.0.113.15 2 -3.541 0.075 -8.621e-06 N \
2305 2 2.940e-03 -2.084e-04 1.534e-02 3.472e-04 8.304e-03
2306 The columns are as follows (the quantities in square brackets
2308 are the values from the example line above) :
2309 1. Date [2017-08-22]
2311 2. Hour:Minute:Second. Note that the date-time pair is
2313 expressed in UTC, not the local time zone. [13:22:36]
2314 3. The IP address of the server or peer to which the local
2316 system is synchronised. [203.0.113.15]
2317 4. The stratum of the local system. [2]
2319 5. The local system frequency (in ppm, positive means the
2321 local system runs fast of UTC). [-3.541]
2322 6. The error bounds on the frequency (in ppm). [0.075]
2324 7. The estimated local offset at the epoch, which is normally
2326 corrected by slewing the local clock (in seconds, positive
2327 indicates the clock is fast of UTC). [-8.621e-06]
2328 8. Leap status (N means normal, + means that the last minute
2330 of this month has 61 seconds, - means that the last minute
2331 of the month has 59 seconds, ? means the clock is not
2332 currently synchronised.) [N]
2333 9. The number of combined sources. [2]
2335 10. The estimated standard deviation of the combined offset
2337 (in seconds). [2.940e-03]
2338 11. The remaining offset correction from the previous update
2340 (in seconds, positive means the system clock is slow of
2341 UTC). [-2.084e-04]
2342 12. The total of the network path delays to the reference
2344 clock to which the local clock is ultimately synchronised
2345 (in seconds). [1.534e-02]
2346 13. The total dispersion accumulated through all the servers
2348 back to the reference clock to which the local clock is
2349 ultimately synchronised (in seconds). [3.472e-04]
2350 14. The maximum estimated error of the system clock in the
2352 interval since the previous update (in seconds). It
2353 includes the offset, remaining offset correction, root
2354 delay, and dispersion from the previous update with the
2355 dispersion which accumulated in the interval. [8.304e-03]
2356 rtc
2358 This option logs information about the system’s real-time
2359 clock. An example line (which actually appears as a single line
2360 in the file) from the rtc.log file is shown below.
2361 2015-07-22 05:40:50 -0.037360 1 -0.037434\
2363 -37.948 12 5 120
2364 The columns are as follows (the quantities in square brackets
2366 are the values from the example line above):
2367 1. Date [2015-07-22]
2369 2. Hour:Minute:Second. Note that the date-time pair is
2371 expressed in UTC, not the local time zone. [05:40:50]
2372 3. The measured offset between the RTC and the system clock in
2374 seconds. Positive indicates that the RTC is fast of the
2375 system time [-0.037360].
2376 4. Flag indicating whether the regression has produced valid
2378 coefficients. (1 for yes, 0 for no). [1]
2379 5. Offset at the current time predicted by the regression
2381 process. A large difference between this value and the
2382 measured offset tends to indicate that the measurement is
2383 an outlier with a serious measurement error. [-0.037434]
2384 6. The rate at which the RTC is losing or gaining time
2386 relative to the system clock. In ppm, with positive
2387 indicating that the RTC is gaining time. [-37.948]
2388 7. The number of measurements used in the regression. [12]
2390 8. The number of runs of regression residuals of the same
2392 sign. Low values indicate that a straight line is no longer
2393 a good model of the measured data and that older
2394 measurements should be discarded. [5]
2395 9. The measurement interval used prior to the measurement
2397 being made (in seconds). [120]
2398 refclocks
2400 This option logs the raw and filtered reference clock
2401 measurements to a file called refclocks.log. An example line
2402 (which actually appears as a single line in the file) from the
2403 log file is shown below.
2404 2009-11-30 14:33:27.000000 PPS2 7 N 1 4.900000e-07 -6.741777e-07 1.000e-06
2406 The columns are as follows (the quantities in square brackets
2408 are the values from the example line above):
2409 1. Date [2009-11-30]
2411 2. Hour:Minute:Second.Microsecond. Note that the date-time
2413 pair is expressed in UTC, not the local time zone.
2414 [14:33:27.000000]
2415 3. Reference ID of the reference clock from which the
2417 measurement came. [PPS2]
2418 4. Sequence number of driver poll within one polling interval
2420 for raw samples, or - for filtered samples. [7]
2421 5. Leap status (N means normal, + means that the last minute
2423 of the current month has 61 seconds, - means that the last
2424 minute of the month has 59 seconds). [N]
2425 6. Flag indicating whether the sample comes from PPS source.
2427 (1 for yes, 0 for no, or - for filtered sample). [1]
2428 7. Local clock error measured by reference clock driver, or -
2430 for filtered sample. [4.900000e-07]
2431 8. Local clock error with applied corrections. Positive
2433 indicates that the local clock is slow. [-6.741777e-07]
2434 9. Assumed dispersion of the sample. [1.000e-06]
2436 tempcomp
2438 This option logs the temperature measurements and system rate
2439 compensations to a file called tempcomp.log. An example line
2440 (which actually appears as a single line in the file) from the
2441 log file is shown below.
2442 2015-04-19 10:39:48 2.8000e+04 3.6600e-01
2444 The columns are as follows (the quantities in square brackets
2446 are the values from the example line above):
2447 1. Date [2015-04-19]
2449 2. Hour:Minute:Second. Note that the date-time pair is
2451 expressed in UTC, not the local time zone. [10:39:48]
2452 3. Temperature read from the sensor. [2.8000e+04]
2454 4. Applied compensation in ppm, positive means the system
2456 clock is running faster than it would be without the
2457 compensation. [3.6600e-01]
2458 An example of the directive is:
2461 log measurements statistics tracking
2463 logbanner entries
2465 A banner is periodically written to the log files enabled by the
2466 log directive to indicate the meanings of the columns.
2467 The logbanner directive specifies after how many entries in the log
2469 file should be the banner written. The default is 32, and 0 can be
2470 used to disable it entirely.
2471 logchange threshold
2473 This directive sets the threshold for the adjustment of the system
2474 clock that will generate a syslog message. Clock errors detected
2475 via NTP packets, reference clocks, or timestamps entered via the
2476 settime command of chronyc are logged.
2477 By default, the threshold is 1 second.
2479 An example of the use is:
2481 logchange 0.1
2483 which would cause a syslog message to be generated if a system
2485 clock error of over 0.1 seconds starts to be compensated.
2486 logdir directory
2488 This directive specifies the directory for writing log files
2489 enabled by the log directive. If the directory does not exist, it
2490 will be created automatically.
2491 An example of the use of this directive is:
2493 logdir /var/log/chrony
2495 mailonchange email threshold
2497 This directive defines an email address to which mail should be
2498 sent if chronyd applies a correction exceeding a particular
2499 threshold to the system clock.
2500 An example of the use of this directive is:
2502 mailonchange root@localhost 0.5
2504 This would send a mail message to root if a change of more than 0.5
2506 seconds were applied to the system clock.
2507 This directive cannot be used when a system call filter is enabled
2509 by the -F option as the chronyd process will not be allowed to fork
2510 and execute the sendmail binary.
2511 Miscellaneous
2513 confdir directory...
2514 The confdir directive includes configuration files with the .conf
2515 suffix from a directory. The files are included in the
2516 lexicographical order of the file names.
2517 Multiple directories (up to 10) can be specified with a single
2519 confdir directive. In this case, if multiple directories contain a
2520 file with the same name, only the first file in the order of the
2521 specified directories will be included. This enables a fragmented
2522 configuration where existing fragments can be replaced by adding
2523 files to a different directory.
2524 This directive can be used multiple times.
2526 An example of the directive is:
2528 confdir /etc/chrony.d
2530 sourcedir directory...
2532 The sourcedir directive is identical to the confdir directive,
2533 except the configuration files have the .sources suffix, they can
2534 only specify NTP sources (i.e. the server, pool, and peer
2535 directives), they are expected to have all lines terminated by the
2536 newline character, and they can be reloaded by the reload sources
2537 command in chronyc. It is particularly useful with dynamic sources
2538 like NTP servers received from a DHCP server, which can be written
2539 to a file specific to the network interface by a networking script.
2540 This directive can be used multiple times.
2542 An example of the directive is:
2544 sourcedir /var/run/chrony-dhcp
2546 include pattern
2548 The include directive includes a configuration file, or multiple
2549 configuration files if a wildcard pattern is specified. Unlike with
2550 the confdir directive, the full name of the files needs to be
2551 specified and at least one file is required to exist.
2552 This directive can be used multiple times.
2554 An example of the directive is:
2556 include /etc/chrony.d/*.conf
2558 hwtimestamp interface [option]...
2560 This directive enables hardware timestamping of NTP packets sent to
2561 and received from the specified network interface. The network
2562 interface controller (NIC) uses its own clock to accurately
2563 timestamp the actual transmissions and receptions, avoiding
2564 processing and queueing delays in the kernel, network driver, and
2565 hardware. This can significantly improve the accuracy of the
2566 timestamps and the measured offset, which is used for
2567 synchronisation of the system clock. In order to get the best
2568 results, both sides receiving and sending NTP packets (i.e. server
2569 and client, or two peers) need to use HW timestamping. If the
2570 server or peer supports the interleaved mode, it needs to be
2571 enabled by the xleave option in the server or the peer directive.
2572 This directive is supported on Linux 3.19 and newer. The NIC must
2574 support HW timestamping, which can be verified with the ethtool -T
2575 command. The list of capabilities should include
2576 SOF_TIMESTAMPING_RAW_HARDWARE, SOF_TIMESTAMPING_TX_HARDWARE, and
2577 SOF_TIMESTAMPING_RX_HARDWARE. Receive filter HWTSTAMP_FILTER_ALL,
2578 or HWTSTAMP_FILTER_NTP_ALL, is necessary for timestamping of
2579 received NTP packets. Timestamping of packets received on bridged
2580 and bonded interfaces is supported on Linux 4.13 and newer. When
2581 chronyd is running, no other process (e.g. a PTP daemon) should be
2582 working with the NIC clock.
2583 If the kernel supports software timestamping, it will be enabled
2585 for all interfaces. The source of timestamps (i.e. hardware,
2586 kernel, or daemon) is indicated in the measurements.log file if
2587 enabled by the log measurements directive, and the ntpdata report
2588 in chronyc.
2589 This directive can be used multiple times to enable HW timestamping
2591 on multiple interfaces. If the specified interface is *, chronyd
2592 will try to enable HW timestamping on all available interfaces.
2593 The hwtimestamp directive has the following options:
2595 minpoll poll
2597 This option specifies the minimum interval between readings of
2598 the NIC clock. It’s defined as a power of two. It should
2599 correspond to the minimum polling interval of all NTP sources
2600 and the minimum expected polling interval of NTP clients. The
2601 default value is 0 (1 second) and the minimum value is -6
2602 (1/64th of a second).
2603 minsamples samples
2605 This option specifies the minimum number of readings kept for
2606 tracking of the NIC clock. The default value is 2.
2607 maxsamples samples
2609 This option specifies the maximum number of readings kept for
2610 tracking of the NIC clock. The default value is 16.
2611 precision precision
2613 This option specifies the assumed precision of reading of the
2614 NIC clock. The default value is 100e-9 (100 nanoseconds).
2615 txcomp compensation
2617 This option specifies the difference in seconds between the
2618 actual transmission time at the physical layer and the reported
2619 transmit timestamp. This value will be added to transmit
2620 timestamps obtained from the NIC. The default value is 0.
2621 rxcomp compensation
2623 This option specifies the difference in seconds between the
2624 reported receive timestamp and the actual reception time at the
2625 physical layer. This value will be subtracted from receive
2626 timestamps obtained from the NIC. The default value is 0.
2627 nocrossts
2629 Some hardware can precisely cross timestamp the NIC clock with
2630 the system clock. This option disables the use of the cross
2631 timestamping.
2632 rxfilter filter
2634 This option selects the receive timestamping filter. The filter
2635 can be one of the following:
2636 all
2638 Enables timestamping of all received packets.
2639 ntp
2641 Enables timestamping of received NTP packets.
2642 ptp
2644 Enables timestamping of received PTP packets.
2645 none
2647 Disables timestamping of received packets.
2648 The most specific filter for timestamping of NTP packets
2651 supported by the NIC is selected by default. Some NICs can
2652 timestamp PTP packets only. By default, they will be configured
2653 with the none filter and expected to provide hardware
2654 timestamps for transmitted packets only. Timestamping of PTP
2655 packets is useful with NTP-over-PTP enabled by the ptpport
2656 directive. Forcing timestamping of all packets with the all
2657 filter could be useful if the NIC supported both the all and
2658 ntp filters, and it should timestamp both NTP and PTP packets,
2659 or NTP packets on a different UDP port.
2660 Examples of the directive are:
2664 hwtimestamp eth0
2666 hwtimestamp eth1 txcomp 300e-9 rxcomp 645e-9
2667 hwtimestamp *
2668 keyfile file
2670 This directive is used to specify the location of the file
2671 containing symmetric keys which are shared between NTP servers and
2672 clients, or peers, in order to authenticate NTP packets with a
2673 message authentication code (MAC) using a cryptographic hash
2674 function or cipher.
2675 The format of the directive is shown in the example below:
2677 keyfile /etc/chrony.keys
2679 The argument is simply the name of the file containing the ID-key
2681 pairs. The format of the file is shown below:
2682 10 tulip
2684 11 hyacinth
2685 20 MD5 ASCII:crocus
2686 25 SHA1 HEX:933F62BE1D604E68A81B557F18CFA200483F5B70
2687 30 AES128 HEX:7EA62AE64D190114D46D5A082F948EC1
2688 31 AES256 HEX:37DDCBC67BB902BCB8E995977FAB4D2B5642F5B32EBCEEE421921D97E5CBFE39
2689 ...
2690 Each line consists of an ID, optional type, and key.
2692 The ID can be any positive integer in the range 1 through 2^32-1.
2694 The type is a name of a cryptographic hash function or cipher which
2696 is used to generate and verify the MAC. The default type is MD5,
2697 which is always supported. If chronyd was built with enabled
2698 support for hashing using a crypto library (nettle, nss, or
2699 libtomcrypt), the following functions are available: MD5, SHA1,
2700 SHA256, SHA384, SHA512. Depending on which library and version is
2701 chronyd using, some of the following hash functions and ciphers may
2702 also be available: SHA3-224, SHA3-256, SHA3-384, SHA3-512, TIGER,
2703 WHIRLPOOL, AES128, AES256.
2704 The key can be specified as a string of ASCII characters not
2706 containing white space with an optional ASCII: prefix, or as a
2707 hexadecimal number with the HEX: prefix. The maximum length of the
2708 line is 2047 characters. If the type is a cipher, the length of the
2709 key must match the cipher (i.e. 128 bits for AES128 and 256 bits
2710 for AES256).
2711 It is recommended to use randomly generated keys, specified in the
2713 hexadecimal format, which are at least 128 bits long (i.e. they
2714 have at least 32 characters after the HEX: prefix). chronyd will
2715 log a warning to syslog on start if a source is specified in the
2716 configuration file with a key shorter than 80 bits.
2717 The recommended key types are AES ciphers and SHA3 hash functions.
2719 MD5 should be avoided unless no other type is supported on the
2720 server and client, or peers.
2721 The keygen command of chronyc can be used to generate random keys
2723 for the key file. By default, it generates 160-bit MD5 or SHA1
2724 keys.
2725 For security reasons, the file should be readable only by root and
2727 the user under which chronyd is normally running (to allow chronyd
2728 to re-read the file when the rekey command is issued by chronyc).
2729 lock_all
2731 The lock_all directive will lock the chronyd process into RAM so
2732 that it will never be paged out. This can result in lower and more
2733 consistent latency. The directive is supported on Linux, FreeBSD,
2734 NetBSD, and illumos.
2735 pidfile file
2737 Unless chronyd is started with the -Q option, it writes its process
2738 ID (PID) to a file, and checks this file on startup to see if
2739 another chronyd might already be running on the system. By default,
2740 the file used is /run/chrony/chronyd.pid. The pidfile directive
2741 allows the name to be changed, e.g.:
2742 pidfile /run/chronyd.pid
2744 ptpport port
2746 The ptpport directive enables chronyd to send and receive NTP
2747 messages contained in PTP event messages (NTP-over-PTP) to enable
2748 hardware timestamping on NICs which cannot timestamp NTP packets,
2749 but can timestamp unicast PTP packets. The port recognized by the
2750 NICs is 319 (PTP event port). The default value is 0 (disabled).
2751 The NTP-over-PTP support is experimental. The protocol and
2753 configuration can change in future. It should be used only in local
2754 networks and expected to work only between servers and clients
2755 running the same version of chronyd.
2756 The PTP port will be open even if chronyd is not configured to
2758 operate as a server or client. The directive does not change the
2759 default protocol of specified NTP sources. Each NTP source that
2760 should use NTP-over-PTP needs to be specified with the port option
2761 set to the PTP port. To actually enable hardware timestamping on
2762 NICs which can timestamp PTP packets only, the rxfilter option of
2763 the hwtimestamp directive needs to be set to ptp.
2764 An example of client configuration is:
2766 server foo.example.net minpoll 0 maxpoll 0 xleave port 319
2768 hwtimestamp * rxfilter ptp
2769 ptpport 319
2770 sched_priority priority
2772 On Linux, FreeBSD, NetBSD, and illumos, the sched_priority
2773 directive will select the SCHED_FIFO real-time scheduler at the
2774 specified priority (which must be between 0 and 100). On macOS,
2775 this option must have either a value of 0 (the default) to disable
2776 the thread time constraint policy or 1 for the policy to be
2777 enabled.
2778 On systems other than macOS, this directive uses the
2780 pthread_setschedparam() system call to instruct the kernel to use
2781 the SCHED_FIFO first-in, first-out real-time scheduling policy for
2782 chronyd with the specified priority. This means that whenever
2783 chronyd is ready to run it will run, interrupting whatever else is
2784 running unless it is a higher priority real-time process. This
2785 should not impact performance as chronyd resource requirements are
2786 modest, but it should result in lower and more consistent latency
2787 since chronyd will not need to wait for the scheduler to get around
2788 to running it. You should not use this unless you really need it.
2789 The pthread_setschedparam(3) man page has more details.
2790 On macOS, this directive uses the thread_policy_set() kernel call
2792 to specify real-time scheduling. As noted above, you should not use
2793 this directive unless you really need it.
2794 user user
2796 The user directive sets the name of the system user to which
2797 chronyd will switch after start in order to drop root privileges.
2798 On Linux, chronyd needs to be compiled with support for the libcap
2800 library. On macOS, FreeBSD, NetBSD and illumos chronyd forks into
2801 two processes. The child process retains root privileges, but can
2802 only perform a very limited range of privileged system calls on
2803 behalf of the parent.
2804 The compiled-in default value is chrony.
2806
2808 NTP client with permanent connection to NTP servers
2809 This section shows how to configure chronyd for computers that are
2810 connected to the Internet (or to any network containing true NTP
2811 servers which ultimately derive their time from a reference clock)
2812 permanently or most of the time.
2813 To operate in this mode, you will need to know the names of the NTP
2815 servers you want to use. You might be able to find names of suitable
2816 servers by one of the following methods:
2817 • Your institution might already operate servers on its network.
2819 Contact your system administrator to find out.
2820 • Your ISP probably has one or more NTP servers available for its
2822 customers.
2823 • Somewhere under the NTP homepage there is a list of public stratum
2825 1 and stratum 2 servers. You should find one or more servers that
2826 are near to you. Check that their access policy allows you to use
2827 their facilities.
2828 • Use public servers from the pool.ntp.org
2830 <https://www.pool.ntp.org/> project.
2831 Assuming that your NTP servers are called foo.example.net,
2833 bar.example.net and baz.example.net, your chrony.conf file could
2834 contain as a minimum:
2835 server foo.example.net
2837 server bar.example.net
2838 server baz.example.net
2839 However, you will probably want to include some of the other
2841 directives. The driftfile, makestep and rtcsync might be particularly
2842 useful. Also, the iburst option of the server directive is useful to
2843 speed up the initial synchronisation. The smallest useful configuration
2844 file would look something like:
2845 server foo.example.net iburst
2847 server bar.example.net iburst
2848 server baz.example.net iburst
2849 driftfile /var/lib/chrony/drift
2850 makestep 1.0 3
2851 rtcsync
2852 When using a pool of NTP servers (one name is used for multiple servers
2854 which might change over time), it is better to specify them with the
2855 pool directive instead of multiple server directives. The configuration
2856 file could in this case look like:
2857 pool pool.ntp.org iburst
2859 driftfile /var/lib/chrony/drift
2860 makestep 1.0 3
2861 rtcsync
2862 If the servers (or pool) support the Network Time Security (NTS)
2864 authentication mechanism and chronyd is compiled with NTS support, the
2865 nts option will enable a secure synchronisation to the servers. The
2866 configuration file could look like:
2867 server foo.example.net iburst nts
2869 server bar.example.net iburst nts
2870 server baz.example.net iburst nts
2871 driftfile /var/lib/chrony/drift
2872 makestep 1.0 3
2873 rtcsync
2874 NTP client with infrequent connection to NTP servers
2876 This section shows how to configure chronyd for computers that have
2877 occasional connections to NTP servers. In this case, you will need some
2878 additional configuration to tell chronyd when the connection goes up
2879 and down. This saves the program from continuously trying to poll the
2880 servers when they are inaccessible.
2881 Again, assuming that your NTP servers are called foo.example.net,
2883 bar.example.net and baz.example.net, your chrony.conf file would now
2884 contain:
2885 server foo.example.net offline
2887 server bar.example.net offline
2888 server baz.example.net offline
2889 driftfile /var/lib/chrony/drift
2890 makestep 1.0 3
2891 rtcsync
2892 The offline keyword indicates that the servers start in an offline
2894 state, and that they should not be contacted until chronyd receives
2895 notification from chronyc that the link to the Internet is present. To
2896 tell chronyd when to start and finish sampling the servers, the online
2897 and offline commands of chronyc need to be used.
2898 To give an example of their use, assuming that pppd is the program
2900 being used to connect to the Internet and that chronyc has been
2901 installed at /usr/bin/chronyc, the script /etc/ppp/ip-up would include:
2902 /usr/bin/chronyc online
2904 and the script /etc/ppp/ip-down would include:
2906 /usr/bin/chronyc offline
2908 chronyd's polling of the servers would now only occur whilst the
2910 machine is actually connected to the Internet.
2911 Isolated networks
2913 This section shows how to configure chronyd for computers that never
2914 have network connectivity to any computer which ultimately derives its
2915 time from a reference clock.
2916 In this situation, one computer is selected to be the primary
2918 timeserver. The other computers are either direct clients of the
2919 server, or clients of clients.
2920 The local directive enables a local reference mode, which allows
2922 chronyd to appear synchronised even when it is not.
2923 The rate value in the server’s drift file needs to be set to the
2925 average rate at which the server gains or loses time. chronyd includes
2926 support for this, in the form of the manual directive and the settime
2927 command in the chronyc program.
2928 If the server is rebooted, chronyd can re-read the drift rate from the
2930 drift file. However, the server has no accurate estimate of the current
2931 time. To get around this, the system can be configured so that the
2932 server can initially set itself to a ‘majority-vote’ of selected
2933 clients' times; this allows the clients to ‘flywheel’ the server while
2934 it is rebooting.
2935 The smoothtime directive is useful when the clocks of the clients need
2937 to stay close together when the local time is adjusted by the settime
2938 command. The smoothing process needs to be activated by the smoothtime
2939 activate command when the local time is ready to be served. After that
2940 point, any adjustments will be smoothed out.
2941 A typical configuration file for the server (called ntp.local) might be
2943 (assuming the clients and the server are in the 192.168.165.x subnet):
2944 initstepslew 1 client1 client3 client6
2946 driftfile /var/lib/chrony/drift
2947 local stratum 8
2948 manual
2949 allow 192.168.165.0/24
2950 smoothtime 400 0.01
2951 rtcsync
2952 For the clients that have to resynchronise the server when it restarts,
2954 the configuration file might be:
2955 server ntp.local iburst
2957 driftfile /var/lib/chrony/drift
2958 allow 192.168.165.0/24
2959 makestep 1.0 3
2960 rtcsync
2961 The rest of the clients would be the same, except that the allow
2963 directive is not required.
2964 If there is no suitable computer to be designated as the primary
2966 server, or there is a requirement to keep the clients synchronised even
2967 when it fails, the orphan option of the local directive enables a
2968 special mode where the server is selected from multiple computers
2969 automatically. They all need to use the same local configuration and
2970 poll one another. The server with the smallest reference ID (which is
2971 based on its IP address) will take the role of the primary server and
2972 others will be synchronised to it. When it fails, the server with the
2973 second smallest reference ID will take over and so on.
2974 A configuration file for the first server might be (assuming there are
2976 three servers called ntp1.local, ntp2.local, and ntp3.local):
2977 initstepslew 1 ntp2.local ntp3.local
2979 server ntp2.local
2980 server ntp3.local
2981 driftfile /var/lib/chrony/drift
2982 local stratum 8 orphan
2983 manual
2984 allow 192.168.165.0/24
2985 rtcsync
2986 The other servers would be the same, except the hostnames in the
2988 initstepslew and server directives would be modified to specify the
2989 other servers. Their clients might be configured to poll all three
2990 servers.
2991 RTC tracking
2993 This section considers a computer which has occasional connections to
2994 the Internet and is turned off between ‘sessions’. In this case,
2995 chronyd relies on the computer’s RTC to maintain the time between the
2996 periods when it is powered up. It assumes that Linux is run exclusively
2997 on the computer. Dual-boot systems might work; it depends what (if
2998 anything) the other system does to the RTC. On 2.6 and later kernels,
2999 if your motherboard has a HPET, you will need to enable the
3000 HPET_EMULATE_RTC option in your kernel configuration. Otherwise,
3001 chronyd will not be able to interact with the RTC device and will give
3002 up using it.
3003 When the computer is connected to the Internet, chronyd has access to
3005 external NTP servers which it makes measurements from. These
3006 measurements are saved, and straight-line fits are performed on them to
3007 provide an estimate of the computer’s time error and rate of gaining or
3008 losing time.
3009 When the computer is taken offline from the Internet, the best estimate
3011 of the gain or loss rate is used to free-run the computer until it next
3012 goes online.
3013 Whilst the computer is running, chronyd makes measurements of the RTC
3015 (via the /dev/rtc interface, which must be compiled into the kernel).
3016 An estimate is made of the RTC error at a particular RTC second, and
3017 the rate at which the RTC gains or loses time relative to true time.
3018 When the computer is powered down, the measurement histories for all
3020 the NTP servers are saved to files, and the RTC tracking information is
3021 also saved to a file (if the rtcfile directive has been specified).
3022 These pieces of information are also saved if the dump and writertc
3023 commands respectively are issued through chronyc.
3024 When the computer is rebooted, chronyd reads the current RTC time and
3026 the RTC information saved at the last shutdown. This information is
3027 used to set the system clock to the best estimate of what its time
3028 would have been now, had it been left running continuously. The
3029 measurement histories for the servers are then reloaded.
3030 The next time the computer goes online, the previous sessions'
3032 measurements can contribute to the line-fitting process, which gives a
3033 much better estimate of the computer’s gain or loss rate.
3034 One problem with saving the measurements and RTC data when the machine
3036 is shut down is what happens if there is a power failure; the most
3037 recent data will not be saved. Although chronyd is robust enough to
3038 cope with this, some performance might be lost. (The main danger arises
3039 if the RTC has been changed during the session, with the trimrtc
3040 command in chronyc. Because of this, trimrtc will make sure that a
3041 meaningful RTC file is saved after the change is completed).
3042 The easiest protection against power failure is to put the dump and
3044 writertc commands in the same place as the offline command is issued to
3045 take chronyd offline; because chronyd free-runs between online
3046 sessions, no parameters will change significantly between going offline
3047 from the Internet and any power failure.
3048 A final point regards computers which are left running for extended
3050 periods and where it is desired to spin down the hard disc when it is
3051 not in use (e.g. when not accessed for 15 minutes). chronyd has been
3052 planned so it supports such operation; this is the reason why the RTC
3053 tracking parameters are not saved to disc after every update, but only
3054 when the user requests such a write, or during the shutdown sequence.
3055 The only other facility that will generate periodic writes to the disc
3056 is the log rtc facility in the configuration file; this option should
3057 not be used if you want your disc to spin down.
3058 To illustrate how a computer might be configured for this case, example
3060 configuration files are shown.
3061 For the chrony.conf file, the following can be used as an example.
3063 server foo.example.net maxdelay 0.4 offline
3065 server bar.example.net maxdelay 0.4 offline
3066 server baz.example.net maxdelay 0.4 offline
3067 logdir /var/log/chrony
3068 log statistics measurements tracking
3069 driftfile /var/lib/chrony/drift
3070 makestep 1.0 3
3071 maxupdateskew 100.0
3072 dumpdir /var/lib/chrony
3073 rtcfile /var/lib/chrony/rtc
3074 pppd is used for connecting to the Internet. This runs two scripts
3076 /etc/ppp/ip-up and /etc/ppp/ip-down when the link goes online and
3077 offline respectively.
3078 The relevant part of the /etc/ppp/ip-up file is:
3080 /usr/bin/chronyc online
3082 and the relevant part of the /etc/ppp/ip-down script is:
3084 /usr/bin/chronyc -m offline dump writertc
3086 chronyd is started during the boot sequence with the -r and -s options.
3088 It might need to be started before any software that depends on the
3089 system clock not jumping or moving backwards, depending on the
3090 directives in chronyd's configuration file.
3091 For the system shutdown, chronyd should receive a SIGTERM several
3093 seconds before the final SIGKILL; the SIGTERM causes the measurement
3094 histories and RTC information to be saved.
3095 Public NTP server
3097 chronyd can be configured to operate as a public NTP server, e.g. to
3098 join the pool.ntp.org <https://www.pool.ntp.org/en/join.html> project.
3099 The configuration is similar to the NTP client with permanent
3100 connection, except it needs to allow client access from all addresses.
3101 It is recommended to find at least four good servers (e.g. from the
3102 pool, or on the NTP homepage). If the server has a hardware reference
3103 clock (e.g. a GPS receiver), it can be specified by the refclock
3104 directive.
3105 The amount of memory used for logging client accesses can be increased
3107 in order to enable clients to use the interleaved mode even when the
3108 server has a large number of clients, and better support rate limiting
3109 if it is enabled by the ratelimit directive. The system timezone
3110 database, if it is kept up to date and includes the right/UTC timezone,
3111 can be used as a reliable source to determine when a leap second will
3112 be applied to UTC. The -r option with the dumpdir directive shortens
3113 the time in which chronyd will not be able to serve time to its clients
3114 when it needs to be restarted (e.g. after upgrading to a newer version,
3115 or a change in the configuration).
3116 The configuration file could look like:
3118 server foo.example.net iburst
3120 server bar.example.net iburst
3121 server baz.example.net iburst
3122 server qux.example.net iburst
3123 makestep 1.0 3
3124 rtcsync
3125 allow
3126 clientloglimit 100000000
3127 leapsectz right/UTC
3128 driftfile /var/lib/chrony/drift
3129 dumpdir /run/chrony
3130
3132 chronyc(1), chronyd(8)
3133
3135 For instructions on how to report bugs, please visit
3136 https://chrony.tuxfamily.org/.
3137
3139 chrony was written by Richard Curnow, Miroslav Lichvar, and others.
3140chrony 4.2 2021-12-16 CHRONY.CONF(5)