1CHRONY.CONF(5)                Configuration Files               CHRONY.CONF(5)
2
3
4

NAME

6       chrony.conf - chronyd configuration file
7

SYNOPSIS

9       chrony.conf
10

DESCRIPTION

12       This file configures the chronyd daemon. The compiled-in location is
13       /etc/chrony.conf. Other locations can be specified on the chronyd
14       command line with the -f option.
15
16       Each directive in the configuration file is placed on a separate line.
17       The following sections describe each of the directives in turn. The
18       directives are not case-sensitive. Generally, the directives can occur
19       in any order in the file and if a directive is specified multiple
20       times, only the last one will be effective. Exceptions are noted in the
21       descriptions.
22
23       The configuration directives can also be specified directly on the
24       chronyd command line. In this case each argument is parsed as a new
25       line and the configuration file is ignored.
26
27       While the number of supported directives is large, only a few of them
28       are typically needed. See the EXAMPLES section for configuration in
29       typical operating scenarios.
30
31       The configuration file might contain comment lines. A comment line is
32       any line that starts with zero or more spaces followed by any one of
33       the following characters: !, ;, #, %. Any line with this format will be
34       ignored.
35

DIRECTIVES

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

EXAMPLES

2746   NTP client with permanent connection to NTP servers
2747       This section shows how to configure chronyd for computers that are
2748       connected to the Internet (or to any network containing true NTP
2749       servers which ultimately derive their time from a reference clock)
2750       permanently or most of the time.
2751
2752       To operate in this mode, you will need to know the names of the NTP
2753       servers you want to use. You might be able to find names of suitable
2754       servers by one of the following methods:
2755
2756       •   Your institution might already operate servers on its network.
2757           Contact your system administrator to find out.
2758
2759       •   Your ISP probably has one or more NTP servers available for its
2760           customers.
2761
2762       •   Somewhere under the NTP homepage there is a list of public stratum
2763           1 and stratum 2 servers. You should find one or more servers that
2764           are near to you. Check that their access policy allows you to use
2765           their facilities.
2766
2767       •   Use public servers from the pool.ntp.org
2768           <https://www.pool.ntp.org/> project.
2769
2770       Assuming that your NTP servers are called foo.example.net,
2771       bar.example.net and baz.example.net, your chrony.conf file could
2772       contain as a minimum:
2773
2774           server foo.example.net
2775           server bar.example.net
2776           server baz.example.net
2777
2778       However, you will probably want to include some of the other
2779       directives. The driftfile, makestep and rtcsync might be particularly
2780       useful. Also, the iburst option of the server directive is useful to
2781       speed up the initial synchronisation. The smallest useful configuration
2782       file would look something like:
2783
2784           server foo.example.net iburst
2785           server bar.example.net iburst
2786           server baz.example.net iburst
2787           driftfile /var/lib/chrony/drift
2788           makestep 1.0 3
2789           rtcsync
2790
2791       When using a pool of NTP servers (one name is used for multiple servers
2792       which might change over time), it is better to specify them with the
2793       pool directive instead of multiple server directives. The configuration
2794       file could in this case look like:
2795
2796           pool pool.ntp.org iburst
2797           driftfile /var/lib/chrony/drift
2798           makestep 1.0 3
2799           rtcsync
2800
2801       If the servers (or pool) support the Network Time Security (NTS)
2802       authentication mechanism and chronyd is compiled with NTS support, the
2803       nts option will enable a secure synchronisation to the servers. The
2804       configuration file could look like:
2805
2806           server foo.example.net iburst nts
2807           server bar.example.net iburst nts
2808           server baz.example.net iburst nts
2809           driftfile /var/lib/chrony/drift
2810           makestep 1.0 3
2811           rtcsync
2812
2813   NTP client with infrequent connection to NTP servers
2814       This section shows how to configure chronyd for computers that have
2815       occasional connections to NTP servers. In this case, you will need some
2816       additional configuration to tell chronyd when the connection goes up
2817       and down. This saves the program from continuously trying to poll the
2818       servers when they are inaccessible.
2819
2820       Again, assuming that your NTP servers are called foo.example.net,
2821       bar.example.net and baz.example.net, your chrony.conf file would now
2822       contain:
2823
2824           server foo.example.net offline
2825           server bar.example.net offline
2826           server baz.example.net offline
2827           driftfile /var/lib/chrony/drift
2828           makestep 1.0 3
2829           rtcsync
2830
2831       The offline keyword indicates that the servers start in an offline
2832       state, and that they should not be contacted until chronyd receives
2833       notification from chronyc that the link to the Internet is present. To
2834       tell chronyd when to start and finish sampling the servers, the online
2835       and offline commands of chronyc need to be used.
2836
2837       To give an example of their use, assuming that pppd is the program
2838       being used to connect to the Internet and that chronyc has been
2839       installed at /usr/bin/chronyc, the script /etc/ppp/ip-up would include:
2840
2841           /usr/bin/chronyc online
2842
2843       and the script /etc/ppp/ip-down would include:
2844
2845           /usr/bin/chronyc offline
2846
2847       chronyd’s polling of the servers would now only occur whilst the
2848       machine is actually connected to the Internet.
2849
2850   Isolated networks
2851       This section shows how to configure chronyd for computers that never
2852       have network connectivity to any computer which ultimately derives its
2853       time from a reference clock.
2854
2855       In this situation, one computer is selected to be the primary
2856       timeserver. The other computers are either direct clients of the
2857       server, or clients of clients.
2858
2859       The local directive enables a local reference mode, which allows
2860       chronyd to appear synchronised even when it is not.
2861
2862       The rate value in the server’s drift file needs to be set to the
2863       average rate at which the server gains or loses time. chronyd includes
2864       support for this, in the form of the manual directive and the settime
2865       command in the chronyc program.
2866
2867       If the server is rebooted, chronyd can re-read the drift rate from the
2868       drift file. However, the server has no accurate estimate of the current
2869       time. To get around this, the system can be configured so that the
2870       server can initially set itself to a ‘majority-vote’ of selected
2871       clients' times; this allows the clients to ‘flywheel’ the server while
2872       it is rebooting.
2873
2874       The smoothtime directive is useful when the clocks of the clients need
2875       to stay close together when the local time is adjusted by the settime
2876       command. The smoothing process needs to be activated by the smoothtime
2877       activate command when the local time is ready to be served. After that
2878       point, any adjustments will be smoothed out.
2879
2880       A typical configuration file for the server (called ntp.local) might be
2881       (assuming the clients and the server are in the 192.168.165.x subnet):
2882
2883           initstepslew 1 client1 client3 client6
2884           driftfile /var/lib/chrony/drift
2885           local stratum 8
2886           manual
2887           allow 192.168.165.0/24
2888           smoothtime 400 0.01
2889           rtcsync
2890
2891       For the clients that have to resynchronise the server when it restarts,
2892       the configuration file might be:
2893
2894           server ntp.local iburst
2895           driftfile /var/lib/chrony/drift
2896           allow 192.168.165.0/24
2897           makestep 1.0 3
2898           rtcsync
2899
2900       The rest of the clients would be the same, except that the allow
2901       directive is not required.
2902
2903       If there is no suitable computer to be designated as the primary
2904       server, or there is a requirement to keep the clients synchronised even
2905       when it fails, the orphan option of the local directive enables a
2906       special mode where the server is selected from multiple computers
2907       automatically. They all need to use the same local configuration and
2908       poll one another. The server with the smallest reference ID (which is
2909       based on its IP address) will take the role of the primary server and
2910       others will be synchronised to it. When it fails, the server with the
2911       second smallest reference ID will take over and so on.
2912
2913       A configuration file for the first server might be (assuming there are
2914       three servers called ntp1.local, ntp2.local, and ntp3.local):
2915
2916           initstepslew 1 ntp2.local ntp3.local
2917           server ntp2.local
2918           server ntp3.local
2919           driftfile /var/lib/chrony/drift
2920           local stratum 8 orphan
2921           manual
2922           allow 192.168.165.0/24
2923           rtcsync
2924
2925       The other servers would be the same, except the hostnames in the
2926       initstepslew and server directives would be modified to specify the
2927       other servers. Their clients might be configured to poll all three
2928       servers.
2929
2930   RTC tracking
2931       This section considers a computer which has occasional connections to
2932       the Internet and is turned off between ‘sessions’. In this case,
2933       chronyd relies on the computer’s RTC to maintain the time between the
2934       periods when it is powered up. It assumes that Linux is run exclusively
2935       on the computer. Dual-boot systems might work; it depends what (if
2936       anything) the other system does to the RTC. On 2.6 and later kernels,
2937       if your motherboard has a HPET, you will need to enable the
2938       HPET_EMULATE_RTC option in your kernel configuration. Otherwise,
2939       chronyd will not be able to interact with the RTC device and will give
2940       up using it.
2941
2942       When the computer is connected to the Internet, chronyd has access to
2943       external NTP servers which it makes measurements from. These
2944       measurements are saved, and straight-line fits are performed on them to
2945       provide an estimate of the computer’s time error and rate of gaining or
2946       losing time.
2947
2948       When the computer is taken offline from the Internet, the best estimate
2949       of the gain or loss rate is used to free-run the computer until it next
2950       goes online.
2951
2952       Whilst the computer is running, chronyd makes measurements of the RTC
2953       (via the /dev/rtc interface, which must be compiled into the kernel).
2954       An estimate is made of the RTC error at a particular RTC second, and
2955       the rate at which the RTC gains or loses time relative to true time.
2956
2957       When the computer is powered down, the measurement histories for all
2958       the NTP servers are saved to files, and the RTC tracking information is
2959       also saved to a file (if the rtcfile directive has been specified).
2960       These pieces of information are also saved if the dump and writertc
2961       commands respectively are issued through chronyc.
2962
2963       When the computer is rebooted, chronyd reads the current RTC time and
2964       the RTC information saved at the last shutdown. This information is
2965       used to set the system clock to the best estimate of what its time
2966       would have been now, had it been left running continuously. The
2967       measurement histories for the servers are then reloaded.
2968
2969       The next time the computer goes online, the previous sessions'
2970       measurements can contribute to the line-fitting process, which gives a
2971       much better estimate of the computer’s gain or loss rate.
2972
2973       One problem with saving the measurements and RTC data when the machine
2974       is shut down is what happens if there is a power failure; the most
2975       recent data will not be saved. Although chronyd is robust enough to
2976       cope with this, some performance might be lost. (The main danger arises
2977       if the RTC has been changed during the session, with the trimrtc
2978       command in chronyc. Because of this, trimrtc will make sure that a
2979       meaningful RTC file is saved after the change is completed).
2980
2981       The easiest protection against power failure is to put the dump and
2982       writertc commands in the same place as the offline command is issued to
2983       take chronyd offline; because chronyd free-runs between online
2984       sessions, no parameters will change significantly between going offline
2985       from the Internet and any power failure.
2986
2987       A final point regards computers which are left running for extended
2988       periods and where it is desired to spin down the hard disc when it is
2989       not in use (e.g. when not accessed for 15 minutes). chronyd has been
2990       planned so it supports such operation; this is the reason why the RTC
2991       tracking parameters are not saved to disc after every update, but only
2992       when the user requests such a write, or during the shutdown sequence.
2993       The only other facility that will generate periodic writes to the disc
2994       is the log rtc facility in the configuration file; this option should
2995       not be used if you want your disc to spin down.
2996
2997       To illustrate how a computer might be configured for this case, example
2998       configuration files are shown.
2999
3000       For the chrony.conf file, the following can be used as an example.
3001
3002           server foo.example.net maxdelay 0.4 offline
3003           server bar.example.net maxdelay 0.4 offline
3004           server baz.example.net maxdelay 0.4 offline
3005           logdir /var/log/chrony
3006           log statistics measurements tracking
3007           driftfile /var/lib/chrony/drift
3008           makestep 1.0 3
3009           maxupdateskew 100.0
3010           dumpdir /var/lib/chrony
3011           rtcfile /var/lib/chrony/rtc
3012
3013       pppd is used for connecting to the Internet. This runs two scripts
3014       /etc/ppp/ip-up and /etc/ppp/ip-down when the link goes online and
3015       offline respectively.
3016
3017       The relevant part of the /etc/ppp/ip-up file is:
3018
3019           /usr/bin/chronyc online
3020
3021       and the relevant part of the /etc/ppp/ip-down script is:
3022
3023           /usr/bin/chronyc -m offline dump writertc
3024
3025       chronyd is started during the boot sequence with the -r and -s options.
3026       It might need to be started before any software that depends on the
3027       system clock not jumping or moving backwards, depending on the
3028       directives in chronyd’s configuration file.
3029
3030       For the system shutdown, chronyd should receive a SIGTERM several
3031       seconds before the final SIGKILL; the SIGTERM causes the measurement
3032       histories and RTC information to be saved.
3033
3034   Public NTP server
3035       chronyd can be configured to operate as a public NTP server, e.g. to
3036       join the pool.ntp.org <https://www.pool.ntp.org/en/join.html> project.
3037       The configuration is similar to the NTP client with permanent
3038       connection, except it needs to allow client access from all addresses.
3039       It is recommended to find at least four good servers (e.g. from the
3040       pool, or on the NTP homepage). If the server has a hardware reference
3041       clock (e.g. a GPS receiver), it can be specified by the refclock
3042       directive.
3043
3044       The amount of memory used for logging client accesses can be increased
3045       in order to enable clients to use the interleaved mode even when the
3046       server has a large number of clients, and better support rate limiting
3047       if it is enabled by the ratelimit directive. The system timezone
3048       database, if it is kept up to date and includes the right/UTC timezone,
3049       can be used as a reliable source to determine when a leap second will
3050       be applied to UTC. The -r option with the dumpdir directive shortens
3051       the time in which chronyd will not be able to serve time to its clients
3052       when it needs to be restarted (e.g. after upgrading to a newer version,
3053       or a change in the configuration).
3054
3055       The configuration file could look like:
3056
3057           server foo.example.net iburst
3058           server bar.example.net iburst
3059           server baz.example.net iburst
3060           server qux.example.net iburst
3061           makestep 1.0 3
3062           rtcsync
3063           allow
3064           clientloglimit 100000000
3065           leapsectz right/UTC
3066           driftfile /var/lib/chrony/drift
3067           dumpdir /run/chrony
3068

SEE ALSO

3070       chronyc(1), chronyd(8)
3071

BUGS

3073       For instructions on how to report bugs, please visit
3074       https://chrony.tuxfamily.org/.
3075

AUTHORS

3077       chrony was written by Richard Curnow, Miroslav Lichvar, and others.
3078
3079
3080
3081chrony 4.1                        2021-05-12                    CHRONY.CONF(5)
Impressum