Adding upstream version 4.5.upstream/4.5upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 3160 insertions, 0 deletions

diff --git a/doc/chrony.conf.adoc b/doc/chrony.conf.adoc
new file mode 100644
index 0000000..cb3f95c
--- /dev/null
+++ b/doc/chrony.conf.adoc
@@ -0,0 +1,3160 @@
+// This file is part of chrony
+//
+// Copyright (C) Richard P. Curnow  1997-2003
+// Copyright (C) Stephen Wadeley  2016
+// Copyright (C) Bryan Christianson  2017
+// Copyright (C) Miroslav Lichvar  2009-2023
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of version 2 of the GNU General Public License as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along
+// with this program; if not, write to the Free Software Foundation, Inc.,
+// 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+
+= chrony.conf(5)
+:doctype: manpage
+:man manual: Configuration Files
+:man source: chrony @CHRONY_VERSION@
+
+== NAME
+chrony.conf - chronyd configuration file
+
+== SYNOPSIS
+*chrony.conf*
+
+== DESCRIPTION
+
+This file configures the *chronyd* daemon. The compiled-in location is
+_@SYSCONFDIR@/chrony.conf_. Other locations can be specified on the
+*chronyd* command line with the *-f* option.
+
+Each directive in the configuration file is placed on a separate line. The
+following sections describe each of the directives in turn. The directives are
+not case-sensitive. Generally, the directives can occur in any order in the file
+and if a directive is specified multiple times, only the last one will be
+effective. Exceptions are noted in the descriptions.
+
+The configuration directives can also be specified directly on the *chronyd*
+command line. In this case each argument is parsed as a new line and the
+configuration file is ignored.
+
+While the number of supported directives is large, only a few of them are
+typically needed. See the <<examples,*EXAMPLES*>> section for configuration in
+typical operating scenarios.
+
+The configuration file might contain comment lines. A comment line is any line
+that starts with zero or more spaces followed by any one of the following
+characters: *!*, *;*, *#*, *%*. Any line with this format will be ignored.
+
+== DIRECTIVES
+
+=== Time sources
+
+[[server]]*server* _hostname_ [_option_]...::
+The *server* directive specifies an NTP server which can be used as a time
+source. The client-server relationship is strictly hierarchical: a client might
+synchronise its system time to that of the server, but the server's system time
+will never be influenced by that of a client.
++
+The server can be specified by its hostname or IP address. If the hostname cannot
+be resolved on start, *chronyd* will try it again in increasing intervals, and
+also when the <<chronyc.adoc#online,*online*>> command is issued in *chronyc*.
++
+The DNS record can change over time. The used address will be replaced with a
+newly resolved address when the server becomes unreachable (i.e. no valid
+response to last 8 requests), unsynchronised, a falseticker (i.e. does not
+agree with a majority of other sources), or the root distance is too large (the
+limit can be configured by the <<maxdistance,*maxdistance*>> directive). The
+automatic replacement happens at most once per 30 minutes.
++
+This directive can be used multiple times to specify multiple servers.
++
+The directive supports the following options:
++
+*minpoll* _poll_:::
+This option specifies the minimum interval between requests sent to the server
+as a power of 2 in seconds. For example, *minpoll 5* would mean that the
+polling interval should not drop below 32 seconds. The default is 6 (64
+seconds), the minimum is -7 (1/128th of a second), and the maximum is 24 (6
+months). Note that intervals shorter than 6 (64 seconds) should generally not
+be used with public servers on the Internet, because it might be considered
+abuse. A sub-second interval will be enabled only when the server is reachable
+and the round-trip delay is shorter than 10 milliseconds, i.e. the server
+should be in a local network.
+*maxpoll* _poll_:::
+This option specifies the maximum interval between requests sent to the server
+as a power of 2 in seconds. For example, *maxpoll 9* indicates that the polling
+interval should stay at or below 9 (512 seconds). The default is 10 (1024
+seconds), the minimum is -7 (1/128th of a second), and the maximum is 24 (6
+months).
+*iburst*:::
+With this option, *chronyd* will start with a burst of 4-8 requests in order to
+make the first update of the clock sooner. It will also repeat the burst every
+time the source is switched from the offline state to online with the
+<<chronyc.adoc#online,*online*>> command in *chronyc*.
+*burst*:::
+With this option, *chronyd* will send a burst of up to 4 requests when it
+cannot get a good measurement from the
+server. The number of requests in the burst is limited by the current polling
+interval to keep the average interval at or above the minimum interval, i.e.
+the current interval needs to be at least two times longer than the minimum
+interval in order to allow a burst with two requests.
+*key* _ID_:::
+The NTP protocol supports a message authentication code (MAC) to prevent
+computers having their system time upset by rogue packets being sent to them.
+The MAC is generated as a function of a key specified in the key file,
+which is specified by the <<keyfile,*keyfile*>> directive.
++
+The *key* option specifies which key (with an ID in the range 1 through 2^32-1)
+should *chronyd* use to authenticate requests sent to the server and verify its
+responses. The server must have the same key for this number configured,
+otherwise no relationship between the computers will be possible.
++
+If the server is running *ntpd* and the output size of the hash function used
+by the key is longer than 160 bits (e.g. SHA256), the *version* option needs to
+be set to 4 for compatibility.
+*nts*:::
+This option enables authentication using the Network Time Security (NTS)
+mechanism. Unlike with the *key* option, the server and client do not need to
+share a key in a key file. NTS has a Key Establishment (NTS-KE) protocol using
+the Transport Layer Security (TLS) protocol to get the keys and cookies
+required by NTS for authentication of NTP packets.
+*certset* _ID_:::
+This option specifies which set of trusted certificates should be used to verify
+the server's certificate when the *nts* option is enabled. Sets of certificates
+can be specified with the <<ntstrustedcerts,*ntstrustedcerts*>> directive. The
+default set is 0, which by default contains certificates of the system's
+default trusted certificate authorities.
+*maxdelay* _delay_:::
+*chronyd* uses the network round-trip delay to the server to determine how
+accurate a particular measurement is likely to be. Long round-trip delays
+indicate that the request, or the response, or both were delayed. If only one
+of the messages was delayed the measurement error is likely to be substantial.
++
+For small variations in the round-trip delay, *chronyd* uses a weighting scheme
+when processing the measurements. However, beyond a certain level of delay the
+measurements are likely to be so corrupted as to be useless. (This is
+particularly so on wireless networks and other slow links, where a long delay
+probably indicates a highly asymmetric delay caused by the response waiting
+behind a lot of packets related to a download of some sort).
++
+If the user knows that round trip delays above a certain level should cause the
+measurement to be ignored, this level can be defined with the *maxdelay*
+option. For example, *maxdelay 0.3* would indicate that measurements with a
+round-trip delay greater than 0.3 seconds should be ignored. The default value
+is 3 seconds and the maximum value is 1000 seconds.
+*maxdelayratio* _ratio_:::
+This option is similar to the *maxdelay* option above. *chronyd* keeps a record
+of the minimum round-trip delay amongst the previous measurements that it has
+buffered. If a measurement has a round-trip delay that is greater than the
+specified ratio times the minimum delay, it will be rejected. By default, this
+test is disabled.
+*maxdelaydevratio* _ratio_:::
+If a measurement has a ratio of the increase in the round-trip delay from the
+minimum delay amongst the previous measurements to the standard deviation of
+the previous measurements that is greater than the specified ratio, it will be
+rejected. The default is 10.0.
+*maxdelayquant* _p_:::
+This option disables the *maxdelaydevratio* test and specifies the maximum
+acceptable delay as a quantile of the round-trip delay instead of a function of
+the minimum delay amongst the buffered measurements. If a measurement has a
+round-trip delay that is greater than a long-term estimate of the _p_-quantile,
+it will be rejected.
++
+The specified _p_ value should be between 0.05 and 0.95. For example,
+*maxdelayquant 0.2* would indicate that only measurements with the lowest 20
+percent of round-trip delays should be accepted. Note that it can take many
+measurements for the estimated quantile to reach the expected value. This
+option is intended for synchronisation in mostly static local networks with
+very short polling intervals and possibly combined with the *filter* option.
+By default, this test is disabled in favour of the *maxdelaydevratio* test.
+*mindelay* _delay_:::
+This option specifies a fixed minimum round-trip delay to be used instead of
+the minimum amongst the previous measurements. This can be useful in networks
+with static configuration to improve the stability of corrections for
+asymmetric jitter, weighting of the measurements, and the *maxdelayratio* and
+*maxdelaydevratio* tests. The value should be set accurately in order to have a
+positive effect on the synchronisation.
+*asymmetry* _ratio_:::
+This option specifies the asymmetry of the network jitter on the path to the
+source, which is used to correct the measured offset according to the delay.
+The asymmetry can be between -0.5 and +0.5. A negative value means the delay of
+packets sent to the source is more variable than the delay of packets sent from
+the source back. By default, *chronyd* estimates the asymmetry automatically.
+*offset* _offset_:::
+This option specifies a correction (in seconds) which will be applied to
+offsets measured with this source. It's particularly useful to compensate for a
+known asymmetry in network delay or timestamping errors. For example, if
+packets sent to the source were on average delayed by 100 microseconds more
+than packets sent from the source back, the correction would be -0.00005 (-50
+microseconds). The default is 0.0.
+*minsamples* _samples_:::
+Set the minimum number of samples kept for this source. This overrides the
+<<minsamples,*minsamples*>> directive.
+*maxsamples* _samples_:::
+Set the maximum number of samples kept for this source. This overrides the
+<<maxsamples,*maxsamples*>> directive.
+*filter* _polls_:::
+This option enables a median filter to reduce noise in NTP measurements. The
+filter will process samples collected in the specified number of polls
+into a single sample. It is intended to be used with very short polling
+intervals in local networks where it is acceptable to generate a lot of NTP
+traffic.
+*offline*:::
+If the server will not be reachable when *chronyd* is started, the *offline*
+option can be specified. *chronyd* will not try to poll the server until it is
+enabled to do so (by using the <<chronyc.adoc#online,*online*>> command in
+*chronyc*).
+*auto_offline*:::
+With this option, the server will be assumed to have gone offline when sending
+a request fails, e.g. due to a missing route to the network. This option avoids
+the need to run the <<chronyc.adoc#offline,*offline*>> command from *chronyc*
+when disconnecting the network link. (It will still be necessary to use the
+<<chronyc.adoc#online,*online*>> command when the link has been established, to
+enable measurements to start.)
+*prefer*:::
+Prefer this source over sources without the *prefer* option.
+*noselect*:::
+Never select this source. This is particularly useful for monitoring.
+*trust*:::
+Assume time from this source is always true. It can be rejected as a
+falseticker in the source selection only if another source with this option
+does not agree with it.
+*require*:::
+Require that at least one of the sources specified with this option is
+selectable (i.e. recently reachable and not a falseticker) before updating the
+clock. Together with the *trust* option this might be useful to allow a trusted
+authenticated source to be safely combined with unauthenticated sources in
+order to improve the accuracy of the clock. They can be selected and used for
+synchronisation only if they agree with the trusted and required source.
+*xleave*:::
+This option enables the interleaved mode of NTP. It enables the server to
+respond with more accurate transmit timestamps (e.g. kernel or hardware
+timestamps), which cannot be contained in the transmitted packet itself and
+need to refer to a previous packet instead. This can significantly improve the
+accuracy and stability of the measurements.
++
+The interleaved mode is compatible with servers that support only the basic
+mode. Note that even
+servers that support the interleaved mode might respond in the basic mode as
+the interleaved mode requires the servers to keep some state for each client
+and the state might be dropped when there are too many clients (e.g.
+<<clientloglimit,*clientloglimit*>> is too small), or it might be overwritten
+by other clients that have the same IP address (e.g. computers behind NAT or
+someone sending requests with a spoofed source address).
++
+The *xleave* option can be combined with the *presend* option in order to
+shorten the interval in which the server has to keep the state to be able to
+respond in the interleaved mode.
+*polltarget* _target_:::
+Target number of measurements to use for the regression algorithm which
+*chronyd* will try to maintain by adjusting the polling interval between
+*minpoll* and *maxpoll*. A higher target makes *chronyd* prefer shorter polling
+intervals. The default is 8 and a useful range is from 6 to 60.
+*port* _port_:::
+This option allows the UDP port on which the server understands NTP requests to
+be specified. For normal servers this option should not be required (the
+default is 123, the standard NTP port).
+*ntsport* _port_:::
+This option specifies the TCP port on which the server is listening for NTS-KE
+connections when the *nts* option is enabled. The default is 4460.
+*presend* _poll_:::
+If the timing measurements being made by *chronyd* are the only network data
+passing between two computers, you might find that some measurements are badly
+skewed due to either the client or the server having to do an ARP lookup on the
+other party prior to transmitting a packet. This is more of a problem with long
+sampling intervals, which might be similar in duration to the lifetime of entries
+in the ARP caches of the machines.
++
+In order to avoid this problem, the *presend* option can be used. It takes a
+single integer argument, which is the smallest polling interval for which an
+extra pair of NTP packets will be exchanged between the client and the server
+prior to the actual measurement. For example, with the following option
+included in a *server* directive:
++
+----
+presend 9
+----
++
+when the polling interval is 512 seconds or more, an extra NTP client packet
+will be sent to the server a short time (2 seconds) before making the actual
+measurement.
++
+If the *presend* option is used together with the *xleave* option, *chronyd*
+will send two extra packets instead of one.
+*minstratum* _stratum_:::
+When the synchronisation source is selected from available sources, sources
+with lower stratum are normally slightly preferred. This option can be used to
+increase stratum of the source to the specified minimum, so *chronyd* will
+avoid selecting that source. This is useful with low-stratum sources that are
+known to be unreliable or inaccurate and which should be used only when other
+sources are unreachable.
+*version* _version_:::
+This option sets the NTP version of packets sent to the server. This can be
+useful when the server runs an old NTP implementation that does not respond to
+requests using a newer version. The default version depends on other options.
+If the *extfield* or *xleave* option is used, the default version is 4. If
+those options are not used and the *key* option specifies a key using a hash
+function with output size longer than 160 bits (e.g. SHA256), the default
+version is 3 for compatibility with older *chronyd* servers. In other cases,
+the default version is 4.
+*copy*:::
+This option specifies that the server and client are closely related, their
+configuration does not allow a synchronisation loop to form between them, and
+the client is allowed to assume the reference ID and stratum of the server.
+This is useful when multiple instances of `chronyd` are running on one computer
+(e.g. for security or performance reasons), one primarily operating as a client
+to synchronise the system clock and other instances started with the *-x*
+option to operate as NTP servers for other computers with their NTP clocks
+synchronised to the first instance.
+*extfield* _type_:::
+This option enables an NTPv4 extension field specified by its type as a
+hexadecimal number. It will be included in requests sent to the server and
+processed in received responses if the server supports it. Note that some
+server implementations do not respond to requests containing an unknown
+extension field (*chronyd* as a server responded to such requests since
+version 2.0).
++
+This option can be used multiple times to enable multiple extension fields.
++
+The following extension fields are supported:
++
+_F323_::::
+An experimental extension field to enable several improvements that were
+proposed for the next version of the NTP protocol (NTPv5). The field contains
+root delay and dispersion in higher resolution and a monotonic receive
+timestamp, which enables a frequency transfer between the server and client to
+significantly improve stability of the synchronisation. This field should be
+enabled only for servers known to be running *chronyd* version 4.2 or later.
+_F324_::::
+An experimental extension field to enable the use of the Precision Time
+Protocol (PTP) correction field in NTP-over-PTP messages updated by one-step
+end-to-end transparent clocks in network switches and routers to significantly
+improve accuracy and stability of the synchronisation. NTP-over-PTP can be
+enabled by the <<ptpport,*ptpport*>> directive and setting the *port* option to
+the PTP port. The corrections are applied only to NTP measurements with HW
+timestamps (enabled by the <<hwtimestamp,*hwtimestamp*>> directive). This
+field should be enabled only for servers known to be running *chronyd* version
+4.5 or later.
+{blank}:::
+
+[[pool]]*pool* _name_ [_option_]...::
+The syntax of this directive is similar to that for the <<server,*server*>>
+directive, except that it is used to specify a pool of NTP servers rather than
+a single NTP server. The pool name is expected to resolve to multiple addresses
+which might change over time.
++
+This directive can be used multiple times to specify multiple pools.
++
+All options valid in the <<server,*server*>> directive can be used in this
+directive too. There is one option specific to the *pool* directive:
++
+*maxsources* _sources_:::
+This option sets the desired number of sources to be used from the pool.
+*chronyd* will repeatedly try to resolve the name until it gets this number of
+sources responding to requests. The default value is 4 and the maximum value is
+16.
++
+An example of the *pool* directive is
++
+----
+pool pool.ntp.org iburst maxsources 3
+----
+
+[[peer]]*peer* _hostname_ [_option_]...::
+The syntax of this directive is identical to that for the <<server,*server*>>
+directive, except that it specifies a symmetric association with an NTP peer
+instead of a client/server association with an NTP server. A single symmetric
+association allows the peers to be both servers and clients to each other. This
+is mainly useful when the NTP implementation of the peer (e.g. *ntpd*) supports
+ephemeral symmetric associations and does not need to be configured with an
+address of this host. *chronyd* does not support ephemeral associations.
++
+This directive can be used multiple times to specify multiple peers.
++
+The following options of the *server* directive do not work in the *peer*
+directive: *iburst*, *burst*, *nts*, *presend*, *copy*.
++
+When using the *xleave* option, both peers must support and have enabled the
+interleaved mode, otherwise the synchronisation will work in one direction
+only.
+When a key is specified by the *key* option to enable authentication, both
+peers must use the same key and the same key number.
++
+Note that the symmetric mode is less secure than the client/server mode. A
+denial-of-service attack is possible on unauthenticated symmetric associations,
+i.e. when the peer was specified without the *key* option. An attacker who does
+not see network traffic between two hosts, but knows that they are peering with
+each other, can periodically send them unauthenticated packets with spoofed
+source addresses in order to disrupt their NTP state and prevent them from
+synchronising to each other. When the association is authenticated, an attacker
+who does see the network traffic, but cannot prevent the packets from reaching
+the other host, can still disrupt the state by replaying old packets. The
+attacker has effectively the same power as a man-in-the-middle attacker. A
+partial protection against this attack is implemented in *chronyd*, which can
+protect the peers if they are using the same polling interval and they never
+sent an authenticated packet with a timestamp from future, but it should not be
+relied on as it is difficult to ensure the conditions are met. If two hosts
+should be able to synchronise to each other in both directions, it is
+recommended to use two separate client/server associations (specified by the
+<<server,*server*>> directive on both hosts) instead.
+
+[[initstepslew]]*initstepslew* _step-threshold_ [_hostname_]...::
+(This directive is deprecated in favour of the <<makestep,*makestep*>>
+directive.)
++
+The purpose of the *initstepslew* directive is to allow *chronyd* to make a
+rapid measurement of the system clock error at boot time, and to correct the
+system clock by stepping before normal operation begins. Since this would
+normally be performed only at an appropriate point in the system boot sequence,
+no other software should be adversely affected by the step.
++
+If the correction required is less than a specified threshold, a slew is used
+instead. This makes it safer to restart *chronyd* whilst the system is in
+normal operation.
++
+The *initstepslew* directive takes a threshold and a list of NTP servers as
+arguments. Each of the servers is rapidly polled several times, and a majority
+voting mechanism used to find the most likely range of system clock error that
+is present. A step or slew is applied to the system clock to correct this
+error. *chronyd* then enters its normal operating mode.
++
+An example of the use of the directive is:
++
+----
+initstepslew 30 ntp1.example.net ntp2.example.net ntp3.example.net
+----
++
+where 3 NTP servers are used to make the measurement. The _30_ indicates that
+if the system's error is found to be 30 seconds or less, a slew will be used to
+correct it; if the error is above 30 seconds, a step will be used.
++
+The *initstepslew* directive can also be used in an isolated LAN environment,
+where the clocks are set manually. The most stable computer is chosen as the
+primary server and the other computers are its clients. If each of the clients
+is configured with the <<local,*local*>> directive, the server can be set up
+with an *initstepslew* directive which references some or all of the clients.
+Then, if the server machine has to be rebooted, the clients can be relied on to
+act analogously to a flywheel and preserve the time for a short period while
+the server completes its reboot.
++
+The *initstepslew* directive is functionally similar to a combination of the
+<<makestep,*makestep*>> and <<server,*server*>> directives with the *iburst*
+option. The main difference is that the *initstepslew* servers are used only
+before normal operation begins and that the foreground *chronyd* process waits
+for *initstepslew* to finish before exiting. This prevent programs started in
+the boot sequence after *chronyd* from reading the clock before it has been
+stepped. With the *makestep* directive, the
+<<chronyc.adoc#waitsync,*waitsync*>> command of *chronyc* can be used instead.
+
+[[refclock]]*refclock* _driver_ _parameter_[:__option__]... [_option_]...::
+The *refclock* directive specifies a hardware reference clock to be used as a
+time source. It has two mandatory parameters, a driver name and a
+driver-specific parameter. The two parameters are followed by zero or more
+refclock options. Some drivers have special options, which can be appended to
+the driver-specific parameter using the *:* character.
++
+This directive can be used multiple times to specify multiple reference clocks.
++
+There are four drivers included in *chronyd*:
++
+*PPS*:::
+Driver for the kernel PPS (pulse per second) API. The parameter is the path to
+the PPS device (typically _/dev/pps?_). As PPS refclocks do not supply full
+time, another time source (e.g. NTP server or non-PPS refclock) is needed to
+complete samples from the PPS refclock. An alternative is to enable the
+<<local,*local*>> directive to allow synchronisation with some unknown but
+constant offset. The driver supports the following option:
++
+*clear*::::
+By default, the PPS refclock uses assert events (rising edge) for
+synchronisation. With this option, it will use clear events (falling edge)
+instead.
++
+{blank}:::
+Examples:
++
+----
+refclock PPS /dev/pps0 lock NMEA refid GPS1
+refclock SOCK /var/run/chrony.clk.ttyS0.sock offset 0.5 delay 0.2 refid NMEA noselect
+refclock PPS /dev/pps1:clear refid GPS2
+----
++
+*SOCK*:::
+Unix domain socket driver. This driver uses a datagram socket to receive
+samples from another application running on the system. The parameter is the
+path to the socket, which *chronyd* will create on start. The format of the
+messages is described in the _refclock_sock.c_ file in the chrony source code.
++
+An application which supports the SOCK protocol is the *gpsd* daemon. It can
+provide accurate measurements using the receiver's PPS signal, and since
+version 3.25 also (much less accurate) measurements based on the timing of
+serial data (e.g. NMEA), which can be useful when the receiver does not provide
+a PPS signal, or it cannot be connected to the computer. The paths where *gpsd*
+expects the sockets to be created by *chronyd* are described in the *gpsd(8)*
+man page. Note that *gpsd* needs to be started after *chronyd* in order to
+connect to the socket.
++
+Examples:
++
+----
+refclock SOCK /var/run/chrony.ttyS0.sock refid GPS1 poll 2 filter 4
+refclock SOCK /var/run/chrony.clk.ttyUSB0.sock refid GPS2 offset 0.2 delay 0.1
+----
++
+*SHM*:::
+NTP shared memory driver. This driver implements the protocol of the *ntpd*
+driver type 28. It is functionally similar to the SOCK driver, but uses a
+shared memory segment instead of a socket. The parameter is the unit number,
+typically a small number like 0, 1, 2, or 3, from which is derived the key of
+the memory segment as 0x4e545030 + unit.
++
+The driver supports the following option:
++
+*perm*=_mode_::::
+This option specifies the permissions of the shared memory segment created by
+*chronyd*. They are specified as a numeric mode. The default value is 0600
+(read-write access for owner only).
+{blank}:::
++
+Unlike with the SOCK driver, there is no prescribed order of starting *chronyd*
+and the program providing measurements. Both are expected to create the memory
+segment if it does not exist. *chronyd* will attach to an existing segment even
+if it has a different owner than root or different permissions than the
+permissions specified by the *perm* option. The segment needs to be created
+before untrusted applications or users can execute code to prevent an attacker
+from feeding *chronyd* with false measurements. The owner and permissions of
+the segment can be verified with the *ipcs -m* command. For this reason, the
+SHM driver is deprecated in favor of SOCK.
++
+Examples:
++
+----
+refclock SHM 0 poll 3 refid GPS1
+refclock SHM 1:perm=0644 refid GPS2
+----
++
+*PHC*:::
+PTP hardware clock (PHC) driver. The parameter is the path to the device of
+the PTP clock which should be used as a time source. If the clock is kept in
+TAI instead of UTC (e.g. it is synchronised by a PTP daemon), the current
+UTC-TAI offset needs to be specified by the *offset* option. Alternatively, the
+*pps* refclock option can be enabled to treat the PHC as a PPS refclock, using
+only the sub-second offset for synchronisation. The driver supports the
+following options:
++
+*nocrossts*::::
+This option disables use of precise cross timestamping.
+*extpps*::::
+This option enables a PPS mode in which the PTP clock is timestamping pulses
+of an external PPS signal connected to the clock. The clock does not need to be
+synchronised, but another time source is needed to complete the PPS samples.
+Note that some PTP clocks cannot be configured to timestamp only assert or
+clear events, and it is necessary to use the *width* option to filter wrong
+PPS samples.
+*pin*=_index_::::
+This option specifies the index of the pin which should be enabled for the
+PPS timestamping. If the PHC does not have configurable pins (i.e. the channel
+function is fixed), the index needs to be set to -1 to disable the pin
+configuration. The default value is 0.
+*channel*=_index_::::
+This option specifies the index of the channel for the PPS mode. The default
+value is 0.
+*clear*::::
+This option enables timestamping of clear events (falling edge) instead of
+assert events (rising edge) in the PPS mode. This may not work with some
+clocks.
+{blank}:::
++
+Examples:
++
+----
+refclock PHC /dev/ptp0 poll 0 dpoll -2 offset -37
+refclock PHC /dev/ptp1:nocrossts poll 3 pps
+refclock PHC /dev/ptp2:extpps:pin=1 width 0.2 poll 2
+----
++
+{blank}::
+The *refclock* directive supports the following options:
++
+*poll* _poll_:::
+Timestamps produced by refclock drivers are not used immediately, but they are
+stored and processed by a median filter in the polling interval specified by
+this option. This is defined as a power of 2 and can be negative to specify a
+sub-second interval. The default is 4 (16 seconds). A shorter interval allows
+*chronyd* to react faster to changes in the frequency of the system clock, but
+it might have a negative effect on its accuracy if the samples have a lot of
+jitter.
+*dpoll* _dpoll_:::
+Some drivers do not listen for external events and try to produce samples in
+their own polling interval. This is defined as a power of 2 and can be negative
+to specify a sub-second interval. The default is 0 (1 second).
+*refid* _refid_:::
+This option is used to specify the reference ID of the refclock, as up to four
+ASCII characters. The default reference ID is composed from the first three
+characters of the driver name and the number of the refclock. Each refclock
+must have a unique reference ID.
+*lock* _refid_:::
+This option can be used to lock a PPS refclock to another refclock, which is
+specified by its reference ID. In this mode received PPS samples are paired
+directly with raw samples from the specified refclock.
+*rate* _rate_:::
+This option sets the rate of the pulses in the PPS signal (in Hz). This option
+controls how the pulses will be completed with real time. To actually receive
+more than one pulse per second, a negative *dpoll* has to be specified (-3 for
+a 5Hz signal). The default is 1.
+*maxlockage* _pulses_:::
+This option specifies in number of pulses how old can be samples from the
+refclock specified by the *lock* option to be paired with the pulses.
+Increasing this value is useful when the samples are produced at a lower rate
+than the pulses. The default is 2.
+*width* _width_:::
+This option specifies the width of the pulses (in seconds). It is used to
+filter PPS samples when the driver provides samples for both rising and falling
+edges. Note that it reduces the maximum allowed error of the time source which
+completes the PPS samples. If the duty cycle is configurable, 50% should be
+preferred in order to maximise the allowed error.
+*pps*:::
+This options forces *chronyd* to treat any refclock (e.g. SHM or PHC) as a PPS
+refclock. This can be useful when the refclock provides time with a variable
+offset of a whole number of seconds (e.g. it uses TAI instead of UTC). Another
+time source is needed to complete samples from the refclock.
+*offset* _offset_:::
+This option can be used to compensate for a constant error. The specified
+offset (in seconds) is applied to all samples produced by the reference clock.
+The default is 0.0.
+*delay* _delay_:::
+This option sets the NTP delay of the source (in seconds). Half of this value
+is included in the maximum assumed error which is used in the source selection
+algorithm. Increasing the delay is useful to avoid having no majority in the
+source selection or to make it prefer other sources. The default is 1e-9 (1
+nanosecond).
+*stratum* _stratum_:::
+This option sets the NTP stratum of the refclock. This can be useful when the
+refclock provides time with a stratum other than 0. The default is 0.
+*precision* _precision_:::
+This option sets the precision of the reference clock (in seconds). The default
+value is the estimated precision of the system clock.
+*maxdispersion* _dispersion_:::
+Maximum allowed dispersion for filtered samples (in seconds). Samples with
+larger estimated dispersion are ignored. By default, this limit is disabled.
+*filter* _samples_:::
+This option sets the length of the median filter which is used to reduce the
+noise in the measurements. With each poll about 40 percent of the stored
+samples are discarded and one final sample is calculated as an average of the
+remaining samples. If the length is 4 or more, at least 4 samples have to be
+collected between polls. For lengths below 4, the filter has to be full. The
+default is 64. With drivers that perform their own polling (PPS, PHC, SHM), the
+maximum value is adjusted to the number of driver polls per source poll, i.e.
+2^(_poll_ - _dpoll_).
+*prefer*:::
+Prefer this source over sources without the prefer option.
+*noselect*:::
+Never select this source. This is useful for monitoring or with sources which
+are not very accurate, but are locked with a PPS refclock.
+*trust*:::
+Assume time from this source is always true. It can be rejected as a
+falseticker in the source selection only if another source with this option
+does not agree with it.
+*require*:::
+Require that at least one of the sources specified with this option is
+selectable (i.e. recently reachable and not a falseticker) before updating the
+clock. Together with the *trust* option this can be useful to allow a trusted,
+but not very precise, reference clock to be safely combined with
+unauthenticated NTP sources in order to improve the accuracy of the clock. They
+can be selected and used for synchronisation only if they agree with the
+trusted and required source.
+*tai*:::
+This option indicates that the reference clock keeps time in TAI instead of UTC
+and that *chronyd* should correct its offset by the current TAI-UTC offset. The
+<<leapsectz,*leapsectz*>> directive must be used with this option and the
+database must be kept up to date in order for this correction to work as
+expected. This option does not make sense with PPS refclocks.
+*local*:::
+This option specifies that the reference clock is an unsynchronised clock which
+is more stable than the system clock (e.g. TCXO, OCXO, or atomic clock) and
+it should be used as a local standard to stabilise the system clock. The
+refclock will bypass the source selection. There should be at most one refclock
+specified with this option and it should have the shortest polling interval
+among all configured sources.
+*minsamples* _samples_:::
+Set the minimum number of samples kept for this source. This overrides the
+<<minsamples,*minsamples*>> directive.
+*maxsamples* _samples_:::
+Set the maximum number of samples kept for this source. This overrides the
+<<maxsamples,*maxsamples*>> directive.
+
+[[manual]]*manual*::
+The *manual* directive enables support at run-time for the
+<<chronyc.adoc#settime,*settime*>> command in *chronyc*. If no *manual*
+directive is included, any attempt to use the *settime* command in *chronyc*
+will be met with an error message.
++
+Note that the *settime* command can be enabled at run-time using
+the <<chronyc.adoc#manual,*manual*>> command in *chronyc*. (The idea of the two
+commands is that the *manual* command controls the manual clock driver's
+behaviour, whereas the *settime* command allows samples of manually entered
+time to be provided.)
+
+[[acquisitionport]]*acquisitionport* _port_::
+By default, *chronyd* as an NTP client opens a new socket for each request with
+the source port chosen randomly by the operating system. The *acquisitionport*
+directive can be used to specify the source port and use only one socket (per
+IPv4 or IPv6 address family) for all configured servers. This can be useful for
+getting through some firewalls. It should not be used if not necessary as there
+is a small impact on security of the client. If set to 0, the source port of
+the permanent socket will be chosen randomly by the operating system.
++
+It can be set to the same port as is used by the NTP server (which can be
+configured with the <<port,*port*>> directive) to use only one socket for all
+NTP packets.
++
+An example of the *acquisitionport* directive is:
++
+----
+acquisitionport 1123
+----
++
+This would change the source port used for client requests to UDP port 1123.
+You could then persuade the firewall administrator to open that port.
+
+[[bindacqaddress]]*bindacqaddress* _address_::
+The *bindacqaddress* directive specifies a local IP address to which
+*chronyd* will bind its NTP and NTS-KE client sockets. The syntax is similar to
+the <<bindaddress,*bindaddress*>> and <<bindcmdaddress,*bindcmdaddress*>>
+directives.
++
+For each of the IPv4 and IPv6 protocols, only one *bindacqaddress* directive
+can be specified.
+
+[[bindacqdevice]]*bindacqdevice* _interface_::
+The *bindacqdevice* directive binds the client sockets to a network device
+specified by the interface name. This can be useful when the local address is
+dynamic, or to enable an NTP source specified with a link-local IPv6 address.
+This directive can specify only one interface and it is supported on Linux
+only.
++
+An example of the directive is:
++
+----
+bindacqdevice eth0
+----
+
+[[dscp]]*dscp* _point_::
+The *dscp* directive sets the Differentiated Services Code Point (DSCP) in
+transmitted NTP packets to the specified value. It can improve stability of NTP
+measurements in local networks where switches or routers are configured to
+prioritise forwarding of packets with specific DSCP values. The default value
+is 0 and the maximum value is 63.
++
+An example of the directive (setting the Expedited Forwarding class) is:
++
+----
+dscp 46
+----
+
+[[dumpdir]]*dumpdir* _directory_::
+To compute the rate of gain or loss of time, *chronyd* has to store a
+measurement history for each of the time sources it uses.
++
+All supported systems, with the exception of macOS 10.12 and earlier, have
+operating system support for setting the rate of gain or loss to compensate for
+known errors.
+(On macOS 10.12 and earlier, *chronyd* must simulate such a capability by
+periodically slewing the system clock forwards or backwards by a suitable amount
+to compensate for the error built up since the previous slew.)
++
+For such systems, it is possible to save the measurement history across
+restarts of *chronyd* (assuming no changes are made to the system clock
+behaviour whilst it is not running). The *dumpdir* directive defines the
+directory where the measurement histories are saved when *chronyd* exits,
+or the <<chronyc.adoc#dump,*dump*>> command in *chronyc* is issued.
++
+If the directory does not exist, it will be created automatically.
++
+The *-r* option of *chronyd* enables loading of the dump files on start. All
+dump files found in the directory will be removed after start, even if the *-r*
+option is not present.
++
+An example of the directive is:
++
+----
+dumpdir @CHRONYRUNDIR@
+----
++
+A source whose IP address is _1.2.3.4_ would have its measurement history saved
+in the file _@CHRONYRUNDIR@/1.2.3.4.dat_. History of reference clocks is saved
+to files named by their reference ID in form of _refid:XXXXXXXX.dat_.
+
+[[maxsamples]]*maxsamples* _samples_::
+The *maxsamples* directive sets the default maximum number of samples that
+*chronyd* should keep for each source. This setting can be overridden for
+individual sources in the <<server,*server*>> and <<refclock,*refclock*>>
+directives. The default value is 0, which disables the configurable limit. The
+useful range is 4 to 64.
++
+As a special case, setting *maxsamples* to 1 disables frequency tracking in
+order to make the sources immediately selectable with only one sample. This can
+be useful when *chronyd* is started with the *-q* or *-Q* option.
+
+[[minsamples]]*minsamples* _samples_::
+The *minsamples* directive sets the default minimum number of samples that
+*chronyd* should keep for each source. This setting can be overridden for
+individual sources in the <<server,*server*>> and <<refclock,*refclock*>>
+directives. The default value is 6. The useful range is 4 to 64.
++
+Forcing *chronyd* to keep more samples than it would normally keep reduces
+noise in the estimated frequency and offset, but slows down the response to
+changes in the frequency and offset of the clock. The offsets in the
+<<chronyc.adoc#tracking,*tracking*>> and
+<<chronyc.adoc#sourcestats,*sourcestats*>> reports (and the _tracking.log_ and
+_statistics.log_ files) may be smaller than the actual offsets.
+
+[[ntsdumpdir1]]*ntsdumpdir* _directory_::
+This directive specifies a directory for the client to save NTS cookies it
+received from the server in order to avoid making an NTS-KE request when
+*chronyd* is started again. The cookies are saved separately for each NTP
+source in files named by the IP address of the NTS-KE server (e.g.
+_1.2.3.4.nts_). By default, the client does not save the cookies.
++
+If the directory does not exist, it will be created automatically.
++
+An example of the directive is:
++
+----
+ntsdumpdir @CHRONYVARDIR@
+----
++
+This directory is used also by the <<ntsdumpdir2,NTS server>> to save keys.
+
+[[ntsrefresh]]*ntsrefresh* _interval_::
+This directive specifies the maximum interval between NTS-KE handshakes (in
+seconds) in order to refresh the keys authenticating NTP packets. The default
+value is 2419200 (4 weeks) and the maximum value is 2^31-1 (68 years).
++
+The interval must be longer than polling intervals of all configured NTP
+sources using NTS, otherwise the source with a longer polling interval will
+refresh the keys on each poll and no NTP packets will be exchanged.
+
+[[ntstrustedcerts]]*ntstrustedcerts* [_set-ID_] _file_|_directory_::
+This directive specifies a file or directory containing trusted certificates
+(in the PEM format) which are needed to verify certificates of NTS-KE servers,
+e.g. certificates of trusted certificate authorities (CA) or self-signed
+certificates of the servers.
++
+The optional _set-ID_ argument is a number in the range 0 through 2^32-1, which
+selects the set of certificates where certificates from the specified file
+or directory are added. The default ID is 0, which is a set containing the
+system's default trusted CAs (unless the *nosystemcert* directive is present).
+All other sets are empty by default. A set of certificates can be selected for
+verification of an NTS server by the *certset* option in the *server* or *pool*
+directive.
++
+This directive can be used multiple times to specify one or more sets of
+trusted certificates, each containing certificates from one or more files
+and/or directories.
++
+It is not necessary to restart *chronyd* in order to reload the certificates if
+they change (e.g. after a renewal).
++
+An example is:
++
+----
+ntstrustedcerts /etc/pki/nts/ca1.example.net.crt
+ntstrustedcerts 1 /etc/pki/nts/ca2.example.net.crt
+ntstrustedcerts 1 /etc/pki/nts/ca3.example.net.crt
+ntstrustedcerts 2 /etc/pki/nts/ntp2.example.net.crt
+----
+
+[[nosystemcert]]*nosystemcert*::
+This directive disables the system's default trusted CAs. Only certificates
+specified by the *ntstrustedcerts* directive will be trusted.
+
+[[nocerttimecheck]]*nocerttimecheck* _limit_::
+This directive disables the checks of the activation and expiration times of
+certificates for the specified number of clock updates. It allows the NTS
+authentication mechanism to be used on computers which start with wrong time
+(e.g. due to not having an RTC or backup battery). Disabling the time checks
+has important security implications and should be used only as a last resort,
+preferably with a minimal number of trusted certificates. The default value is
+0, which means the time checks are always enabled.
++
+An example of the directive is:
++
+----
+nocerttimecheck 1
+----
++
+This would disable the time checks until the clock is updated for the first
+time, assuming the first update corrects the clock and later checks can work
+with correct time.
+
+[[refresh]]*refresh* _interval_::
+This directive specifies the interval (in seconds) between refreshing IP
+addresses of NTP sources specified by hostname. If the hostname no longer
+resolves to the currently used address, it will be replaced with one of the new
+addresses to avoid using a server which is no longer intended for service, even
+if it is still responding correctly and would not be replaced as unreachable.
+Only one source is refreshed at a time. The default value is 1209600 (2 weeks)
+and the maximum value is 2^31-1 (68 years). A value of 0 disables the periodic
+refreshment.
++
+The <<chronyc.adoc#refresh,*refresh*>> command can be used to refresh all
+sources immediately.
+
+=== Source selection
+
+[[authselectmode]]*authselectmode* _mode_::
+NTP sources can be specified with the *key* or *nts* option to enable
+authentication to limit the impact of man-in-the-middle attacks. The
+attackers can drop or delay NTP packets (up to the *maxdelay* and
+<<maxdistance,*maxdistance*>> limits), but they cannot modify the timestamps
+contained in the packets. The attack can cause only a limited slew or step, and
+also cause the clock to run faster or slower than real time (up to double of
+the <<maxdrift,*maxdrift*>> limit).
++
+When authentication is enabled for an NTP source, it is important to disable
+unauthenticated NTP sources which could be exploited in the attack, e.g. if
+they are not reachable only over a trusted network. Alternatively, the source
+selection can be configured with the *require* and *trust* options to
+synchronise to the unauthenticated sources only if they agree with the
+authenticated sources and might have a positive impact on the accuracy of the
+clock. Note that in this case the impact of the attack is higher. The attackers
+cannot cause an arbitrarily large step or slew, but they have more control over
+the frequency of the clock and can cause *chronyd* to report false information,
+e.g. a significantly smaller root delay and dispersion.
++
+This directive determines the default selection options for authenticated and
+unauthenticated sources in order to simplify the configuration with the
+configuration file and *chronyc* commands. It sets a policy for authentication.
++
+Sources specified with the *noselect* option are ignored (not counted as either
+authenticated or unauthenticated), and they always have only the selection
+options specified in the configuration.
++
+There are four modes:
++
+*require*:::
+Authentication is strictly required for NTP sources in this mode. If any
+unauthenticated NTP sources are specified, they will automatically get the
+*noselect* option to prevent them from being selected for synchronisation.
+*prefer*:::
+In this mode, authentication is optional and preferred. If it is enabled for at
+least one NTP source, all unauthenticated NTP sources will get the *noselect*
+option.
+*mix*:::
+In this mode, authentication is optional and synchronisation to a mix of
+authenticated and unauthenticated NTP sources is allowed. If both authenticated
+and unauthenticated NTP sources are specified, all authenticated NTP sources
+and reference clocks will get the *require* and *trust* options to prevent
+synchronisation to unauthenticated NTP sources if they do not agree with a
+majority of the authenticated sources and reference clocks. This is the default
+mode.
+*ignore*:::
+In this mode, authentication is ignored in the source selection. All sources
+will have only the selection options that were specified in the configuration
+file, or *chronyc* command. This was the behaviour of *chronyd* in versions
+before 4.0.
+{blank}::
++
+As an example, the following configuration using the default *mix* mode:
++
+----
+server ntp1.example.net nts
+server ntp2.example.net nts
+server ntp3.example.net
+refclock SOCK /var/run/chrony.ttyS0.sock
+----
++
+is equivalent to the following configuration using the *ignore* mode:
++
+----
+authselectmode ignore
+server ntp1.example.net nts require trust
+server ntp2.example.net nts require trust
+server ntp3.example.net
+refclock /var/run/chrony.ttyS0.sock require trust
+----
+
+[[combinelimit]]*combinelimit* _limit_::
+When *chronyd* has multiple sources available for synchronisation, it has to
+select one source as the synchronisation source. The measured offsets and
+frequencies of the system clock relative to the other sources, however, can be
+combined with the selected source to improve the accuracy of the system clock.
++
+The *combinelimit* directive limits which sources are included in the combining
+algorithm. Their synchronisation distance has to be shorter than the distance
+of the selected source multiplied by the value of the limit. Also, their
+measured frequencies have to be close to the frequency of the selected source.
+If the selected source was specified with the *prefer* option, it can be
+combined only with other sources specified with this option.
++
+By default, the limit is 3. Setting the limit to 0 effectively disables the
+source combining algorithm and only the selected source will be used to control
+the system clock.
+
+[[maxdistance]]*maxdistance* _distance_::
+The *maxdistance* directive sets the maximum root distance of a source to be
+acceptable for synchronisation of the clock. Sources that have a distance
+larger than the specified distance will be rejected. The distance estimates the
+maximum error of the source. It includes the root dispersion and half of the
+root delay (round-trip time) accumulated on the path to the primary source.
++
+By default, the maximum root distance is 3 seconds.
++
+Setting *maxdistance* to a larger value can be useful to allow synchronisation
+with a server that only has a very infrequent connection to its sources and can
+accumulate a large dispersion between updates of its clock.
+
+[[maxjitter]]*maxjitter* _jitter_::
+The *maxjitter* directive sets the maximum allowed jitter of the sources to not
+be rejected by the source selection algorithm. This prevents synchronisation
+with sources that have a small root distance, but their time is too variable.
++
+By default, the maximum jitter is 1 second.
+
+[[minsources]]*minsources* _sources_::
+The *minsources* directive sets the minimum number of sources that need to be
+considered as selectable in the source selection algorithm before the local
+clock is updated. The default value is 1.
++
+Setting this option to a larger number can be used to improve the reliability.
+More sources will have to agree with each other and the clock will not be
+updated when only one source (which could be serving incorrect time) is
+reachable.
+
+[[reselectdist]]*reselectdist* _distance_::
+When *chronyd* selects a synchronisation source from available sources, it
+will prefer the one with the shortest synchronisation distance. However, to
+avoid frequent reselecting when there are sources with similar distance, a
+fixed distance is added to the distance for sources that are currently not
+selected. This can be set with the *reselectdist* directive. By default, the
+distance is 100 microseconds.
+
+[[stratumweight]]*stratumweight* _distance_::
+The *stratumweight* directive sets how much distance should be added per
+stratum to the synchronisation distance when *chronyd* selects the
+synchronisation source from available sources.
++
+By default, the weight is 0.001 seconds. This means that the stratum of the sources
+in the selection process matters only when the differences between the
+distances are in milliseconds.
+
+=== System clock
+
+[[clockprecision]]*clockprecision* _precision_::
+The *clockprecision* directive specifies the precision of the system clock (in
+seconds). It is used by *chronyd* to estimate the minimum noise in NTP
+measurements and randomise low-order bits of timestamps in NTP responses. By
+default, the precision is measured on start as the minimum time to read the
+clock.
++
+The measured value works well in most cases. However, it generally
+overestimates the precision and it can be sensitive to the CPU speed, which can
+change over time to save power. In some cases with a high-precision clocksource
+(e.g. the Time Stamp Counter of the CPU) and hardware timestamping, setting the
+precision on the server to a smaller value can improve stability of clients'
+NTP measurements. The server's precision is reported on clients by the
+<<chronyc.adoc#ntpdata,*ntpdata*>> command.
++
+An example setting the precision to 8 nanoseconds is:
++
+----
+clockprecision 8e-9
+----
+
+[[corrtimeratio]]*corrtimeratio* _ratio_::
+When *chronyd* is slewing the system clock to correct an offset, the rate at
+which it is slewing adds to the frequency error of the clock. On all supported
+systems, with the exception of macOS 12 and earlier, this rate can be
+controlled.
++
+The *corrtimeratio* directive sets the ratio between the duration in which the
+clock is slewed for an average correction according to the source history and
+the interval in which the corrections are done (usually the NTP polling
+interval). Corrections larger than the average take less time and smaller
+corrections take more time, the amount of the correction and the correction
+time are inversely proportional.
++
+Increasing *corrtimeratio* improves the overall frequency error of the system
+clock, but increases the overall time error as the corrections take longer.
++
+By default, the ratio is set to 3, the time accuracy of the clock is preferred
+over its frequency accuracy.
++
+The maximum allowed slew rate can be set by the <<maxslewrate,*maxslewrate*>>
+directive. The current remaining correction is shown in the
+<<chronyc.adoc#tracking,*tracking*>> report as the *System time* value.
+
+[[driftfile]]*driftfile* _file_::
+One of the main activities of the *chronyd* program is to work out the rate at
+which the system clock gains or loses time relative to real time.
++
+Whenever *chronyd* computes a new value of the gain or loss rate, it is desirable
+to record it somewhere. This allows *chronyd* to begin compensating the system
+clock at that rate whenever it is restarted, even before it has had a chance to
+obtain an equally good estimate of the rate during the new run. (This process
+can take many minutes, at least.)
++
+The *driftfile* directive allows a file to be specified into which *chronyd*
+can store the rate information. Two parameters are recorded in the file. The
+first is the rate at which the system clock gains or loses time, expressed in
+parts per million, with gains positive. Therefore, a value of 100.0 indicates
+that when the system clock has advanced by a second, it has gained 100
+microseconds in reality (so the true time has only advanced by 999900
+microseconds). The second is an estimate of the error bound around the first
+value in which the true rate actually lies.
++
+An example of the driftfile directive is:
++
+----
+driftfile @CHRONYVARDIR@/drift
+----
+
+[[fallbackdrift]]*fallbackdrift* _min-interval_ _max-interval_::
+Fallback drifts are long-term averages of the system clock drift calculated
+over exponentially increasing intervals. They are used to avoid quickly
+drifting away from true time when the clock was not updated for a longer period
+of time and there was a short-term deviation in the drift before the updates
+stopped.
++
+The directive specifies the minimum and maximum interval since the last clock
+update to switch between fallback drifts. They are defined as a power of 2 (in
+seconds). The syntax is as follows:
++
+----
+fallbackdrift 16 19
+----
++
+In this example, the minimum interval is 16 (18 hours) and the maximum interval is
+19 (6 days). The system clock frequency will be set to the first fallback 18
+hours after last clock update, to the second after 36 hours, and so on. This
+might be a good setting to cover frequency changes due to daily and weekly
+temperature fluctuations. When the frequency is set to a fallback, the state of
+the clock will change to '`Not synchronised`'.
++
+By default (or if the specified maximum or minimum is 0), no fallbacks are used
+and the clock frequency changes only with new measurements from NTP sources,
+reference clocks, or manual input.
+
+[[leapsecmode]]*leapsecmode* _mode_::
+A leap second is an adjustment that is occasionally applied to UTC to keep it
+close to the mean solar time. When a leap second is inserted, the last day of
+June or December has an extra second 23:59:60.
++
+For computer clocks that is a problem. The Unix time is defined as number of
+seconds since 00:00:00 UTC on 1 January 1970 without leap seconds. The system
+clock cannot have time 23:59:60, every minute has 60 seconds and every day has
+86400 seconds by definition. The inserted leap second is skipped and the clock
+is suddenly ahead of UTC by one second. The *leapsecmode* directive selects how
+that error is corrected. There are four options:
++
+*system*:::
+When inserting a leap second, the kernel steps the system clock backwards by
+one second when the clock gets to 00:00:00 UTC. When deleting a leap second, it
+steps forward by one second when the clock gets to 23:59:59 UTC. This is the
+default mode when the system driver supports leap seconds (i.e. all supported
+systems with the exception of macOS 12 and earlier).
+*step*:::
+This is similar to the *system* mode, except the clock is stepped by
+*chronyd* instead of the kernel. It can be useful to avoid bugs in the kernel
+code that would be executed in the *system* mode. This is the default mode
+when the system driver does not support leap seconds.
+*slew*:::
+The clock is corrected by slewing started at 00:00:00 UTC when a leap second
+is inserted or 23:59:59 UTC when a leap second is deleted. This might be
+preferred over the *system* and *step* modes when applications running on the
+system are sensitive to jumps in the system time and it is acceptable that the
+clock will be off for a longer time. On Linux with the default
+<<maxslewrate,*maxslewrate*>> value the correction takes 12 seconds.
+*ignore*:::
+No correction is applied to the clock for the leap second. The clock will be
+corrected later in normal operation when new measurements are made and the
+estimated offset includes the one second error. This option is particularly
+useful when multiple *chronyd* instances are running on the system, one
+controlling the system clock and others started with the *-x* option, which
+should rely on the first instance to correct the system clock and ignore it for
+the correction of their own NTP clock running on top of the system clock.
+{blank}::
++
+When serving time to NTP clients that cannot be configured to correct their
+clocks for a leap second by slewing, or to clients that would correct at
+slightly different rates when it is necessary to keep them close together, the
+*slew* mode can be combined with the <<smoothtime,*smoothtime*>> directive to
+enable a server leap smear.
++
+When smearing a leap second, the leap status is suppressed on the server and
+the served time is corrected slowly by slewing instead of stepping. The clients
+do not need any special configuration as they do not know there is any leap
+second and they follow the server time which eventually brings them back to
+UTC. Care must be taken to ensure they use only NTP servers which smear the
+leap second in exactly the same way for synchronisation.
++
+This feature must be used carefully, because the server is intentionally not
+serving its best estimate of the true time.
++
+A recommended configuration to enable a server leap smear is:
++
+----
+leapsecmode slew
+maxslewrate 1000
+smoothtime 400 0.001024 leaponly
+----
++
+The first directive is necessary to disable the clock step which would reset
+the smoothing process. The second directive limits the slewing rate of the
+local clock to 1000 ppm, which improves the stability of the smoothing process
+when the local correction starts and ends. The third directive enables the
+server time smoothing process. It will start when the clock gets to 00:00:00
+UTC and it will take 62500 seconds (about 17.36 hours) to finish. The frequency
+offset will be changing by 0.001024 ppm per second and will reach a maximum of
+32 ppm in 31250 seconds. The *leaponly* option makes the duration of the leap
+smear constant and allows the clients to safely synchronise with multiple
+identically configured leap smearing servers.
++
+The duration of the leap smear can be calculated from the specified wander as
++
+----
+duration = sqrt(4 / wander)
+----
+
+[[leapsectz]]*leapsectz* _timezone_::
+This directive specifies a timezone in the system timezone database which
+*chronyd* can use to determine when will the next leap second occur and what is
+the current offset between TAI and UTC. It will periodically check if 23:59:59
+and 23:59:60 are valid times in the timezone. This normally works with the
+_right/UTC_ timezone.
++
+When a leap second is announced, the timezone needs to be updated at least 12
+hours before the leap second. It is not necessary to restart *chronyd*.
++
+This directive is useful with reference clocks and other time sources which do
+not announce leap seconds, or announce them too late for an NTP server to
+forward them to its own clients. Clients of leap smearing servers must not
+use this directive.
++
+It is also useful when the system clock is required to have correct TAI-UTC
+offset. Note that the offset is set only when leap seconds are handled by the
+kernel, i.e. <<leapsecmode,*leapsecmode*>> is set to *system*.
++
+The specified timezone is not used as an exclusive source of information about
+leap seconds. If a majority of time sources announce on the last day of June or
+December that a leap second should be inserted or deleted, it will be accepted
+even if it is not included in the timezone.
++
+An example of the directive is:
++
+----
+leapsectz right/UTC
+----
++
+The following shell command verifies that the timezone contains leap seconds
+and can be used with this directive:
++
+----
+$ TZ=right/UTC date -d 'Dec 31 2008 23:59:60'
+Wed Dec 31 23:59:60 UTC 2008
+----
+
+[[makestep]]*makestep* _threshold_ _limit_::
+Normally *chronyd* will cause the system to gradually correct any time offset,
+by slowing down or speeding up the clock as required. In certain situations,
+e.g. when *chronyd* is initially started, the system clock might be so far
+adrift that this slewing process would take a very long time to correct the
+system clock.
++
+This directive forces *chronyd* to step the system clock if the adjustment is
+larger than a threshold value, but only if there were no more clock updates
+since *chronyd* was started than the specified limit. A negative value disables
+the limit.
++
+On most systems it is desirable to step the system clock only on boot, before
+starting programs that rely on time advancing monotonically forwards.
++
+An example of the use of this directive is:
++
+----
+makestep 0.1 3
+----
++
+This would step the system clock if the adjustment is larger than 0.1 seconds, but
+only in the first three clock updates.
+
+[[maxchange]]*maxchange* _offset_ _start_ _ignore_::
+This directive sets the maximum offset to be accepted on a clock update. The
+offset is measured relative to the current estimate of the true time, which is
+different from the system time if a previous slew did not finish.
++
+The check is enabled after the specified number of clock updates to allow a
+large initial offset to be corrected on start. Offsets larger than the
+specified maximum will be ignored for the specified number of times. Another
+large offset will cause *chronyd* to give up and exit. A negative value
+can be used to disable the limit to ignore all large offsets. A syslog message
+will be generated when an offset is ignored or it causes the exit.
++
+An example of the use of this directive is:
++
+----
+maxchange 1000 1 2
+----
++
+After the first clock update, *chronyd* will check the offset on every clock
+update, it will ignore two adjustments larger than 1000 seconds and exit on
+another one.
+
+[[maxclockerror]]*maxclockerror* _error-in-ppm_::
+The *maxclockerror* directive sets the maximum assumed frequency error that the
+system clock can gain on its own between clock updates. It describes the
+stability of the clock.
++
+By default, the maximum error is 1 ppm.
++
+Typical values for _error-in-ppm_ might be 10 for a low quality clock and 0.1
+for a high quality clock using a temperature compensated crystal oscillator.
+
+[[maxdrift]]*maxdrift* _drift-in-ppm_::
+This directive specifies the maximum assumed drift (frequency error) of the
+system clock. It limits the frequency adjustment that *chronyd* is allowed to
+use to correct the measured drift. It is an additional limit to the maximum
+adjustment that can be set by the system driver (100000 ppm on Linux, 500 ppm
+on FreeBSD, NetBSD, and macOS 10.13+, 32500 ppm on illumos).
++
+By default, the maximum assumed drift is 500000 ppm, i.e. the adjustment is
+limited by the system driver rather than this directive.
+
+[[maxupdateskew]]*maxupdateskew* _skew-in-ppm_::
+One of *chronyd*'s tasks is to work out how fast or slow the computer's clock
+runs relative to its reference sources. In addition, it computes an estimate of
+the error bounds around the estimated value.
++
+If the range of error is too large, it probably indicates that the measurements
+have not settled down yet, and that the estimated gain or loss rate is not very
+reliable.
++
+The *maxupdateskew* directive sets the threshold for determining whether an
+estimate might be so unreliable that it should not be used. By default, the
+threshold is 1000 ppm.
++
+Typical values for _skew-in-ppm_ might be 100 for NTP sources polled over a
+wireless network, and 10 or smaller for sources on a local wired network.
++
+It should be noted that this is not the only means of protection against using
+unreliable estimates. At all times, *chronyd* keeps track of both the estimated
+gain or loss rate, and the error bound on the estimate. When a new estimate is
+generated following another measurement from one of the sources, a weighted
+combination algorithm is used to update the existing estimate. If it has
+significantly smaller error bounds than the new estimate, the existing estimate
+will dominate in the new combined value.
+
+[[maxslewrate]]*maxslewrate* _rate-in-ppm_::
+The *maxslewrate* directive sets the maximum rate at which *chronyd* is allowed
+to slew the time. It limits the slew rate controlled by the correction time
+ratio (which can be set by the <<corrtimeratio,*corrtimeratio*>> directive) and
+is effective only on systems where *chronyd* is able to control the rate (i.e.
+all supported systems with the exception of macOS 12 or earlier).
++
+For each system there is a maximum frequency offset of the clock that can be set
+by the driver. On Linux it is 100000 ppm, on FreeBSD, NetBSD and macOS 10.13+ it
+is 5000 ppm, and on illumos it is 32500 ppm. Also, due to a kernel limitation,
+setting *maxslewrate* on FreeBSD, NetBSD, macOS 10.13+ to a value between 500
+ppm and 5000 ppm will effectively set it to 500 ppm.
++
+By default, the maximum slew rate is set to 83333.333 ppm (one twelfth).
+
+[[tempcomp]]
+*tempcomp* _file_ _interval_ _T0_ _k0_ _k1_ _k2_::
+*tempcomp* _file_ _interval_ _points-file_::
+Normally, changes in the rate of drift of the system clock are caused mainly by
+changes in the temperature of the crystal oscillator on the motherboard.
++
+If there are temperature measurements available from a sensor close to the
+oscillator, the *tempcomp* directive can be used to compensate for the changes
+in the temperature and improve the stability and accuracy of the clock.
++
+The result depends on many factors, including the resolution of the sensor, the
+amount of noise in the measurements, the polling interval of the time source,
+the compensation update interval, how well the compensation is specified, and
+how close the sensor is to the oscillator. When it is working well, the
+frequency reported in the _tracking.log_ file is more stable and the maximum
+reached offset is smaller.
++
+There are two forms of the directive. The first one has six parameters: a path
+to the file containing the current temperature from the sensor (in text
+format), the compensation update interval (in seconds), and temperature
+coefficients _T0_, _k0_, _k1_, _k2_.
++
+The frequency compensation is calculated (in ppm) as
++
+----
+comp = k0 + (T - T0) * k1 + (T - T0)^2 * k2
+----
++
+The result has to be between -10 ppm and 10 ppm, otherwise the measurement is
+considered invalid and will be ignored. The _k0_ coefficient can be adjusted to
+keep the compensation in that range.
++
+An example of the use is:
++
+----
+tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 26000 0.0 0.000183 0.0
+----
++
+The measured temperature will be read from the file in the Linux sysfs
+filesystem every 30 seconds. When the temperature is 26000 (26 degrees
+Celsius), the frequency correction will be zero. When it is 27000 (27 degrees
+Celsius), the clock will be set to run faster by 0.183 ppm, etc.
++
+The second form has three parameters: the path to the sensor file, the update
+interval, and a path to a file containing a list of (temperature, compensation)
+points, from which the compensation is linearly interpolated or extrapolated.
++
+An example is:
++
+----
+tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 /etc/chrony.tempcomp
+----
++
+where the _/etc/chrony.tempcomp_ file could have
++
+----
+20000 1.0
+21000 0.64
+22000 0.36
+23000 0.16
+24000 0.04
+25000 0.0
+26000 0.04
+27000 0.16
+28000 0.36
+29000 0.64
+30000 1.0
+----
++
+Valid measurements with corresponding compensations are logged to the
+_tempcomp.log_ file if enabled by the <<log,*log tempcomp*>> directive.
+
+=== NTP server
+
+[[allow]]*allow* [*all*] [_subnet_]::
+The *allow* directive is used to designate a particular subnet from which NTP
+clients are allowed to access the computer as an NTP server. It also controls
+access of NTS-KE clients when NTS is enabled on the server.
++
+The default is that no clients are allowed access, i.e. *chronyd* operates
+purely as an NTP client. If the *allow* directive is used, *chronyd* will be
+both a client of its servers, and a server to other clients.
++
+This directive can be used multiple times.
++
+Examples of the use of the directive are as follows:
++
+----
+allow 1.2.3.4
+allow 3.4.5.0/24
+allow 3.4.5
+allow 2001:db8::/32
+allow 0/0
+allow ::/0
+allow
+----
++
+The first directive allows access from an IPv4 address. The second directive
+allows access from all computers in an IPv4 subnet specified in the CIDR
+notation. The third directive specifies the same subnet using a simpler
+notation where the prefix length is determined by the number of dots. The
+fourth directive specifies an IPv6 subnet. The fifth and sixth directives allow
+access from all IPv4 and IPv6 addresses respectively. The seventh directive
+allows access from all addresses (both IPv4 or IPv6).
++
+A second form of the directive, *allow all*, has a greater effect, depending on
+the ordering of directives in the configuration file. To illustrate the effect,
+consider the two examples:
++
+----
+allow 1.2.3.4
+deny 1.2.3.0/24
+allow 1.2.0.0/16
+----
++
+and
++
+----
+allow 1.2.3.4
+deny 1.2.3.0/24
+allow all 1.2.0.0/16
+----
++
+In the first example, the effect is the same regardless of what order the three
+directives are given in. So the _1.2.0.0/16_ subnet is allowed access, except
+for the _1.2.3.0/24_ subnet, which is denied access, however the host _1.2.3.4_
+is allowed access.
++
+In the second example, the *allow all 1.2.0.0/16* directive overrides the
+effect of _any_ previous directive relating to a subnet within the specified
+subnet. Within a configuration file this capability is probably rather moot;
+however, it is of greater use for reconfiguration at run-time via *chronyc*
+with the <<chronyc.adoc#allow,*allow all*>> command.
++
+The rules are internally represented as a tree of tables with one level per
+four bits of the IPv4 or IPv6 address. The order of the *allow* and *deny*
+directives matters if they modify the same records of one table, i.e. if one
+subnet is included in the other subnet and their prefix lengths are at the same
+level. For example, _1.2.3.0/28_ and _1.2.3.0/29_ are in different tables, but
+_1.2.3.0/25_ and _1.2.3.0/28_ are in the same table. The configuration can be
+verified for individual addresses with the <<chronyc.adoc#accheck,*accheck*>>
+command in *chronyc*.
++
+A hostname can be specified in the directives instead of the IP address, but
+the name must be resolvable when *chronyd* is started, i.e. the network is
+already up and DNS is working. If the hostname resolves to multiple addresses,
+only the first address (in the order returned by the system resolver) will be
+allowed or denied.
++
+Note, if the <<initstepslew,*initstepslew*>> directive is used in the
+configuration file, each of the computers listed in that directive must allow
+client access by this computer for it to work.
+
+[[deny]]*deny* [*all*] [_subnet_]::
+This is similar to the <<allow,*allow*>> directive, except that it denies NTP
+and NTS-KE client access to a particular subnet or host, rather than allowing
+it.
++
+The syntax is identical and the directive can be used multiple times too.
++
+There is also a *deny all* directive with similar behaviour to the *allow all*
+directive.
+
+[[bindaddress]]*bindaddress* _address_::
+The *bindaddress* directive binds the sockets on which *chronyd* listens for
+NTP and NTS-KE requests to a local address of the computer. On systems other
+than Linux, the address of the computer needs to be already configured when
+*chronyd* is started.
++
+An example of the use of the directive is:
++
+----
+bindaddress 192.168.1.1
+----
++
+Currently, for each of the IPv4 and IPv6 protocols, only one *bindaddress*
+directive can be specified. Therefore, it is not useful on computers which
+should serve NTP on multiple network interfaces.
+
+[[binddevice]]*binddevice* _interface_::
+The *binddevice* directive binds the NTP and NTS-KE server sockets to a network
+device specified by the interface name. This directive can specify only one
+interface and it is supported on Linux only.
++
+An example of the directive is:
++
+----
+binddevice eth0
+----
+
+[[broadcast]]*broadcast* _interval_ _address_ [_port_]::
+The *broadcast* directive is used to declare a broadcast address to which
+chronyd should send packets in the NTP broadcast mode (i.e. make *chronyd* act
+as a broadcast server). Broadcast clients on that subnet will be able to
+synchronise.
++
+This directive can be used multiple times to specify multiple addresses.
++
+The syntax is as follows:
++
+----
+broadcast 32 192.168.1.255
+broadcast 64 192.168.2.255 12123
+broadcast 64 ff02::101
+----
++
+In the first example, the destination port defaults to UDP port 123 (the normal NTP
+port). In the second example, the destination port is specified as 12123. The
+first parameter in each case (32 or 64 respectively) is the interval in seconds
+between broadcast packets being sent. The second parameter in each case is the
+broadcast address to send the packet to. This should correspond to the
+broadcast address of one of the network interfaces on the computer where
+*chronyd* is running.
++
+You can have more than 1 *broadcast* directive if you have more than 1 network
+interface onto which you want to send NTP broadcast packets.
++
+*chronyd* itself cannot act as a broadcast client; it must always be configured
+as a point-to-point client by defining specific NTP servers and peers. This
+broadcast server feature is intended for providing a time source to other NTP
+implementations.
++
+If *ntpd* is used as the broadcast client, it will try to measure the
+round-trip delay between the server and client with normal client mode packets.
+Thus, the broadcast subnet should also be the subject of an <<allow,*allow*>>
+directive.
+
+[[clientloglimit]]*clientloglimit* _limit_::
+This directive specifies the maximum amount of memory that *chronyd* is allowed
+to allocate for logging of client accesses and the state that *chronyd* as an
+NTP server needs to support the interleaved mode for its clients. The default
+limit is 524288 bytes, which enables monitoring of up to 4096 IP addresses at
+the same time and holding NTP timestamps for up to 4096 clients using the
+interleaved mode (depending on uniformity of their polling interval). The
+number of addresses and timestamps is always a power of 2. The maximum
+effective value is 2147483648 (2 GB), which corresponds to 16777216 addresses
+and timestamps.
++
+An example of the use of this directive is:
++
+----
+clientloglimit 1048576
+----
+
+[[noclientlog]]*noclientlog*::
+This directive, which takes no arguments, specifies that client accesses are
+not to be logged. Normally they are logged, allowing statistics to be reported
+using the <<chronyc.adoc#clients,*clients*>> command in *chronyc*. This option
+also effectively disables server support for the NTP interleaved mode.
+
+[[local]]*local* [_option_]...::
+The *local* directive enables a local reference mode, which allows *chronyd*
+operating as an NTP server to appear synchronised to real time (from the
+viewpoint of clients polling it), even when it was never synchronised or
+the last update of the clock happened a long time ago.
++
+This directive is normally used in an isolated network, where computers are
+required to be synchronised to one another, but not necessarily to real time.
+The server can be kept vaguely in line with real time by manual input.
++
+The *local* directive has the following options:
++
+*stratum* _stratum_:::
+This option sets the stratum of the server which will be reported to clients
+when the local reference is active. The specified value is in the range 1
+through 15, and the default value is 10. It should be larger than the maximum
+expected stratum in the network when external NTP servers are accessible.
++
+Stratum 1 indicates a computer that has a true real-time reference directly
+connected to it (e.g. GPS, atomic clock, etc.), such computers are expected to
+be very close to real time. Stratum 2 computers are those which have a stratum
+1 server; stratum 3 computers have a stratum 2 server and so on. A value
+of 10 indicates that the clock is so many hops away from a reference clock that
+its time is fairly unreliable.
+*distance* _distance_:::
+This option sets the threshold for the root distance which will activate the local
+reference. If *chronyd* was synchronised to some source, the local reference
+will not be activated until its root distance reaches the specified value (the
+rate at which the distance is increasing depends on how well the clock was
+tracking the source). The default value is 1 second.
++
+The current root distance can be calculated from root delay and root dispersion
+(reported by the <<chronyc.adoc#tracking,*tracking*>> command in *chronyc*) as:
++
+----
+distance = delay / 2 + dispersion
+----
+*orphan*:::
+This option enables a special '`orphan`' mode, where sources with stratum equal
+to the local _stratum_ are assumed to not serve real time. They are ignored
+unless no other source is selectable and their reference IDs are smaller than
+the local reference ID.
++
+This allows multiple servers in the network to use the same *local*
+configuration and to be synchronised to one another, without confusing clients
+that poll more than one server. Each server needs to be configured to poll all
+other servers with the *local* directive. This ensures only the server with the
+smallest reference ID has the local reference active and others are
+synchronised to it. If that server stops responding, the server with the second
+smallest reference ID will take over when its local reference mode activates
+(root distance reaches the threshold configured by the *distance* option).
++
+The *orphan* mode is compatible with the *ntpd*'s orphan mode (enabled by the
+*tos orphan* command).
+{blank}::
++
+An example of the directive is:
++
+----
+local stratum 10 orphan distance 0.1
+----
+
+[[ntpsigndsocket]]*ntpsigndsocket* _directory_::
+This directive specifies the location of the Samba *ntp_signd* socket when it
+is running as a Domain Controller (DC). If *chronyd* is compiled with this
+feature, responses to MS-SNTP clients will be signed by the *smbd* daemon.
++
+Note that MS-SNTP requests are not authenticated and any client that is allowed
+to access the server by the <<allow,*allow*>> directive, or the
+<<chronyc.adoc#allow,*allow*>> command in *chronyc*, can get an MS-SNTP
+response signed with a trust account's password and try to crack the password
+in a brute-force attack. Access to the server should be carefully controlled.
++
+An example of the directive is:
++
+----
+ntpsigndsocket /var/lib/samba/ntp_signd
+----
+
+[[ntsport]]*ntsport* _port_::
+This directive specifies the TCP port on which *chronyd* will provide the NTS
+Key Establishment (NTS-KE) service. The default port is 4460.
++
+The port will be open only when a certificate and key is specified by the
+*ntsservercert* and *ntsserverkey* directives.
+
+[[ntsservercert]]*ntsservercert* _file_::
+This directive specifies a file containing a certificate in the PEM format
+for *chronyd* to operate as an NTS server. The file should also include
+any intermediate certificates that the clients will need to validate the
+server's certificate. The file needs to be readable by the user under which
+*chronyd* is running after dropping root privileges.
++
+This directive can be used multiple times to specify multiple certificates for
+different names of the server.
++
+The files are loaded only once. *chronyd* needs to be restarted in order to
+load a renewed certificate. The <<ntsdumpdir,*ntsdumpdir*>> and
+<<dumpdir,*dumpdir*>> directives with the *-r* option of *chronyd* are
+recommended for a near-seamless server operation.
+
+[[ntsserverkey]]*ntsserverkey* _file_::
+This directive specifies a file containing a private key in the PEM format
+for *chronyd* to operate as an NTS server. The file needs to be readable by
+the user under which *chronyd* is running after dropping root privileges. For
+security reasons, it should not be readable by other users.
++
+This directive can be used multiple times to specify multiple keys. The number
+of keys must be the same as the number of certificates and the corresponding
+files must be specified in the same order.
+
+[[ntsprocesses]]*ntsprocesses* _processes_::
+This directive specifies how many helper processes will *chronyd* operating
+as an NTS server start for handling client NTS-KE requests in order to improve
+performance with multi-core CPUs and multithreading. If set to 0, no helper
+process will be started and all NTS-KE requests will be handled by the main
+*chronyd* process. The default value is 1.
+
+[[maxntsconnections]]*maxntsconnections* _connections_::
+This directive specifies the maximum number of concurrent NTS-KE connections
+per process that the NTS server will accept. The default value is 100. The
+maximum practical value is half of the system *FD_SETSIZE* constant (usually
+1024).
+
+[[ntsdumpdir2]]*ntsdumpdir* _directory_::
+This directive specifies a directory where *chronyd* operating as an NTS server
+can save the keys which encrypt NTS cookies provided to clients. The keys are
+saved to a single file named _ntskeys_. When *chronyd* is restarted, reloading
+the keys allows the clients to continue using old cookies and avoids a storm of
+NTS-KE requests. By default, the server does not save the keys.
++
+An example of the directive is:
++
+----
+ntsdumpdir @CHRONYVARDIR@
+----
++
+This directory is used also by the <<ntsdumpdir1,NTS client>> to save NTS cookies.
+
+[[ntsntpserver]]*ntsntpserver* _hostname_::
+This directive specifies the hostname (as a fully qualified domain name) or
+address of the NTP server(s) which is
+provided in the NTS-KE response to the clients. It allows the NTS-KE server to
+be separated from the NTP server. However, the servers need to share the keys,
+i.e. external key management needs to be enabled by setting
+<<ntsrotate,*ntsrotate*>> to 0. By default, no hostname or address is provided
+to the clients, which means they should use the same server for NTS-KE and NTP.
+
+[[ntsrotate]]*ntsrotate* _interval_::
+This directive specifies the rotation interval (in seconds) of the server key
+which encrypts the NTS cookies. New keys are generated automatically from the
+_/dev/urandom_ device. The server keeps two previous keys to give the clients
+time to get new cookies encrypted by the latest key. The interval is measured
+as the server's operating time, i.e. the actual interval can be longer if
+*chronyd* is not running continuously. The default interval is 604800 seconds
+(1 week). The maximum value is 2^31-1 (68 years).
++
+The automatic rotation of the keys can be disabled by setting *ntsrotate* to 0.
+In this case the keys are assumed to be managed externally. *chronyd* will not
+save the keys to the _ntskeys_ file and will reload the keys from the file when
+the <<chronyc.adoc#rekey,*rekey*>> command is issued in *chronyc*. The file can
+be periodically copied from another server running *chronyd* (which does
+not have *ntsrotate* set to 0) in order to have one or more servers dedicated
+to NTS-KE. The file includes the subsequent key to which the NTS-KE server will
+switch on the next rotation, i.e. the process copying and reloading the file
+does not need to be timed precisely (it can be delayed by up to one rotation
+interval). The NTS-KE servers need to be configured with the
+<<ntsntpserver,*ntsntpserver*>> directive to point the clients to the right NTP
+server.
++
+An example of the directive is:
++
+----
+ntsrotate 2592000
+----
+
+[[port]]*port* _port_::
+This option allows you to configure the port on which *chronyd* will listen for
+NTP requests. The port will be open only when an address is allowed by the
+<<allow,*allow*>> directive or the <<chronyc.adoc#allow,*allow*>> command in
+*chronyc*, an NTP peer is configured, or the broadcast server mode is enabled.
++
+The default value is 123, the standard NTP port. If set to 0, *chronyd* will
+never open the server port and will operate strictly in a client-only mode. The
+source port used in NTP client requests can be set by the
+<<acquisitionport,*acquisitionport*>> directive.
+
+[[ratelimit]]*ratelimit* [_option_]...::
+This directive enables response rate limiting for NTP packets. Its purpose is
+to reduce network traffic with misconfigured or broken NTP clients that are
+polling the server too frequently. The limits are applied to individual IP
+addresses. If multiple clients share one IP address (e.g. multiple hosts behind
+NAT), the sum of their traffic will be limited. If a client that increases its
+polling rate when it does not receive a reply is detected, its rate limiting
+will be temporarily suspended to avoid increasing the overall amount of
+traffic. The maximum number of IP addresses which can be monitored at the same
+time depends on the memory limit set by the <<clientloglimit,*clientloglimit*>>
+directive.
++
+The *ratelimit* directive supports a number of options (which can be defined
+in any order):
++
+*interval* _interval_:::
+This option sets the minimum interval between responses. It is defined as a
+power of 2 in seconds. The default value is 3 (8 seconds). The minimum value
+is -19 (524288 packets per second) and the maximum value is 12 (one packet per
+4096 seconds). Note that with values below -4 the rate limiting is coarse
+(responses are allowed in bursts, even if the interval between them is shorter
+than the specified interval).
+*burst* _responses_:::
+This option sets the maximum number of responses that can be sent in a burst,
+temporarily exceeding the limit specified by the *interval* option. This is
+useful for clients that make rapid measurements on start (e.g. *chronyd* with
+the *iburst* option). The default value is 8. The minimum value is 1 and the
+maximum value is 255.
+*leak* _rate_:::
+This option sets the rate at which responses are randomly allowed even if the
+limits specified by the *interval* and *burst* options are exceeded. This is
+necessary to prevent an attacker who is sending requests with a spoofed
+source address from completely blocking responses to that address. The leak
+rate is defined as a power of 1/2 and it is 2 by default, i.e. on average at
+least every fourth request has a response. The minimum value is 1 and the
+maximum value is 4.
+{blank}::
++
+An example use of the directive is:
++
+----
+ratelimit interval 1 burst 16
+----
++
+This would reduce the response rate for IP addresses sending packets on average
+more than once per 2 seconds, or sending packets in bursts of more than 16
+packets, by up to 75% (with default *leak* of 2).
+
+[[ntsratelimit]]*ntsratelimit* [_option_]...::
+This directive enables rate limiting of NTS-KE requests. It is similar to the
+<<ratelimit,*ratelimit*>> directive, except the default interval is 6
+(1 connection per 64 seconds).
++
+An example of the use of the directive is:
++
+----
+ntsratelimit interval 3 burst 1
+----
+
+[[smoothtime]]*smoothtime* _max-freq_ _max-wander_ [*leaponly*]::
+The *smoothtime* directive can be used to enable smoothing of the time that
+*chronyd* serves to its clients to make it easier for them to track it and keep
+their clocks close together even when large offset or frequency corrections are
+applied to the server's clock, for example after being offline for a longer
+time.
++
+BE WARNED: The server is intentionally not serving its best estimate of the
+true time. If a large offset has been accumulated, it can take a very long time
+to smooth it out. This directive should be used only when the clients are not
+configured to also poll another NTP server, because they could reject this
+server as a falseticker or fail to select a source completely.
++
+The smoothing process is implemented with a quadratic spline function with two
+or three pieces. It is independent from any slewing applied to the local system
+clock, but the accumulated offset and frequency will be reset when the clock is
+corrected by stepping, e.g. by the <<makestep,*makestep*>> directive or the
+<<chronyc.adoc#makestep,*makestep*>> command in *chronyc*. The process can be
+reset without stepping the clock by the <<chronyc.adoc#smoothtime,*smoothtime
+reset*>> command.
++
+The first two arguments of the directive are the maximum frequency offset of
+the smoothed time to the tracked NTP time (in ppm) and the maximum rate at
+which the frequency offset is allowed to change (in ppm per second). *leaponly*
+is an optional third argument which enables a mode where only leap seconds are
+smoothed out and normal offset and frequency changes are ignored. The *leaponly*
+option is useful in a combination with the <<leapsecmode,*leapsecmode slew*>>
+directive to allow the clients to use multiple time smoothing servers safely.
++
+The smoothing process is activated automatically when 1/10000 of the estimated
+skew of the local clock falls below the maximum rate of frequency change. It
+can be also activated manually by the <<chronyc.adoc#smoothtime,*smoothtime
+activate*>> command, which is particularly useful when the clock is
+synchronised only with manual input and the skew is always larger than the
+threshold. The <<chronyc.adoc#smoothing,*smoothing*>> command can be used to
+monitor the process.
++
+An example suitable for clients using *ntpd* and 1024 second polling interval
+could be:
++
+----
+smoothtime 400 0.001
+----
++
+An example suitable for clients using *chronyd* on Linux could be:
++
+----
+smoothtime 50000 0.01
+----
+
+=== Command and monitoring access
+
+[[bindcmdaddress]]*bindcmdaddress* _address_::
+The *bindcmdaddress* directive specifies a local IP address to which *chronyd*
+will bind the UDP socket listening for monitoring command packets (issued
+by *chronyc*). On systems other than Linux, the address of the interface needs
+to be already configured when *chronyd* is started.
++
+This directive can also change the path of the Unix domain command socket,
+which is used by *chronyc* to send configuration commands. The socket must be
+in a directory that is accessible only by the root or _chrony_ user. The
+directory will be created on start if it does not exist. The compiled-in default
+path of the socket is _@CHRONYRUNDIR@/chronyd.sock_. The socket can be
+disabled by setting the path to _/_.
++
+By default, *chronyd* binds the UDP sockets to the addresses _127.0.0.1_ and
+_::1_ (i.e. the loopback interface). This blocks all access except from
+localhost. To listen for command packets on all interfaces, you can add the
+lines:
++
+----
+bindcmdaddress 0.0.0.0
+bindcmdaddress ::
+----
++
+to the configuration file.
++
+For each of the IPv4, IPv6, and Unix domain protocols, only one
+*bindcmdaddress* directive can be specified.
++
+An example that sets the path of the Unix domain command socket is:
++
+----
+bindcmdaddress /var/run/chrony/chronyd.sock
+----
+
+[[bindcmddevice]]*bindcmddevice* _interface_::
+The *bindcmddevice* directive binds the UDP command sockets to a network device
+specified by the interface name. This directive can specify only one interface
+and it is supported on Linux only.
++
+An example of the directive is:
++
+----
+bindcmddevice eth0
+----
+
+[[cmdallow]]*cmdallow* [*all*] [_subnet_]::
+This is similar to the <<allow,*allow*>> directive, except that it allows
+monitoring access (rather than NTP client access) to a particular subnet or
+host. (By '`monitoring access`' is meant that *chronyc* can be run on those
+hosts and retrieve monitoring data from *chronyd* on this computer.)
++
+The syntax is identical to the *allow* directive.
++
+There is also a *cmdallow all* directive with similar behaviour to the *allow
+all* directive (but applying to monitoring access in this case, of course).
++
+Note that *chronyd* has to be configured with the
+<<bindcmdaddress,*bindcmdaddress*>> directive to not listen only on the
+loopback interface to actually allow remote access.
+
+[[cmddeny]]*cmddeny* [*all*] [_subnet_]::
+This is similar to the <<cmdallow,*cmdallow*>> directive, except that it denies
+monitoring access to a particular subnet or host, rather than allowing it.
++
+The syntax is identical.
++
+There is also a *cmddeny all* directive with similar behaviour to the *cmdallow
+all* directive.
+
+[[cmdport]]*cmdport* _port_::
+The *cmdport* directive allows the port that is used for run-time monitoring
+(via the *chronyc* program) to be altered from its default (323). If set to 0,
+*chronyd* will not open the port, which disables remote *chronyc* access (with
+a non-default *bindcmdaddress*) and local access for unprivileged users. It
+does not disable the Unix domain command socket.
++
+An example shows the syntax:
++
+----
+cmdport 257
+----
++
+This would make *chronyd* use UDP 257 as its command port. (*chronyc* would
+need to be run with the *-p 257* option to inter-operate correctly.)
+
+[[cmdratelimit]]*cmdratelimit* [_option_]...::
+This directive enables response rate limiting for command packets. It is
+similar to the <<ratelimit,*ratelimit*>> directive, except responses to
+localhost are never limited and the default interval is -4 (16 packets per
+second).
++
+An example of the use of the directive is:
++
+----
+cmdratelimit interval 2
+----
+
+=== Real-time clock (RTC)
+
+[[hwclockfile]]*hwclockfile* _file_::
+The *hwclockfile* directive sets the location of the adjtime file which is
+used by the *hwclock* program on Linux. *chronyd* parses the file to find out
+if the RTC keeps local time or UTC. It overrides the <<rtconutc,*rtconutc*>>
+directive.
++
+The compiled-in default value is '_@DEFAULT_HWCLOCK_FILE@_'.
++
+An example of the directive is:
++
+----
+hwclockfile /etc/adjtime
+----
+
+[[rtcautotrim]]*rtcautotrim* _threshold_::
+The *rtcautotrim* directive is used to keep the RTC close to the system clock
+automatically. When the system clock is synchronised and the estimated error
+between the two clocks is larger than the specified threshold, *chronyd* will
+trim the RTC as if the <<chronyc.adoc#trimrtc,*trimrtc*>> command in *chronyc*
+was issued. The trimming operation is accurate to only about 1 second, which is
+the minimum effective threshold.
++
+This directive is effective only with the <<rtcfile,*rtcfile*>> directive.
++
+An example of the use of this directive is:
++
+----
+rtcautotrim 30
+----
++
+This would set the threshold error to 30 seconds.
+
+[[rtcdevice]]*rtcdevice* _device_::
+The *rtcdevice* directive sets the path to the device file for accessing the
+RTC. The default path is _@DEFAULT_RTC_DEVICE@_.
+
+[[rtcfile]]*rtcfile* _file_::
+The *rtcfile* directive defines the name of the file in which *chronyd* can
+save parameters associated with tracking the accuracy of the RTC.
++
+An example of the directive is:
++
+----
+rtcfile @CHRONYVARDIR@/rtc
+----
++
+*chronyd* saves information in this file when it exits and when the *writertc*
+command is issued in *chronyc*. The information saved is the RTC's error at
+some epoch, that epoch (in seconds since January 1 1970), and the rate at which
+the RTC gains or loses time.
++
+So far, the support for real-time clocks is limited; their code is even more
+system-specific than the rest of the software. You can only use the RTC
+facilities (the <<rtcfile,*rtcfile*>> directive and the *-s* command-line
+option to *chronyd*) if the following three conditions apply:
++
+. You are running Linux.
+. The kernel is compiled with extended real-time clock support (i.e. the
+  _/dev/rtc_ device is capable of doing useful things).
+. You do not have other applications that need to make use of _/dev/rtc_ at all.
+
+[[rtconutc]]*rtconutc*::
+*chronyd* assumes by default that the RTC keeps local time (including any
+daylight saving changes). This is convenient on PCs running Linux which are
+dual-booted with Windows.
++
+If you keep the RTC on local time and your computer is off when daylight saving
+(summer time) starts or ends, the computer's system time will be one hour in
+error when you next boot and start chronyd.
++
+An alternative is for the RTC to keep Universal Coordinated Time (UTC). This
+does not suffer from the 1 hour problem when daylight saving starts or ends.
++
+If the *rtconutc* directive appears, it means the RTC is required to keep UTC.
+The directive takes no arguments. It is equivalent to specifying the *-u*
+switch to the Linux *hwclock* program.
++
+Note that this setting is overridden by the <<hwclockfile,*hwclockfile*>> file
+and is not relevant for the <<rtcsync,*rtcsync*>> directive.
+
+[[rtcsync]]*rtcsync*::
+The *rtcsync* directive enables a mode where the system time is periodically
+copied to the RTC and *chronyd* does not try to track its drift. This directive
+cannot be used with the <<rtcfile,*rtcfile*>> directive.
++
+On Linux, the RTC copy is performed by the kernel every 11 minutes.
++
+On macOS, <<chronyd,*chronyd*>> will perform the RTC copy every 60 minutes
+when the system clock is in a synchronised state.
++
+On other systems this directive does nothing.
+
+=== Logging
+
+[[log]]*log* [_option_]...::
+The *log* directive indicates that certain information is to be logged.
+The log files are written to the directory specified by the <<logdir,*logdir*>>
+directive. A banner is periodically written to the files to indicate the
+meanings of the columns.
++
+*rawmeasurements*:::
+This option logs the raw NTP measurements and related information to a file
+called _measurements.log_. An entry is made for each packet received from the
+source. This can be useful when debugging a problem. An example line (which
+actually appears as a single line in the file) from the log file is shown
+below.
++
+----
+2016-11-09 05:40:50 203.0.113.15    N  2 111 111 1111  10 10 1.0 \
+   -4.966e-03  2.296e-01  1.577e-05  1.615e-01  7.446e-03 CB00717B 4B D K
+----
++
+The columns are as follows (the quantities in square brackets are the values
+from the example line above):
++
+. Date [2015-10-13]
+. Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the
+  local time zone. [05:40:50]
+. IP address of server or peer from which measurement came [203.0.113.15]
+. Leap status (_N_ means normal, _+_ means that the last minute of the current
+  month has 61 seconds, _-_ means that the last minute of the month has 59
+  seconds, _?_ means the remote computer is not currently synchronised.) [N]
+. Stratum of remote computer. [2]
+. RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111]
+. RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111]
+. Results of the *maxdelay*, *maxdelayratio*, and *maxdelaydevratio* (or
+  *maxdelayquant*) tests, and a test for synchronisation loop (1=pass,
+  0=fail). The first test from these four also checks the server precision,
+  response time, and whether an interleaved response is acceptable for
+  synchronisation. [1111]
+. Local poll [10]
+. Remote poll [10]
+. '`Score`' (an internal score within each polling level used to decide when to
+  increase or decrease the polling level. This is adjusted based on number of
+  measurements currently being used for the regression algorithm). [1.0]
+. The estimated local clock error (_theta_ in RFC 5905). Positive indicates
+  that the local clock is slow of the remote source. [-4.966e-03]
+. The peer delay (_delta_ in RFC 5905). [2.296e-01]
+. The peer dispersion (_epsilon_ in RFC 5905). [1.577e-05]
+. The root delay (_DELTA_ in RFC 5905). [1.615e-01]
+. The root dispersion (_EPSILON_ in RFC 5905). [7.446e-03]
+. Reference ID of the server's source as a hexadecimal number. [CB00717B]
+. NTP mode of the received packet (_1_=active peer, _2_=passive peer,
+  _4_=server, _B_=basic, _I_=interleaved). [4B]
+. Source of the local transmit timestamp
+  (_D_=daemon, _K_=kernel, _H_=hardware). [D]
+. Source of the local receive timestamp
+  (_D_=daemon, _K_=kernel, _H_=hardware). [K]
++
+*measurements*:::
+This option is identical to the *rawmeasurements* option, except it logs only
+valid measurements from synchronised sources, i.e. measurements which passed
+the RFC 5905 tests 1 through 7. This can be useful for producing graphs of the
+source's performance.
++
+*statistics*:::
+This option logs information about the regression processing to a file called
+_statistics.log_. An example line (which actually appears as a single line in
+the file) from the log file is shown below.
++
+----
+2016-08-10 05:40:50 203.0.113.15     6.261e-03 -3.247e-03 \
+     2.220e-03  1.874e-06  1.080e-06 7.8e-02  16   0   8  0.00
+----
++
+The columns are as follows (the quantities in square brackets are the values
+from the example line above):
++
+. Date [2015-07-22]
+. Hour:Minute:Second. Note that the date-time pair is expressed in
+  UTC, not the local time zone. [05:40:50]
+. IP address of server or peer from which measurement comes [203.0.113.15]
+. The estimated standard deviation of the measurements from the source (in
+  seconds). [6.261e-03]
+. The estimated offset of the source (in seconds, positive means the local
+  clock is estimated to be fast, in this case). [-3.247e-03]
+. The estimated standard deviation of the offset estimate (in seconds).
+  [2.220e-03]
+. The estimated rate at which the local clock is gaining or losing time
+  relative to the source (in seconds per second, positive means the local clock
+  is gaining). This is relative to the compensation currently being applied to
+  the local clock, _not_ to the local clock without any compensation.
+  [1.874e-06]
+. The estimated error in the rate value (in seconds per second). [1.080e-06].
+. The ratio of |old_rate - new_rate| / old_rate_error. Large values
+  indicate the statistics are not modelling the source very well. [7.8e-02]
+. The number of measurements currently being used for the regression
+  algorithm. [16]
+. The new starting index (the oldest sample has index 0; this is the method
+  used to prune old samples when it no longer looks like the measurements fit a
+  linear model). [0, i.e. no samples discarded this time]
+. The number of runs. The number of runs of regression residuals with the same
+  sign is computed. If this is too small it indicates that the measurements are
+  no longer represented well by a linear model and that some older samples need
+  to be discarded. The number of runs for the data that is being retained is
+  tabulated. Values of approximately half the number of samples are expected.
+  [8]
+. The estimated or configured asymmetry of network jitter on the path to the
+  source which was used to correct the measured offsets. The asymmetry can be
+  between -0.5 and +0.5. A negative value means the delay of packets sent to
+  the source is more variable than the delay of packets sent from the source
+  back. [0.00, i.e. no correction for asymmetry]
++
+*selection*:::
+This option logs information about selection of sources for synchronisation to
+a file called _selection.log_. Note that the rate of entries written to this
+file grows quadratically with the number of specified sources (each measurement
+triggers the selection for all sources). An example line (which actually
+appears as a single line in the file) from the log file is shown below.
++
+----
+2022-05-01 02:01:20 203.0.113.15    * -----  377  1.00  \
+     4.228e+01 -1.575e-04  1.239e-04
+----
++
+The columns are as follows (the quantities in square brackets are the values
+from the example line above):
++
+. Date [2022-05-01]
+. Hour:Minute:Second. Note that the date-time pair is expressed in
+  UTC, not the local time zone. [02:01:20]
+. IP address or reference ID of the source. [203.0.113.15]
+. State of the source indicated with one of the following symbols. [*]
+{blank}::::
+Not considered selectable for synchronisation:
+* _N_ - has the *noselect* option.
+* _s_ - is not synchronised.
+* _M_ - does not have enough measurements.
+* _d_ - has a root distance larger than the maximum distance (configured by the
+        <<maxdistance,*maxdistance*>> directive).
+* _~_ - has a jitter larger than the maximum jitter (configured by the
+        <<maxjitter,*maxjitter*>> directive).
+* _w_ - waits for other sources to get out of the _M_ state.
+* _S_ - has older measurements than other sources.
+* _O_ - has a stratum equal or larger than the orphan stratum (configured by
+        the <<local,*local*>> directive).
+* _T_ - does not fully agree with sources that have the *trust* option.
+* _x_ - does not agree with other sources (falseticker).
+{blank}::::
+Considered selectable for synchronisation, but not currently used:
+* _W_ - waits for other sources to be selectable (required by the
+        <<minsources,*minsources*>> directive, or the *require* option of
+        another source).
+* _P_ - another selectable source is preferred due to the *prefer* option.
+* _U_ - waits for a new measurement (after selecting a different best source).
+* _D_ - has, or recently had, a root distance which is too large to be combined
+        with other sources (configured by the <<combinelimit,*combinelimit*>>
+        directive).
+{blank}::::
+Used for synchronisation of the local clock:
+* _+_ - combined with the best source.
+* _*_ - selected as the best source to update the reference data (e.g. root
+        delay, root dispersion).
+. Current effective selection options of the source. which can be different
+  from the configured options due to the authentication selection mode
+  (configured by the <<authselectmode,*authselectmode*>> directive). [-----]
+* _N_ indicates the *noselect* option.
+* _P_ indicates the *prefer* option.
+* _T_ indicates the *trust* option.
+* _R_ indicates the *require* option.
+. Reachability register printed as an octal number. The register has 8 bits and
+  is updated on every received or missed packet from the source. A value of 377
+  indicates that a valid reply was received for all from the last eight
+  transmissions. [377]
+. Current score against the source in the _*_ state. The scoring system avoids
+  frequent reselection when multiple sources have a similar root distance. A
+  value larger than 1 indicates this source was better than the _*_ source in
+  recent selections. If the score reaches 10, the best source will be reselected
+  and the scores will be reset to 1. [1.00]
+. Interval since the last measurement of the source in seconds. [4.228e+01]
+. Lower endpoint of the interval which was expected to contain the true offset
+  of the local clock determined by the root distance of the source. [-1.575e-04]
+. Upper endpoint of the interval which was expected to contain the true offset
+  of the local clock determined by the root distance of the source. [1.239e-04]
++
+*tracking*:::
+This option logs changes to the estimate of the system's gain or loss rate, and
+any slews made, to a file called _tracking.log_. An example line (which
+actually appears as a single line in the file) from the log file is shown
+below.
++
+----
+2017-08-22 13:22:36 203.0.113.15     2     -3.541      0.075 -8.621e-06 N \
+            2  2.940e-03 -2.084e-04  1.534e-02  3.472e-04  8.304e-03
+----
++
+The columns are as follows (the quantities in square brackets are the
+values from the example line above) :
++
+. Date [2017-08-22]
+. Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the
+  local time zone. [13:22:36]
+. The IP address of the server or peer to which the local system is synchronised.
+  [203.0.113.15]
+. The stratum of the local system. [2]
+. The local system frequency (in ppm, positive means the local system runs fast
+  of UTC). [-3.541]
+. The error bounds on the frequency (in ppm). [0.075]
+. The estimated local offset at the epoch, which is normally corrected by
+  slewing the local clock (in seconds, positive indicates the clock is fast of
+  UTC). [-8.621e-06]
+. Leap status (_N_ means normal, _+_ means that the last minute of this month
+  has 61 seconds, _-_ means that the last minute of the month has 59 seconds,
+  _?_ means the clock is not currently synchronised.) [N]
+. The number of combined sources. [2]
+. The estimated standard deviation of the combined offset (in seconds).
+  [2.940e-03]
+. The remaining offset correction from the previous update (in seconds,
+  positive means the system clock is slow of UTC). [-2.084e-04]
+. The total of the network path delays to the reference clock to which
+  the local clock is ultimately synchronised (in seconds). [1.534e-02]
+. The total dispersion accumulated through all the servers back to the
+  reference clock to which the local clock is ultimately synchronised
+  (in seconds). [3.472e-04]
+. The maximum estimated error of the system clock in the interval since the
+  previous update (in seconds). It includes the offset, remaining offset
+  correction, root delay, and dispersion from the previous update with the
+  dispersion which accumulated in the interval. [8.304e-03]
++
+*rtc*:::
+This option logs information about the system's real-time clock. An example
+line (which actually appears as a single line in the file) from the _rtc.log_
+file is shown below.
++
+----
+2015-07-22 05:40:50     -0.037360 1       -0.037434\
+          -37.948  12   5  120
+----
++
+The columns are as follows (the quantities in square brackets are the
+values from the example line above):
++
+. Date [2015-07-22]
+. Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the
+  local time zone. [05:40:50]
+. The measured offset between the RTC and the system clock in seconds.
+  Positive indicates that the RTC is fast of the system time [-0.037360].
+. Flag indicating whether the regression has produced valid coefficients.
+  (1 for yes, 0 for no). [1]
+. Offset at the current time predicted by the regression process. A large
+  difference between this value and the measured offset tends to indicate that
+  the measurement is an outlier with a serious measurement error. [-0.037434]
+. The rate at which the RTC is losing or gaining time relative to the system
+  clock. In ppm, with positive indicating that the RTC is gaining time.
+  [-37.948]
+. The number of measurements used in the regression. [12]
+. The number of runs of regression residuals of the same sign. Low values
+  indicate that a straight line is no longer a good model of the measured data
+  and that older measurements should be discarded. [5]
+. The measurement interval used prior to the measurement being made (in
+  seconds). [120]
++
+*refclocks*:::
+This option logs the raw and filtered reference clock measurements to a file
+called _refclocks.log_. An example line (which actually appears as a single
+line in the file) from the log file is shown below.
++
+----
+2009-11-30 14:33:27.000000 PPS2    7 N 1  4.900000e-07 -6.741777e-07  1.000e-06
+----
++
+The columns are as follows (the quantities in square brackets are the values
+from the example line above):
++
+. Date [2009-11-30]
+. Hour:Minute:Second.Microsecond. Note that the date-time pair is expressed in
+  UTC, not the local time zone. [14:33:27.000000]
+. Reference ID of the reference clock from which the measurement came. [PPS2]
+. Sequence number of driver poll within one polling interval for raw samples,
+  or _-_ for filtered samples. [7]
+. Leap status (_N_ means normal, _+_ means that the last minute of the current
+  month has 61 seconds, _-_ means that the last minute of the month has 59
+  seconds). [N]
+. Flag indicating whether the sample comes from PPS source. (1 for yes,
+  0 for no, or _-_ for filtered sample). [1]
+. Local clock error measured by reference clock driver, or _-_ for filtered sample.
+  [4.900000e-07]
+. Local clock error with applied corrections. Positive indicates that the local
+  clock is slow. [-6.741777e-07]
+. Assumed dispersion of the sample. [1.000e-06]
++
+*tempcomp*:::
+This option logs the temperature measurements and system rate compensations to
+a file called _tempcomp.log_. An example line (which actually appears as a
+single line in the file) from the log file is shown below.
++
+----
+2015-04-19 10:39:48  2.8000e+04  3.6600e-01
+----
++
+The columns are as follows (the quantities in square brackets are the values
+from the example line above):
++
+. Date [2015-04-19]
+. Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the
+  local time zone. [10:39:48]
+. Temperature read from the sensor. [2.8000e+04]
+. Applied compensation in ppm, positive means the system clock is running
+  faster than it would be without the compensation. [3.6600e-01]
++
+{blank}::
+An example of the directive is:
++
+----
+log measurements statistics tracking
+----
+
+[[logbanner]]*logbanner* _entries_::
+A banner is periodically written to the log files enabled by the <<log,*log*>>
+directive to indicate the meanings of the columns.
++
+The *logbanner* directive specifies after how many entries in the log file
+should be the banner written. The default is 32, and 0 can be used to disable
+it entirely.
+
+[[logchange]]*logchange* _threshold_::
+This directive sets the threshold for the adjustment of the system clock that
+will generate a syslog message. Clock errors detected via NTP packets,
+reference clocks, or timestamps entered via the
+<<chronyc.adoc#settime,*settime*>> command of *chronyc* are logged.
++
+By default, the threshold is 1 second.
++
+An example of the use is:
++
+----
+logchange 0.1
+----
++
+which would cause a syslog message to be generated if a system clock error of over
+0.1 seconds starts to be compensated.
+
+[[logdir]]*logdir* _directory_::
+This directive specifies the directory for writing log files enabled by the
+*log* directive. If the directory does not exist, it will be created
+automatically.
++
+An example of the use of this directive is:
++
+----
+logdir /var/log/chrony
+----
+
+[[mailonchange]]*mailonchange* _email_ _threshold_::
+This directive defines an email address to which mail should be sent if
+*chronyd* applies a correction exceeding a particular threshold to the system
+clock.
++
+An example of the use of this directive is:
++
+----
+mailonchange root@localhost 0.5
+----
++
+This would send a mail message to root if a change of more than 0.5 seconds
+were applied to the system clock.
++
+This directive cannot be used when a system call filter is enabled by the *-F*
+option as the *chronyd* process will not be allowed to fork and execute the
+sendmail binary.
+
+=== Miscellaneous
+
+[[confdir]]*confdir* _directory_...::
+The *confdir* directive includes configuration files with the _.conf_ suffix
+from a directory. The files are included in the lexicographical order of the
+file names.
++
+Multiple directories (up to 10) can be specified with a single *confdir*
+directive. In this case, if multiple directories contain a file with the same
+name, only the first file in the order of the specified directories will be
+included. This enables a fragmented configuration where existing fragments can
+be replaced by adding files to a different directory.
++
+This directive can be used multiple times.
++
+An example of the directive is:
++
+----
+confdir @SYSCONFDIR@/chrony.d
+----
+
+[[sourcedir]]*sourcedir* _directory_...::
+The *sourcedir* directive is identical to the *confdir* directive, except the
+configuration files have the _.sources_ suffix, they can only specify NTP
+sources (i.e. the *server*, *pool*, and *peer* directives), they are expected
+to have all lines terminated by the newline character, and they can be
+reloaded by the <<chronyc.adoc#reload,*reload sources*>> command in
+*chronyc*. It is particularly useful with dynamic sources like NTP servers
+received from a DHCP server, which can be written to a file specific to the
+network interface by a networking script.
++
+This directive can be used multiple times.
++
+An example of the directive is:
++
+----
+sourcedir /var/run/chrony-dhcp
+----
+
+[[include]]*include* _pattern_::
+The *include* directive includes a configuration file, or multiple configuration
+files if a wildcard pattern is specified. Unlike with the *confdir* directive,
+the full name of the files needs to be specified and at least one file is
+required to exist.
++
+This directive can be used multiple times.
++
+An example of the directive is:
++
+----
+include @SYSCONFDIR@/chrony.d/*.conf
+----
+
+[[hwtimestamp]]*hwtimestamp* _interface_ [_option_]...::
+This directive enables hardware timestamping of NTP packets sent to and
+received from the specified network interface. The network interface controller
+(NIC) uses its own clock to accurately timestamp the actual transmissions and
+receptions, avoiding processing and queueing delays in the kernel, network
+driver, and hardware. This can significantly improve the accuracy of the
+timestamps and the measured offset, which is used for synchronisation of the
+system clock. In order to get the best results, both sides receiving and
+sending NTP packets (i.e. server and client, or two peers) need to use HW
+timestamping. If the server or peer supports the interleaved mode, it needs to
+be enabled by the *xleave* option in the <<server,*server*>> or the
+<<peer,*peer*>> directive.
++
+This directive is supported on Linux 3.19 and newer. The NIC must support HW
+timestamping, which can be verified with the *ethtool -T* command. The list of
+capabilities should include _hardware-raw-clock_, _hardware-transmit_, and
+_hardware-receive_. The receive filter _all_, or _ntp_, is necessary for
+timestamping of received NTP packets. Timestamping of packets received on
+bridged and bonded interfaces is supported on Linux 4.13 and newer. If HW
+timestamping does not work for received packets, *chronyd* will use kernel
+receive timestamps instead. Transmit-only HW timestamping can still be useful
+to improve stability of the synchronisation.
++
+*chronyd* does not synchronise the NIC clock. It assumes the clock is running
+free. Multiple instances of *chronyd* can use the same interface with enabled
+HW timestamping. Applications which need HW timestamping with a synchronised
+clock (e.g. a PTP daemon) should use a virtual clock running on top of the
+physical clock created by writing to _/sys/class/ptp/ptpX/n_vclocks_. This
+feature is available on Linux 5.14 and newer.
++
+If the kernel supports software timestamping, it will be enabled for all
+interfaces automatically.
++
+The source of timestamps (i.e. hardware, kernel, or daemon) is indicated on the
+client side in the _measurements.log_ file (if enabled by the <<log,*log*>>
+directive) and the <<chronyc.adoc#ntpdata,*ntpdata*>> report. On the server
+side, the number of served timestamps from each source is provided in the
+<<chronyc.adoc#serverstats,*serverstats*>> report.
++
+This directive can be used multiple times to enable HW timestamping on multiple
+interfaces. If the specified interface is _*_, *chronyd* will try to enable HW
+timestamping on all available interfaces.
++
+The *hwtimestamp* directive has the following options:
++
+*minpoll* _poll_:::
+This option specifies the minimum interval between readings of the NIC clock.
+It's defined as a power of 2. It should correspond to the minimum polling
+interval of all NTP sources and the minimum expected polling interval of NTP
+clients. The default value is 0 (1 second), the minimum value is -6 (1/64th
+of a second), and the maximum value is 20 (about 12 days).
+*maxpoll* _poll_:::
+This option specifies the maximum interval between readings of the NIC clock,
+as a power of 2. The default value is *minpoll* + 1, i.e. 1 (2 seconds) with
+the default *minpoll* of 0. The minimum and maximum values are the same as with
+the *minpoll* option.
+*minsamples* _samples_:::
+This option specifies the minimum number of readings kept for tracking of the
+NIC clock. The default value is 2.
+*maxsamples* _samples_:::
+This option specifies the maximum number of readings kept for tracking of the
+NIC clock. The default value is 16.
+*precision* _precision_:::
+This option specifies the assumed precision of reading of the NIC clock. The
+default value is 100e-9 (100 nanoseconds).
+*txcomp* _compensation_:::
+This option specifies the difference in seconds between the actual transmission
+time at the physical layer and the reported transmit timestamp. This value will
+be added to transmit timestamps obtained from the NIC. The default value is 0.
+*rxcomp* _compensation_:::
+This option specifies the difference in seconds between the reported receive
+timestamp and the actual reception time at the physical layer. This value will
+be subtracted from receive timestamps obtained from the NIC. The default value
+is 0.
+*nocrossts*:::
+Some hardware can precisely cross timestamp the NIC clock with the system
+clock. This option disables the use of the cross timestamping.
+*rxfilter* _filter_:::
+This option selects the receive timestamping filter. The _filter_ can be one of
+the following:
+_all_::::
+Enables timestamping of all received packets.
+_ntp_::::
+Enables timestamping of received NTP packets.
+_ptp_::::
+Enables timestamping of received PTP packets.
+_none_::::
+Disables timestamping of received packets.
+{blank}:::
+The most specific filter for timestamping of NTP packets supported by the NIC
+is selected by default. Some NICs can timestamp PTP packets only. By default,
+they will be configured with the _none_ filter and expected to provide hardware
+timestamps for transmitted packets only. Timestamping of PTP packets is useful
+with NTP-over-PTP enabled by the <<chrony.conf.adoc#ptpport,*ptpport*>>
+directive, or when another application is receiving PTP packets on the
+interface. Forcing timestamping of all packets with the _all_ filter could be
+useful if the NIC supported both the _all_ and _ntp_ filters, and it should
+timestamp both NTP and PTP packets, or NTP packets on a different UDP port.
+{blank}::
++
+Examples of the directive are:
++
+----
+hwtimestamp eth0
+hwtimestamp eth1 txcomp 300e-9 rxcomp 645e-9
+hwtimestamp *
+----
+
+[[hwtstimeout]]*hwtstimeout* _timeout_::
+If hardware timestamping is used with a close NTP server, or the NIC or its
+driver is slow in providing the transmit timestamp of NTP requests, a response
+from the server can be received before the transmit timestamp of the request.
+To avoid calculating the offset with a less accurate transmit timestamp,
+*chronyd* can save the response for later processing and wait for the hardware
+transmit timestamp. There is no guarantee that the timestamp will be provided
+(NICs typically have a limited rate of transmit timestamping). This directive
+configures how long should *chronyd* wait for the timestamp after receiving a
+valid response from the server. If a second valid response is received from the
+server while waiting for the timestamp, they will be both processed
+immediately.
++
+The default value is 0.001 seconds, which should be sufficient with most
+hardware. If you frequently see kernel transmit timestamps in the
+_measurements.log_ file or <<chronyc.adoc#ntpdata,*ntpdata*>> report, and it is
+not a server handling a high rate of requests in the interleaved mode on the
+same interface (which would compete with timestamping of the server's own
+requests), increasing the timeout to 0.01 or possibly even longer might help.
+Note that the maximum timeout is limited by the NTP polling interval.
+
+[[keyfile]]*keyfile* _file_::
+This directive is used to specify the location of the file containing symmetric
+keys which are shared between NTP servers and clients, or peers, in order to
+authenticate NTP packets with a message authentication code (MAC) using a
+cryptographic hash function or cipher.
++
+The format of the directive is shown in the example below:
++
+----
+keyfile @SYSCONFDIR@/chrony.keys
+----
++
+The argument is simply the name of the file containing the ID-key pairs. The
+format of the file is shown below:
++
+----
+10 tulip
+11 hyacinth
+20 MD5 ASCII:crocus
+25 SHA1 HEX:933F62BE1D604E68A81B557F18CFA200483F5B70
+30 AES128 HEX:7EA62AE64D190114D46D5A082F948EC1
+31 AES256 HEX:37DDCBC67BB902BCB8E995977FAB4D2B5642F5B32EBCEEE421921D97E5CBFE39
+ ...
+----
++
+Each line consists of an ID, optional type, and key.
++
+The ID can be any positive integer in the range 1 through 2^32-1.
++
+The type is a name of a cryptographic hash function or cipher which is used to
+generate and verify the MAC. The default type is *MD5*, which is always
+supported.
+If *chronyd* was built with enabled support for hashing using a crypto library
+(Nettle, GnuTLS, NSS, or LibTomCrypt), the following functions are available: *MD5*,
+*SHA1*, *SHA256*, *SHA384*, *SHA512*. Depending on which library and version is
+*chronyd* using, some of the following hash functions and ciphers may
+also be available:
+*SHA3-224*, *SHA3-256*, *SHA3-384*, *SHA3-512*, *TIGER*, *WHIRLPOOL*, *AES128*,
+*AES256*.
++
+The key can be specified as a string of ASCII characters not containing white
+space with an optional *ASCII:* prefix, or as a hexadecimal number with the
+*HEX:* prefix. The maximum length of the line is 2047 characters.
+If the type is a cipher, the length of the key must match the cipher (i.e. 128
+bits for AES128 and 256 bits for AES256).
++
+It is recommended to use randomly generated keys, specified in the hexadecimal
+format, which are at least 128 bits long (i.e. they have at least 32 characters
+after the *HEX:* prefix). *chronyd* will log a warning to syslog on start if a
+source is specified in the configuration file with a key shorter than 80 bits.
++
+The recommended key types are AES ciphers and SHA3 hash functions. MD5 should
+be avoided unless no other type is supported on the server and client, or
+peers.
++
+The <<chronyc.adoc#keygen,*keygen*>> command of *chronyc* can be used to
+generate random keys for the key file. By default, it generates 160-bit MD5 or
+SHA1 keys.
++
+For security reasons, the file should be readable only by root and the user
+under which *chronyd* is normally running (to allow *chronyd* to re-read the
+file when the <<chronyc.adoc#rekey,*rekey*>> command is issued by *chronyc*).
+
+[[lock_all]]*lock_all*::
+The *lock_all* directive will lock the *chronyd* process into RAM so that it
+will never be paged out. This can result in lower and more consistent latency.
+The directive is supported on Linux, FreeBSD, NetBSD, and illumos.
+
+[[pidfile]]*pidfile* _file_::
+Unless *chronyd* is started with the *-Q* option, it writes its process ID
+(PID) to a file, and checks this file on startup to see if another *chronyd*
+might already be running on the system. By default, the file used is
+_@DEFAULT_PID_FILE@_. The *pidfile* directive allows the name to be changed,
+e.g.:
++
+----
+pidfile /run/chronyd.pid
+----
+
+[[ptpport]]*ptpport* _port_::
+The *ptpport* directive enables *chronyd* to send and receive NTP messages
+contained in PTP event messages (NTP-over-PTP) to enable hardware timestamping
+on NICs which cannot timestamp NTP packets, but can timestamp unicast PTP
+packets, and also use corrections provided by PTP one-step end-to-end
+transparent clocks in network switches and routers. The port recognized by the
+NICs and PTP transparent clocks is 319 (PTP event port). The default value is 0
+(disabled).
++
+The NTP-over-PTP support is experimental. The protocol and configuration can
+change in future. It should be used only in local networks.
++
+The PTP port will be open even if *chronyd* is not configured to operate as a
+server or client. The directive does not change the default protocol of
+specified NTP sources. Each NTP source that should use NTP-over-PTP needs to
+be specified with the *port* option set to the PTP port. To actually enable
+hardware timestamping on NICs which can timestamp PTP packets only, the
+*rxfilter* option of the *hwtimestamp* directive needs to be set to _ptp_. The
+extension field _F324_ needs to be enabled to use the corrections provided by
+the PTP transparent clocks.
++
+An example of client configuration is:
++
+----
+server ntp1.example.net minpoll 0 maxpoll 0 xleave port 319 extfield F324
+hwtimestamp * rxfilter ptp
+ptpport 319
+----
+
+[[sched_priority]]*sched_priority* _priority_::
+On Linux, FreeBSD, NetBSD, and illumos, the *sched_priority* directive will
+select the SCHED_FIFO real-time scheduler at the specified priority (which must
+be between 0 and 100). On macOS, this option must have either a value of 0 (the
+default) to disable the thread time constraint policy or 1 for the policy to be
+enabled.
++
+On systems other than macOS, this directive uses the *pthread_setschedparam()*
+system call to instruct the kernel to use the SCHED_FIFO first-in, first-out
+real-time scheduling policy for *chronyd* with the specified priority. This
+means that whenever *chronyd* is ready to run it will run, interrupting
+whatever else is running unless it is a higher priority real-time process. This
+should not impact performance as *chronyd* resource requirements are modest,
+but it should result in lower and more consistent latency since *chronyd* will
+not need to wait for the scheduler to get around to running it. You should not
+use this unless you really need it. The *pthread_setschedparam(3)* man page has
+more details.
++
+On macOS, this directive uses the *thread_policy_set()* kernel call to
+specify real-time scheduling. As noted above, you should not use this directive
+unless you really need it.
+
+[[user]]*user* _user_::
+The *user* directive sets the name of the system user to which *chronyd* will
+switch after start in order to drop root privileges.
++
+On Linux, *chronyd* needs to be compiled with support for the *libcap* library.
+On macOS, FreeBSD, NetBSD and illumos *chronyd* forks into two processes.
+The child process retains root privileges, but can only perform a very limited
+range of privileged system calls on behalf of the parent.
++
+The compiled-in default value is _@DEFAULT_USER@_.
+
+[[examples]]
+== EXAMPLES
+
+=== NTP client with permanent connection to NTP servers
+
+This section shows how to configure *chronyd* for computers that are connected
+to the Internet (or to any network containing true NTP servers which ultimately
+derive their time from a reference clock) permanently or most of the time.
+
+To operate in this mode, you will need to know the names of the NTP servers
+you want to use. You might be able to find names of suitable servers by one of
+the following methods:
+
+* Your institution might already operate servers on its network.
+  Contact your system administrator to find out.
+* Your ISP probably has one or more NTP servers available for its
+  customers.
+* Somewhere under the NTP homepage there is a list of public
+  stratum 1 and stratum 2 servers. You should find one or more servers that are
+  near to you. Check that their access policy allows you to use their
+  facilities.
+* Use public servers from the https://www.pool.ntp.org/[pool.ntp.org] project.
+
+Assuming that your NTP servers are called _ntp1.example.net_, _ntp2.example.net_
+and _ntp3.example.net_, your _chrony.conf_ file could contain as a minimum:
+
+----
+server ntp1.example.net
+server ntp2.example.net
+server ntp3.example.net
+----
+
+However, you will probably want to include some of the other directives. The
+<<driftfile,*driftfile*>>, <<makestep,*makestep*>> and <<rtcsync,*rtcsync*>>
+might be particularly useful. Also, the *iburst* option of the
+<<server,*server*>> directive is useful to speed up the initial
+synchronisation. The smallest useful configuration file would look something
+like:
+
+----
+server ntp1.example.net iburst
+server ntp2.example.net iburst
+server ntp3.example.net iburst
+driftfile @CHRONYVARDIR@/drift
+makestep 1.0 3
+rtcsync
+----
+
+When using a pool of NTP servers (one name is used for multiple servers which
+might change over time), it is better to specify them with the <<pool,*pool*>>
+directive instead of multiple *server* directives. The configuration file could
+in this case look like:
+
+----
+pool pool.ntp.org iburst
+driftfile @CHRONYVARDIR@/drift
+makestep 1.0 3
+rtcsync
+----
+
+If the servers (or pool) support the Network Time Security (NTS)
+authentication mechanism and *chronyd* is compiled with NTS support, the *nts*
+option will enable a secure synchronisation to the servers. The configuration
+file could look like:
+
+----
+server ntp1.example.net iburst nts
+server ntp2.example.net iburst nts
+server ntp3.example.net iburst nts
+driftfile @CHRONYVARDIR@/drift
+makestep 1.0 3
+rtcsync
+----
+
+=== NTP client with infrequent connection to NTP servers
+
+This section shows how to configure *chronyd* for computers that have
+occasional connections to NTP servers. In this case, you will need some
+additional configuration to tell *chronyd* when the connection goes up and
+down. This saves the program from continuously trying to poll the servers when
+they are inaccessible.
+
+Again, assuming that your NTP servers are called _ntp1.example.net_,
+_ntp2.example.net_ and _ntp3.example.net_, your _chrony.conf_ file would now
+contain:
+
+----
+server ntp1.example.net offline
+server ntp2.example.net offline
+server ntp3.example.net offline
+driftfile @CHRONYVARDIR@/drift
+makestep 1.0 3
+rtcsync
+----
+
+The *offline* keyword indicates that the servers start in an offline state, and
+that they should not be contacted until *chronyd* receives notification from
+*chronyc* that the link to the Internet is present. To tell *chronyd* when to
+start and finish sampling the servers, the <<chronyc.adoc#online,*online*>> and
+<<chronyc.adoc#offline,*offline*>> commands of *chronyc* need to be used.
+
+To give an example of their use, assuming that *pppd* is the program being
+used to connect to the Internet and that *chronyc* has been installed at
+_@BINDIR@/chronyc_, the script _/etc/ppp/ip-up_ would include:
+
+----
+@BINDIR@/chronyc online
+----
+
+and the script _/etc/ppp/ip-down_ would include:
+
+----
+@BINDIR@/chronyc offline
+----
+
+*chronyd*'s polling of the servers would now only occur whilst the machine is
+actually connected to the Internet.
+
+=== Isolated networks
+
+This section shows how to configure *chronyd* for computers that never have
+network connectivity to any computer which ultimately derives its time from a
+reference clock.
+
+In this situation, one computer is selected to be the primary timeserver. The
+other computers are either direct clients of the server, or clients of clients.
+
+The <<local,*local*>> directive enables a local reference mode, which allows
+*chronyd* to appear synchronised even when it is not.
+
+The rate value in the server's drift file needs to be set to the average rate
+at which the server gains or loses time. *chronyd* includes support for this,
+in the form of the <<manual,*manual*>> directive and the
+<<chronyc.adoc#settime,*settime*>> command in the *chronyc* program.
+
+If the server is rebooted, *chronyd* can re-read the drift rate from the drift
+file. However, the server has no accurate estimate of the current time. To get
+around this, the system can be configured so that the server can initially set
+itself to a '`majority-vote`' of selected clients' times; this allows the
+clients to '`flywheel`' the server while it is rebooting.
+
+The <<smoothtime,*smoothtime*>> directive is useful when the clocks of the
+clients need to stay close together when the local time is adjusted by the
+<<chronyc.adoc#settime,*settime*>> command. The smoothing process needs to be
+activated by the <<chronyc.adoc#smoothtime,*smoothtime activate*>> command when
+the local time is ready to be served. After that point, any adjustments will be
+smoothed out.
+
+A typical configuration file for the server (called _ntp.local_) might be
+(assuming the clients and the server are in the _192.168.165.x_ subnet):
+
+----
+initstepslew 1 client1 client3 client6
+driftfile @CHRONYVARDIR@/drift
+local stratum 8
+manual
+allow 192.168.165.0/24
+smoothtime 400 0.01
+rtcsync
+----
+
+For the clients that have to resynchronise the server when it restarts,
+the configuration file might be:
+
+----
+server ntp.local iburst
+driftfile @CHRONYVARDIR@/drift
+allow 192.168.165.0/24
+makestep 1.0 3
+rtcsync
+----
+
+The rest of the clients would be the same, except that the *allow* directive is
+not required.
+
+If there is no suitable computer to be designated as the primary server, or
+there is a requirement to keep the clients synchronised even when it fails, the
+*orphan* option of the *local* directive enables a special mode where the
+server is selected from multiple computers automatically. They all need to use
+the same *local* configuration and poll one another. The server with the
+smallest reference ID (which is based on its IP address) will take the role of
+the primary server and others will be synchronised to it. When it fails, the
+server with the second smallest reference ID will take over and so on.
+
+A configuration file for the first server might be (assuming there are three
+servers called _ntp1.local_, _ntp2.local_, and _ntp3.local_):
+
+----
+initstepslew 1 ntp2.local ntp3.local
+server ntp2.local
+server ntp3.local
+driftfile @CHRONYVARDIR@/drift
+local stratum 8 orphan
+manual
+allow 192.168.165.0/24
+rtcsync
+----
+
+The other servers would be the same, except the hostnames in the *initstepslew*
+and *server* directives would be modified to specify the other servers. Their
+clients might be configured to poll all three servers.
+
+=== RTC tracking
+
+This section considers a computer which has occasional connections to the
+Internet and is turned off between '`sessions`'. In this case, *chronyd* relies
+on the computer's RTC to maintain the time between the periods when it is
+powered up. It assumes that Linux is run exclusively on the computer. Dual-boot
+systems might work; it depends what (if anything) the other system does to the
+RTC. On 2.6 and later kernels, if your motherboard has a HPET, you will need to
+enable the *HPET_EMULATE_RTC* option in your kernel configuration. Otherwise,
+*chronyd* will not be able to interact with the RTC device and will give up
+using it.
+
+When the computer is connected to the Internet, *chronyd* has access to
+external NTP servers which it makes measurements from. These measurements are
+saved, and straight-line fits are performed on them to provide an estimate of
+the computer's time error and rate of gaining or losing time.
+
+When the computer is taken offline from the Internet, the best estimate of the
+gain or loss rate is used to free-run the computer until it next goes online.
+
+Whilst the computer is running, *chronyd* makes measurements of the RTC (via
+the _/dev/rtc_ interface, which must be compiled into the kernel). An estimate
+is made of the RTC error at a particular RTC second, and the rate at which the
+RTC gains or loses time relative to true time.
+
+When the computer is powered down, the measurement histories for all the NTP
+servers are saved to files, and the RTC tracking information is also
+saved to a file (if the <<rtcfile,*rtcfile*>> directive has been specified).
+These pieces of information are also saved if the <<chronyc.adoc#dump,*dump*>>
+and <<chronyc.adoc#writertc,*writertc*>> commands respectively are issued
+through *chronyc*.
+
+When the computer is rebooted, *chronyd* reads the current RTC time and the RTC
+information saved at the last shutdown. This information is used to set the
+system clock to the best estimate of what its time would have been now, had it
+been left running continuously. The measurement histories for the servers are
+then reloaded.
+
+The next time the computer goes online, the previous sessions' measurements can
+contribute to the line-fitting process, which gives a much better estimate of
+the computer's gain or loss rate.
+
+One problem with saving the measurements and RTC data when the machine is shut
+down is what happens if there is a power failure; the most recent data will not
+be saved. Although *chronyd* is robust enough to cope with this, some
+performance might be lost. (The main danger arises if the RTC has been changed
+during the session, with the *trimrtc* command in *chronyc*. Because of this,
+*trimrtc* will make sure that a meaningful RTC file is saved after the
+change is completed).
+
+The easiest protection against power failure is to put the *dump* and
+*writertc* commands in the same place as the *offline* command is issued to
+take *chronyd* offline; because *chronyd* free-runs between online sessions, no
+parameters will change significantly between going offline from the Internet
+and any power failure.
+
+A final point regards computers which are left running for extended periods and
+where it is desired to spin down the hard disc when it is not in use (e.g. when
+not accessed for 15 minutes). *chronyd* has been planned so it supports such
+operation; this is the reason why the RTC tracking parameters are not saved to
+disc after every update, but only when the user requests such a write, or
+during the shutdown sequence. The only other facility that will generate
+periodic writes to the disc is the *log rtc* facility in the configuration
+file; this option should not be used if you want your disc to spin down.
+
+To illustrate how a computer might be configured for this case, example
+configuration files are shown.
+
+For the _chrony.conf_ file, the following can be used as an example.
+
+----
+server ntp1.example.net maxdelay 0.4 offline
+server ntp2.example.net maxdelay 0.4 offline
+server ntp3.example.net maxdelay 0.4 offline
+logdir /var/log/chrony
+log statistics measurements tracking
+driftfile @CHRONYVARDIR@/drift
+makestep 1.0 3
+maxupdateskew 100.0
+dumpdir @CHRONYVARDIR@
+rtcfile @CHRONYVARDIR@/rtc
+----
+
+*pppd* is used for connecting to the Internet. This runs two scripts
+_/etc/ppp/ip-up_ and _/etc/ppp/ip-down_ when the link goes online and offline
+respectively.
+
+The relevant part of the _/etc/ppp/ip-up_ file is:
+
+----
+@BINDIR@/chronyc online
+----
+
+and the relevant part of the _/etc/ppp/ip-down_ script is:
+
+----
+@BINDIR@/chronyc -m offline dump writertc
+----
+
+*chronyd* is started during the boot sequence with the *-r* and *-s* options.
+It might need to be started before any software that depends on the system clock
+not jumping or moving backwards, depending on the directives in *chronyd*'s
+configuration file.
+
+For the system shutdown, *chronyd* should receive a SIGTERM several seconds
+before the final SIGKILL; the SIGTERM causes the measurement histories and RTC
+information to be saved.
+
+=== Public NTP server
+
+*chronyd* can be configured to operate as a public NTP server, e.g. to join the
+https://www.pool.ntp.org/en/join.html[pool.ntp.org] project. The configuration
+is similar to the NTP client with permanent connection, except it needs to
+allow client access from all addresses. It is recommended to find at least four
+good servers (e.g. from the pool, or on the NTP homepage). If the server has a
+hardware reference clock (e.g. a GPS receiver), it can be specified by the
+<<refclock,*refclock*>> directive.
+
+The amount of memory used for logging client accesses can be increased in order
+to enable clients to use the interleaved mode even when the server has a large
+number of clients, and better support rate limiting if it is enabled by the
+<<ratelimit,*ratelimit*>> directive. The system timezone database, if it is
+kept up to date and includes the _right/UTC_ timezone, can be used as a
+reliable source to determine when a leap second will be applied to UTC. The
+*-r* option with the <<dumpdir,*dumpdir*>> directive shortens the time in which
+*chronyd* will not be able to serve time to its clients when it needs to be
+restarted (e.g. after upgrading to a newer version, or a change in the
+configuration).
+
+The configuration file could look like:
+
+----
+server ntp1.example.net iburst
+server ntp2.example.net iburst
+server ntp3.example.net iburst
+server ntp4.example.net iburst
+makestep 1.0 3
+rtcsync
+allow
+clientloglimit 100000000
+leapsectz right/UTC
+driftfile @CHRONYVARDIR@/drift
+dumpdir @CHRONYRUNDIR@
+----
+
+== SEE ALSO
+
+<<chronyc.adoc#,*chronyc(1)*>>, <<chronyd.adoc#,*chronyd(8)*>>
+
+== BUGS
+
+For instructions on how to report bugs, please visit
+https://chrony-project.org/.
+
+== AUTHORS
+
+chrony was written by Richard Curnow, Miroslav Lichvar, and others.