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