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