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 The server can be specified by its hostname or IP address. If the
46 hostname cannot be resolved on start, chronyd will try it again in
47 increasing intervals, and also when the online command is issued in
48 chronyc.
49 The DNS record can change over time. The used address will be
51 replaced with a newly resolved address when the server becomes
52 unreachable (i.e. no valid response to last 8 requests),
53 unsynchronised, a falseticker (i.e. does not agree with a majority
54 of other sources), or the root distance is too large (the limit can
55 be configured by the maxdistance directive). The automatic
56 replacement happens at most once per 30 minutes. It can also be
57 triggered manually for all sources by the refresh command in
58 chronyc.
59 This directive can be used multiple times to specify multiple
61 servers.
62 The directive supports the following options:
64 minpoll poll
66 This option specifies the minimum interval between requests
67 sent to the server as a power of 2 in seconds. For example,
68 minpoll 5 would mean that the polling interval should not drop
69 below 32 seconds. The default is 6 (64 seconds), the minimum is
70 -7 (1/128th of a second), and the maximum is 24 (6 months).
71 Note that intervals shorter than 6 (64 seconds) should
72 generally not be used with public servers on the Internet,
73 because it might be considered abuse. A sub-second interval
74 will be enabled only when the server is reachable and the
75 round-trip delay is shorter than 10 milliseconds, i.e. the
76 server should be in a local network.
77 maxpoll poll
79 This option specifies the maximum interval between requests
80 sent to the server as a power of 2 in seconds. For example,
81 maxpoll 9 indicates that the polling interval should stay at or
82 below 9 (512 seconds). The default is 10 (1024 seconds), the
83 minimum is -7 (1/128th of a second), and the maximum is 24 (6
84 months).
85 iburst
87 With this option, chronyd will start with a burst of 4-8
88 requests in order to make the first update of the clock sooner.
89 It will also repeat the burst every time the source is switched
90 from the offline state to online with the online command in
91 chronyc.
92 burst
94 With this option, chronyd will send a burst of up to 4 requests
95 when it cannot get a good measurement from the server. The
96 number of requests in the burst is limited by the current
97 polling interval to keep the average interval at or above the
98 minimum interval, i.e. the current interval needs to be at
99 least two times longer than the minimum interval in order to
100 allow a burst with two requests.
101 key ID
103 The NTP protocol supports a message authentication code (MAC)
104 to prevent computers having their system time upset by rogue
105 packets being sent to them. The MAC is generated as a function
106 of a key specified in the key file, which is specified by the
107 keyfile directive.
108 The key option specifies which key (with an ID in the range 1
110 through 2^32-1) should chronyd use to authenticate requests
111 sent to the server and verify its responses. The server must
112 have the same key for this number configured, otherwise no
113 relationship between the computers will be possible.
114 If the server is running ntpd and the output size of the hash
116 function used by the key is longer than 160 bits (e.g. SHA256),
117 the version option needs to be set to 4 for compatibility.
118 nts
120 This option enables authentication using the Network Time
121 Security (NTS) mechanism. Unlike with the key option, the
122 server and client do not need to share a key in a key file. NTS
123 has a Key Establishment (NTS-KE) protocol using the Transport
124 Layer Security (TLS) protocol to get the keys and cookies
125 required by NTS for authentication of NTP packets.
126 certset ID
128 This option specifies which set of trusted certificates should
129 be used to verify the server’s certificate when the nts option
130 is enabled. Sets of certificates can be specified with the
131 ntstrustedcerts directive. The default set is 0, which by
132 default contains certificates of the system’s default trusted
133 certificate authorities.
134 maxdelay delay
136 chronyd uses the network round-trip delay to the server to
137 determine how accurate a particular measurement is likely to
138 be. Long round-trip delays indicate that the request, or the
139 response, or both were delayed. If only one of the messages was
140 delayed the measurement error is likely to be substantial.
141 For small variations in the round-trip delay, chronyd uses a
143 weighting scheme when processing the measurements. However,
144 beyond a certain level of delay the measurements are likely to
145 be so corrupted as to be useless. (This is particularly so on
146 wireless networks and other slow links, where a long delay
147 probably indicates a highly asymmetric delay caused by the
148 response waiting behind a lot of packets related to a download
149 of some sort).
150 If the user knows that round trip delays above a certain level
152 should cause the measurement to be ignored, this level can be
153 defined with the maxdelay option. For example, maxdelay 0.3
154 would indicate that measurements with a round-trip delay
155 greater than 0.3 seconds should be ignored. The default value
156 is 3 seconds and the maximum value is 1000 seconds.
157 maxdelayratio ratio
159 This option is similar to the maxdelay option above. chronyd
160 keeps a record of the minimum round-trip delay amongst the
161 previous measurements that it has buffered. If a measurement
162 has a round-trip delay that is greater than the specified ratio
163 times the minimum delay, it will be rejected. By default, this
164 test is disabled.
165 maxdelaydevratio ratio
167 If a measurement has a ratio of the increase in the round-trip
168 delay from the minimum delay amongst the previous measurements
169 to the standard deviation of the previous measurements that is
170 greater than the specified ratio, it will be rejected. The
171 default is 10.0.
172 maxdelayquant p
174 This option disables the maxdelaydevratio test and specifies
175 the maximum acceptable delay as a quantile of the round-trip
176 delay instead of a function of the minimum delay amongst the
177 buffered measurements. If a measurement has a round-trip delay
178 that is greater than a long-term estimate of the p-quantile, it
179 will be rejected.
180 The specified p value should be between 0.05 and 0.95. For
182 example, maxdelayquant 0.2 would indicate that only
183 measurements with the lowest 20 percent of round-trip delays
184 should be accepted. Note that it can take many measurements for
185 the estimated quantile to reach the expected value. This option
186 is intended for synchronisation in mostly static local networks
187 with very short polling intervals and possibly combined with
188 the filter option. By default, this test is disabled in favour
189 of the maxdelaydevratio test.
190 mindelay delay
192 This option specifies a fixed minimum round-trip delay to be
193 used instead of the minimum amongst the previous measurements.
194 This can be useful in networks with static configuration to
195 improve the stability of corrections for asymmetric jitter,
196 weighting of the measurements, and the maxdelayratio and
197 maxdelaydevratio tests. The value should be set accurately in
198 order to have a positive effect on the synchronisation.
199 asymmetry ratio
201 This option specifies the asymmetry of the network jitter on
202 the path to the source, which is used to correct the measured
203 offset according to the delay. The asymmetry can be between
204 -0.5 and +0.5. A negative value means the delay of packets sent
205 to the source is more variable than the delay of packets sent
206 from the source back. By default, chronyd estimates the
207 asymmetry automatically.
208 offset offset
210 This option specifies a correction (in seconds) which will be
211 applied to offsets measured with this source. It’s particularly
212 useful to compensate for a known asymmetry in network delay or
213 timestamping errors. For example, if packets sent to the source
214 were on average delayed by 100 microseconds more than packets
215 sent from the source back, the correction would be -0.00005
216 (-50 microseconds). The default is 0.0.
217 minsamples samples
219 Set the minimum number of samples kept for this source. This
220 overrides the minsamples directive.
221 maxsamples samples
223 Set the maximum number of samples kept for this source. This
224 overrides the maxsamples directive.
225 filter polls
227 This option enables a median filter to reduce noise in NTP
228 measurements. The filter will process samples collected in the
229 specified number of polls into a single sample. It is intended
230 to be used with very short polling intervals in local networks
231 where it is acceptable to generate a lot of NTP traffic.
232 offline
234 If the server will not be reachable when chronyd is started,
235 the offline option can be specified. chronyd will not try to
236 poll the server until it is enabled to do so (by using the
237 online command in chronyc).
238 auto_offline
240 With this option, the server will be assumed to have gone
241 offline when sending a request fails, e.g. due to a missing
242 route to the network. This option avoids the need to run the
243 offline command from chronyc when disconnecting the network
244 link. (It will still be necessary to use the online command
245 when the link has been established, to enable measurements to
246 start.)
247 prefer
249 Prefer this source over sources without the prefer option.
250 noselect
252 Never select this source. This is particularly useful for
253 monitoring.
254 trust
256 Assume time from this source is always true. It can be rejected
257 as a falseticker in the source selection only if another source
258 with this option does not agree with it.
259 require
261 Require that at least one of the sources specified with this
262 option is selectable (i.e. recently reachable and not a
263 falseticker) before updating the clock. Together with the trust
264 option this might be useful to allow a trusted authenticated
265 source to be safely combined with unauthenticated sources in
266 order to improve the accuracy of the clock. They can be
267 selected and used for synchronisation only if they agree with
268 the trusted and required source.
269 xleave
271 This option enables the interleaved mode of NTP. It enables the
272 server to respond with more accurate transmit timestamps (e.g.
273 kernel or hardware timestamps), which cannot be contained in
274 the transmitted packet itself and need to refer to a previous
275 packet instead. This can significantly improve the accuracy and
276 stability of the measurements.
277 The interleaved mode is compatible with servers that support
279 only the basic mode. Note that even servers that support the
280 interleaved mode might respond in the basic mode as the
281 interleaved mode requires the servers to keep some state for
282 each client and the state might be dropped when there are too
283 many clients (e.g. clientloglimit is too small), or it might be
284 overwritten by other clients that have the same IP address
285 (e.g. computers behind NAT or someone sending requests with a
286 spoofed source address).
287 The xleave option can be combined with the presend option in
289 order to shorten the interval in which the server has to keep
290 the state to be able to respond in the interleaved mode.
291 polltarget target
293 Target number of measurements to use for the regression
294 algorithm which chronyd will try to maintain by adjusting the
295 polling interval between minpoll and maxpoll. A higher target
296 makes chronyd prefer shorter polling intervals. The default is
297 8 and a useful range is from 6 to 60.
298 port port
300 This option allows the UDP port on which the server understands
301 NTP requests to be specified. For normal servers this option
302 should not be required (the default is 123, the standard NTP
303 port).
304 ntsport port
306 This option specifies the TCP port on which the server is
307 listening for NTS-KE connections when the nts option is
308 enabled. The default is 4460.
309 presend poll
311 If the timing measurements being made by chronyd are the only
312 network data passing between two computers, you might find that
313 some measurements are badly skewed due to either the client or
314 the server having to do an ARP lookup on the other party prior
315 to transmitting a packet. This is more of a problem with long
316 sampling intervals, which might be similar in duration to the
317 lifetime of entries in the ARP caches of the machines.
318 In order to avoid this problem, the presend option can be used.
320 It takes a single integer argument, which is the smallest
321 polling interval for which an extra pair of NTP packets will be
322 exchanged between the client and the server prior to the actual
323 measurement. For example, with the following option included in
324 a server directive:
325 presend 9
327 when the polling interval is 512 seconds or more, an extra NTP
329 client packet will be sent to the server a short time (2
330 seconds) before making the actual measurement.
331 If the presend option is used together with the xleave option,
333 chronyd will send two extra packets instead of one.
334 minstratum stratum
336 When the synchronisation source is selected from available
337 sources, sources with lower stratum are normally slightly
338 preferred. This option can be used to increase stratum of the
339 source to the specified minimum, so chronyd will avoid
340 selecting that source. This is useful with low-stratum sources
341 that are known to be unreliable or inaccurate and which should
342 be used only when other sources are unreachable.
343 version version
345 This option sets the NTP version of packets sent to the server.
346 This can be useful when the server runs an old NTP
347 implementation that does not respond to requests using a newer
348 version. The default version depends on other options. If the
349 extfield or xleave option is used, the default version is 4. If
350 those options are not used and the key option specifies a key
351 using a hash function with output size longer than 160 bits
352 (e.g. SHA256), the default version is 3 for compatibility with
353 older chronyd servers. In other cases, the default version is
354 4.
355 copy
357 This option specifies that the server and client are closely
358 related, their configuration does not allow a synchronisation
359 loop to form between them, and the client is allowed to assume
360 the reference ID and stratum of the server. This is useful when
361 multiple instances of chronyd are running on one computer (e.g.
362 for security or performance reasons), one primarily operating
363 as a client to synchronise the system clock and other instances
364 started with the -x option to operate as NTP servers for other
365 computers with their NTP clocks synchronised to the first
366 instance.
367 extfield type
369 This option enables an NTPv4 extension field specified by its
370 type as a hexadecimal number. It will be included in requests
371 sent to the server and processed in received responses if the
372 server supports it. Note that some server implementations do
373 not respond to requests containing an unknown extension field
374 (chronyd as a server responded to such requests since version
375 2.0).
376 The following extension field can be enabled by this option:
378 F323
380 This is an experimental extension field for some
381 improvements that were proposed for the next version of the
382 NTP protocol (NTPv5). The field contains root delay and
383 dispersion in higher resolution and a monotonic receive
384 timestamp, which enables a frequency transfer between the
385 server and client. It can significantly improve stability
386 of the synchronization. Generally, it should be expected to
387 work only between servers and clients running the same
388 version of chronyd.
389 pool name [option]...
393 The syntax of this directive is similar to that for the server
394 directive, except that it is used to specify a pool of NTP servers
395 rather than a single NTP server. The pool name is expected to
396 resolve to multiple addresses which might change over time.
397 This directive can be used multiple times to specify multiple
399 pools.
400 All options valid in the server directive can be used in this
402 directive too. There is one option specific to the pool directive:
403 maxsources sources
405 This option sets the desired number of sources to be used from
406 the pool. chronyd will repeatedly try to resolve the name until
407 it gets this number of sources responding to requests. The
408 default value is 4 and the maximum value is 16.
409 An example of the pool directive is
411 pool pool.ntp.org iburst maxsources 3
413 peer hostname [option]...
415 The syntax of this directive is identical to that for the server
416 directive, except that it specifies a symmetric association with an
417 NTP peer instead of a client/server association with an NTP server.
418 A single symmetric association allows the peers to be both servers
419 and clients to each other. This is mainly useful when the NTP
420 implementation of the peer (e.g. ntpd) supports ephemeral symmetric
421 associations and does not need to be configured with an address of
422 this host. chronyd does not support ephemeral associations.
423 This directive can be used multiple times to specify multiple
425 peers.
426 The following options of the server directive do not work in the
428 peer directive: iburst, burst, nts, presend, copy.
429 When using the xleave option, both peers must support and have
431 enabled the interleaved mode, otherwise the synchronisation will
432 work in one direction only. When a key is specified by the key
433 option to enable authentication, both peers must use the same key
434 and the same key number.
435 Note that the symmetric mode is less secure than the client/server
437 mode. A denial-of-service attack is possible on unauthenticated
438 symmetric associations, i.e. when the peer was specified without
439 the key option. An attacker who does not see network traffic
440 between two hosts, but knows that they are peering with each other,
441 can periodically send them unauthenticated packets with spoofed
442 source addresses in order to disrupt their NTP state and prevent
443 them from synchronising to each other. When the association is
444 authenticated, an attacker who does see the network traffic, but
445 cannot prevent the packets from reaching the other host, can still
446 disrupt the state by replaying old packets. The attacker has
447 effectively the same power as a man-in-the-middle attacker. A
448 partial protection against this attack is implemented in chronyd,
449 which can protect the peers if they are using the same polling
450 interval and they never sent an authenticated packet with a
451 timestamp from future, but it should not be relied on as it is
452 difficult to ensure the conditions are met. If two hosts should be
453 able to synchronise to each other in both directions, it is
454 recommended to use two separate client/server associations
455 (specified by the server directive on both hosts) instead.
456 initstepslew step-threshold [hostname]...
458 (This directive is deprecated in favour of the makestep directive.)
459 The purpose of the initstepslew directive is to allow chronyd to
461 make a rapid measurement of the system clock error at boot time,
462 and to correct the system clock by stepping before normal operation
463 begins. Since this would normally be performed only at an
464 appropriate point in the system boot sequence, no other software
465 should be adversely affected by the step.
466 If the correction required is less than a specified threshold, a
468 slew is used instead. This makes it safer to restart chronyd whilst
469 the system is in normal operation.
470 The initstepslew directive takes a threshold and a list of NTP
472 servers as arguments. Each of the servers is rapidly polled several
473 times, and a majority voting mechanism used to find the most likely
474 range of system clock error that is present. A step or slew is
475 applied to the system clock to correct this error. chronyd then
476 enters its normal operating mode.
477 An example of the use of the directive is:
479 initstepslew 30 foo.example.net bar.example.net baz.example.net
481 where 3 NTP servers are used to make the measurement. The 30
483 indicates that if the system’s error is found to be 30 seconds or
484 less, a slew will be used to correct it; if the error is above 30
485 seconds, a step will be used.
486 The initstepslew directive can also be used in an isolated LAN
488 environment, where the clocks are set manually. The most stable
489 computer is chosen as the primary server and the other computers
490 are its clients. If each of the clients is configured with the
491 local directive, the server can be set up with an initstepslew
492 directive which references some or all of the clients. Then, if the
493 server machine has to be rebooted, the clients can be relied on to
494 act analogously to a flywheel and preserve the time for a short
495 period while the server completes its reboot.
496 The initstepslew directive is functionally similar to a combination
498 of the makestep and server directives with the iburst option. The
499 main difference is that the initstepslew servers are used only
500 before normal operation begins and that the foreground chronyd
501 process waits for initstepslew to finish before exiting. This
502 prevent programs started in the boot sequence after chronyd from
503 reading the clock before it has been stepped. With the makestep
504 directive, the waitsync command of chronyc can be used instead.
505 refclock driver parameter[:option]... [option]...
507 The refclock directive specifies a hardware reference clock to be
508 used as a time source. It has two mandatory parameters, a driver
509 name and a driver-specific parameter. The two parameters are
510 followed by zero or more refclock options. Some drivers have
511 special options, which can be appended to the driver-specific
512 parameter using the : character.
513 This directive can be used multiple times to specify multiple
515 reference clocks.
516 There are four drivers included in chronyd:
518 PPS
520 Driver for the kernel PPS (pulse per second) API. The parameter
521 is the path to the PPS device (typically /dev/pps?). As PPS
522 refclocks do not supply full time, another time source (e.g.
523 NTP server or non-PPS refclock) is needed to complete samples
524 from the PPS refclock. An alternative is to enable the local
525 directive to allow synchronisation with some unknown but
526 constant offset. The driver supports the following option:
527 clear
529 By default, the PPS refclock uses assert events (rising
530 edge) for synchronisation. With this option, it will use
531 clear events (falling edge) instead.
532 Examples:
535 refclock PPS /dev/pps0 lock NMEA refid GPS
537 refclock SHM 0 offset 0.5 delay 0.2 refid NMEA noselect
538 refclock PPS /dev/pps1:clear refid GPS2
539 SHM
541 NTP shared memory driver. This driver uses a shared memory
542 segment to receive samples from another process (e.g. gpsd).
543 The parameter is the number of the shared memory segment,
544 typically a small number like 0, 1, 2, or 3. The driver
545 supports the following option:
546 perm=mode
548 This option specifies the permissions of the shared memory
549 segment created by chronyd. They are specified as a numeric
550 mode. The default value is 0600 (read-write access for
551 owner only).
552 Examples:
556 refclock SHM 0 poll 3 refid GPS1
558 refclock SHM 1:perm=0644 refid GPS2
559 SOCK
561 Unix domain socket driver. It is similar to the SHM driver, but
562 samples are received from a Unix domain socket instead of
563 shared memory and the messages have a different format. The
564 parameter is the path to the socket, which chronyd creates on
565 start. An advantage over the SHM driver is that SOCK does not
566 require polling and it can receive PPS samples with incomplete
567 time. The format of the messages is described in the
568 refclock_sock.c file in the chrony source code.
569 An application which supports the SOCK protocol is the gpsd
571 daemon. The path where gpsd expects the socket to be created is
572 described in the gpsd(8) man page. For example:
573 refclock SOCK /var/run/chrony.ttyS0.sock
575 PHC
577 PTP hardware clock (PHC) driver. The parameter is the path to
578 the device of the PTP clock which should be used as a time
579 source. If the clock is kept in TAI instead of UTC (e.g. it is
580 synchronised by a PTP daemon), the current UTC-TAI offset needs
581 to be specified by the offset option. Alternatively, the pps
582 refclock option can be enabled to treat the PHC as a PPS
583 refclock, using only the sub-second offset for synchronisation.
584 The driver supports the following options:
585 nocrossts
587 This option disables use of precise cross timestamping.
588 extpps
590 This option enables a PPS mode in which the PTP clock is
591 timestamping pulses of an external PPS signal connected to
592 the clock. The clock does not need to be synchronised, but
593 another time source is needed to complete the PPS samples.
594 Note that some PTP clocks cannot be configured to timestamp
595 only assert or clear events, and it is necessary to use the
596 width option to filter wrong PPS samples.
597 pin=index
599 This option specifies the index of the pin which should be
600 enabled for the PPS timestamping. If the PHC does not have
601 configurable pins (i.e. the channel function is fixed), the
602 index needs to be set to -1 to disable the pin
603 configuration. The default value is 0.
604 channel=index
606 This option specifies the index of the channel for the PPS
607 mode. The default value is 0.
608 clear
610 This option enables timestamping of clear events (falling
611 edge) instead of assert events (rising edge) in the PPS
612 mode. This may not work with some clocks.
613 Examples:
617 refclock PHC /dev/ptp0 poll 0 dpoll -2 offset -37
619 refclock PHC /dev/ptp1:nocrossts poll 3 pps
620 refclock PHC /dev/ptp2:extpps:pin=1 width 0.2 poll 2
621 The refclock directive supports the following options:
624 poll poll
626 Timestamps produced by refclock drivers are not used
627 immediately, but they are stored and processed by a median
628 filter in the polling interval specified by this option. This
629 is defined as a power of 2 and can be negative to specify a
630 sub-second interval. The default is 4 (16 seconds). A shorter
631 interval allows chronyd to react faster to changes in the
632 frequency of the system clock, but it might have a negative
633 effect on its accuracy if the samples have a lot of jitter.
634 dpoll dpoll
636 Some drivers do not listen for external events and try to
637 produce samples in their own polling interval. This is defined
638 as a power of 2 and can be negative to specify a sub-second
639 interval. The default is 0 (1 second).
640 refid refid
642 This option is used to specify the reference ID of the
643 refclock, as up to four ASCII characters. The default reference
644 ID is composed from the first three characters of the driver
645 name and the number of the refclock. Each refclock must have a
646 unique reference ID.
647 lock refid
649 This option can be used to lock a PPS refclock to another
650 refclock, which is specified by its reference ID. In this mode
651 received PPS samples are paired directly with raw samples from
652 the specified refclock.
653 rate rate
655 This option sets the rate of the pulses in the PPS signal (in
656 Hz). This option controls how the pulses will be completed with
657 real time. To actually receive more than one pulse per second,
658 a negative dpoll has to be specified (-3 for a 5Hz signal). The
659 default is 1.
660 maxlockage pulses
662 This option specifies in number of pulses how old can be
663 samples from the refclock specified by the lock option to be
664 paired with the pulses. Increasing this value is useful when
665 the samples are produced at a lower rate than the pulses. The
666 default is 2.
667 width width
669 This option specifies the width of the pulses (in seconds). It
670 is used to filter PPS samples when the driver provides samples
671 for both rising and falling edges. Note that it reduces the
672 maximum allowed error of the time source which completes the
673 PPS samples. If the duty cycle is configurable, 50% should be
674 preferred in order to maximise the allowed error.
675 pps
677 This options forces chronyd to treat any refclock (e.g. SHM or
678 PHC) as a PPS refclock. This can be useful when the refclock
679 provides time with a variable offset of a whole number of
680 seconds (e.g. it uses TAI instead of UTC). Another time source
681 is needed to complete samples from the refclock.
682 offset offset
684 This option can be used to compensate for a constant error. The
685 specified offset (in seconds) is applied to all samples
686 produced by the reference clock. The default is 0.0.
687 delay delay
689 This option sets the NTP delay of the source (in seconds). Half
690 of this value is included in the maximum assumed error which is
691 used in the source selection algorithm. Increasing the delay is
692 useful to avoid having no majority in the source selection or
693 to make it prefer other sources. The default is 1e-9 (1
694 nanosecond).
695 stratum stratum
697 This option sets the NTP stratum of the refclock. This can be
698 useful when the refclock provides time with a stratum other
699 than 0. The default is 0.
700 precision precision
702 This option sets the precision of the reference clock (in
703 seconds). The default value is the estimated precision of the
704 system clock.
705 maxdispersion dispersion
707 Maximum allowed dispersion for filtered samples (in seconds).
708 Samples with larger estimated dispersion are ignored. By
709 default, this limit is disabled.
710 filter samples
712 This option sets the length of the median filter which is used
713 to reduce the noise in the measurements. With each poll about
714 40 percent of the stored samples are discarded and one final
715 sample is calculated as an average of the remaining samples. If
716 the length is 4 or more, at least 4 samples have to be
717 collected between polls. For lengths below 4, the filter has to
718 be full. The default is 64.
719 prefer
721 Prefer this source over sources without the prefer option.
722 noselect
724 Never select this source. This is useful for monitoring or with
725 sources which are not very accurate, but are locked with a PPS
726 refclock.
727 trust
729 Assume time from this source is always true. It can be rejected
730 as a falseticker in the source selection only if another source
731 with this option does not agree with it.
732 require
734 Require that at least one of the sources specified with this
735 option is selectable (i.e. recently reachable and not a
736 falseticker) before updating the clock. Together with the trust
737 option this can be useful to allow a trusted, but not very
738 precise, reference clock to be safely combined with
739 unauthenticated NTP sources in order to improve the accuracy of
740 the clock. They can be selected and used for synchronisation
741 only if they agree with the trusted and required source.
742 tai
744 This option indicates that the reference clock keeps time in
745 TAI instead of UTC and that chronyd should correct its offset
746 by the current TAI-UTC offset. The leapsectz directive must be
747 used with this option and the database must be kept up to date
748 in order for this correction to work as expected. This option
749 does not make sense with PPS refclocks.
750 local
752 This option specifies that the reference clock is an
753 unsynchronised clock which is more stable than the system clock
754 (e.g. TCXO, OCXO, or atomic clock) and it should be used as a
755 local standard to stabilise the system clock. The refclock will
756 bypass the source selection. There should be at most one
757 refclock specified with this option and it should have the
758 shortest polling interval among all configured sources.
759 minsamples samples
761 Set the minimum number of samples kept for this source. This
762 overrides the minsamples directive.
763 maxsamples samples
765 Set the maximum number of samples kept for this source. This
766 overrides the maxsamples directive.
767 manual
769 The manual directive enables support at run-time for the settime
770 command in chronyc. If no manual directive is included, any attempt
771 to use the settime command in chronyc will be met with an error
772 message.
773 Note that the settime command can be enabled at run-time using the
775 manual command in chronyc. (The idea of the two commands is that
776 the manual command controls the manual clock driver’s behaviour,
777 whereas the settime command allows samples of manually entered time
778 to be provided.)
779 acquisitionport port
781 By default, chronyd as an NTP client opens a new socket for each
782 request with the source port chosen randomly by the operating
783 system. The acquisitionport directive can be used to specify the
784 source port and use only one socket (per IPv4 or IPv6 address
785 family) for all configured servers. This can be useful for getting
786 through some firewalls. It should not be used if not necessary as
787 there is a small impact on security of the client. If set to 0, the
788 source port of the permanent socket will be chosen randomly by the
789 operating system.
790 It can be set to the same port as is used by the NTP server (which
792 can be configured with the port directive) to use only one socket
793 for all NTP packets.
794 An example of the acquisitionport directive is:
796 acquisitionport 1123
798 This would change the source port used for client requests to UDP
800 port 1123. You could then persuade the firewall administrator to
801 open that port.
802 bindacqaddress address
804 The bindacqaddress directive specifies a local IP address to which
805 chronyd will bind its NTP and NTS-KE client sockets. The syntax is
806 similar to the bindaddress and bindcmdaddress directives.
807 For each of the IPv4 and IPv6 protocols, only one bindacqaddress
809 directive can be specified.
810 bindacqdevice interface
812 The bindacqdevice directive binds the client sockets to a network
813 device specified by the interface name. This can be useful when the
814 local address is dynamic, or to enable an NTP source specified with
815 a link-local IPv6 address. This directive can specify only one
816 interface and it is supported on Linux only.
817 An example of the directive is:
819 bindacqdevice eth0
821 dscp point
823 The dscp directive sets the Differentiated Services Code Point
824 (DSCP) in transmitted NTP packets to the specified value. It can
825 improve stability of NTP measurements in local networks where
826 switches or routers are configured to prioritise forwarding of
827 packets with specific DSCP values. The default value is 0 and the
828 maximum value is 63.
829 An example of the directive (setting the Expedited Forwarding
831 class) is:
832 dscp 46
834 dumpdir directory
836 To compute the rate of gain or loss of time, chronyd has to store a
837 measurement history for each of the time sources it uses.
838 All supported systems, with the exception of macOS 10.12 and
840 earlier, have operating system support for setting the rate of gain
841 or loss to compensate for known errors. (On macOS 10.12 and
842 earlier, chronyd must simulate such a capability by periodically
843 slewing the system clock forwards or backwards by a suitable amount
844 to compensate for the error built up since the previous slew.)
845 For such systems, it is possible to save the measurement history
847 across restarts of chronyd (assuming no changes are made to the
848 system clock behaviour whilst it is not running). The dumpdir
849 directive defines the directory where the measurement histories are
850 saved when chronyd exits, or the dump command in chronyc is issued.
851 If the directory does not exist, it will be created automatically.
853 The -r option of chronyd enables loading of the dump files on
855 start. All dump files found in the directory will be removed after
856 start, even if the -r option is not present.
857 An example of the directive is:
859 dumpdir /run/chrony
861 A source whose IP address is 1.2.3.4 would have its measurement
863 history saved in the file /run/chrony/1.2.3.4.dat. History of
864 reference clocks is saved to files named by their reference ID in
865 form of refid:XXXXXXXX.dat.
866 maxsamples samples
868 The maxsamples directive sets the default maximum number of samples
869 that chronyd should keep for each source. This setting can be
870 overridden for individual sources in the server and refclock
871 directives. The default value is 0, which disables the configurable
872 limit. The useful range is 4 to 64.
873 As a special case, setting maxsamples to 1 disables frequency
875 tracking in order to make the sources immediately selectable with
876 only one sample. This can be useful when chronyd is started with
877 the -q or -Q option.
878 minsamples samples
880 The minsamples directive sets the default minimum number of samples
881 that chronyd should keep for each source. This setting can be
882 overridden for individual sources in the server and refclock
883 directives. The default value is 6. The useful range is 4 to 64.
884 Forcing chronyd to keep more samples than it would normally keep
886 reduces noise in the estimated frequency and offset, but slows down
887 the response to changes in the frequency and offset of the clock.
888 The offsets in the tracking and sourcestats reports (and the
889 tracking.log and statistics.log files) may be smaller than the
890 actual offsets.
891 ntsdumpdir directory
893 This directive specifies a directory for the client to save NTS
894 cookies it received from the server in order to avoid making an
895 NTS-KE request when chronyd is started again. The cookies are saved
896 separately for each NTP source in files named by the IP address of
897 the NTS-KE server (e.g. 1.2.3.4.nts). By default, the client does
898 not save the cookies.
899 If the directory does not exist, it will be created automatically.
901 An example of the directive is:
903 ntsdumpdir /var/lib/chrony
905 This directory is used also by the NTS server to save keys.
907 ntsrefresh interval
909 This directive specifies the maximum interval between NTS-KE
910 handshakes (in seconds) in order to refresh the keys authenticating
911 NTP packets. The default value is 2419200 (4 weeks) and the maximum
912 value is 2^31-1 (68 years).
913 ntstrustedcerts [set-ID] file|directory
915 This directive specifies a file or directory containing
916 certificates (in the PEM format) of trusted certificate authorities
917 (CA) which can be used to verify certificates of NTS servers.
918 The optional set-ID argument is a number in the range 0 through
920 2^32-1, which selects the set of certificates where certificates
921 from the specified file or directory are added. The default ID is
922 0, which is a set containing the system’s default trusted CAs
923 (unless the nosystemcert directive is present). All other sets are
924 empty by default. A set of certificates can be selected for
925 verification of an NTS server by the certset option in the server
926 or pool directive.
927 This directive can be used multiple times to specify one or more
929 sets of trusted certificates, each containing certificates from one
930 or more files and/or directories.
931 It is not necessary to restart chronyd in order to reload the
933 certificates if they change (e.g. after a renewal).
934 An example is:
936 ntstrustedcerts /etc/pki/nts/foo.crt
938 ntstrustedcerts 1 /etc/pki/nts/bar.crt
939 ntstrustedcerts 1 /etc/pki/nts/baz.crt
940 ntstrustedcerts 2 /etc/pki/nts/qux.crt
941 nosystemcert
943 This directive disables the system’s default trusted CAs. Only
944 certificates specified by the ntstrustedcerts directive will be
945 trusted.
946 nocerttimecheck limit
948 This directive disables the checks of the activation and expiration
949 times of certificates for the specified number of clock updates. It
950 allows the NTS authentication mechanism to be used on computers
951 which start with wrong time (e.g. due to not having an RTC or
952 backup battery). Disabling the time checks has important security
953 implications and should be used only as a last resort, preferably
954 with a minimal number of trusted certificates. The default value is
955 0, which means the time checks are always enabled.
956 An example of the directive is:
958 nocerttimecheck 1
960 This would disable the time checks until the clock is updated for
962 the first time, assuming the first update corrects the clock and
963 later checks can work with correct time.
964 Source selection
966 authselectmode mode
967 NTP sources can be specified with the key or nts option to enable
968 authentication to limit the impact of man-in-the-middle attacks.
969 The attackers can drop or delay NTP packets (up to the maxdelay and
970 maxdistance limits), but they cannot modify the timestamps
971 contained in the packets. The attack can cause only a limited slew
972 or step, and also cause the clock to run faster or slower than real
973 time (up to double of the maxdrift limit).
974 When authentication is enabled for an NTP source, it is important
976 to disable unauthenticated NTP sources which could be exploited in
977 the attack, e.g. if they are not reachable only over a trusted
978 network. Alternatively, the source selection can be configured with
979 the require and trust options to synchronise to the unauthenticated
980 sources only if they agree with the authenticated sources and might
981 have a positive impact on the accuracy of the clock. Note that in
982 this case the impact of the attack is higher. The attackers cannot
983 cause an arbitrarily large step or slew, but they have more control
984 over the frequency of the clock and can cause chronyd to report
985 false information, e.g. a significantly smaller root delay and
986 dispersion.
987 This directive determines the default selection options for
989 authenticated and unauthenticated sources in order to simplify the
990 configuration with the configuration file and chronyc commands. It
991 sets a policy for authentication.
992 Sources specified with the noselect option are ignored (not counted
994 as either authenticated or unauthenticated), and they always have
995 only the selection options specified in the configuration.
996 There are four modes:
998 require
1000 Authentication is strictly required for NTP sources in this
1001 mode. If any unauthenticated NTP sources are specified, they
1002 will automatically get the noselect option to prevent them from
1003 being selected for synchronisation.
1004 prefer
1006 In this mode, authentication is optional and preferred. If it
1007 is enabled for at least one NTP source, all unauthenticated NTP
1008 sources will get the noselect option.
1009 mix
1011 In this mode, authentication is optional and synchronisation to
1012 a mix of authenticated and unauthenticated NTP sources is
1013 allowed. If both authenticated and unauthenticated NTP sources
1014 are specified, all authenticated NTP sources and reference
1015 clocks will get the require and trust options to prevent
1016 synchronisation to unauthenticated NTP sources if they do not
1017 agree with a majority of the authenticated sources and
1018 reference clocks. This is the default mode.
1019 ignore
1021 In this mode, authentication is ignored in the source
1022 selection. All sources will have only the selection options
1023 that were specified in the configuration file, or chronyc
1024 command. This was the behaviour of chronyd in versions before
1025 4.0.
1026 As an example, the following configuration using the default mix
1030 mode:
1031 server foo.example.net nts
1033 server bar.example.net nts
1034 server baz.example.net
1035 refclock SHM 0
1036 is equivalent to the following configuration using the ignore mode:
1038 authselectmode ignore
1040 server foo.example.net nts require trust
1041 server bar.example.net nts require trust
1042 server baz.example.net
1043 refclock SHM 0 require trust
1044 combinelimit limit
1046 When chronyd has multiple sources available for synchronisation, it
1047 has to select one source as the synchronisation source. The
1048 measured offsets and frequencies of the system clock relative to
1049 the other sources, however, can be combined with the selected
1050 source to improve the accuracy of the system clock.
1051 The combinelimit directive limits which sources are included in the
1053 combining algorithm. Their synchronisation distance has to be
1054 shorter than the distance of the selected source multiplied by the
1055 value of the limit. Also, their measured frequencies have to be
1056 close to the frequency of the selected source. If the selected
1057 source was specified with the prefer option, it can be combined
1058 only with other sources specified with this option.
1059 By default, the limit is 3. Setting the limit to 0 effectively
1061 disables the source combining algorithm and only the selected
1062 source will be used to control the system clock.
1063 maxdistance distance
1065 The maxdistance directive sets the maximum root distance of a
1066 source to be acceptable for synchronisation of the clock. Sources
1067 that have a distance larger than the specified distance will be
1068 rejected. The distance estimates the maximum error of the source.
1069 It includes the root dispersion and half of the root delay
1070 (round-trip time) accumulated on the path to the primary source.
1071 By default, the maximum root distance is 3 seconds.
1073 Setting maxdistance to a larger value can be useful to allow
1075 synchronisation with a server that only has a very infrequent
1076 connection to its sources and can accumulate a large dispersion
1077 between updates of its clock.
1078 maxjitter jitter
1080 The maxjitter directive sets the maximum allowed jitter of the
1081 sources to not be rejected by the source selection algorithm. This
1082 prevents synchronisation with sources that have a small root
1083 distance, but their time is too variable.
1084 By default, the maximum jitter is 1 second.
1086 minsources sources
1088 The minsources directive sets the minimum number of sources that
1089 need to be considered as selectable in the source selection
1090 algorithm before the local clock is updated. The default value is
1091 1.
1092 Setting this option to a larger number can be used to improve the
1094 reliability. More sources will have to agree with each other and
1095 the clock will not be updated when only one source (which could be
1096 serving incorrect time) is reachable.
1097 reselectdist distance
1099 When chronyd selects a synchronisation source from available
1100 sources, it will prefer the one with the shortest synchronisation
1101 distance. However, to avoid frequent reselecting when there are
1102 sources with similar distance, a fixed distance is added to the
1103 distance for sources that are currently not selected. This can be
1104 set with the reselectdist directive. By default, the distance is
1105 100 microseconds.
1106 stratumweight distance
1108 The stratumweight directive sets how much distance should be added
1109 per stratum to the synchronisation distance when chronyd selects
1110 the synchronisation source from available sources.
1111 By default, the weight is 0.001 seconds. This means that the
1113 stratum of the sources in the selection process matters only when
1114 the differences between the distances are in milliseconds.
1115 System clock
1117 clockprecision precision
1118 The clockprecision directive specifies the precision of the system
1119 clock (in seconds). It is used by chronyd to estimate the minimum
1120 noise in NTP measurements and randomise low-order bits of
1121 timestamps in NTP responses. By default, the precision is measured
1122 on start as the minimum time to read the clock.
1123 The measured value works well in most cases. However, it generally
1125 overestimates the precision and it can be sensitive to the CPU
1126 speed, which can change over time to save power. In some cases with
1127 a high-precision clocksource (e.g. the Time Stamp Counter of the
1128 CPU) and hardware timestamping, setting the precision on the server
1129 to a smaller value can improve stability of clients' NTP
1130 measurements. The server’s precision is reported on clients by the
1131 ntpdata command.
1132 An example setting the precision to 8 nanoseconds is:
1134 clockprecision 8e-9
1136 corrtimeratio ratio
1138 When chronyd is slewing the system clock to correct an offset, the
1139 rate at which it is slewing adds to the frequency error of the
1140 clock. On all supported systems, with the exception of macOS 12 and
1141 earlier, this rate can be controlled.
1142 The corrtimeratio directive sets the ratio between the duration in
1144 which the clock is slewed for an average correction according to
1145 the source history and the interval in which the corrections are
1146 done (usually the NTP polling interval). Corrections larger than
1147 the average take less time and smaller corrections take more time,
1148 the amount of the correction and the correction time are inversely
1149 proportional.
1150 Increasing corrtimeratio improves the overall frequency error of
1152 the system clock, but increases the overall time error as the
1153 corrections take longer.
1154 By default, the ratio is set to 3, the time accuracy of the clock
1156 is preferred over its frequency accuracy.
1157 The maximum allowed slew rate can be set by the maxslewrate
1159 directive. The current remaining correction is shown in the
1160 tracking report as the System time value.
1161 driftfile file
1163 One of the main activities of the chronyd program is to work out
1164 the rate at which the system clock gains or loses time relative to
1165 real time.
1166 Whenever chronyd computes a new value of the gain or loss rate, it
1168 is desirable to record it somewhere. This allows chronyd to begin
1169 compensating the system clock at that rate whenever it is
1170 restarted, even before it has had a chance to obtain an equally
1171 good estimate of the rate during the new run. (This process can
1172 take many minutes, at least.)
1173 The driftfile directive allows a file to be specified into which
1175 chronyd can store the rate information. Two parameters are recorded
1176 in the file. The first is the rate at which the system clock gains
1177 or loses time, expressed in parts per million, with gains positive.
1178 Therefore, a value of 100.0 indicates that when the system clock
1179 has advanced by a second, it has gained 100 microseconds in reality
1180 (so the true time has only advanced by 999900 microseconds). The
1181 second is an estimate of the error bound around the first value in
1182 which the true rate actually lies.
1183 An example of the driftfile directive is:
1185 driftfile /var/lib/chrony/drift
1187 fallbackdrift min-interval max-interval
1189 Fallback drifts are long-term averages of the system clock drift
1190 calculated over exponentially increasing intervals. They are used
1191 to avoid quickly drifting away from true time when the clock was
1192 not updated for a longer period of time and there was a short-term
1193 deviation in the drift before the updates stopped.
1194 The directive specifies the minimum and maximum interval since the
1196 last clock update to switch between fallback drifts. They are
1197 defined as a power of 2 (in seconds). The syntax is as follows:
1198 fallbackdrift 16 19
1200 In this example, the minimum interval is 16 (18 hours) and the
1202 maximum interval is 19 (6 days). The system clock frequency will be
1203 set to the first fallback 18 hours after last clock update, to the
1204 second after 36 hours, and so on. This might be a good setting to
1205 cover frequency changes due to daily and weekly temperature
1206 fluctuations. When the frequency is set to a fallback, the state of
1207 the clock will change to ‘Not synchronised’.
1208 By default (or if the specified maximum or minimum is 0), no
1210 fallbacks are used and the clock frequency changes only with new
1211 measurements from NTP sources, reference clocks, or manual input.
1212 leapsecmode mode
1214 A leap second is an adjustment that is occasionally applied to UTC
1215 to keep it close to the mean solar time. When a leap second is
1216 inserted, the last day of June or December has an extra second
1217 23:59:60.
1218 For computer clocks that is a problem. The Unix time is defined as
1220 number of seconds since 00:00:00 UTC on 1 January 1970 without leap
1221 seconds. The system clock cannot have time 23:59:60, every minute
1222 has 60 seconds and every day has 86400 seconds by definition. The
1223 inserted leap second is skipped and the clock is suddenly ahead of
1224 UTC by one second. The leapsecmode directive selects how that error
1225 is corrected. There are four options:
1226 system
1228 When inserting a leap second, the kernel steps the system clock
1229 backwards by one second when the clock gets to 00:00:00 UTC.
1230 When deleting a leap second, it steps forward by one second
1231 when the clock gets to 23:59:59 UTC. This is the default mode
1232 when the system driver supports leap seconds (i.e. all
1233 supported systems with the exception of macOS 12 and earlier).
1234 step
1236 This is similar to the system mode, except the clock is stepped
1237 by chronyd instead of the kernel. It can be useful to avoid
1238 bugs in the kernel code that would be executed in the system
1239 mode. This is the default mode when the system driver does not
1240 support leap seconds.
1241 slew
1243 The clock is corrected by slewing started at 00:00:00 UTC when
1244 a leap second is inserted or 23:59:59 UTC when a leap second is
1245 deleted. This might be preferred over the system and step modes
1246 when applications running on the system are sensitive to jumps
1247 in the system time and it is acceptable that the clock will be
1248 off for a longer time. On Linux with the default maxslewrate
1249 value the correction takes 12 seconds.
1250 ignore
1252 No correction is applied to the clock for the leap second. The
1253 clock will be corrected later in normal operation when new
1254 measurements are made and the estimated offset includes the one
1255 second error. This option is particularly useful when multiple
1256 chronyd instances are running on the system, one controlling
1257 the system clock and others started with the -x option, which
1258 should rely on the first instance to correct the system clock
1259 and ignore it for the correction of their own NTP clock running
1260 on top of the system clock.
1261 When serving time to NTP clients that cannot be configured to
1265 correct their clocks for a leap second by slewing, or to clients
1266 that would correct at slightly different rates when it is necessary
1267 to keep them close together, the slew mode can be combined with the
1268 smoothtime directive to enable a server leap smear.
1269 When smearing a leap second, the leap status is suppressed on the
1271 server and the served time is corrected slowly by slewing instead
1272 of stepping. The clients do not need any special configuration as
1273 they do not know there is any leap second and they follow the
1274 server time which eventually brings them back to UTC. Care must be
1275 taken to ensure they use only NTP servers which smear the leap
1276 second in exactly the same way for synchronisation.
1277 This feature must be used carefully, because the server is
1279 intentionally not serving its best estimate of the true time.
1280 A recommended configuration to enable a server leap smear is:
1282 leapsecmode slew
1284 maxslewrate 1000
1285 smoothtime 400 0.001024 leaponly
1286 The first directive is necessary to disable the clock step which
1288 would reset the smoothing process. The second directive limits the
1289 slewing rate of the local clock to 1000 ppm, which improves the
1290 stability of the smoothing process when the local correction starts
1291 and ends. The third directive enables the server time smoothing
1292 process. It will start when the clock gets to 00:00:00 UTC and it
1293 will take 62500 seconds (about 17.36 hours) to finish. The
1294 frequency offset will be changing by 0.001024 ppm per second and
1295 will reach a maximum of 32 ppm in 31250 seconds. The leaponly
1296 option makes the duration of the leap smear constant and allows the
1297 clients to safely synchronise with multiple identically configured
1298 leap smearing servers.
1299 The duration of the leap smear can be calculated from the specified
1301 wander as
1302 duration = sqrt(4 / wander)
1304 leapsectz timezone
1306 This directive specifies a timezone in the system timezone database
1307 which chronyd can use to determine when will the next leap second
1308 occur and what is the current offset between TAI and UTC. It will
1309 periodically check if 23:59:59 and 23:59:60 are valid times in the
1310 timezone. This normally works with the right/UTC timezone.
1311 When a leap second is announced, the timezone needs to be updated
1313 at least 12 hours before the leap second. It is not necessary to
1314 restart chronyd.
1315 This directive is useful with reference clocks and other time
1317 sources which do not announce leap seconds, or announce them too
1318 late for an NTP server to forward them to its own clients. Clients
1319 of leap smearing servers must not use this directive.
1320 It is also useful when the system clock is required to have correct
1322 TAI-UTC offset. Note that the offset is set only when leap seconds
1323 are handled by the kernel, i.e. leapsecmode is set to system.
1324 The specified timezone is not used as an exclusive source of
1326 information about leap seconds. If a majority of time sources
1327 announce on the last day of June or December that a leap second
1328 should be inserted or deleted, it will be accepted even if it is
1329 not included in the timezone.
1330 An example of the directive is:
1332 leapsectz right/UTC
1334 The following shell command verifies that the timezone contains
1336 leap seconds and can be used with this directive:
1337 $ TZ=right/UTC date -d 'Dec 31 2008 23:59:60'
1339 Wed Dec 31 23:59:60 UTC 2008
1340 makestep threshold limit
1342 Normally chronyd will cause the system to gradually correct any
1343 time offset, by slowing down or speeding up the clock as required.
1344 In certain situations, e.g. when chronyd is initially started, the
1345 system clock might be so far adrift that this slewing process would
1346 take a very long time to correct the system clock.
1347 This directive forces chronyd to step the system clock if the
1349 adjustment is larger than a threshold value, but only if there were
1350 no more clock updates since chronyd was started than the specified
1351 limit. A negative value disables the limit.
1352 On most systems it is desirable to step the system clock only on
1354 boot, before starting programs that rely on time advancing
1355 monotonically forwards.
1356 An example of the use of this directive is:
1358 makestep 0.1 3
1360 This would step the system clock if the adjustment is larger than
1362 0.1 seconds, but only in the first three clock updates.
1363 maxchange offset start ignore
1365 This directive sets the maximum offset to be accepted on a clock
1366 update. The offset is measured relative to the current estimate of
1367 the true time, which is different from the system time if a
1368 previous slew did not finish.
1369 The check is enabled after the specified number of clock updates to
1371 allow a large initial offset to be corrected on start. Offsets
1372 larger than the specified maximum will be ignored for the specified
1373 number of times. Another large offset will cause chronyd to give up
1374 and exit. A negative value can be used to disable the limit to
1375 ignore all large offsets. A syslog message will be generated when
1376 an offset is ignored or it causes the exit.
1377 An example of the use of this directive is:
1379 maxchange 1000 1 2
1381 After the first clock update, chronyd will check the offset on
1383 every clock update, it will ignore two adjustments larger than 1000
1384 seconds and exit on another one.
1385 maxclockerror error-in-ppm
1387 The maxclockerror directive sets the maximum assumed frequency
1388 error that the system clock can gain on its own between clock
1389 updates. It describes the stability of the clock.
1390 By default, the maximum error is 1 ppm.
1392 Typical values for error-in-ppm might be 10 for a low quality clock
1394 and 0.1 for a high quality clock using a temperature compensated
1395 crystal oscillator.
1396 maxdrift drift-in-ppm
1398 This directive specifies the maximum assumed drift (frequency
1399 error) of the system clock. It limits the frequency adjustment that
1400 chronyd is allowed to use to correct the measured drift. It is an
1401 additional limit to the maximum adjustment that can be set by the
1402 system driver (100000 ppm on Linux, 500 ppm on FreeBSD, NetBSD, and
1403 macOS 10.13+, 32500 ppm on illumos).
1404 By default, the maximum assumed drift is 500000 ppm, i.e. the
1406 adjustment is limited by the system driver rather than this
1407 directive.
1408 maxupdateskew skew-in-ppm
1410 One of chronyd's tasks is to work out how fast or slow the
1411 computer’s clock runs relative to its reference sources. In
1412 addition, it computes an estimate of the error bounds around the
1413 estimated value.
1414 If the range of error is too large, it probably indicates that the
1416 measurements have not settled down yet, and that the estimated gain
1417 or loss rate is not very reliable.
1418 The maxupdateskew directive sets the threshold for determining
1420 whether an estimate might be so unreliable that it should not be
1421 used. By default, the threshold is 1000 ppm.
1422 Typical values for skew-in-ppm might be 100 for NTP sources polled
1424 over a wireless network, and 10 or smaller for sources on a local
1425 wired network.
1426 It should be noted that this is not the only means of protection
1428 against using unreliable estimates. At all times, chronyd keeps
1429 track of both the estimated gain or loss rate, and the error bound
1430 on the estimate. When a new estimate is generated following another
1431 measurement from one of the sources, a weighted combination
1432 algorithm is used to update the master estimate. So if chronyd has
1433 an existing highly-reliable master estimate and a new estimate is
1434 generated which has large error bounds, the existing master
1435 estimate will dominate in the new master estimate.
1436 maxslewrate rate-in-ppm
1438 The maxslewrate directive sets the maximum rate at which chronyd is
1439 allowed to slew the time. It limits the slew rate controlled by the
1440 correction time ratio (which can be set by the corrtimeratio
1441 directive) and is effective only on systems where chronyd is able
1442 to control the rate (i.e. all supported systems with the exception
1443 of macOS 12 or earlier).
1444 For each system there is a maximum frequency offset of the clock
1446 that can be set by the driver. On Linux it is 100000 ppm, on
1447 FreeBSD, NetBSD and macOS 10.13+ it is 5000 ppm, and on illumos it
1448 is 32500 ppm. Also, due to a kernel limitation, setting maxslewrate
1449 on FreeBSD, NetBSD, macOS 10.13+ to a value between 500 ppm and
1450 5000 ppm will effectively set it to 500 ppm.
1451 By default, the maximum slew rate is set to 83333.333 ppm (one
1453 twelfth).
1454 tempcomp file interval T0 k0 k1 k2, tempcomp file interval points-file
1456 Normally, changes in the rate of drift of the system clock are
1457 caused mainly by changes in the temperature of the crystal
1458 oscillator on the motherboard.
1459 If there are temperature measurements available from a sensor close
1461 to the oscillator, the tempcomp directive can be used to compensate
1462 for the changes in the temperature and improve the stability and
1463 accuracy of the clock.
1464 The result depends on many factors, including the resolution of the
1466 sensor, the amount of noise in the measurements, the polling
1467 interval of the time source, the compensation update interval, how
1468 well the compensation is specified, and how close the sensor is to
1469 the oscillator. When it is working well, the frequency reported in
1470 the tracking.log file is more stable and the maximum reached offset
1471 is smaller.
1472 There are two forms of the directive. The first one has six
1474 parameters: a path to the file containing the current temperature
1475 from the sensor (in text format), the compensation update interval
1476 (in seconds), and temperature coefficients T0, k0, k1, k2.
1477 The frequency compensation is calculated (in ppm) as
1479 comp = k0 + (T - T0) * k1 + (T - T0)^2 * k2
1481 The result has to be between -10 ppm and 10 ppm, otherwise the
1483 measurement is considered invalid and will be ignored. The k0
1484 coefficient can be adjusted to keep the compensation in that range.
1485 An example of the use is:
1487 tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 26000 0.0 0.000183 0.0
1489 The measured temperature will be read from the file in the Linux
1491 sysfs filesystem every 30 seconds. When the temperature is 26000
1492 (26 degrees Celsius), the frequency correction will be zero. When
1493 it is 27000 (27 degrees Celsius), the clock will be set to run
1494 faster by 0.183 ppm, etc.
1495 The second form has three parameters: the path to the sensor file,
1497 the update interval, and a path to a file containing a list of
1498 (temperature, compensation) points, from which the compensation is
1499 linearly interpolated or extrapolated.
1500 An example is:
1502 tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 /etc/chrony.tempcomp
1504 where the /etc/chrony.tempcomp file could have
1506 20000 1.0
1508 21000 0.64
1509 22000 0.36
1510 23000 0.16
1511 24000 0.04
1512 25000 0.0
1513 26000 0.04
1514 27000 0.16
1515 28000 0.36
1516 29000 0.64
1517 30000 1.0
1518 Valid measurements with corresponding compensations are logged to
1520 the tempcomp.log file if enabled by the log tempcomp directive.
1521 NTP server
1523 allow [all] [subnet]
1524 The allow directive is used to designate a particular subnet from
1525 which NTP clients are allowed to access the computer as an NTP
1526 server. It also controls access of NTS-KE clients when NTS is
1527 enabled on the server.
1528 The default is that no clients are allowed access, i.e. chronyd
1530 operates purely as an NTP client. If the allow directive is used,
1531 chronyd will be both a client of its servers, and a server to other
1532 clients.
1533 This directive can be used multiple times.
1535 Examples of the use of the directive are as follows:
1537 allow 1.2.3.4
1539 allow 3.4.5.0/24
1540 allow 3.4.5
1541 allow 2001:db8::/32
1542 allow 0/0
1543 allow ::/0
1544 allow
1545 The first directive allows access from an IPv4 address. The second
1547 directive allows access from all computers in an IPv4 subnet
1548 specified in the CIDR notation. The third directive specifies the
1549 same subnet using a simpler notation where the prefix length is
1550 determined by the number of dots. The fourth directive specifies an
1551 IPv6 subnet. The fifth and sixth directives allow access from all
1552 IPv4 and IPv6 addresses respectively. The seventh directive allows
1553 access from all addresses (both IPv4 or IPv6).
1554 A second form of the directive, allow all, has a greater effect,
1556 depending on the ordering of directives in the configuration file.
1557 To illustrate the effect, consider the two examples:
1558 allow 1.2.3.4
1560 deny 1.2.3.0/24
1561 allow 1.2.0.0/16
1562 and
1564 allow 1.2.3.4
1566 deny 1.2.3.0/24
1567 allow all 1.2.0.0/16
1568 In the first example, the effect is the same regardless of what
1570 order the three directives are given in. So the 1.2.0.0/16 subnet
1571 is allowed access, except for the 1.2.3.0/24 subnet, which is
1572 denied access, however the host 1.2.3.4 is allowed access.
1573 In the second example, the allow all 1.2.0.0/16 directive overrides
1575 the effect of any previous directive relating to a subnet within
1576 the specified subnet. Within a configuration file this capability
1577 is probably rather moot; however, it is of greater use for
1578 reconfiguration at run-time via chronyc with the allow all command.
1579 The rules are internally represented as a tree of tables with one
1581 level per four bits of the IPv4 or IPv6 address. The order of the
1582 allow and deny directives matters if they modify the same records
1583 of one table, i.e. if one subnet is included in the other subnet
1584 and their prefix lengths are at the same level. For example,
1585 1.2.3.0/28 and 1.2.3.0/29 are in different tables, but 1.2.3.0/25
1586 and 1.2.3.0/28 are in the same table. The configuration can be
1587 verified for individual addresses with the accheck command in
1588 chronyc.
1589 A hostname can be specified in the directives instead of the IP
1591 address, but the name must be resolvable when chronyd is started,
1592 i.e. the network is already up and DNS is working. If the hostname
1593 resolves to multiple addresses, only the first address (in the
1594 order returned by the system resolver) will be allowed or denied.
1595 Note, if the initstepslew directive is used in the configuration
1597 file, each of the computers listed in that directive must allow
1598 client access by this computer for it to work.
1599 deny [all] [subnet]
1601 This is similar to the allow directive, except that it denies NTP
1602 and NTS-KE client access to a particular subnet or host, rather
1603 than allowing it.
1604 The syntax is identical and the directive can be used multiple
1606 times too.
1607 There is also a deny all directive with similar behaviour to the
1609 allow all directive.
1610 bindaddress address
1612 The bindaddress directive binds the sockets on which chronyd
1613 listens for NTP and NTS-KE requests to a local address of the
1614 computer. On systems other than Linux, the address of the computer
1615 needs to be already configured when chronyd is started.
1616 An example of the use of the directive is:
1618 bindaddress 192.168.1.1
1620 Currently, for each of the IPv4 and IPv6 protocols, only one
1622 bindaddress directive can be specified. Therefore, it is not useful
1623 on computers which should serve NTP on multiple network interfaces.
1624 binddevice interface
1626 The binddevice directive binds the NTP and NTS-KE server sockets to
1627 a network device specified by the interface name. This directive
1628 can specify only one interface and it is supported on Linux only.
1629 An example of the directive is:
1631 binddevice eth0
1633 broadcast interval address [port]
1635 The broadcast directive is used to declare a broadcast address to
1636 which chronyd should send packets in the NTP broadcast mode (i.e.
1637 make chronyd act as a broadcast server). Broadcast clients on that
1638 subnet will be able to synchronise.
1639 This directive can be used multiple times to specify multiple
1641 addresses.
1642 The syntax is as follows:
1644 broadcast 32 192.168.1.255
1646 broadcast 64 192.168.2.255 12123
1647 broadcast 64 ff02::101
1648 In the first example, the destination port defaults to UDP port 123
1650 (the normal NTP port). In the second example, the destination port
1651 is specified as 12123. The first parameter in each case (32 or 64
1652 respectively) is the interval in seconds between broadcast packets
1653 being sent. The second parameter in each case is the broadcast
1654 address to send the packet to. This should correspond to the
1655 broadcast address of one of the network interfaces on the computer
1656 where chronyd is running.
1657 You can have more than 1 broadcast directive if you have more than
1659 1 network interface onto which you want to send NTP broadcast
1660 packets.
1661 chronyd itself cannot act as a broadcast client; it must always be
1663 configured as a point-to-point client by defining specific NTP
1664 servers and peers. This broadcast server feature is intended for
1665 providing a time source to other NTP implementations.
1666 If ntpd is used as the broadcast client, it will try to measure the
1668 round-trip delay between the server and client with normal client
1669 mode packets. Thus, the broadcast subnet should also be the subject
1670 of an allow directive.
1671 clientloglimit limit
1673 This directive specifies the maximum amount of memory that chronyd
1674 is allowed to allocate for logging of client accesses and the state
1675 that chronyd as an NTP server needs to support the interleaved mode
1676 for its clients. The default limit is 524288 bytes, which enables
1677 monitoring of up to 4096 IP addresses at the same time and holding
1678 NTP timestamps for up to 4096 clients using the interleaved mode
1679 (depending on uniformity of their polling interval). The number of
1680 addresses and timestamps is always a power of 2. The maximum
1681 effective value is 2147483648 (2 GB), which corresponds to 16777216
1682 addresses and timestamps.
1683 An example of the use of this directive is:
1685 clientloglimit 1048576
1687 noclientlog
1689 This directive, which takes no arguments, specifies that client
1690 accesses are not to be logged. Normally they are logged, allowing
1691 statistics to be reported using the clients command in chronyc.
1692 This option also effectively disables server support for the NTP
1693 interleaved mode.
1694 local [option]...
1696 The local directive enables a local reference mode, which allows
1697 chronyd operating as an NTP server to appear synchronised to real
1698 time (from the viewpoint of clients polling it), even when it was
1699 never synchronised or the last update of the clock happened a long
1700 time ago.
1701 This directive is normally used in an isolated network, where
1703 computers are required to be synchronised to one another, but not
1704 necessarily to real time. The server can be kept vaguely in line
1705 with real time by manual input.
1706 The local directive has the following options:
1708 stratum stratum
1710 This option sets the stratum of the server which will be
1711 reported to clients when the local reference is active. The
1712 specified value is in the range 1 through 15, and the default
1713 value is 10. It should be larger than the maximum expected
1714 stratum in the network when external NTP servers are
1715 accessible.
1716 Stratum 1 indicates a computer that has a true real-time
1718 reference directly connected to it (e.g. GPS, atomic clock,
1719 etc.), such computers are expected to be very close to real
1720 time. Stratum 2 computers are those which have a stratum 1
1721 server; stratum 3 computers have a stratum 2 server and so on.
1722 A value of 10 indicates that the clock is so many hops away
1723 from a reference clock that its time is fairly unreliable.
1724 distance distance
1726 This option sets the threshold for the root distance which will
1727 activate the local reference. If chronyd was synchronised to
1728 some source, the local reference will not be activated until
1729 its root distance reaches the specified value (the rate at
1730 which the distance is increasing depends on how well the clock
1731 was tracking the source). The default value is 1 second.
1732 The current root distance can be calculated from root delay and
1734 root dispersion (reported by the tracking command in chronyc)
1735 as:
1736 distance = delay / 2 + dispersion
1738 orphan
1740 This option enables a special ‘orphan’ mode, where sources with
1741 stratum equal to the local stratum are assumed to not serve
1742 real time. They are ignored unless no other source is
1743 selectable and their reference IDs are smaller than the local
1744 reference ID.
1745 This allows multiple servers in the network to use the same
1747 local configuration and to be synchronised to one another,
1748 without confusing clients that poll more than one server. Each
1749 server needs to be configured to poll all other servers with
1750 the local directive. This ensures only the server with the
1751 smallest reference ID has the local reference active and others
1752 are synchronised to it. If that server stops responding, the
1753 server with the second smallest reference ID will take over
1754 when its local reference mode activates (root distance reaches
1755 the threshold configured by the distance option).
1756 The orphan mode is compatible with the ntpd's orphan mode
1758 (enabled by the tos orphan command).
1759 An example of the directive is:
1763 local stratum 10 orphan distance 0.1
1765 ntpsigndsocket directory
1767 This directive specifies the location of the Samba ntp_signd socket
1768 when it is running as a Domain Controller (DC). If chronyd is
1769 compiled with this feature, responses to MS-SNTP clients will be
1770 signed by the smbd daemon.
1771 Note that MS-SNTP requests are not authenticated and any client
1773 that is allowed to access the server by the allow directive, or the
1774 allow command in chronyc, can get an MS-SNTP response signed with a
1775 trust account’s password and try to crack the password in a
1776 brute-force attack. Access to the server should be carefully
1777 controlled.
1778 An example of the directive is:
1780 ntpsigndsocket /var/lib/samba/ntp_signd
1782 ntsport port
1784 This directive specifies the TCP port on which chronyd will provide
1785 the NTS Key Establishment (NTS-KE) service. The default port is
1786 4460.
1787 The port will be open only when a certificate and key is specified
1789 by the ntsservercert and ntsserverkey directives.
1790 ntsservercert file
1792 This directive specifies a file containing a certificate in the PEM
1793 format for chronyd to operate as an NTS server. The file should
1794 also include any intermediate certificates that the clients will
1795 need to validate the server’s certificate. The file needs to be
1796 readable by the user under which chronyd is running after dropping
1797 root privileges.
1798 This directive can be used multiple times to specify multiple
1800 certificates for different names of the server.
1801 The files are loaded only once. chronyd needs to be restarted in
1803 order to load a renewed certificate. The ntsdumpdir and dumpdir
1804 directives with the -r option of chronyd are recommended for a
1805 near-seamless server operation.
1806 ntsserverkey file
1808 This directive specifies a file containing a private key in the PEM
1809 format for chronyd to operate as an NTS server. The file needs to
1810 be readable by the user under which chronyd is running after
1811 dropping root privileges. For security reasons, it should not be
1812 readable by other users.
1813 This directive can be used multiple times to specify multiple keys.
1815 The number of keys must be the same as the number of certificates
1816 and the corresponding files must be specified in the same order.
1817 ntsprocesses processes
1819 This directive specifies how many helper processes will chronyd
1820 operating as an NTS server start for handling client NTS-KE
1821 requests in order to improve performance with multi-core CPUs and
1822 multithreading. If set to 0, no helper process will be started and
1823 all NTS-KE requests will be handled by the main chronyd process.
1824 The default value is 1.
1825 maxntsconnections connections
1827 This directive specifies the maximum number of concurrent NTS-KE
1828 connections per process that the NTS server will accept. The
1829 default value is 100. The maximum practical value is half of the
1830 system FD_SETSIZE constant (usually 1024).
1831 ntsdumpdir directory
1833 This directive specifies a directory where chronyd operating as an
1834 NTS server can save the keys which encrypt NTS cookies provided to
1835 clients. The keys are saved to a single file named ntskeys. When
1836 chronyd is restarted, reloading the keys allows the clients to
1837 continue using old cookies and avoids a storm of NTS-KE requests.
1838 By default, the server does not save the keys.
1839 An example of the directive is:
1841 ntsdumpdir /var/lib/chrony
1843 This directory is used also by the NTS client to save NTS cookies.
1845 ntsntpserver hostname
1847 This directive specifies the hostname (as a fully qualified domain
1848 name) or address of the NTP server(s) which is provided in the
1849 NTS-KE response to the clients. It allows the NTS-KE server to be
1850 separated from the NTP server. However, the servers need to share
1851 the keys, i.e. external key management needs to be enabled by
1852 setting ntsrotate to 0. By default, no hostname or address is
1853 provided to the clients, which means they should use the same
1854 server for NTS-KE and NTP.
1855 ntsrotate interval
1857 This directive specifies the rotation interval (in seconds) of the
1858 server key which encrypts the NTS cookies. New keys are generated
1859 automatically from the /dev/urandom device. The server keeps two
1860 previous keys to give the clients time to get new cookies encrypted
1861 by the latest key. The interval is measured as the server’s
1862 operating time, i.e. the actual interval can be longer if chronyd
1863 is not running continuously. The default interval is 604800 seconds
1864 (1 week). The maximum value is 2^31-1 (68 years).
1865 The automatic rotation of the keys can be disabled by setting
1867 ntsrotate to 0. In this case the keys are assumed to be managed
1868 externally. chronyd will not save the keys to the ntskeys file and
1869 will reload the keys from the file when the rekey command is issued
1870 in chronyc. The file can be periodically copied from another server
1871 running chronyd (which does not have ntsrotate set to 0) in order
1872 to have one or more servers dedicated to NTS-KE. The NTS-KE servers
1873 need to be configured with the ntsntpserver directive to point the
1874 clients to the right NTP server.
1875 An example of the directive is:
1877 ntsrotate 2592000
1879 port port
1881 This option allows you to configure the port on which chronyd will
1882 listen for NTP requests. The port will be open only when an address
1883 is allowed by the allow directive or the allow command in chronyc,
1884 an NTP peer is configured, or the broadcast server mode is enabled.
1885 The default value is 123, the standard NTP port. If set to 0,
1887 chronyd will never open the server port and will operate strictly
1888 in a client-only mode. The source port used in NTP client requests
1889 can be set by the acquisitionport directive.
1890 ratelimit [option]...
1892 This directive enables response rate limiting for NTP packets. Its
1893 purpose is to reduce network traffic with misconfigured or broken
1894 NTP clients that are polling the server too frequently. The limits
1895 are applied to individual IP addresses. If multiple clients share
1896 one IP address (e.g. multiple hosts behind NAT), the sum of their
1897 traffic will be limited. If a client that increases its polling
1898 rate when it does not receive a reply is detected, its rate
1899 limiting will be temporarily suspended to avoid increasing the
1900 overall amount of traffic. The maximum number of IP addresses which
1901 can be monitored at the same time depends on the memory limit set
1902 by the clientloglimit directive.
1903 The ratelimit directive supports a number of options (which can be
1905 defined in any order):
1906 interval interval
1908 This option sets the minimum interval between responses. It is
1909 defined as a power of 2 in seconds. The default value is 3 (8
1910 seconds). The minimum value is -19 (524288 packets per second)
1911 and the maximum value is 12 (one packet per 4096 seconds). Note
1912 that with values below -4 the rate limiting is coarse
1913 (responses are allowed in bursts, even if the interval between
1914 them is shorter than the specified interval).
1915 burst responses
1917 This option sets the maximum number of responses that can be
1918 sent in a burst, temporarily exceeding the limit specified by
1919 the interval option. This is useful for clients that make rapid
1920 measurements on start (e.g. chronyd with the iburst option).
1921 The default value is 8. The minimum value is 1 and the maximum
1922 value is 255.
1923 leak rate
1925 This option sets the rate at which responses are randomly
1926 allowed even if the limits specified by the interval and burst
1927 options are exceeded. This is necessary to prevent an attacker
1928 who is sending requests with a spoofed source address from
1929 completely blocking responses to that address. The leak rate is
1930 defined as a power of 1/2 and it is 2 by default, i.e. on
1931 average at least every fourth request has a response. The
1932 minimum value is 1 and the maximum value is 4.
1933 An example use of the directive is:
1937 ratelimit interval 1 burst 16
1939 This would reduce the response rate for IP addresses sending
1941 packets on average more than once per 2 seconds, or sending packets
1942 in bursts of more than 16 packets, by up to 75% (with default leak
1943 of 2).
1944 ntsratelimit [option]...
1946 This directive enables rate limiting of NTS-KE requests. It is
1947 similar to the ratelimit directive, except the default interval is
1948 6 (1 connection per 64 seconds).
1949 An example of the use of the directive is:
1951 ntsratelimit interval 3 burst 1
1953 smoothtime max-freq max-wander [leaponly]
1955 The smoothtime directive can be used to enable smoothing of the
1956 time that chronyd serves to its clients to make it easier for them
1957 to track it and keep their clocks close together even when large
1958 offset or frequency corrections are applied to the server’s clock,
1959 for example after being offline for a longer time.
1960 BE WARNED: The server is intentionally not serving its best
1962 estimate of the true time. If a large offset has been accumulated,
1963 it can take a very long time to smooth it out. This directive
1964 should be used only when the clients are not configured to also
1965 poll another NTP server, because they could reject this server as a
1966 falseticker or fail to select a source completely.
1967 The smoothing process is implemented with a quadratic spline
1969 function with two or three pieces. It is independent from any
1970 slewing applied to the local system clock, but the accumulated
1971 offset and frequency will be reset when the clock is corrected by
1972 stepping, e.g. by the makestep directive or the makestep command in
1973 chronyc. The process can be reset without stepping the clock by the
1974 smoothtime reset command.
1975 The first two arguments of the directive are the maximum frequency
1977 offset of the smoothed time to the tracked NTP time (in ppm) and
1978 the maximum rate at which the frequency offset is allowed to change
1979 (in ppm per second). leaponly is an optional third argument which
1980 enables a mode where only leap seconds are smoothed out and normal
1981 offset and frequency changes are ignored. The leaponly option is
1982 useful in a combination with the leapsecmode slew directive to
1983 allow the clients to use multiple time smoothing servers safely.
1984 The smoothing process is activated automatically when 1/10000 of
1986 the estimated skew of the local clock falls below the maximum rate
1987 of frequency change. It can be also activated manually by the
1988 smoothtime activate command, which is particularly useful when the
1989 clock is synchronised only with manual input and the skew is always
1990 larger than the threshold. The smoothing command can be used to
1991 monitor the process.
1992 An example suitable for clients using ntpd and 1024 second polling
1994 interval could be:
1995 smoothtime 400 0.001
1997 An example suitable for clients using chronyd on Linux could be:
1999 smoothtime 50000 0.01
2001 Command and monitoring access
2003 bindcmdaddress address
2004 The bindcmdaddress directive specifies a local IP address to which
2005 chronyd will bind the UDP socket listening for monitoring command
2006 packets (issued by chronyc). On systems other than Linux, the
2007 address of the interface needs to be already configured when
2008 chronyd is started.
2009 This directive can also change the path of the Unix domain command
2011 socket, which is used by chronyc to send configuration commands.
2012 The socket must be in a directory that is accessible only by the
2013 root or chrony user. The directory will be created on start if it
2014 does not exist. The compiled-in default path of the socket is
2015 /run/chrony/chronyd.sock. The socket can be disabled by setting the
2016 path to /.
2017 By default, chronyd binds the UDP sockets to the addresses
2019 127.0.0.1 and ::1 (i.e. the loopback interface). This blocks all
2020 access except from localhost. To listen for command packets on all
2021 interfaces, you can add the lines:
2022 bindcmdaddress 0.0.0.0
2024 bindcmdaddress ::
2025 to the configuration file.
2027 For each of the IPv4, IPv6, and Unix domain protocols, only one
2029 bindcmdaddress directive can be specified.
2030 An example that sets the path of the Unix domain command socket is:
2032 bindcmdaddress /var/run/chrony/chronyd.sock
2034 bindcmddevice interface
2036 The bindcmddevice directive binds the UDP command sockets to a
2037 network device specified by the interface name. This directive can
2038 specify only one interface and it is supported on Linux only.
2039 An example of the directive is:
2041 bindcmddevice eth0
2043 cmdallow [all] [subnet]
2045 This is similar to the allow directive, except that it allows
2046 monitoring access (rather than NTP client access) to a particular
2047 subnet or host. (By ‘monitoring access’ is meant that chronyc can
2048 be run on those hosts and retrieve monitoring data from chronyd on
2049 this computer.)
2050 The syntax is identical to the allow directive.
2052 There is also a cmdallow all directive with similar behaviour to
2054 the allow all directive (but applying to monitoring access in this
2055 case, of course).
2056 Note that chronyd has to be configured with the bindcmdaddress
2058 directive to not listen only on the loopback interface to actually
2059 allow remote access.
2060 cmddeny [all] [subnet]
2062 This is similar to the cmdallow directive, except that it denies
2063 monitoring access to a particular subnet or host, rather than
2064 allowing it.
2065 The syntax is identical.
2067 There is also a cmddeny all directive with similar behaviour to the
2069 cmdallow all directive.
2070 cmdport port
2072 The cmdport directive allows the port that is used for run-time
2073 monitoring (via the chronyc program) to be altered from its default
2074 (323). If set to 0, chronyd will not open the port, this is useful
2075 to disable chronyc access from the Internet. (It does not disable
2076 the Unix domain command socket.)
2077 An example shows the syntax:
2079 cmdport 257
2081 This would make chronyd use UDP 257 as its command port. (chronyc
2083 would need to be run with the -p 257 switch to inter-operate
2084 correctly.)
2085 cmdratelimit [option]...
2087 This directive enables response rate limiting for command packets.
2088 It is similar to the ratelimit directive, except responses to
2089 localhost are never limited and the default interval is -4 (16
2090 packets per second).
2091 An example of the use of the directive is:
2093 cmdratelimit interval 2
2095 Real-time clock (RTC)
2097 hwclockfile file
2098 The hwclockfile directive sets the location of the adjtime file
2099 which is used by the hwclock program on Linux. chronyd parses the
2100 file to find out if the RTC keeps local time or UTC. It overrides
2101 the rtconutc directive.
2102 The compiled-in default value is '/etc/adjtime'.
2104 An example of the directive is:
2106 hwclockfile /etc/adjtime
2108 rtcautotrim threshold
2110 The rtcautotrim directive is used to keep the RTC close to the
2111 system clock automatically. When the system clock is synchronised
2112 and the estimated error between the two clocks is larger than the
2113 specified threshold, chronyd will trim the RTC as if the trimrtc
2114 command in chronyc was issued. The trimming operation is accurate
2115 to only about 1 second, which is the minimum effective threshold.
2116 This directive is effective only with the rtcfile directive.
2118 An example of the use of this directive is:
2120 rtcautotrim 30
2122 This would set the threshold error to 30 seconds.
2124 rtcdevice device
2126 The rtcdevice directive sets the path to the device file for
2127 accessing the RTC. The default path is /dev/rtc.
2128 rtcfile file
2130 The rtcfile directive defines the name of the file in which chronyd
2131 can save parameters associated with tracking the accuracy of the
2132 RTC.
2133 An example of the directive is:
2135 rtcfile /var/lib/chrony/rtc
2137 chronyd saves information in this file when it exits and when the
2139 writertc command is issued in chronyc. The information saved is the
2140 RTC’s error at some epoch, that epoch (in seconds since January 1
2141 1970), and the rate at which the RTC gains or loses time.
2142 So far, the support for real-time clocks is limited; their code is
2144 even more system-specific than the rest of the software. You can
2145 only use the RTC facilities (the rtcfile directive and the -s
2146 command-line option to chronyd) if the following three conditions
2147 apply:
2148 1. You are running Linux.
2150 2. The kernel is compiled with extended real-time clock support
2152 (i.e. the /dev/rtc device is capable of doing useful things).
2153 3. You do not have other applications that need to make use of
2155 /dev/rtc at all.
2156 rtconutc
2158 chronyd assumes by default that the RTC keeps local time (including
2159 any daylight saving changes). This is convenient on PCs running
2160 Linux which are dual-booted with Windows.
2161 If you keep the RTC on local time and your computer is off when
2163 daylight saving (summer time) starts or ends, the computer’s system
2164 time will be one hour in error when you next boot and start
2165 chronyd.
2166 An alternative is for the RTC to keep Universal Coordinated Time
2168 (UTC). This does not suffer from the 1 hour problem when daylight
2169 saving starts or ends.
2170 If the rtconutc directive appears, it means the RTC is required to
2172 keep UTC. The directive takes no arguments. It is equivalent to
2173 specifying the -u switch to the Linux hwclock program.
2174 Note that this setting is overridden by the hwclockfile file and is
2176 not relevant for the rtcsync directive.
2177 rtcsync
2179 The rtcsync directive enables a mode where the system time is
2180 periodically copied to the RTC and chronyd does not try to track
2181 its drift. This directive cannot be used with the rtcfile
2182 directive.
2183 On Linux, the RTC copy is performed by the kernel every 11 minutes.
2185 On macOS, chronyd will perform the RTC copy every 60 minutes when
2187 the system clock is in a synchronised state.
2188 On other systems this directive does nothing.
2190 Logging
2192 log [option]...
2193 The log directive indicates that certain information is to be
2194 logged. The log files are written to the directory specified by the
2195 logdir directive. A banner is periodically written to the files to
2196 indicate the meanings of the columns.
2197 rawmeasurements
2199 This option logs the raw NTP measurements and related
2200 information to a file called measurements.log. An entry is made
2201 for each packet received from the source. This can be useful
2202 when debugging a problem. An example line (which actually
2203 appears as a single line in the file) from the log file is
2204 shown below.
2205 2016-11-09 05:40:50 203.0.113.15 N 2 111 111 1111 10 10 1.0 \
2207 -4.966e-03 2.296e-01 1.577e-05 1.615e-01 7.446e-03 CB00717B 4B D K
2208 The columns are as follows (the quantities in square brackets
2210 are the values from the example line above):
2211 1. Date [2015-10-13]
2213 2. Hour:Minute:Second. Note that the date-time pair is
2215 expressed in UTC, not the local time zone. [05:40:50]
2216 3. IP address of server or peer from which measurement came
2218 [203.0.113.15]
2219 4. Leap status (N means normal, + means that the last minute
2221 of the current month has 61 seconds, - means that the last
2222 minute of the month has 59 seconds, ? means the remote
2223 computer is not currently synchronised.) [N]
2224 5. Stratum of remote computer. [2]
2226 6. RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111]
2228 7. RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111]
2230 8. Results of the maxdelay, maxdelayratio, and
2232 maxdelaydevratio (or maxdelayquant) tests, and a test for
2233 synchronisation loop (1=pass, 0=fail). The first test from
2234 these four also checks the server precision, response time,
2235 and whether an interleaved response is acceptable for
2236 synchronisation. [1111]
2237 9. Local poll [10]
2239 10. Remote poll [10]
2241 11. ‘Score’ (an internal score within each polling level used
2243 to decide when to increase or decrease the polling level.
2244 This is adjusted based on number of measurements currently
2245 being used for the regression algorithm). [1.0]
2246 12. The estimated local clock error (theta in RFC 5905).
2248 Positive indicates that the local clock is slow of the
2249 remote source. [-4.966e-03]
2250 13. The peer delay (delta in RFC 5905). [2.296e-01]
2252 14. The peer dispersion (epsilon in RFC 5905). [1.577e-05]
2254 15. The root delay (DELTA in RFC 5905). [1.615e-01]
2256 16. The root dispersion (EPSILON in RFC 5905). [7.446e-03]
2258 17. Reference ID of the server’s source as a hexadecimal
2260 number. [CB00717B]
2261 18. NTP mode of the received packet (1=active peer, 2=passive
2263 peer, 4=server, B=basic, I=interleaved). [4B]
2264 19. Source of the local transmit timestamp (D=daemon,
2266 K=kernel, H=hardware). [D]
2267 20. Source of the local receive timestamp (D=daemon, K=kernel,
2269 H=hardware). [K]
2270 measurements
2272 This option is identical to the rawmeasurements option, except
2273 it logs only valid measurements from synchronised sources, i.e.
2274 measurements which passed the RFC 5905 tests 1 through 7. This
2275 can be useful for producing graphs of the source’s performance.
2276 statistics
2278 This option logs information about the regression processing to
2279 a file called statistics.log. An example line (which actually
2280 appears as a single line in the file) from the log file is
2281 shown below.
2282 2016-08-10 05:40:50 203.0.113.15 6.261e-03 -3.247e-03 \
2284 2.220e-03 1.874e-06 1.080e-06 7.8e-02 16 0 8 0.00
2285 The columns are as follows (the quantities in square brackets
2287 are the values from the example line above):
2288 1. Date [2015-07-22]
2290 2. Hour:Minute:Second. Note that the date-time pair is
2292 expressed in UTC, not the local time zone. [05:40:50]
2293 3. IP address of server or peer from which measurement comes
2295 [203.0.113.15]
2296 4. The estimated standard deviation of the measurements from
2298 the source (in seconds). [6.261e-03]
2299 5. The estimated offset of the source (in seconds, positive
2301 means the local clock is estimated to be fast, in this
2302 case). [-3.247e-03]
2303 6. The estimated standard deviation of the offset estimate (in
2305 seconds). [2.220e-03]
2306 7. The estimated rate at which the local clock is gaining or
2308 losing time relative to the source (in seconds per second,
2309 positive means the local clock is gaining). This is
2310 relative to the compensation currently being applied to the
2311 local clock, not to the local clock without any
2312 compensation. [1.874e-06]
2313 8. The estimated error in the rate value (in seconds per
2315 second). [1.080e-06].
2316 9. The ratio of |old_rate - new_rate| / old_rate_error. Large
2318 values indicate the statistics are not modelling the source
2319 very well. [7.8e-02]
2320 10. The number of measurements currently being used for the
2322 regression algorithm. [16]
2323 11. The new starting index (the oldest sample has index 0;
2325 this is the method used to prune old samples when it no
2326 longer looks like the measurements fit a linear model). [0,
2327 i.e. no samples discarded this time]
2328 12. The number of runs. The number of runs of regression
2330 residuals with the same sign is computed. If this is too
2331 small it indicates that the measurements are no longer
2332 represented well by a linear model and that some older
2333 samples need to be discarded. The number of runs for the
2334 data that is being retained is tabulated. Values of
2335 approximately half the number of samples are expected. [8]
2336 13. The estimated or configured asymmetry of network jitter on
2338 the path to the source which was used to correct the
2339 measured offsets. The asymmetry can be between -0.5 and
2340 +0.5. A negative value means the delay of packets sent to
2341 the source is more variable than the delay of packets sent
2342 from the source back. [0.00, i.e. no correction for
2343 asymmetry]
2344 selection
2346 This option logs information about selection of sources for
2347 synchronisation to a file called selection.log. Note that the
2348 rate of entries written to this file grows quadratically with
2349 the number of specified sources (each measurement triggers the
2350 selection for all sources). An example line (which actually
2351 appears as a single line in the file) from the log file is
2352 shown below.
2353 2022-05-01 02:01:20 203.0.113.15 * ----- 377 1.00 \
2355 4.228e+01 -1.575e-04 1.239e-04
2356 The columns are as follows (the quantities in square brackets
2358 are the values from the example line above):
2359 1. Date [2022-05-01]
2361 2. Hour:Minute:Second. Note that the date-time pair is
2363 expressed in UTC, not the local time zone. [02:01:20]
2364 3. IP address or reference ID of the source. [203.0.113.15]
2366 4. State of the source indicated with one of the following
2368 symbols. [*]
2369 Not considered selectable for synchronisation:
2372 • N - has the noselect option.
2374 • s - is not synchronised.
2376 • M - does not have enough measurements.
2378 • d - has a root distance larger than the maximum
2380 distance (configured by the maxdistance directive).
2381 • ~ - has a jitter larger than the maximum jitter
2383 (configured by the maxjitter directive).
2384 • w - waits for other sources to get out of the M
2386 state.
2387 • S - has older measurements than other sources.
2389 • O - has a stratum equal or larger than the orphan
2391 stratum (configured by the local directive).
2392 • T - does not fully agree with sources that have the
2394 trust option.
2395 • x - does not agree with other sources
2397 (falseticker).
2398 Considered selectable for synchronisation, but not
2401 currently used:
2402 • W - waits for other sources to be selectable
2404 (required by the minsources directive, or the
2405 require option of another source).
2406 • P - another selectable source is preferred due to
2408 the prefer option.
2409 • U - waits for a new measurement (after selecting a
2411 different best source).
2412 • D - has, or recently had, a root distance which is
2414 too large to be combined with other sources
2415 (configured by the combinelimit directive).
2416 Used for synchronisation of the local clock:
2419 • + - combined with the best source.
2421 • * - selected as the best source to update the
2423 reference data (e.g. root delay, root dispersion).
2424 5. Reachability register printed as an octal number. The
2426 register has 8 bits and is updated on every received or
2427 missed packet from the source. A value of 377 indicates
2428 that a valid reply was received for all from the last eight
2429 transmissions. [377]
2430 6. Current score against the source in the * state. The
2432 scoring system avoids frequent reselection when multiple
2433 sources have a similar root distance. A value larger than 1
2434 indicates this source was better than the * source in
2435 recent selections. If the score reaches 10, the best source
2436 will be reselected and the scores will be reset to 1.
2437 [1.00]
2438 7. Interval since the last measurement of the source in
2440 seconds. [4.228e+01]
2441 8. Lower endpoint of the interval which was expected to
2443 contain the true offset of the local clock determined by
2444 the root distance of the source. [-1.575e-04]
2445 9. Upper endpoint of the interval which was expected to
2447 contain the true offset of the local clock determined by
2448 the root distance of the source. [1.239e-04]
2449 tracking
2451 This option logs changes to the estimate of the system’s gain
2452 or loss rate, and any slews made, to a file called
2453 tracking.log. An example line (which actually appears as a
2454 single line in the file) from the log file is shown below.
2455 2017-08-22 13:22:36 203.0.113.15 2 -3.541 0.075 -8.621e-06 N \
2457 2 2.940e-03 -2.084e-04 1.534e-02 3.472e-04 8.304e-03
2458 The columns are as follows (the quantities in square brackets
2460 are the values from the example line above) :
2461 1. Date [2017-08-22]
2463 2. Hour:Minute:Second. Note that the date-time pair is
2465 expressed in UTC, not the local time zone. [13:22:36]
2466 3. The IP address of the server or peer to which the local
2468 system is synchronised. [203.0.113.15]
2469 4. The stratum of the local system. [2]
2471 5. The local system frequency (in ppm, positive means the
2473 local system runs fast of UTC). [-3.541]
2474 6. The error bounds on the frequency (in ppm). [0.075]
2476 7. The estimated local offset at the epoch, which is normally
2478 corrected by slewing the local clock (in seconds, positive
2479 indicates the clock is fast of UTC). [-8.621e-06]
2480 8. Leap status (N means normal, + means that the last minute
2482 of this month has 61 seconds, - means that the last minute
2483 of the month has 59 seconds, ? means the clock is not
2484 currently synchronised.) [N]
2485 9. The number of combined sources. [2]
2487 10. The estimated standard deviation of the combined offset
2489 (in seconds). [2.940e-03]
2490 11. The remaining offset correction from the previous update
2492 (in seconds, positive means the system clock is slow of
2493 UTC). [-2.084e-04]
2494 12. The total of the network path delays to the reference
2496 clock to which the local clock is ultimately synchronised
2497 (in seconds). [1.534e-02]
2498 13. The total dispersion accumulated through all the servers
2500 back to the reference clock to which the local clock is
2501 ultimately synchronised (in seconds). [3.472e-04]
2502 14. The maximum estimated error of the system clock in the
2504 interval since the previous update (in seconds). It
2505 includes the offset, remaining offset correction, root
2506 delay, and dispersion from the previous update with the
2507 dispersion which accumulated in the interval. [8.304e-03]
2508 rtc
2510 This option logs information about the system’s real-time
2511 clock. An example line (which actually appears as a single line
2512 in the file) from the rtc.log file is shown below.
2513 2015-07-22 05:40:50 -0.037360 1 -0.037434\
2515 -37.948 12 5 120
2516 The columns are as follows (the quantities in square brackets
2518 are the values from the example line above):
2519 1. Date [2015-07-22]
2521 2. Hour:Minute:Second. Note that the date-time pair is
2523 expressed in UTC, not the local time zone. [05:40:50]
2524 3. The measured offset between the RTC and the system clock in
2526 seconds. Positive indicates that the RTC is fast of the
2527 system time [-0.037360].
2528 4. Flag indicating whether the regression has produced valid
2530 coefficients. (1 for yes, 0 for no). [1]
2531 5. Offset at the current time predicted by the regression
2533 process. A large difference between this value and the
2534 measured offset tends to indicate that the measurement is
2535 an outlier with a serious measurement error. [-0.037434]
2536 6. The rate at which the RTC is losing or gaining time
2538 relative to the system clock. In ppm, with positive
2539 indicating that the RTC is gaining time. [-37.948]
2540 7. The number of measurements used in the regression. [12]
2542 8. The number of runs of regression residuals of the same
2544 sign. Low values indicate that a straight line is no longer
2545 a good model of the measured data and that older
2546 measurements should be discarded. [5]
2547 9. The measurement interval used prior to the measurement
2549 being made (in seconds). [120]
2550 refclocks
2552 This option logs the raw and filtered reference clock
2553 measurements to a file called refclocks.log. An example line
2554 (which actually appears as a single line in the file) from the
2555 log file is shown below.
2556 2009-11-30 14:33:27.000000 PPS2 7 N 1 4.900000e-07 -6.741777e-07 1.000e-06
2558 The columns are as follows (the quantities in square brackets
2560 are the values from the example line above):
2561 1. Date [2009-11-30]
2563 2. Hour:Minute:Second.Microsecond. Note that the date-time
2565 pair is expressed in UTC, not the local time zone.
2566 [14:33:27.000000]
2567 3. Reference ID of the reference clock from which the
2569 measurement came. [PPS2]
2570 4. Sequence number of driver poll within one polling interval
2572 for raw samples, or - for filtered samples. [7]
2573 5. Leap status (N means normal, + means that the last minute
2575 of the current month has 61 seconds, - means that the last
2576 minute of the month has 59 seconds). [N]
2577 6. Flag indicating whether the sample comes from PPS source.
2579 (1 for yes, 0 for no, or - for filtered sample). [1]
2580 7. Local clock error measured by reference clock driver, or -
2582 for filtered sample. [4.900000e-07]
2583 8. Local clock error with applied corrections. Positive
2585 indicates that the local clock is slow. [-6.741777e-07]
2586 9. Assumed dispersion of the sample. [1.000e-06]
2588 tempcomp
2590 This option logs the temperature measurements and system rate
2591 compensations to a file called tempcomp.log. An example line
2592 (which actually appears as a single line in the file) from the
2593 log file is shown below.
2594 2015-04-19 10:39:48 2.8000e+04 3.6600e-01
2596 The columns are as follows (the quantities in square brackets
2598 are the values from the example line above):
2599 1. Date [2015-04-19]
2601 2. Hour:Minute:Second. Note that the date-time pair is
2603 expressed in UTC, not the local time zone. [10:39:48]
2604 3. Temperature read from the sensor. [2.8000e+04]
2606 4. Applied compensation in ppm, positive means the system
2608 clock is running faster than it would be without the
2609 compensation. [3.6600e-01]
2610 An example of the directive is:
2613 log measurements statistics tracking
2615 logbanner entries
2617 A banner is periodically written to the log files enabled by the
2618 log directive to indicate the meanings of the columns.
2619 The logbanner directive specifies after how many entries in the log
2621 file should be the banner written. The default is 32, and 0 can be
2622 used to disable it entirely.
2623 logchange threshold
2625 This directive sets the threshold for the adjustment of the system
2626 clock that will generate a syslog message. Clock errors detected
2627 via NTP packets, reference clocks, or timestamps entered via the
2628 settime command of chronyc are logged.
2629 By default, the threshold is 1 second.
2631 An example of the use is:
2633 logchange 0.1
2635 which would cause a syslog message to be generated if a system
2637 clock error of over 0.1 seconds starts to be compensated.
2638 logdir directory
2640 This directive specifies the directory for writing log files
2641 enabled by the log directive. If the directory does not exist, it
2642 will be created automatically.
2643 An example of the use of this directive is:
2645 logdir /var/log/chrony
2647 mailonchange email threshold
2649 This directive defines an email address to which mail should be
2650 sent if chronyd applies a correction exceeding a particular
2651 threshold to the system clock.
2652 An example of the use of this directive is:
2654 mailonchange root@localhost 0.5
2656 This would send a mail message to root if a change of more than 0.5
2658 seconds were applied to the system clock.
2659 This directive cannot be used when a system call filter is enabled
2661 by the -F option as the chronyd process will not be allowed to fork
2662 and execute the sendmail binary.
2663 Miscellaneous
2665 confdir directory...
2666 The confdir directive includes configuration files with the .conf
2667 suffix from a directory. The files are included in the
2668 lexicographical order of the file names.
2669 Multiple directories (up to 10) can be specified with a single
2671 confdir directive. In this case, if multiple directories contain a
2672 file with the same name, only the first file in the order of the
2673 specified directories will be included. This enables a fragmented
2674 configuration where existing fragments can be replaced by adding
2675 files to a different directory.
2676 This directive can be used multiple times.
2678 An example of the directive is:
2680 confdir /etc/chrony.d
2682 sourcedir directory...
2684 The sourcedir directive is identical to the confdir directive,
2685 except the configuration files have the .sources suffix, they can
2686 only specify NTP sources (i.e. the server, pool, and peer
2687 directives), they are expected to have all lines terminated by the
2688 newline character, and they can be reloaded by the reload sources
2689 command in chronyc. It is particularly useful with dynamic sources
2690 like NTP servers received from a DHCP server, which can be written
2691 to a file specific to the network interface by a networking script.
2692 This directive can be used multiple times.
2694 An example of the directive is:
2696 sourcedir /var/run/chrony-dhcp
2698 include pattern
2700 The include directive includes a configuration file, or multiple
2701 configuration files if a wildcard pattern is specified. Unlike with
2702 the confdir directive, the full name of the files needs to be
2703 specified and at least one file is required to exist.
2704 This directive can be used multiple times.
2706 An example of the directive is:
2708 include /etc/chrony.d/*.conf
2710 hwtimestamp interface [option]...
2712 This directive enables hardware timestamping of NTP packets sent to
2713 and received from the specified network interface. The network
2714 interface controller (NIC) uses its own clock to accurately
2715 timestamp the actual transmissions and receptions, avoiding
2716 processing and queueing delays in the kernel, network driver, and
2717 hardware. This can significantly improve the accuracy of the
2718 timestamps and the measured offset, which is used for
2719 synchronisation of the system clock. In order to get the best
2720 results, both sides receiving and sending NTP packets (i.e. server
2721 and client, or two peers) need to use HW timestamping. If the
2722 server or peer supports the interleaved mode, it needs to be
2723 enabled by the xleave option in the server or the peer directive.
2724 This directive is supported on Linux 3.19 and newer. The NIC must
2726 support HW timestamping, which can be verified with the ethtool -T
2727 command. The list of capabilities should include
2728 hardware-raw-clock, hardware-transmit, and hardware-receive. The
2729 receive filter all, or ntp, is necessary for timestamping of
2730 received NTP packets. Timestamping of packets received on bridged
2731 and bonded interfaces is supported on Linux 4.13 and newer. If HW
2732 timestamping does not work for received packets, chronyd will use
2733 kernel receive timestamps instead. Transmit-only HW timestamping
2734 can still be useful to improve stability of the synchronisation.
2735 chronyd does not synchronise the NIC clock. It assumes the clock is
2737 running free. Multiple instances of chronyd can use the same
2738 interface with enabled HW timestamping. Applications which need HW
2739 timestamping with a synchronised clock (e.g. a PTP daemon) should
2740 use a virtual clock running on top of the physical clock created by
2741 writing to /sys/class/ptp/ptpX/n_vclocks. This feature is available
2742 on Linux 5.14 and newer.
2743 If the kernel supports software timestamping, it will be enabled
2745 for all interfaces. The source of timestamps (i.e. hardware,
2746 kernel, or daemon) is indicated in the measurements.log file if
2747 enabled by the log measurements directive, and the ntpdata report
2748 in chronyc.
2749 This directive can be used multiple times to enable HW timestamping
2751 on multiple interfaces. If the specified interface is *, chronyd
2752 will try to enable HW timestamping on all available interfaces.
2753 The hwtimestamp directive has the following options:
2755 minpoll poll
2757 This option specifies the minimum interval between readings of
2758 the NIC clock. It’s defined as a power of two. It should
2759 correspond to the minimum polling interval of all NTP sources
2760 and the minimum expected polling interval of NTP clients. The
2761 default value is 0 (1 second) and the minimum value is -6
2762 (1/64th of a second).
2763 minsamples samples
2765 This option specifies the minimum number of readings kept for
2766 tracking of the NIC clock. The default value is 2.
2767 maxsamples samples
2769 This option specifies the maximum number of readings kept for
2770 tracking of the NIC clock. The default value is 16.
2771 precision precision
2773 This option specifies the assumed precision of reading of the
2774 NIC clock. The default value is 100e-9 (100 nanoseconds).
2775 txcomp compensation
2777 This option specifies the difference in seconds between the
2778 actual transmission time at the physical layer and the reported
2779 transmit timestamp. This value will be added to transmit
2780 timestamps obtained from the NIC. The default value is 0.
2781 rxcomp compensation
2783 This option specifies the difference in seconds between the
2784 reported receive timestamp and the actual reception time at the
2785 physical layer. This value will be subtracted from receive
2786 timestamps obtained from the NIC. The default value is 0.
2787 nocrossts
2789 Some hardware can precisely cross timestamp the NIC clock with
2790 the system clock. This option disables the use of the cross
2791 timestamping.
2792 rxfilter filter
2794 This option selects the receive timestamping filter. The filter
2795 can be one of the following:
2796 all
2798 Enables timestamping of all received packets.
2799 ntp
2801 Enables timestamping of received NTP packets.
2802 ptp
2804 Enables timestamping of received PTP packets.
2805 none
2807 Disables timestamping of received packets.
2808 The most specific filter for timestamping of NTP packets
2811 supported by the NIC is selected by default. Some NICs can
2812 timestamp PTP packets only. By default, they will be configured
2813 with the none filter and expected to provide hardware
2814 timestamps for transmitted packets only. Timestamping of PTP
2815 packets is useful with NTP-over-PTP enabled by the ptpport
2816 directive, or when another application is receiving PTP packets
2817 on the interface. Forcing timestamping of all packets with the
2818 all filter could be useful if the NIC supported both the all
2819 and ntp filters, and it should timestamp both NTP and PTP
2820 packets, or NTP packets on a different UDP port.
2821 Examples of the directive are:
2825 hwtimestamp eth0
2827 hwtimestamp eth1 txcomp 300e-9 rxcomp 645e-9
2828 hwtimestamp *
2829 keyfile file
2831 This directive is used to specify the location of the file
2832 containing symmetric keys which are shared between NTP servers and
2833 clients, or peers, in order to authenticate NTP packets with a
2834 message authentication code (MAC) using a cryptographic hash
2835 function or cipher.
2836 The format of the directive is shown in the example below:
2838 keyfile /etc/chrony.keys
2840 The argument is simply the name of the file containing the ID-key
2842 pairs. The format of the file is shown below:
2843 10 tulip
2845 11 hyacinth
2846 20 MD5 ASCII:crocus
2847 25 SHA1 HEX:933F62BE1D604E68A81B557F18CFA200483F5B70
2848 30 AES128 HEX:7EA62AE64D190114D46D5A082F948EC1
2849 31 AES256 HEX:37DDCBC67BB902BCB8E995977FAB4D2B5642F5B32EBCEEE421921D97E5CBFE39
2850 ...
2851 Each line consists of an ID, optional type, and key.
2853 The ID can be any positive integer in the range 1 through 2^32-1.
2855 The type is a name of a cryptographic hash function or cipher which
2857 is used to generate and verify the MAC. The default type is MD5,
2858 which is always supported. If chronyd was built with enabled
2859 support for hashing using a crypto library (Nettle, GnuTLS, NSS, or
2860 LibTomCrypt), the following functions are available: MD5, SHA1,
2861 SHA256, SHA384, SHA512. Depending on which library and version is
2862 chronyd using, some of the following hash functions and ciphers may
2863 also be available: SHA3-224, SHA3-256, SHA3-384, SHA3-512, TIGER,
2864 WHIRLPOOL, AES128, AES256.
2865 The key can be specified as a string of ASCII characters not
2867 containing white space with an optional ASCII: prefix, or as a
2868 hexadecimal number with the HEX: prefix. The maximum length of the
2869 line is 2047 characters. If the type is a cipher, the length of the
2870 key must match the cipher (i.e. 128 bits for AES128 and 256 bits
2871 for AES256).
2872 It is recommended to use randomly generated keys, specified in the
2874 hexadecimal format, which are at least 128 bits long (i.e. they
2875 have at least 32 characters after the HEX: prefix). chronyd will
2876 log a warning to syslog on start if a source is specified in the
2877 configuration file with a key shorter than 80 bits.
2878 The recommended key types are AES ciphers and SHA3 hash functions.
2880 MD5 should be avoided unless no other type is supported on the
2881 server and client, or peers.
2882 The keygen command of chronyc can be used to generate random keys
2884 for the key file. By default, it generates 160-bit MD5 or SHA1
2885 keys.
2886 For security reasons, the file should be readable only by root and
2888 the user under which chronyd is normally running (to allow chronyd
2889 to re-read the file when the rekey command is issued by chronyc).
2890 lock_all
2892 The lock_all directive will lock the chronyd process into RAM so
2893 that it will never be paged out. This can result in lower and more
2894 consistent latency. The directive is supported on Linux, FreeBSD,
2895 NetBSD, and illumos.
2896 pidfile file
2898 Unless chronyd is started with the -Q option, it writes its process
2899 ID (PID) to a file, and checks this file on startup to see if
2900 another chronyd might already be running on the system. By default,
2901 the file used is /run/chrony/chronyd.pid. The pidfile directive
2902 allows the name to be changed, e.g.:
2903 pidfile /run/chronyd.pid
2905 ptpport port
2907 The ptpport directive enables chronyd to send and receive NTP
2908 messages contained in PTP event messages (NTP-over-PTP) to enable
2909 hardware timestamping on NICs which cannot timestamp NTP packets,
2910 but can timestamp unicast PTP packets. The port recognized by the
2911 NICs is 319 (PTP event port). The default value is 0 (disabled).
2912 The NTP-over-PTP support is experimental. The protocol and
2914 configuration can change in future. It should be used only in local
2915 networks and expected to work only between servers and clients
2916 running the same version of chronyd.
2917 The PTP port will be open even if chronyd is not configured to
2919 operate as a server or client. The directive does not change the
2920 default protocol of specified NTP sources. Each NTP source that
2921 should use NTP-over-PTP needs to be specified with the port option
2922 set to the PTP port. To actually enable hardware timestamping on
2923 NICs which can timestamp PTP packets only, the rxfilter option of
2924 the hwtimestamp directive needs to be set to ptp.
2925 An example of client configuration is:
2927 server foo.example.net minpoll 0 maxpoll 0 xleave port 319
2929 hwtimestamp * rxfilter ptp
2930 ptpport 319
2931 sched_priority priority
2933 On Linux, FreeBSD, NetBSD, and illumos, the sched_priority
2934 directive will select the SCHED_FIFO real-time scheduler at the
2935 specified priority (which must be between 0 and 100). On macOS,
2936 this option must have either a value of 0 (the default) to disable
2937 the thread time constraint policy or 1 for the policy to be
2938 enabled.
2939 On systems other than macOS, this directive uses the
2941 pthread_setschedparam() system call to instruct the kernel to use
2942 the SCHED_FIFO first-in, first-out real-time scheduling policy for
2943 chronyd with the specified priority. This means that whenever
2944 chronyd is ready to run it will run, interrupting whatever else is
2945 running unless it is a higher priority real-time process. This
2946 should not impact performance as chronyd resource requirements are
2947 modest, but it should result in lower and more consistent latency
2948 since chronyd will not need to wait for the scheduler to get around
2949 to running it. You should not use this unless you really need it.
2950 The pthread_setschedparam(3) man page has more details.
2951 On macOS, this directive uses the thread_policy_set() kernel call
2953 to specify real-time scheduling. As noted above, you should not use
2954 this directive unless you really need it.
2955 user user
2957 The user directive sets the name of the system user to which
2958 chronyd will switch after start in order to drop root privileges.
2959 On Linux, chronyd needs to be compiled with support for the libcap
2961 library. On macOS, FreeBSD, NetBSD and illumos chronyd forks into
2962 two processes. The child process retains root privileges, but can
2963 only perform a very limited range of privileged system calls on
2964 behalf of the parent.
2965 The compiled-in default value is chrony.
2967
2969 NTP client with permanent connection to NTP servers
2970 This section shows how to configure chronyd for computers that are
2971 connected to the Internet (or to any network containing true NTP
2972 servers which ultimately derive their time from a reference clock)
2973 permanently or most of the time.
2974 To operate in this mode, you will need to know the names of the NTP
2976 servers you want to use. You might be able to find names of suitable
2977 servers by one of the following methods:
2978 • Your institution might already operate servers on its network.
2980 Contact your system administrator to find out.
2981 • Your ISP probably has one or more NTP servers available for its
2983 customers.
2984 • Somewhere under the NTP homepage there is a list of public stratum
2986 1 and stratum 2 servers. You should find one or more servers that
2987 are near to you. Check that their access policy allows you to use
2988 their facilities.
2989 • Use public servers from the pool.ntp.org
2991 <https://www.pool.ntp.org/> project.
2992 Assuming that your NTP servers are called foo.example.net,
2994 bar.example.net and baz.example.net, your chrony.conf file could
2995 contain as a minimum:
2996 server foo.example.net
2998 server bar.example.net
2999 server baz.example.net
3000 However, you will probably want to include some of the other
3002 directives. The driftfile, makestep and rtcsync might be particularly
3003 useful. Also, the iburst option of the server directive is useful to
3004 speed up the initial synchronisation. The smallest useful configuration
3005 file would look something like:
3006 server foo.example.net iburst
3008 server bar.example.net iburst
3009 server baz.example.net iburst
3010 driftfile /var/lib/chrony/drift
3011 makestep 1.0 3
3012 rtcsync
3013 When using a pool of NTP servers (one name is used for multiple servers
3015 which might change over time), it is better to specify them with the
3016 pool directive instead of multiple server directives. The configuration
3017 file could in this case look like:
3018 pool pool.ntp.org iburst
3020 driftfile /var/lib/chrony/drift
3021 makestep 1.0 3
3022 rtcsync
3023 If the servers (or pool) support the Network Time Security (NTS)
3025 authentication mechanism and chronyd is compiled with NTS support, the
3026 nts option will enable a secure synchronisation to the servers. The
3027 configuration file could look like:
3028 server foo.example.net iburst nts
3030 server bar.example.net iburst nts
3031 server baz.example.net iburst nts
3032 driftfile /var/lib/chrony/drift
3033 makestep 1.0 3
3034 rtcsync
3035 NTP client with infrequent connection to NTP servers
3037 This section shows how to configure chronyd for computers that have
3038 occasional connections to NTP servers. In this case, you will need some
3039 additional configuration to tell chronyd when the connection goes up
3040 and down. This saves the program from continuously trying to poll the
3041 servers when they are inaccessible.
3042 Again, assuming that your NTP servers are called foo.example.net,
3044 bar.example.net and baz.example.net, your chrony.conf file would now
3045 contain:
3046 server foo.example.net offline
3048 server bar.example.net offline
3049 server baz.example.net offline
3050 driftfile /var/lib/chrony/drift
3051 makestep 1.0 3
3052 rtcsync
3053 The offline keyword indicates that the servers start in an offline
3055 state, and that they should not be contacted until chronyd receives
3056 notification from chronyc that the link to the Internet is present. To
3057 tell chronyd when to start and finish sampling the servers, the online
3058 and offline commands of chronyc need to be used.
3059 To give an example of their use, assuming that pppd is the program
3061 being used to connect to the Internet and that chronyc has been
3062 installed at /usr/bin/chronyc, the script /etc/ppp/ip-up would include:
3063 /usr/bin/chronyc online
3065 and the script /etc/ppp/ip-down would include:
3067 /usr/bin/chronyc offline
3069 chronyd's polling of the servers would now only occur whilst the
3071 machine is actually connected to the Internet.
3072 Isolated networks
3074 This section shows how to configure chronyd for computers that never
3075 have network connectivity to any computer which ultimately derives its
3076 time from a reference clock.
3077 In this situation, one computer is selected to be the primary
3079 timeserver. The other computers are either direct clients of the
3080 server, or clients of clients.
3081 The local directive enables a local reference mode, which allows
3083 chronyd to appear synchronised even when it is not.
3084 The rate value in the server’s drift file needs to be set to the
3086 average rate at which the server gains or loses time. chronyd includes
3087 support for this, in the form of the manual directive and the settime
3088 command in the chronyc program.
3089 If the server is rebooted, chronyd can re-read the drift rate from the
3091 drift file. However, the server has no accurate estimate of the current
3092 time. To get around this, the system can be configured so that the
3093 server can initially set itself to a ‘majority-vote’ of selected
3094 clients' times; this allows the clients to ‘flywheel’ the server while
3095 it is rebooting.
3096 The smoothtime directive is useful when the clocks of the clients need
3098 to stay close together when the local time is adjusted by the settime
3099 command. The smoothing process needs to be activated by the smoothtime
3100 activate command when the local time is ready to be served. After that
3101 point, any adjustments will be smoothed out.
3102 A typical configuration file for the server (called ntp.local) might be
3104 (assuming the clients and the server are in the 192.168.165.x subnet):
3105 initstepslew 1 client1 client3 client6
3107 driftfile /var/lib/chrony/drift
3108 local stratum 8
3109 manual
3110 allow 192.168.165.0/24
3111 smoothtime 400 0.01
3112 rtcsync
3113 For the clients that have to resynchronise the server when it restarts,
3115 the configuration file might be:
3116 server ntp.local iburst
3118 driftfile /var/lib/chrony/drift
3119 allow 192.168.165.0/24
3120 makestep 1.0 3
3121 rtcsync
3122 The rest of the clients would be the same, except that the allow
3124 directive is not required.
3125 If there is no suitable computer to be designated as the primary
3127 server, or there is a requirement to keep the clients synchronised even
3128 when it fails, the orphan option of the local directive enables a
3129 special mode where the server is selected from multiple computers
3130 automatically. They all need to use the same local configuration and
3131 poll one another. The server with the smallest reference ID (which is
3132 based on its IP address) will take the role of the primary server and
3133 others will be synchronised to it. When it fails, the server with the
3134 second smallest reference ID will take over and so on.
3135 A configuration file for the first server might be (assuming there are
3137 three servers called ntp1.local, ntp2.local, and ntp3.local):
3138 initstepslew 1 ntp2.local ntp3.local
3140 server ntp2.local
3141 server ntp3.local
3142 driftfile /var/lib/chrony/drift
3143 local stratum 8 orphan
3144 manual
3145 allow 192.168.165.0/24
3146 rtcsync
3147 The other servers would be the same, except the hostnames in the
3149 initstepslew and server directives would be modified to specify the
3150 other servers. Their clients might be configured to poll all three
3151 servers.
3152 RTC tracking
3154 This section considers a computer which has occasional connections to
3155 the Internet and is turned off between ‘sessions’. In this case,
3156 chronyd relies on the computer’s RTC to maintain the time between the
3157 periods when it is powered up. It assumes that Linux is run exclusively
3158 on the computer. Dual-boot systems might work; it depends what (if
3159 anything) the other system does to the RTC. On 2.6 and later kernels,
3160 if your motherboard has a HPET, you will need to enable the
3161 HPET_EMULATE_RTC option in your kernel configuration. Otherwise,
3162 chronyd will not be able to interact with the RTC device and will give
3163 up using it.
3164 When the computer is connected to the Internet, chronyd has access to
3166 external NTP servers which it makes measurements from. These
3167 measurements are saved, and straight-line fits are performed on them to
3168 provide an estimate of the computer’s time error and rate of gaining or
3169 losing time.
3170 When the computer is taken offline from the Internet, the best estimate
3172 of the gain or loss rate is used to free-run the computer until it next
3173 goes online.
3174 Whilst the computer is running, chronyd makes measurements of the RTC
3176 (via the /dev/rtc interface, which must be compiled into the kernel).
3177 An estimate is made of the RTC error at a particular RTC second, and
3178 the rate at which the RTC gains or loses time relative to true time.
3179 When the computer is powered down, the measurement histories for all
3181 the NTP servers are saved to files, and the RTC tracking information is
3182 also saved to a file (if the rtcfile directive has been specified).
3183 These pieces of information are also saved if the dump and writertc
3184 commands respectively are issued through chronyc.
3185 When the computer is rebooted, chronyd reads the current RTC time and
3187 the RTC information saved at the last shutdown. This information is
3188 used to set the system clock to the best estimate of what its time
3189 would have been now, had it been left running continuously. The
3190 measurement histories for the servers are then reloaded.
3191 The next time the computer goes online, the previous sessions'
3193 measurements can contribute to the line-fitting process, which gives a
3194 much better estimate of the computer’s gain or loss rate.
3195 One problem with saving the measurements and RTC data when the machine
3197 is shut down is what happens if there is a power failure; the most
3198 recent data will not be saved. Although chronyd is robust enough to
3199 cope with this, some performance might be lost. (The main danger arises
3200 if the RTC has been changed during the session, with the trimrtc
3201 command in chronyc. Because of this, trimrtc will make sure that a
3202 meaningful RTC file is saved after the change is completed).
3203 The easiest protection against power failure is to put the dump and
3205 writertc commands in the same place as the offline command is issued to
3206 take chronyd offline; because chronyd free-runs between online
3207 sessions, no parameters will change significantly between going offline
3208 from the Internet and any power failure.
3209 A final point regards computers which are left running for extended
3211 periods and where it is desired to spin down the hard disc when it is
3212 not in use (e.g. when not accessed for 15 minutes). chronyd has been
3213 planned so it supports such operation; this is the reason why the RTC
3214 tracking parameters are not saved to disc after every update, but only
3215 when the user requests such a write, or during the shutdown sequence.
3216 The only other facility that will generate periodic writes to the disc
3217 is the log rtc facility in the configuration file; this option should
3218 not be used if you want your disc to spin down.
3219 To illustrate how a computer might be configured for this case, example
3221 configuration files are shown.
3222 For the chrony.conf file, the following can be used as an example.
3224 server foo.example.net maxdelay 0.4 offline
3226 server bar.example.net maxdelay 0.4 offline
3227 server baz.example.net maxdelay 0.4 offline
3228 logdir /var/log/chrony
3229 log statistics measurements tracking
3230 driftfile /var/lib/chrony/drift
3231 makestep 1.0 3
3232 maxupdateskew 100.0
3233 dumpdir /var/lib/chrony
3234 rtcfile /var/lib/chrony/rtc
3235 pppd is used for connecting to the Internet. This runs two scripts
3237 /etc/ppp/ip-up and /etc/ppp/ip-down when the link goes online and
3238 offline respectively.
3239 The relevant part of the /etc/ppp/ip-up file is:
3241 /usr/bin/chronyc online
3243 and the relevant part of the /etc/ppp/ip-down script is:
3245 /usr/bin/chronyc -m offline dump writertc
3247 chronyd is started during the boot sequence with the -r and -s options.
3249 It might need to be started before any software that depends on the
3250 system clock not jumping or moving backwards, depending on the
3251 directives in chronyd's configuration file.
3252 For the system shutdown, chronyd should receive a SIGTERM several
3254 seconds before the final SIGKILL; the SIGTERM causes the measurement
3255 histories and RTC information to be saved.
3256 Public NTP server
3258 chronyd can be configured to operate as a public NTP server, e.g. to
3259 join the pool.ntp.org <https://www.pool.ntp.org/en/join.html> project.
3260 The configuration is similar to the NTP client with permanent
3261 connection, except it needs to allow client access from all addresses.
3262 It is recommended to find at least four good servers (e.g. from the
3263 pool, or on the NTP homepage). If the server has a hardware reference
3264 clock (e.g. a GPS receiver), it can be specified by the refclock
3265 directive.
3266 The amount of memory used for logging client accesses can be increased
3268 in order to enable clients to use the interleaved mode even when the
3269 server has a large number of clients, and better support rate limiting
3270 if it is enabled by the ratelimit directive. The system timezone
3271 database, if it is kept up to date and includes the right/UTC timezone,
3272 can be used as a reliable source to determine when a leap second will
3273 be applied to UTC. The -r option with the dumpdir directive shortens
3274 the time in which chronyd will not be able to serve time to its clients
3275 when it needs to be restarted (e.g. after upgrading to a newer version,
3276 or a change in the configuration).
3277 The configuration file could look like:
3279 server foo.example.net iburst
3281 server bar.example.net iburst
3282 server baz.example.net iburst
3283 server qux.example.net iburst
3284 makestep 1.0 3
3285 rtcsync
3286 allow
3287 clientloglimit 100000000
3288 leapsectz right/UTC
3289 driftfile /var/lib/chrony/drift
3290 dumpdir /run/chrony
3291
3293 chronyc(1), chronyd(8)
3294
3296 For instructions on how to report bugs, please visit
3297 https://chrony.tuxfamily.org/.
3298
3300 chrony was written by Richard Curnow, Miroslav Lichvar, and others.
3301chrony 4.3 2022-08-29 CHRONY.CONF(5)