From b2d2d555a704148968cb7e566735a2a1b1a2f189 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Tue, 9 Apr 2024 14:48:01 +0200 Subject: Adding upstream version 4.5. Signed-off-by: Daniel Baumann --- doc/chrony.conf.adoc | 3160 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3160 insertions(+) create mode 100644 doc/chrony.conf.adoc (limited to 'doc/chrony.conf.adoc') 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 <> 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 <> 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 <> 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 +<> 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 <> 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 <> 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 +<> directive. +*maxsamples* _samples_::: +Set the maximum number of samples kept for this source. This overrides the +<> 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 <> 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 <> command from *chronyc* +when disconnecting the network link. (It will still be necessary to use the +<> 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. +<> 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 <> directive and setting the *port* option to +the PTP port. The corrections are applied only to NTP measurements with HW +timestamps (enabled by the <> 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 <> +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 <> 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 <> +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 +<> directive on both hosts) instead. + +[[initstepslew]]*initstepslew* _step-threshold_ [_hostname_]...:: +(This directive is deprecated in favour of the <> +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 <> 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 +<> and <> 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 +<> 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 +<> 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 +<> 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 +<> directive. +*maxsamples* _samples_::: +Set the maximum number of samples kept for this source. This overrides the +<> directive. + +[[manual]]*manual*:: +The *manual* directive enables support at run-time for the +<> 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 <> 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 <> 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 <> and <> +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 <> 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 <> and <> +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 <> and <> +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 +<> and +<> 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 <> 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 <> 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 +<> 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 <> 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 +<> 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 <> +directive. The current remaining correction is shown in the +<> 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 +<> 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 <> 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. <> 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 <> 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 <> 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 <> 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 <> +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 <> 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 <> 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 <> +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 <> 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 <> 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 <> directive, or the +<> 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 <> and +<> 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 <> 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 +<> 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 <> 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 +<> 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 +<> directive or the <> 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 +<> 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 <> +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 +<> 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 <> directive or the +<> command in *chronyc*. The process can be +reset without stepping the clock by the <> 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 <> +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 <> command, which is particularly useful when the clock is +synchronised only with manual input and the skew is always larger than the +threshold. The <> 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 <> 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 +<> directive to not listen only on the +loopback interface to actually allow remote access. + +[[cmddeny]]*cmddeny* [*all*] [_subnet_]:: +This is similar to the <> 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 <> 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 <> +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 <> 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 <> 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 <> 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 <> file +and is not relevant for the <> 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 <> directive. ++ +On Linux, the RTC copy is performed by the kernel every 11 minutes. ++ +On macOS, <> 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 <> +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 + <> directive). +* _~_ - has a jitter larger than the maximum jitter (configured by the + <> 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 <> 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 + <> 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 <> + 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 <> 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 <> +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 +<> 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 <> 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 <> or the +<> 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 <> +directive) and the <> report. On the server +side, the number of served timestamps from each source is provided in the +<> 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 <> +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 <> 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 <> 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 <> 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 +<>, <> and <> +might be particularly useful. Also, the *iburst* option of the +<> 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 <> +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 <> and +<> 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 <> 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 <> directive and the +<> 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 <> directive is useful when the clocks of the +clients need to stay close together when the local time is adjusted by the +<> command. The smoothing process needs to be +activated by the <> 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 <> directive has been specified). +These pieces of information are also saved if the <> +and <> 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 +<> 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 +<> 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 <> 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 + +<>, <> + +== 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. -- cgit v1.2.3