diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.in | 76 | ||||
| -rw-r--r-- | doc/chrony.conf.adoc | 3160 | ||||
| -rw-r--r-- | doc/chrony.conf.man.in | 5043 | ||||
| -rw-r--r-- | doc/chronyc.adoc | 1559 | ||||
| -rw-r--r-- | doc/chronyc.man.in | 2756 | ||||
| -rw-r--r-- | doc/chronyd.adoc | 235 | ||||
| -rw-r--r-- | doc/chronyd.man.in | 278 | ||||
| -rw-r--r-- | doc/faq.adoc | 1172 | ||||
| -rw-r--r-- | doc/installation.adoc | 200 |
9 files changed, 14479 insertions, 0 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..1777da5 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,76 @@ +ADOC = asciidoctor +ADOC_FLAGS = +SED = sed +HTML_TO_TXT = w3m -dump -T text/html + +MAN_FILES = chrony.conf.man chronyc.man chronyd.man +TXT_FILES = faq.txt installation.txt +HTML_FILES = $(MAN_FILES:%.man=%.html) $(TXT_FILES:%.txt=%.html) +MAN_IN_FILES = $(MAN_FILES:%.man=%.man.in) + +SYSCONFDIR = @SYSCONFDIR@ +BINDIR = @BINDIR@ +SBINDIR = @SBINDIR@ +MANDIR = @MANDIR@ +DOCDIR = @DOCDIR@ +CHRONYRUNDIR = @CHRONYRUNDIR@ +CHRONYVARDIR = @CHRONYVARDIR@ +CHRONY_VERSION = @CHRONY_VERSION@ +DEFAULT_USER = @DEFAULT_USER@ +DEFAULT_HWCLOCK_FILE = @DEFAULT_HWCLOCK_FILE@ +DEFAULT_PID_FILE = @DEFAULT_PID_FILE@ +DEFAULT_RTC_DEVICE = @DEFAULT_RTC_DEVICE@ + +SED_COMMANDS = "s%\@SYSCONFDIR\@%$(SYSCONFDIR)%g;\ + s%\@BINDIR\@%$(BINDIR)%g;\ + s%\@SBINDIR\@%$(SBINDIR)%g;\ + s%\@CHRONY_VERSION\@%$(CHRONY_VERSION)%g;\ + s%\@DEFAULT_HWCLOCK_FILE\@%$(DEFAULT_HWCLOCK_FILE)%g;\ + s%\@DEFAULT_PID_FILE\@%$(DEFAULT_PID_FILE)%g;\ + s%\@DEFAULT_RTC_DEVICE\@%$(DEFAULT_RTC_DEVICE)%g;\ + s%\@DEFAULT_USER\@%$(DEFAULT_USER)%g;\ + s%\@CHRONYRUNDIR\@%$(CHRONYRUNDIR)%g;\ + s%\@CHRONYVARDIR\@%$(CHRONYVARDIR)%g;" + +man: $(MAN_FILES) $(MAN_IN_FILES) +html: $(HTML_FILES) +txt: $(TXT_FILES) +docs: man html + +%.html: %.adoc + $(ADOC) $(ADOC_FLAGS) -b html -o - $< | $(SED) -e $(SED_COMMANDS) > $@ + +%.man.in: %.adoc + $(ADOC) $(ADOC_FLAGS) -b manpage -o $@ $< + +%.man: %.man.in + $(SED) -e $(SED_COMMANDS) < $< > $@ + +%.txt: %.html + $(HTML_TO_TXT) < $< > $@ + +install: $(MAN_FILES) + [ -d $(DESTDIR)$(MANDIR)/man1 ] || mkdir -p $(DESTDIR)$(MANDIR)/man1 + [ -d $(DESTDIR)$(MANDIR)/man5 ] || mkdir -p $(DESTDIR)$(MANDIR)/man5 + [ -d $(DESTDIR)$(MANDIR)/man8 ] || mkdir -p $(DESTDIR)$(MANDIR)/man8 + cp chronyc.man $(DESTDIR)$(MANDIR)/man1/chronyc.1 + chmod 644 $(DESTDIR)$(MANDIR)/man1/chronyc.1 + cp chronyd.man $(DESTDIR)$(MANDIR)/man8/chronyd.8 + chmod 644 $(DESTDIR)$(MANDIR)/man8/chronyd.8 + cp chrony.conf.man $(DESTDIR)$(MANDIR)/man5/chrony.conf.5 + chmod 644 $(DESTDIR)$(MANDIR)/man5/chrony.conf.5 + +install-docs: $(HTML_FILES) + [ -d $(DESTDIR)$(DOCDIR) ] || mkdir -p $(DESTDIR)$(DOCDIR) + for f in $(HTML_FILES); do \ + cp $$f $(DESTDIR)$(DOCDIR); \ + chmod 644 $(DESTDIR)$(DOCDIR)/$$f; \ + done + +clean: + rm -f $(MAN_FILES) $(TXT_FILES) $(HTML_FILES) + rm -f $(MAN_IN_FILES) + +distclean: + rm -f $(MAN_FILES) $(TXT_FILES) $(HTML_FILES) + rm -f Makefile diff --git a/doc/chrony.conf.adoc b/doc/chrony.conf.adoc new file mode 100644 index 0000000..cb3f95c --- /dev/null +++ b/doc/chrony.conf.adoc @@ -0,0 +1,3160 @@ +// This file is part of chrony +// +// Copyright (C) Richard P. Curnow 1997-2003 +// Copyright (C) Stephen Wadeley 2016 +// Copyright (C) Bryan Christianson 2017 +// Copyright (C) Miroslav Lichvar 2009-2023 +// +// This program is free software; you can redistribute it and/or modify +// it under the terms of version 2 of the GNU General Public License as +// published by the Free Software Foundation. +// +// This program is distributed in the hope that it will be useful, but +// WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +// General Public License for more details. +// +// You should have received a copy of the GNU General Public License along +// with this program; if not, write to the Free Software Foundation, Inc., +// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + += chrony.conf(5) +:doctype: manpage +:man manual: Configuration Files +:man source: chrony @CHRONY_VERSION@ + +== NAME +chrony.conf - chronyd configuration file + +== SYNOPSIS +*chrony.conf* + +== DESCRIPTION + +This file configures the *chronyd* daemon. The compiled-in location is +_@SYSCONFDIR@/chrony.conf_. Other locations can be specified on the +*chronyd* command line with the *-f* option. + +Each directive in the configuration file is placed on a separate line. The +following sections describe each of the directives in turn. The directives are +not case-sensitive. Generally, the directives can occur in any order in the file +and if a directive is specified multiple times, only the last one will be +effective. Exceptions are noted in the descriptions. + +The configuration directives can also be specified directly on the *chronyd* +command line. In this case each argument is parsed as a new line and the +configuration file is ignored. + +While the number of supported directives is large, only a few of them are +typically needed. See the <<examples,*EXAMPLES*>> section for configuration in +typical operating scenarios. + +The configuration file might contain comment lines. A comment line is any line +that starts with zero or more spaces followed by any one of the following +characters: *!*, *;*, *#*, *%*. Any line with this format will be ignored. + +== DIRECTIVES + +=== Time sources + +[[server]]*server* _hostname_ [_option_]...:: +The *server* directive specifies an NTP server which can be used as a time +source. The client-server relationship is strictly hierarchical: a client might +synchronise its system time to that of the server, but the server's system time +will never be influenced by that of a client. ++ +The server can be specified by its hostname or IP address. If the hostname cannot +be resolved on start, *chronyd* will try it again in increasing intervals, and +also when the <<chronyc.adoc#online,*online*>> command is issued in *chronyc*. ++ +The DNS record can change over time. The used address will be replaced with a +newly resolved address when the server becomes unreachable (i.e. no valid +response to last 8 requests), unsynchronised, a falseticker (i.e. does not +agree with a majority of other sources), or the root distance is too large (the +limit can be configured by the <<maxdistance,*maxdistance*>> directive). The +automatic replacement happens at most once per 30 minutes. ++ +This directive can be used multiple times to specify multiple servers. ++ +The directive supports the following options: ++ +*minpoll* _poll_::: +This option specifies the minimum interval between requests sent to the server +as a power of 2 in seconds. For example, *minpoll 5* would mean that the +polling interval should not drop below 32 seconds. The default is 6 (64 +seconds), the minimum is -7 (1/128th of a second), and the maximum is 24 (6 +months). Note that intervals shorter than 6 (64 seconds) should generally not +be used with public servers on the Internet, because it might be considered +abuse. A sub-second interval will be enabled only when the server is reachable +and the round-trip delay is shorter than 10 milliseconds, i.e. the server +should be in a local network. +*maxpoll* _poll_::: +This option specifies the maximum interval between requests sent to the server +as a power of 2 in seconds. For example, *maxpoll 9* indicates that the polling +interval should stay at or below 9 (512 seconds). The default is 10 (1024 +seconds), the minimum is -7 (1/128th of a second), and the maximum is 24 (6 +months). +*iburst*::: +With this option, *chronyd* will start with a burst of 4-8 requests in order to +make the first update of the clock sooner. It will also repeat the burst every +time the source is switched from the offline state to online with the +<<chronyc.adoc#online,*online*>> command in *chronyc*. +*burst*::: +With this option, *chronyd* will send a burst of up to 4 requests when it +cannot get a good measurement from the +server. The number of requests in the burst is limited by the current polling +interval to keep the average interval at or above the minimum interval, i.e. +the current interval needs to be at least two times longer than the minimum +interval in order to allow a burst with two requests. +*key* _ID_::: +The NTP protocol supports a message authentication code (MAC) to prevent +computers having their system time upset by rogue packets being sent to them. +The MAC is generated as a function of a key specified in the key file, +which is specified by the <<keyfile,*keyfile*>> directive. ++ +The *key* option specifies which key (with an ID in the range 1 through 2^32-1) +should *chronyd* use to authenticate requests sent to the server and verify its +responses. The server must have the same key for this number configured, +otherwise no relationship between the computers will be possible. ++ +If the server is running *ntpd* and the output size of the hash function used +by the key is longer than 160 bits (e.g. SHA256), the *version* option needs to +be set to 4 for compatibility. +*nts*::: +This option enables authentication using the Network Time Security (NTS) +mechanism. Unlike with the *key* option, the server and client do not need to +share a key in a key file. NTS has a Key Establishment (NTS-KE) protocol using +the Transport Layer Security (TLS) protocol to get the keys and cookies +required by NTS for authentication of NTP packets. +*certset* _ID_::: +This option specifies which set of trusted certificates should be used to verify +the server's certificate when the *nts* option is enabled. Sets of certificates +can be specified with the <<ntstrustedcerts,*ntstrustedcerts*>> directive. The +default set is 0, which by default contains certificates of the system's +default trusted certificate authorities. +*maxdelay* _delay_::: +*chronyd* uses the network round-trip delay to the server to determine how +accurate a particular measurement is likely to be. Long round-trip delays +indicate that the request, or the response, or both were delayed. If only one +of the messages was delayed the measurement error is likely to be substantial. ++ +For small variations in the round-trip delay, *chronyd* uses a weighting scheme +when processing the measurements. However, beyond a certain level of delay the +measurements are likely to be so corrupted as to be useless. (This is +particularly so on wireless networks and other slow links, where a long delay +probably indicates a highly asymmetric delay caused by the response waiting +behind a lot of packets related to a download of some sort). ++ +If the user knows that round trip delays above a certain level should cause the +measurement to be ignored, this level can be defined with the *maxdelay* +option. For example, *maxdelay 0.3* would indicate that measurements with a +round-trip delay greater than 0.3 seconds should be ignored. The default value +is 3 seconds and the maximum value is 1000 seconds. +*maxdelayratio* _ratio_::: +This option is similar to the *maxdelay* option above. *chronyd* keeps a record +of the minimum round-trip delay amongst the previous measurements that it has +buffered. If a measurement has a round-trip delay that is greater than the +specified ratio times the minimum delay, it will be rejected. By default, this +test is disabled. +*maxdelaydevratio* _ratio_::: +If a measurement has a ratio of the increase in the round-trip delay from the +minimum delay amongst the previous measurements to the standard deviation of +the previous measurements that is greater than the specified ratio, it will be +rejected. The default is 10.0. +*maxdelayquant* _p_::: +This option disables the *maxdelaydevratio* test and specifies the maximum +acceptable delay as a quantile of the round-trip delay instead of a function of +the minimum delay amongst the buffered measurements. If a measurement has a +round-trip delay that is greater than a long-term estimate of the _p_-quantile, +it will be rejected. ++ +The specified _p_ value should be between 0.05 and 0.95. For example, +*maxdelayquant 0.2* would indicate that only measurements with the lowest 20 +percent of round-trip delays should be accepted. Note that it can take many +measurements for the estimated quantile to reach the expected value. This +option is intended for synchronisation in mostly static local networks with +very short polling intervals and possibly combined with the *filter* option. +By default, this test is disabled in favour of the *maxdelaydevratio* test. +*mindelay* _delay_::: +This option specifies a fixed minimum round-trip delay to be used instead of +the minimum amongst the previous measurements. This can be useful in networks +with static configuration to improve the stability of corrections for +asymmetric jitter, weighting of the measurements, and the *maxdelayratio* and +*maxdelaydevratio* tests. The value should be set accurately in order to have a +positive effect on the synchronisation. +*asymmetry* _ratio_::: +This option specifies the asymmetry of the network jitter on the path to the +source, which is used to correct the measured offset according to the delay. +The asymmetry can be between -0.5 and +0.5. A negative value means the delay of +packets sent to the source is more variable than the delay of packets sent from +the source back. By default, *chronyd* estimates the asymmetry automatically. +*offset* _offset_::: +This option specifies a correction (in seconds) which will be applied to +offsets measured with this source. It's particularly useful to compensate for a +known asymmetry in network delay or timestamping errors. For example, if +packets sent to the source were on average delayed by 100 microseconds more +than packets sent from the source back, the correction would be -0.00005 (-50 +microseconds). The default is 0.0. +*minsamples* _samples_::: +Set the minimum number of samples kept for this source. This overrides the +<<minsamples,*minsamples*>> directive. +*maxsamples* _samples_::: +Set the maximum number of samples kept for this source. This overrides the +<<maxsamples,*maxsamples*>> directive. +*filter* _polls_::: +This option enables a median filter to reduce noise in NTP measurements. The +filter will process samples collected in the specified number of polls +into a single sample. It is intended to be used with very short polling +intervals in local networks where it is acceptable to generate a lot of NTP +traffic. +*offline*::: +If the server will not be reachable when *chronyd* is started, the *offline* +option can be specified. *chronyd* will not try to poll the server until it is +enabled to do so (by using the <<chronyc.adoc#online,*online*>> command in +*chronyc*). +*auto_offline*::: +With this option, the server will be assumed to have gone offline when sending +a request fails, e.g. due to a missing route to the network. This option avoids +the need to run the <<chronyc.adoc#offline,*offline*>> command from *chronyc* +when disconnecting the network link. (It will still be necessary to use the +<<chronyc.adoc#online,*online*>> command when the link has been established, to +enable measurements to start.) +*prefer*::: +Prefer this source over sources without the *prefer* option. +*noselect*::: +Never select this source. This is particularly useful for monitoring. +*trust*::: +Assume time from this source is always true. It can be rejected as a +falseticker in the source selection only if another source with this option +does not agree with it. +*require*::: +Require that at least one of the sources specified with this option is +selectable (i.e. recently reachable and not a falseticker) before updating the +clock. Together with the *trust* option this might be useful to allow a trusted +authenticated source to be safely combined with unauthenticated sources in +order to improve the accuracy of the clock. They can be selected and used for +synchronisation only if they agree with the trusted and required source. +*xleave*::: +This option enables the interleaved mode of NTP. It enables the server to +respond with more accurate transmit timestamps (e.g. kernel or hardware +timestamps), which cannot be contained in the transmitted packet itself and +need to refer to a previous packet instead. This can significantly improve the +accuracy and stability of the measurements. ++ +The interleaved mode is compatible with servers that support only the basic +mode. Note that even +servers that support the interleaved mode might respond in the basic mode as +the interleaved mode requires the servers to keep some state for each client +and the state might be dropped when there are too many clients (e.g. +<<clientloglimit,*clientloglimit*>> is too small), or it might be overwritten +by other clients that have the same IP address (e.g. computers behind NAT or +someone sending requests with a spoofed source address). ++ +The *xleave* option can be combined with the *presend* option in order to +shorten the interval in which the server has to keep the state to be able to +respond in the interleaved mode. +*polltarget* _target_::: +Target number of measurements to use for the regression algorithm which +*chronyd* will try to maintain by adjusting the polling interval between +*minpoll* and *maxpoll*. A higher target makes *chronyd* prefer shorter polling +intervals. The default is 8 and a useful range is from 6 to 60. +*port* _port_::: +This option allows the UDP port on which the server understands NTP requests to +be specified. For normal servers this option should not be required (the +default is 123, the standard NTP port). +*ntsport* _port_::: +This option specifies the TCP port on which the server is listening for NTS-KE +connections when the *nts* option is enabled. The default is 4460. +*presend* _poll_::: +If the timing measurements being made by *chronyd* are the only network data +passing between two computers, you might find that some measurements are badly +skewed due to either the client or the server having to do an ARP lookup on the +other party prior to transmitting a packet. This is more of a problem with long +sampling intervals, which might be similar in duration to the lifetime of entries +in the ARP caches of the machines. ++ +In order to avoid this problem, the *presend* option can be used. It takes a +single integer argument, which is the smallest polling interval for which an +extra pair of NTP packets will be exchanged between the client and the server +prior to the actual measurement. For example, with the following option +included in a *server* directive: ++ +---- +presend 9 +---- ++ +when the polling interval is 512 seconds or more, an extra NTP client packet +will be sent to the server a short time (2 seconds) before making the actual +measurement. ++ +If the *presend* option is used together with the *xleave* option, *chronyd* +will send two extra packets instead of one. +*minstratum* _stratum_::: +When the synchronisation source is selected from available sources, sources +with lower stratum are normally slightly preferred. This option can be used to +increase stratum of the source to the specified minimum, so *chronyd* will +avoid selecting that source. This is useful with low-stratum sources that are +known to be unreliable or inaccurate and which should be used only when other +sources are unreachable. +*version* _version_::: +This option sets the NTP version of packets sent to the server. This can be +useful when the server runs an old NTP implementation that does not respond to +requests using a newer version. The default version depends on other options. +If the *extfield* or *xleave* option is used, the default version is 4. If +those options are not used and the *key* option specifies a key using a hash +function with output size longer than 160 bits (e.g. SHA256), the default +version is 3 for compatibility with older *chronyd* servers. In other cases, +the default version is 4. +*copy*::: +This option specifies that the server and client are closely related, their +configuration does not allow a synchronisation loop to form between them, and +the client is allowed to assume the reference ID and stratum of the server. +This is useful when multiple instances of `chronyd` are running on one computer +(e.g. for security or performance reasons), one primarily operating as a client +to synchronise the system clock and other instances started with the *-x* +option to operate as NTP servers for other computers with their NTP clocks +synchronised to the first instance. +*extfield* _type_::: +This option enables an NTPv4 extension field specified by its type as a +hexadecimal number. It will be included in requests sent to the server and +processed in received responses if the server supports it. Note that some +server implementations do not respond to requests containing an unknown +extension field (*chronyd* as a server responded to such requests since +version 2.0). ++ +This option can be used multiple times to enable multiple extension fields. ++ +The following extension fields are supported: ++ +_F323_:::: +An experimental extension field to enable several improvements that were +proposed for the next version of the NTP protocol (NTPv5). The field contains +root delay and dispersion in higher resolution and a monotonic receive +timestamp, which enables a frequency transfer between the server and client to +significantly improve stability of the synchronisation. This field should be +enabled only for servers known to be running *chronyd* version 4.2 or later. +_F324_:::: +An experimental extension field to enable the use of the Precision Time +Protocol (PTP) correction field in NTP-over-PTP messages updated by one-step +end-to-end transparent clocks in network switches and routers to significantly +improve accuracy and stability of the synchronisation. NTP-over-PTP can be +enabled by the <<ptpport,*ptpport*>> directive and setting the *port* option to +the PTP port. The corrections are applied only to NTP measurements with HW +timestamps (enabled by the <<hwtimestamp,*hwtimestamp*>> directive). This +field should be enabled only for servers known to be running *chronyd* version +4.5 or later. +{blank}::: + +[[pool]]*pool* _name_ [_option_]...:: +The syntax of this directive is similar to that for the <<server,*server*>> +directive, except that it is used to specify a pool of NTP servers rather than +a single NTP server. The pool name is expected to resolve to multiple addresses +which might change over time. ++ +This directive can be used multiple times to specify multiple pools. ++ +All options valid in the <<server,*server*>> directive can be used in this +directive too. There is one option specific to the *pool* directive: ++ +*maxsources* _sources_::: +This option sets the desired number of sources to be used from the pool. +*chronyd* will repeatedly try to resolve the name until it gets this number of +sources responding to requests. The default value is 4 and the maximum value is +16. ++ +An example of the *pool* directive is ++ +---- +pool pool.ntp.org iburst maxsources 3 +---- + +[[peer]]*peer* _hostname_ [_option_]...:: +The syntax of this directive is identical to that for the <<server,*server*>> +directive, except that it specifies a symmetric association with an NTP peer +instead of a client/server association with an NTP server. A single symmetric +association allows the peers to be both servers and clients to each other. This +is mainly useful when the NTP implementation of the peer (e.g. *ntpd*) supports +ephemeral symmetric associations and does not need to be configured with an +address of this host. *chronyd* does not support ephemeral associations. ++ +This directive can be used multiple times to specify multiple peers. ++ +The following options of the *server* directive do not work in the *peer* +directive: *iburst*, *burst*, *nts*, *presend*, *copy*. ++ +When using the *xleave* option, both peers must support and have enabled the +interleaved mode, otherwise the synchronisation will work in one direction +only. +When a key is specified by the *key* option to enable authentication, both +peers must use the same key and the same key number. ++ +Note that the symmetric mode is less secure than the client/server mode. A +denial-of-service attack is possible on unauthenticated symmetric associations, +i.e. when the peer was specified without the *key* option. An attacker who does +not see network traffic between two hosts, but knows that they are peering with +each other, can periodically send them unauthenticated packets with spoofed +source addresses in order to disrupt their NTP state and prevent them from +synchronising to each other. When the association is authenticated, an attacker +who does see the network traffic, but cannot prevent the packets from reaching +the other host, can still disrupt the state by replaying old packets. The +attacker has effectively the same power as a man-in-the-middle attacker. A +partial protection against this attack is implemented in *chronyd*, which can +protect the peers if they are using the same polling interval and they never +sent an authenticated packet with a timestamp from future, but it should not be +relied on as it is difficult to ensure the conditions are met. If two hosts +should be able to synchronise to each other in both directions, it is +recommended to use two separate client/server associations (specified by the +<<server,*server*>> directive on both hosts) instead. + +[[initstepslew]]*initstepslew* _step-threshold_ [_hostname_]...:: +(This directive is deprecated in favour of the <<makestep,*makestep*>> +directive.) ++ +The purpose of the *initstepslew* directive is to allow *chronyd* to make a +rapid measurement of the system clock error at boot time, and to correct the +system clock by stepping before normal operation begins. Since this would +normally be performed only at an appropriate point in the system boot sequence, +no other software should be adversely affected by the step. ++ +If the correction required is less than a specified threshold, a slew is used +instead. This makes it safer to restart *chronyd* whilst the system is in +normal operation. ++ +The *initstepslew* directive takes a threshold and a list of NTP servers as +arguments. Each of the servers is rapidly polled several times, and a majority +voting mechanism used to find the most likely range of system clock error that +is present. A step or slew is applied to the system clock to correct this +error. *chronyd* then enters its normal operating mode. ++ +An example of the use of the directive is: ++ +---- +initstepslew 30 ntp1.example.net ntp2.example.net ntp3.example.net +---- ++ +where 3 NTP servers are used to make the measurement. The _30_ indicates that +if the system's error is found to be 30 seconds or less, a slew will be used to +correct it; if the error is above 30 seconds, a step will be used. ++ +The *initstepslew* directive can also be used in an isolated LAN environment, +where the clocks are set manually. The most stable computer is chosen as the +primary server and the other computers are its clients. If each of the clients +is configured with the <<local,*local*>> directive, the server can be set up +with an *initstepslew* directive which references some or all of the clients. +Then, if the server machine has to be rebooted, the clients can be relied on to +act analogously to a flywheel and preserve the time for a short period while +the server completes its reboot. ++ +The *initstepslew* directive is functionally similar to a combination of the +<<makestep,*makestep*>> and <<server,*server*>> directives with the *iburst* +option. The main difference is that the *initstepslew* servers are used only +before normal operation begins and that the foreground *chronyd* process waits +for *initstepslew* to finish before exiting. This prevent programs started in +the boot sequence after *chronyd* from reading the clock before it has been +stepped. With the *makestep* directive, the +<<chronyc.adoc#waitsync,*waitsync*>> command of *chronyc* can be used instead. + +[[refclock]]*refclock* _driver_ _parameter_[:__option__]... [_option_]...:: +The *refclock* directive specifies a hardware reference clock to be used as a +time source. It has two mandatory parameters, a driver name and a +driver-specific parameter. The two parameters are followed by zero or more +refclock options. Some drivers have special options, which can be appended to +the driver-specific parameter using the *:* character. ++ +This directive can be used multiple times to specify multiple reference clocks. ++ +There are four drivers included in *chronyd*: ++ +*PPS*::: +Driver for the kernel PPS (pulse per second) API. The parameter is the path to +the PPS device (typically _/dev/pps?_). As PPS refclocks do not supply full +time, another time source (e.g. NTP server or non-PPS refclock) is needed to +complete samples from the PPS refclock. An alternative is to enable the +<<local,*local*>> directive to allow synchronisation with some unknown but +constant offset. The driver supports the following option: ++ +*clear*:::: +By default, the PPS refclock uses assert events (rising edge) for +synchronisation. With this option, it will use clear events (falling edge) +instead. ++ +{blank}::: +Examples: ++ +---- +refclock PPS /dev/pps0 lock NMEA refid GPS1 +refclock SOCK /var/run/chrony.clk.ttyS0.sock offset 0.5 delay 0.2 refid NMEA noselect +refclock PPS /dev/pps1:clear refid GPS2 +---- ++ +*SOCK*::: +Unix domain socket driver. This driver uses a datagram socket to receive +samples from another application running on the system. The parameter is the +path to the socket, which *chronyd* will create on start. The format of the +messages is described in the _refclock_sock.c_ file in the chrony source code. ++ +An application which supports the SOCK protocol is the *gpsd* daemon. It can +provide accurate measurements using the receiver's PPS signal, and since +version 3.25 also (much less accurate) measurements based on the timing of +serial data (e.g. NMEA), which can be useful when the receiver does not provide +a PPS signal, or it cannot be connected to the computer. The paths where *gpsd* +expects the sockets to be created by *chronyd* are described in the *gpsd(8)* +man page. Note that *gpsd* needs to be started after *chronyd* in order to +connect to the socket. ++ +Examples: ++ +---- +refclock SOCK /var/run/chrony.ttyS0.sock refid GPS1 poll 2 filter 4 +refclock SOCK /var/run/chrony.clk.ttyUSB0.sock refid GPS2 offset 0.2 delay 0.1 +---- ++ +*SHM*::: +NTP shared memory driver. This driver implements the protocol of the *ntpd* +driver type 28. It is functionally similar to the SOCK driver, but uses a +shared memory segment instead of a socket. The parameter is the unit number, +typically a small number like 0, 1, 2, or 3, from which is derived the key of +the memory segment as 0x4e545030 + unit. ++ +The driver supports the following option: ++ +*perm*=_mode_:::: +This option specifies the permissions of the shared memory segment created by +*chronyd*. They are specified as a numeric mode. The default value is 0600 +(read-write access for owner only). +{blank}::: ++ +Unlike with the SOCK driver, there is no prescribed order of starting *chronyd* +and the program providing measurements. Both are expected to create the memory +segment if it does not exist. *chronyd* will attach to an existing segment even +if it has a different owner than root or different permissions than the +permissions specified by the *perm* option. The segment needs to be created +before untrusted applications or users can execute code to prevent an attacker +from feeding *chronyd* with false measurements. The owner and permissions of +the segment can be verified with the *ipcs -m* command. For this reason, the +SHM driver is deprecated in favor of SOCK. ++ +Examples: ++ +---- +refclock SHM 0 poll 3 refid GPS1 +refclock SHM 1:perm=0644 refid GPS2 +---- ++ +*PHC*::: +PTP hardware clock (PHC) driver. The parameter is the path to the device of +the PTP clock which should be used as a time source. If the clock is kept in +TAI instead of UTC (e.g. it is synchronised by a PTP daemon), the current +UTC-TAI offset needs to be specified by the *offset* option. Alternatively, the +*pps* refclock option can be enabled to treat the PHC as a PPS refclock, using +only the sub-second offset for synchronisation. The driver supports the +following options: ++ +*nocrossts*:::: +This option disables use of precise cross timestamping. +*extpps*:::: +This option enables a PPS mode in which the PTP clock is timestamping pulses +of an external PPS signal connected to the clock. The clock does not need to be +synchronised, but another time source is needed to complete the PPS samples. +Note that some PTP clocks cannot be configured to timestamp only assert or +clear events, and it is necessary to use the *width* option to filter wrong +PPS samples. +*pin*=_index_:::: +This option specifies the index of the pin which should be enabled for the +PPS timestamping. If the PHC does not have configurable pins (i.e. the channel +function is fixed), the index needs to be set to -1 to disable the pin +configuration. The default value is 0. +*channel*=_index_:::: +This option specifies the index of the channel for the PPS mode. The default +value is 0. +*clear*:::: +This option enables timestamping of clear events (falling edge) instead of +assert events (rising edge) in the PPS mode. This may not work with some +clocks. +{blank}::: ++ +Examples: ++ +---- +refclock PHC /dev/ptp0 poll 0 dpoll -2 offset -37 +refclock PHC /dev/ptp1:nocrossts poll 3 pps +refclock PHC /dev/ptp2:extpps:pin=1 width 0.2 poll 2 +---- ++ +{blank}:: +The *refclock* directive supports the following options: ++ +*poll* _poll_::: +Timestamps produced by refclock drivers are not used immediately, but they are +stored and processed by a median filter in the polling interval specified by +this option. This is defined as a power of 2 and can be negative to specify a +sub-second interval. The default is 4 (16 seconds). A shorter interval allows +*chronyd* to react faster to changes in the frequency of the system clock, but +it might have a negative effect on its accuracy if the samples have a lot of +jitter. +*dpoll* _dpoll_::: +Some drivers do not listen for external events and try to produce samples in +their own polling interval. This is defined as a power of 2 and can be negative +to specify a sub-second interval. The default is 0 (1 second). +*refid* _refid_::: +This option is used to specify the reference ID of the refclock, as up to four +ASCII characters. The default reference ID is composed from the first three +characters of the driver name and the number of the refclock. Each refclock +must have a unique reference ID. +*lock* _refid_::: +This option can be used to lock a PPS refclock to another refclock, which is +specified by its reference ID. In this mode received PPS samples are paired +directly with raw samples from the specified refclock. +*rate* _rate_::: +This option sets the rate of the pulses in the PPS signal (in Hz). This option +controls how the pulses will be completed with real time. To actually receive +more than one pulse per second, a negative *dpoll* has to be specified (-3 for +a 5Hz signal). The default is 1. +*maxlockage* _pulses_::: +This option specifies in number of pulses how old can be samples from the +refclock specified by the *lock* option to be paired with the pulses. +Increasing this value is useful when the samples are produced at a lower rate +than the pulses. The default is 2. +*width* _width_::: +This option specifies the width of the pulses (in seconds). It is used to +filter PPS samples when the driver provides samples for both rising and falling +edges. Note that it reduces the maximum allowed error of the time source which +completes the PPS samples. If the duty cycle is configurable, 50% should be +preferred in order to maximise the allowed error. +*pps*::: +This options forces *chronyd* to treat any refclock (e.g. SHM or PHC) as a PPS +refclock. This can be useful when the refclock provides time with a variable +offset of a whole number of seconds (e.g. it uses TAI instead of UTC). Another +time source is needed to complete samples from the refclock. +*offset* _offset_::: +This option can be used to compensate for a constant error. The specified +offset (in seconds) is applied to all samples produced by the reference clock. +The default is 0.0. +*delay* _delay_::: +This option sets the NTP delay of the source (in seconds). Half of this value +is included in the maximum assumed error which is used in the source selection +algorithm. Increasing the delay is useful to avoid having no majority in the +source selection or to make it prefer other sources. The default is 1e-9 (1 +nanosecond). +*stratum* _stratum_::: +This option sets the NTP stratum of the refclock. This can be useful when the +refclock provides time with a stratum other than 0. The default is 0. +*precision* _precision_::: +This option sets the precision of the reference clock (in seconds). The default +value is the estimated precision of the system clock. +*maxdispersion* _dispersion_::: +Maximum allowed dispersion for filtered samples (in seconds). Samples with +larger estimated dispersion are ignored. By default, this limit is disabled. +*filter* _samples_::: +This option sets the length of the median filter which is used to reduce the +noise in the measurements. With each poll about 40 percent of the stored +samples are discarded and one final sample is calculated as an average of the +remaining samples. If the length is 4 or more, at least 4 samples have to be +collected between polls. For lengths below 4, the filter has to be full. The +default is 64. With drivers that perform their own polling (PPS, PHC, SHM), the +maximum value is adjusted to the number of driver polls per source poll, i.e. +2^(_poll_ - _dpoll_). +*prefer*::: +Prefer this source over sources without the prefer option. +*noselect*::: +Never select this source. This is useful for monitoring or with sources which +are not very accurate, but are locked with a PPS refclock. +*trust*::: +Assume time from this source is always true. It can be rejected as a +falseticker in the source selection only if another source with this option +does not agree with it. +*require*::: +Require that at least one of the sources specified with this option is +selectable (i.e. recently reachable and not a falseticker) before updating the +clock. Together with the *trust* option this can be useful to allow a trusted, +but not very precise, reference clock to be safely combined with +unauthenticated NTP sources in order to improve the accuracy of the clock. They +can be selected and used for synchronisation only if they agree with the +trusted and required source. +*tai*::: +This option indicates that the reference clock keeps time in TAI instead of UTC +and that *chronyd* should correct its offset by the current TAI-UTC offset. The +<<leapsectz,*leapsectz*>> directive must be used with this option and the +database must be kept up to date in order for this correction to work as +expected. This option does not make sense with PPS refclocks. +*local*::: +This option specifies that the reference clock is an unsynchronised clock which +is more stable than the system clock (e.g. TCXO, OCXO, or atomic clock) and +it should be used as a local standard to stabilise the system clock. The +refclock will bypass the source selection. There should be at most one refclock +specified with this option and it should have the shortest polling interval +among all configured sources. +*minsamples* _samples_::: +Set the minimum number of samples kept for this source. This overrides the +<<minsamples,*minsamples*>> directive. +*maxsamples* _samples_::: +Set the maximum number of samples kept for this source. This overrides the +<<maxsamples,*maxsamples*>> directive. + +[[manual]]*manual*:: +The *manual* directive enables support at run-time for the +<<chronyc.adoc#settime,*settime*>> command in *chronyc*. If no *manual* +directive is included, any attempt to use the *settime* command in *chronyc* +will be met with an error message. ++ +Note that the *settime* command can be enabled at run-time using +the <<chronyc.adoc#manual,*manual*>> command in *chronyc*. (The idea of the two +commands is that the *manual* command controls the manual clock driver's +behaviour, whereas the *settime* command allows samples of manually entered +time to be provided.) + +[[acquisitionport]]*acquisitionport* _port_:: +By default, *chronyd* as an NTP client opens a new socket for each request with +the source port chosen randomly by the operating system. The *acquisitionport* +directive can be used to specify the source port and use only one socket (per +IPv4 or IPv6 address family) for all configured servers. This can be useful for +getting through some firewalls. It should not be used if not necessary as there +is a small impact on security of the client. If set to 0, the source port of +the permanent socket will be chosen randomly by the operating system. ++ +It can be set to the same port as is used by the NTP server (which can be +configured with the <<port,*port*>> directive) to use only one socket for all +NTP packets. ++ +An example of the *acquisitionport* directive is: ++ +---- +acquisitionport 1123 +---- ++ +This would change the source port used for client requests to UDP port 1123. +You could then persuade the firewall administrator to open that port. + +[[bindacqaddress]]*bindacqaddress* _address_:: +The *bindacqaddress* directive specifies a local IP address to which +*chronyd* will bind its NTP and NTS-KE client sockets. The syntax is similar to +the <<bindaddress,*bindaddress*>> and <<bindcmdaddress,*bindcmdaddress*>> +directives. ++ +For each of the IPv4 and IPv6 protocols, only one *bindacqaddress* directive +can be specified. + +[[bindacqdevice]]*bindacqdevice* _interface_:: +The *bindacqdevice* directive binds the client sockets to a network device +specified by the interface name. This can be useful when the local address is +dynamic, or to enable an NTP source specified with a link-local IPv6 address. +This directive can specify only one interface and it is supported on Linux +only. ++ +An example of the directive is: ++ +---- +bindacqdevice eth0 +---- + +[[dscp]]*dscp* _point_:: +The *dscp* directive sets the Differentiated Services Code Point (DSCP) in +transmitted NTP packets to the specified value. It can improve stability of NTP +measurements in local networks where switches or routers are configured to +prioritise forwarding of packets with specific DSCP values. The default value +is 0 and the maximum value is 63. ++ +An example of the directive (setting the Expedited Forwarding class) is: ++ +---- +dscp 46 +---- + +[[dumpdir]]*dumpdir* _directory_:: +To compute the rate of gain or loss of time, *chronyd* has to store a +measurement history for each of the time sources it uses. ++ +All supported systems, with the exception of macOS 10.12 and earlier, have +operating system support for setting the rate of gain or loss to compensate for +known errors. +(On macOS 10.12 and earlier, *chronyd* must simulate such a capability by +periodically slewing the system clock forwards or backwards by a suitable amount +to compensate for the error built up since the previous slew.) ++ +For such systems, it is possible to save the measurement history across +restarts of *chronyd* (assuming no changes are made to the system clock +behaviour whilst it is not running). The *dumpdir* directive defines the +directory where the measurement histories are saved when *chronyd* exits, +or the <<chronyc.adoc#dump,*dump*>> command in *chronyc* is issued. ++ +If the directory does not exist, it will be created automatically. ++ +The *-r* option of *chronyd* enables loading of the dump files on start. All +dump files found in the directory will be removed after start, even if the *-r* +option is not present. ++ +An example of the directive is: ++ +---- +dumpdir @CHRONYRUNDIR@ +---- ++ +A source whose IP address is _1.2.3.4_ would have its measurement history saved +in the file _@CHRONYRUNDIR@/1.2.3.4.dat_. History of reference clocks is saved +to files named by their reference ID in form of _refid:XXXXXXXX.dat_. + +[[maxsamples]]*maxsamples* _samples_:: +The *maxsamples* directive sets the default maximum number of samples that +*chronyd* should keep for each source. This setting can be overridden for +individual sources in the <<server,*server*>> and <<refclock,*refclock*>> +directives. The default value is 0, which disables the configurable limit. The +useful range is 4 to 64. ++ +As a special case, setting *maxsamples* to 1 disables frequency tracking in +order to make the sources immediately selectable with only one sample. This can +be useful when *chronyd* is started with the *-q* or *-Q* option. + +[[minsamples]]*minsamples* _samples_:: +The *minsamples* directive sets the default minimum number of samples that +*chronyd* should keep for each source. This setting can be overridden for +individual sources in the <<server,*server*>> and <<refclock,*refclock*>> +directives. The default value is 6. The useful range is 4 to 64. ++ +Forcing *chronyd* to keep more samples than it would normally keep reduces +noise in the estimated frequency and offset, but slows down the response to +changes in the frequency and offset of the clock. The offsets in the +<<chronyc.adoc#tracking,*tracking*>> and +<<chronyc.adoc#sourcestats,*sourcestats*>> reports (and the _tracking.log_ and +_statistics.log_ files) may be smaller than the actual offsets. + +[[ntsdumpdir1]]*ntsdumpdir* _directory_:: +This directive specifies a directory for the client to save NTS cookies it +received from the server in order to avoid making an NTS-KE request when +*chronyd* is started again. The cookies are saved separately for each NTP +source in files named by the IP address of the NTS-KE server (e.g. +_1.2.3.4.nts_). By default, the client does not save the cookies. ++ +If the directory does not exist, it will be created automatically. ++ +An example of the directive is: ++ +---- +ntsdumpdir @CHRONYVARDIR@ +---- ++ +This directory is used also by the <<ntsdumpdir2,NTS server>> to save keys. + +[[ntsrefresh]]*ntsrefresh* _interval_:: +This directive specifies the maximum interval between NTS-KE handshakes (in +seconds) in order to refresh the keys authenticating NTP packets. The default +value is 2419200 (4 weeks) and the maximum value is 2^31-1 (68 years). ++ +The interval must be longer than polling intervals of all configured NTP +sources using NTS, otherwise the source with a longer polling interval will +refresh the keys on each poll and no NTP packets will be exchanged. + +[[ntstrustedcerts]]*ntstrustedcerts* [_set-ID_] _file_|_directory_:: +This directive specifies a file or directory containing trusted certificates +(in the PEM format) which are needed to verify certificates of NTS-KE servers, +e.g. certificates of trusted certificate authorities (CA) or self-signed +certificates of the servers. ++ +The optional _set-ID_ argument is a number in the range 0 through 2^32-1, which +selects the set of certificates where certificates from the specified file +or directory are added. The default ID is 0, which is a set containing the +system's default trusted CAs (unless the *nosystemcert* directive is present). +All other sets are empty by default. A set of certificates can be selected for +verification of an NTS server by the *certset* option in the *server* or *pool* +directive. ++ +This directive can be used multiple times to specify one or more sets of +trusted certificates, each containing certificates from one or more files +and/or directories. ++ +It is not necessary to restart *chronyd* in order to reload the certificates if +they change (e.g. after a renewal). ++ +An example is: ++ +---- +ntstrustedcerts /etc/pki/nts/ca1.example.net.crt +ntstrustedcerts 1 /etc/pki/nts/ca2.example.net.crt +ntstrustedcerts 1 /etc/pki/nts/ca3.example.net.crt +ntstrustedcerts 2 /etc/pki/nts/ntp2.example.net.crt +---- + +[[nosystemcert]]*nosystemcert*:: +This directive disables the system's default trusted CAs. Only certificates +specified by the *ntstrustedcerts* directive will be trusted. + +[[nocerttimecheck]]*nocerttimecheck* _limit_:: +This directive disables the checks of the activation and expiration times of +certificates for the specified number of clock updates. It allows the NTS +authentication mechanism to be used on computers which start with wrong time +(e.g. due to not having an RTC or backup battery). Disabling the time checks +has important security implications and should be used only as a last resort, +preferably with a minimal number of trusted certificates. The default value is +0, which means the time checks are always enabled. ++ +An example of the directive is: ++ +---- +nocerttimecheck 1 +---- ++ +This would disable the time checks until the clock is updated for the first +time, assuming the first update corrects the clock and later checks can work +with correct time. + +[[refresh]]*refresh* _interval_:: +This directive specifies the interval (in seconds) between refreshing IP +addresses of NTP sources specified by hostname. If the hostname no longer +resolves to the currently used address, it will be replaced with one of the new +addresses to avoid using a server which is no longer intended for service, even +if it is still responding correctly and would not be replaced as unreachable. +Only one source is refreshed at a time. The default value is 1209600 (2 weeks) +and the maximum value is 2^31-1 (68 years). A value of 0 disables the periodic +refreshment. ++ +The <<chronyc.adoc#refresh,*refresh*>> command can be used to refresh all +sources immediately. + +=== Source selection + +[[authselectmode]]*authselectmode* _mode_:: +NTP sources can be specified with the *key* or *nts* option to enable +authentication to limit the impact of man-in-the-middle attacks. The +attackers can drop or delay NTP packets (up to the *maxdelay* and +<<maxdistance,*maxdistance*>> limits), but they cannot modify the timestamps +contained in the packets. The attack can cause only a limited slew or step, and +also cause the clock to run faster or slower than real time (up to double of +the <<maxdrift,*maxdrift*>> limit). ++ +When authentication is enabled for an NTP source, it is important to disable +unauthenticated NTP sources which could be exploited in the attack, e.g. if +they are not reachable only over a trusted network. Alternatively, the source +selection can be configured with the *require* and *trust* options to +synchronise to the unauthenticated sources only if they agree with the +authenticated sources and might have a positive impact on the accuracy of the +clock. Note that in this case the impact of the attack is higher. The attackers +cannot cause an arbitrarily large step or slew, but they have more control over +the frequency of the clock and can cause *chronyd* to report false information, +e.g. a significantly smaller root delay and dispersion. ++ +This directive determines the default selection options for authenticated and +unauthenticated sources in order to simplify the configuration with the +configuration file and *chronyc* commands. It sets a policy for authentication. ++ +Sources specified with the *noselect* option are ignored (not counted as either +authenticated or unauthenticated), and they always have only the selection +options specified in the configuration. ++ +There are four modes: ++ +*require*::: +Authentication is strictly required for NTP sources in this mode. If any +unauthenticated NTP sources are specified, they will automatically get the +*noselect* option to prevent them from being selected for synchronisation. +*prefer*::: +In this mode, authentication is optional and preferred. If it is enabled for at +least one NTP source, all unauthenticated NTP sources will get the *noselect* +option. +*mix*::: +In this mode, authentication is optional and synchronisation to a mix of +authenticated and unauthenticated NTP sources is allowed. If both authenticated +and unauthenticated NTP sources are specified, all authenticated NTP sources +and reference clocks will get the *require* and *trust* options to prevent +synchronisation to unauthenticated NTP sources if they do not agree with a +majority of the authenticated sources and reference clocks. This is the default +mode. +*ignore*::: +In this mode, authentication is ignored in the source selection. All sources +will have only the selection options that were specified in the configuration +file, or *chronyc* command. This was the behaviour of *chronyd* in versions +before 4.0. +{blank}:: ++ +As an example, the following configuration using the default *mix* mode: ++ +---- +server ntp1.example.net nts +server ntp2.example.net nts +server ntp3.example.net +refclock SOCK /var/run/chrony.ttyS0.sock +---- ++ +is equivalent to the following configuration using the *ignore* mode: ++ +---- +authselectmode ignore +server ntp1.example.net nts require trust +server ntp2.example.net nts require trust +server ntp3.example.net +refclock /var/run/chrony.ttyS0.sock require trust +---- + +[[combinelimit]]*combinelimit* _limit_:: +When *chronyd* has multiple sources available for synchronisation, it has to +select one source as the synchronisation source. The measured offsets and +frequencies of the system clock relative to the other sources, however, can be +combined with the selected source to improve the accuracy of the system clock. ++ +The *combinelimit* directive limits which sources are included in the combining +algorithm. Their synchronisation distance has to be shorter than the distance +of the selected source multiplied by the value of the limit. Also, their +measured frequencies have to be close to the frequency of the selected source. +If the selected source was specified with the *prefer* option, it can be +combined only with other sources specified with this option. ++ +By default, the limit is 3. Setting the limit to 0 effectively disables the +source combining algorithm and only the selected source will be used to control +the system clock. + +[[maxdistance]]*maxdistance* _distance_:: +The *maxdistance* directive sets the maximum root distance of a source to be +acceptable for synchronisation of the clock. Sources that have a distance +larger than the specified distance will be rejected. The distance estimates the +maximum error of the source. It includes the root dispersion and half of the +root delay (round-trip time) accumulated on the path to the primary source. ++ +By default, the maximum root distance is 3 seconds. ++ +Setting *maxdistance* to a larger value can be useful to allow synchronisation +with a server that only has a very infrequent connection to its sources and can +accumulate a large dispersion between updates of its clock. + +[[maxjitter]]*maxjitter* _jitter_:: +The *maxjitter* directive sets the maximum allowed jitter of the sources to not +be rejected by the source selection algorithm. This prevents synchronisation +with sources that have a small root distance, but their time is too variable. ++ +By default, the maximum jitter is 1 second. + +[[minsources]]*minsources* _sources_:: +The *minsources* directive sets the minimum number of sources that need to be +considered as selectable in the source selection algorithm before the local +clock is updated. The default value is 1. ++ +Setting this option to a larger number can be used to improve the reliability. +More sources will have to agree with each other and the clock will not be +updated when only one source (which could be serving incorrect time) is +reachable. + +[[reselectdist]]*reselectdist* _distance_:: +When *chronyd* selects a synchronisation source from available sources, it +will prefer the one with the shortest synchronisation distance. However, to +avoid frequent reselecting when there are sources with similar distance, a +fixed distance is added to the distance for sources that are currently not +selected. This can be set with the *reselectdist* directive. By default, the +distance is 100 microseconds. + +[[stratumweight]]*stratumweight* _distance_:: +The *stratumweight* directive sets how much distance should be added per +stratum to the synchronisation distance when *chronyd* selects the +synchronisation source from available sources. ++ +By default, the weight is 0.001 seconds. This means that the stratum of the sources +in the selection process matters only when the differences between the +distances are in milliseconds. + +=== System clock + +[[clockprecision]]*clockprecision* _precision_:: +The *clockprecision* directive specifies the precision of the system clock (in +seconds). It is used by *chronyd* to estimate the minimum noise in NTP +measurements and randomise low-order bits of timestamps in NTP responses. By +default, the precision is measured on start as the minimum time to read the +clock. ++ +The measured value works well in most cases. However, it generally +overestimates the precision and it can be sensitive to the CPU speed, which can +change over time to save power. In some cases with a high-precision clocksource +(e.g. the Time Stamp Counter of the CPU) and hardware timestamping, setting the +precision on the server to a smaller value can improve stability of clients' +NTP measurements. The server's precision is reported on clients by the +<<chronyc.adoc#ntpdata,*ntpdata*>> command. ++ +An example setting the precision to 8 nanoseconds is: ++ +---- +clockprecision 8e-9 +---- + +[[corrtimeratio]]*corrtimeratio* _ratio_:: +When *chronyd* is slewing the system clock to correct an offset, the rate at +which it is slewing adds to the frequency error of the clock. On all supported +systems, with the exception of macOS 12 and earlier, this rate can be +controlled. ++ +The *corrtimeratio* directive sets the ratio between the duration in which the +clock is slewed for an average correction according to the source history and +the interval in which the corrections are done (usually the NTP polling +interval). Corrections larger than the average take less time and smaller +corrections take more time, the amount of the correction and the correction +time are inversely proportional. ++ +Increasing *corrtimeratio* improves the overall frequency error of the system +clock, but increases the overall time error as the corrections take longer. ++ +By default, the ratio is set to 3, the time accuracy of the clock is preferred +over its frequency accuracy. ++ +The maximum allowed slew rate can be set by the <<maxslewrate,*maxslewrate*>> +directive. The current remaining correction is shown in the +<<chronyc.adoc#tracking,*tracking*>> report as the *System time* value. + +[[driftfile]]*driftfile* _file_:: +One of the main activities of the *chronyd* program is to work out the rate at +which the system clock gains or loses time relative to real time. ++ +Whenever *chronyd* computes a new value of the gain or loss rate, it is desirable +to record it somewhere. This allows *chronyd* to begin compensating the system +clock at that rate whenever it is restarted, even before it has had a chance to +obtain an equally good estimate of the rate during the new run. (This process +can take many minutes, at least.) ++ +The *driftfile* directive allows a file to be specified into which *chronyd* +can store the rate information. Two parameters are recorded in the file. The +first is the rate at which the system clock gains or loses time, expressed in +parts per million, with gains positive. Therefore, a value of 100.0 indicates +that when the system clock has advanced by a second, it has gained 100 +microseconds in reality (so the true time has only advanced by 999900 +microseconds). The second is an estimate of the error bound around the first +value in which the true rate actually lies. ++ +An example of the driftfile directive is: ++ +---- +driftfile @CHRONYVARDIR@/drift +---- + +[[fallbackdrift]]*fallbackdrift* _min-interval_ _max-interval_:: +Fallback drifts are long-term averages of the system clock drift calculated +over exponentially increasing intervals. They are used to avoid quickly +drifting away from true time when the clock was not updated for a longer period +of time and there was a short-term deviation in the drift before the updates +stopped. ++ +The directive specifies the minimum and maximum interval since the last clock +update to switch between fallback drifts. They are defined as a power of 2 (in +seconds). The syntax is as follows: ++ +---- +fallbackdrift 16 19 +---- ++ +In this example, the minimum interval is 16 (18 hours) and the maximum interval is +19 (6 days). The system clock frequency will be set to the first fallback 18 +hours after last clock update, to the second after 36 hours, and so on. This +might be a good setting to cover frequency changes due to daily and weekly +temperature fluctuations. When the frequency is set to a fallback, the state of +the clock will change to '`Not synchronised`'. ++ +By default (or if the specified maximum or minimum is 0), no fallbacks are used +and the clock frequency changes only with new measurements from NTP sources, +reference clocks, or manual input. + +[[leapsecmode]]*leapsecmode* _mode_:: +A leap second is an adjustment that is occasionally applied to UTC to keep it +close to the mean solar time. When a leap second is inserted, the last day of +June or December has an extra second 23:59:60. ++ +For computer clocks that is a problem. The Unix time is defined as number of +seconds since 00:00:00 UTC on 1 January 1970 without leap seconds. The system +clock cannot have time 23:59:60, every minute has 60 seconds and every day has +86400 seconds by definition. The inserted leap second is skipped and the clock +is suddenly ahead of UTC by one second. The *leapsecmode* directive selects how +that error is corrected. There are four options: ++ +*system*::: +When inserting a leap second, the kernel steps the system clock backwards by +one second when the clock gets to 00:00:00 UTC. When deleting a leap second, it +steps forward by one second when the clock gets to 23:59:59 UTC. This is the +default mode when the system driver supports leap seconds (i.e. all supported +systems with the exception of macOS 12 and earlier). +*step*::: +This is similar to the *system* mode, except the clock is stepped by +*chronyd* instead of the kernel. It can be useful to avoid bugs in the kernel +code that would be executed in the *system* mode. This is the default mode +when the system driver does not support leap seconds. +*slew*::: +The clock is corrected by slewing started at 00:00:00 UTC when a leap second +is inserted or 23:59:59 UTC when a leap second is deleted. This might be +preferred over the *system* and *step* modes when applications running on the +system are sensitive to jumps in the system time and it is acceptable that the +clock will be off for a longer time. On Linux with the default +<<maxslewrate,*maxslewrate*>> value the correction takes 12 seconds. +*ignore*::: +No correction is applied to the clock for the leap second. The clock will be +corrected later in normal operation when new measurements are made and the +estimated offset includes the one second error. This option is particularly +useful when multiple *chronyd* instances are running on the system, one +controlling the system clock and others started with the *-x* option, which +should rely on the first instance to correct the system clock and ignore it for +the correction of their own NTP clock running on top of the system clock. +{blank}:: ++ +When serving time to NTP clients that cannot be configured to correct their +clocks for a leap second by slewing, or to clients that would correct at +slightly different rates when it is necessary to keep them close together, the +*slew* mode can be combined with the <<smoothtime,*smoothtime*>> directive to +enable a server leap smear. ++ +When smearing a leap second, the leap status is suppressed on the server and +the served time is corrected slowly by slewing instead of stepping. The clients +do not need any special configuration as they do not know there is any leap +second and they follow the server time which eventually brings them back to +UTC. Care must be taken to ensure they use only NTP servers which smear the +leap second in exactly the same way for synchronisation. ++ +This feature must be used carefully, because the server is intentionally not +serving its best estimate of the true time. ++ +A recommended configuration to enable a server leap smear is: ++ +---- +leapsecmode slew +maxslewrate 1000 +smoothtime 400 0.001024 leaponly +---- ++ +The first directive is necessary to disable the clock step which would reset +the smoothing process. The second directive limits the slewing rate of the +local clock to 1000 ppm, which improves the stability of the smoothing process +when the local correction starts and ends. The third directive enables the +server time smoothing process. It will start when the clock gets to 00:00:00 +UTC and it will take 62500 seconds (about 17.36 hours) to finish. The frequency +offset will be changing by 0.001024 ppm per second and will reach a maximum of +32 ppm in 31250 seconds. The *leaponly* option makes the duration of the leap +smear constant and allows the clients to safely synchronise with multiple +identically configured leap smearing servers. ++ +The duration of the leap smear can be calculated from the specified wander as ++ +---- +duration = sqrt(4 / wander) +---- + +[[leapsectz]]*leapsectz* _timezone_:: +This directive specifies a timezone in the system timezone database which +*chronyd* can use to determine when will the next leap second occur and what is +the current offset between TAI and UTC. It will periodically check if 23:59:59 +and 23:59:60 are valid times in the timezone. This normally works with the +_right/UTC_ timezone. ++ +When a leap second is announced, the timezone needs to be updated at least 12 +hours before the leap second. It is not necessary to restart *chronyd*. ++ +This directive is useful with reference clocks and other time sources which do +not announce leap seconds, or announce them too late for an NTP server to +forward them to its own clients. Clients of leap smearing servers must not +use this directive. ++ +It is also useful when the system clock is required to have correct TAI-UTC +offset. Note that the offset is set only when leap seconds are handled by the +kernel, i.e. <<leapsecmode,*leapsecmode*>> is set to *system*. ++ +The specified timezone is not used as an exclusive source of information about +leap seconds. If a majority of time sources announce on the last day of June or +December that a leap second should be inserted or deleted, it will be accepted +even if it is not included in the timezone. ++ +An example of the directive is: ++ +---- +leapsectz right/UTC +---- ++ +The following shell command verifies that the timezone contains leap seconds +and can be used with this directive: ++ +---- +$ TZ=right/UTC date -d 'Dec 31 2008 23:59:60' +Wed Dec 31 23:59:60 UTC 2008 +---- + +[[makestep]]*makestep* _threshold_ _limit_:: +Normally *chronyd* will cause the system to gradually correct any time offset, +by slowing down or speeding up the clock as required. In certain situations, +e.g. when *chronyd* is initially started, the system clock might be so far +adrift that this slewing process would take a very long time to correct the +system clock. ++ +This directive forces *chronyd* to step the system clock if the adjustment is +larger than a threshold value, but only if there were no more clock updates +since *chronyd* was started than the specified limit. A negative value disables +the limit. ++ +On most systems it is desirable to step the system clock only on boot, before +starting programs that rely on time advancing monotonically forwards. ++ +An example of the use of this directive is: ++ +---- +makestep 0.1 3 +---- ++ +This would step the system clock if the adjustment is larger than 0.1 seconds, but +only in the first three clock updates. + +[[maxchange]]*maxchange* _offset_ _start_ _ignore_:: +This directive sets the maximum offset to be accepted on a clock update. The +offset is measured relative to the current estimate of the true time, which is +different from the system time if a previous slew did not finish. ++ +The check is enabled after the specified number of clock updates to allow a +large initial offset to be corrected on start. Offsets larger than the +specified maximum will be ignored for the specified number of times. Another +large offset will cause *chronyd* to give up and exit. A negative value +can be used to disable the limit to ignore all large offsets. A syslog message +will be generated when an offset is ignored or it causes the exit. ++ +An example of the use of this directive is: ++ +---- +maxchange 1000 1 2 +---- ++ +After the first clock update, *chronyd* will check the offset on every clock +update, it will ignore two adjustments larger than 1000 seconds and exit on +another one. + +[[maxclockerror]]*maxclockerror* _error-in-ppm_:: +The *maxclockerror* directive sets the maximum assumed frequency error that the +system clock can gain on its own between clock updates. It describes the +stability of the clock. ++ +By default, the maximum error is 1 ppm. ++ +Typical values for _error-in-ppm_ might be 10 for a low quality clock and 0.1 +for a high quality clock using a temperature compensated crystal oscillator. + +[[maxdrift]]*maxdrift* _drift-in-ppm_:: +This directive specifies the maximum assumed drift (frequency error) of the +system clock. It limits the frequency adjustment that *chronyd* is allowed to +use to correct the measured drift. It is an additional limit to the maximum +adjustment that can be set by the system driver (100000 ppm on Linux, 500 ppm +on FreeBSD, NetBSD, and macOS 10.13+, 32500 ppm on illumos). ++ +By default, the maximum assumed drift is 500000 ppm, i.e. the adjustment is +limited by the system driver rather than this directive. + +[[maxupdateskew]]*maxupdateskew* _skew-in-ppm_:: +One of *chronyd*'s tasks is to work out how fast or slow the computer's clock +runs relative to its reference sources. In addition, it computes an estimate of +the error bounds around the estimated value. ++ +If the range of error is too large, it probably indicates that the measurements +have not settled down yet, and that the estimated gain or loss rate is not very +reliable. ++ +The *maxupdateskew* directive sets the threshold for determining whether an +estimate might be so unreliable that it should not be used. By default, the +threshold is 1000 ppm. ++ +Typical values for _skew-in-ppm_ might be 100 for NTP sources polled over a +wireless network, and 10 or smaller for sources on a local wired network. ++ +It should be noted that this is not the only means of protection against using +unreliable estimates. At all times, *chronyd* keeps track of both the estimated +gain or loss rate, and the error bound on the estimate. When a new estimate is +generated following another measurement from one of the sources, a weighted +combination algorithm is used to update the existing estimate. If it has +significantly smaller error bounds than the new estimate, the existing estimate +will dominate in the new combined value. + +[[maxslewrate]]*maxslewrate* _rate-in-ppm_:: +The *maxslewrate* directive sets the maximum rate at which *chronyd* is allowed +to slew the time. It limits the slew rate controlled by the correction time +ratio (which can be set by the <<corrtimeratio,*corrtimeratio*>> directive) and +is effective only on systems where *chronyd* is able to control the rate (i.e. +all supported systems with the exception of macOS 12 or earlier). ++ +For each system there is a maximum frequency offset of the clock that can be set +by the driver. On Linux it is 100000 ppm, on FreeBSD, NetBSD and macOS 10.13+ it +is 5000 ppm, and on illumos it is 32500 ppm. Also, due to a kernel limitation, +setting *maxslewrate* on FreeBSD, NetBSD, macOS 10.13+ to a value between 500 +ppm and 5000 ppm will effectively set it to 500 ppm. ++ +By default, the maximum slew rate is set to 83333.333 ppm (one twelfth). + +[[tempcomp]] +*tempcomp* _file_ _interval_ _T0_ _k0_ _k1_ _k2_:: +*tempcomp* _file_ _interval_ _points-file_:: +Normally, changes in the rate of drift of the system clock are caused mainly by +changes in the temperature of the crystal oscillator on the motherboard. ++ +If there are temperature measurements available from a sensor close to the +oscillator, the *tempcomp* directive can be used to compensate for the changes +in the temperature and improve the stability and accuracy of the clock. ++ +The result depends on many factors, including the resolution of the sensor, the +amount of noise in the measurements, the polling interval of the time source, +the compensation update interval, how well the compensation is specified, and +how close the sensor is to the oscillator. When it is working well, the +frequency reported in the _tracking.log_ file is more stable and the maximum +reached offset is smaller. ++ +There are two forms of the directive. The first one has six parameters: a path +to the file containing the current temperature from the sensor (in text +format), the compensation update interval (in seconds), and temperature +coefficients _T0_, _k0_, _k1_, _k2_. ++ +The frequency compensation is calculated (in ppm) as ++ +---- +comp = k0 + (T - T0) * k1 + (T - T0)^2 * k2 +---- ++ +The result has to be between -10 ppm and 10 ppm, otherwise the measurement is +considered invalid and will be ignored. The _k0_ coefficient can be adjusted to +keep the compensation in that range. ++ +An example of the use is: ++ +---- +tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 26000 0.0 0.000183 0.0 +---- ++ +The measured temperature will be read from the file in the Linux sysfs +filesystem every 30 seconds. When the temperature is 26000 (26 degrees +Celsius), the frequency correction will be zero. When it is 27000 (27 degrees +Celsius), the clock will be set to run faster by 0.183 ppm, etc. ++ +The second form has three parameters: the path to the sensor file, the update +interval, and a path to a file containing a list of (temperature, compensation) +points, from which the compensation is linearly interpolated or extrapolated. ++ +An example is: ++ +---- +tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 /etc/chrony.tempcomp +---- ++ +where the _/etc/chrony.tempcomp_ file could have ++ +---- +20000 1.0 +21000 0.64 +22000 0.36 +23000 0.16 +24000 0.04 +25000 0.0 +26000 0.04 +27000 0.16 +28000 0.36 +29000 0.64 +30000 1.0 +---- ++ +Valid measurements with corresponding compensations are logged to the +_tempcomp.log_ file if enabled by the <<log,*log tempcomp*>> directive. + +=== NTP server + +[[allow]]*allow* [*all*] [_subnet_]:: +The *allow* directive is used to designate a particular subnet from which NTP +clients are allowed to access the computer as an NTP server. It also controls +access of NTS-KE clients when NTS is enabled on the server. ++ +The default is that no clients are allowed access, i.e. *chronyd* operates +purely as an NTP client. If the *allow* directive is used, *chronyd* will be +both a client of its servers, and a server to other clients. ++ +This directive can be used multiple times. ++ +Examples of the use of the directive are as follows: ++ +---- +allow 1.2.3.4 +allow 3.4.5.0/24 +allow 3.4.5 +allow 2001:db8::/32 +allow 0/0 +allow ::/0 +allow +---- ++ +The first directive allows access from an IPv4 address. The second directive +allows access from all computers in an IPv4 subnet specified in the CIDR +notation. The third directive specifies the same subnet using a simpler +notation where the prefix length is determined by the number of dots. The +fourth directive specifies an IPv6 subnet. The fifth and sixth directives allow +access from all IPv4 and IPv6 addresses respectively. The seventh directive +allows access from all addresses (both IPv4 or IPv6). ++ +A second form of the directive, *allow all*, has a greater effect, depending on +the ordering of directives in the configuration file. To illustrate the effect, +consider the two examples: ++ +---- +allow 1.2.3.4 +deny 1.2.3.0/24 +allow 1.2.0.0/16 +---- ++ +and ++ +---- +allow 1.2.3.4 +deny 1.2.3.0/24 +allow all 1.2.0.0/16 +---- ++ +In the first example, the effect is the same regardless of what order the three +directives are given in. So the _1.2.0.0/16_ subnet is allowed access, except +for the _1.2.3.0/24_ subnet, which is denied access, however the host _1.2.3.4_ +is allowed access. ++ +In the second example, the *allow all 1.2.0.0/16* directive overrides the +effect of _any_ previous directive relating to a subnet within the specified +subnet. Within a configuration file this capability is probably rather moot; +however, it is of greater use for reconfiguration at run-time via *chronyc* +with the <<chronyc.adoc#allow,*allow all*>> command. ++ +The rules are internally represented as a tree of tables with one level per +four bits of the IPv4 or IPv6 address. The order of the *allow* and *deny* +directives matters if they modify the same records of one table, i.e. if one +subnet is included in the other subnet and their prefix lengths are at the same +level. For example, _1.2.3.0/28_ and _1.2.3.0/29_ are in different tables, but +_1.2.3.0/25_ and _1.2.3.0/28_ are in the same table. The configuration can be +verified for individual addresses with the <<chronyc.adoc#accheck,*accheck*>> +command in *chronyc*. ++ +A hostname can be specified in the directives instead of the IP address, but +the name must be resolvable when *chronyd* is started, i.e. the network is +already up and DNS is working. If the hostname resolves to multiple addresses, +only the first address (in the order returned by the system resolver) will be +allowed or denied. ++ +Note, if the <<initstepslew,*initstepslew*>> directive is used in the +configuration file, each of the computers listed in that directive must allow +client access by this computer for it to work. + +[[deny]]*deny* [*all*] [_subnet_]:: +This is similar to the <<allow,*allow*>> directive, except that it denies NTP +and NTS-KE client access to a particular subnet or host, rather than allowing +it. ++ +The syntax is identical and the directive can be used multiple times too. ++ +There is also a *deny all* directive with similar behaviour to the *allow all* +directive. + +[[bindaddress]]*bindaddress* _address_:: +The *bindaddress* directive binds the sockets on which *chronyd* listens for +NTP and NTS-KE requests to a local address of the computer. On systems other +than Linux, the address of the computer needs to be already configured when +*chronyd* is started. ++ +An example of the use of the directive is: ++ +---- +bindaddress 192.168.1.1 +---- ++ +Currently, for each of the IPv4 and IPv6 protocols, only one *bindaddress* +directive can be specified. Therefore, it is not useful on computers which +should serve NTP on multiple network interfaces. + +[[binddevice]]*binddevice* _interface_:: +The *binddevice* directive binds the NTP and NTS-KE server sockets to a network +device specified by the interface name. This directive can specify only one +interface and it is supported on Linux only. ++ +An example of the directive is: ++ +---- +binddevice eth0 +---- + +[[broadcast]]*broadcast* _interval_ _address_ [_port_]:: +The *broadcast* directive is used to declare a broadcast address to which +chronyd should send packets in the NTP broadcast mode (i.e. make *chronyd* act +as a broadcast server). Broadcast clients on that subnet will be able to +synchronise. ++ +This directive can be used multiple times to specify multiple addresses. ++ +The syntax is as follows: ++ +---- +broadcast 32 192.168.1.255 +broadcast 64 192.168.2.255 12123 +broadcast 64 ff02::101 +---- ++ +In the first example, the destination port defaults to UDP port 123 (the normal NTP +port). In the second example, the destination port is specified as 12123. The +first parameter in each case (32 or 64 respectively) is the interval in seconds +between broadcast packets being sent. The second parameter in each case is the +broadcast address to send the packet to. This should correspond to the +broadcast address of one of the network interfaces on the computer where +*chronyd* is running. ++ +You can have more than 1 *broadcast* directive if you have more than 1 network +interface onto which you want to send NTP broadcast packets. ++ +*chronyd* itself cannot act as a broadcast client; it must always be configured +as a point-to-point client by defining specific NTP servers and peers. This +broadcast server feature is intended for providing a time source to other NTP +implementations. ++ +If *ntpd* is used as the broadcast client, it will try to measure the +round-trip delay between the server and client with normal client mode packets. +Thus, the broadcast subnet should also be the subject of an <<allow,*allow*>> +directive. + +[[clientloglimit]]*clientloglimit* _limit_:: +This directive specifies the maximum amount of memory that *chronyd* is allowed +to allocate for logging of client accesses and the state that *chronyd* as an +NTP server needs to support the interleaved mode for its clients. The default +limit is 524288 bytes, which enables monitoring of up to 4096 IP addresses at +the same time and holding NTP timestamps for up to 4096 clients using the +interleaved mode (depending on uniformity of their polling interval). The +number of addresses and timestamps is always a power of 2. The maximum +effective value is 2147483648 (2 GB), which corresponds to 16777216 addresses +and timestamps. ++ +An example of the use of this directive is: ++ +---- +clientloglimit 1048576 +---- + +[[noclientlog]]*noclientlog*:: +This directive, which takes no arguments, specifies that client accesses are +not to be logged. Normally they are logged, allowing statistics to be reported +using the <<chronyc.adoc#clients,*clients*>> command in *chronyc*. This option +also effectively disables server support for the NTP interleaved mode. + +[[local]]*local* [_option_]...:: +The *local* directive enables a local reference mode, which allows *chronyd* +operating as an NTP server to appear synchronised to real time (from the +viewpoint of clients polling it), even when it was never synchronised or +the last update of the clock happened a long time ago. ++ +This directive is normally used in an isolated network, where computers are +required to be synchronised to one another, but not necessarily to real time. +The server can be kept vaguely in line with real time by manual input. ++ +The *local* directive has the following options: ++ +*stratum* _stratum_::: +This option sets the stratum of the server which will be reported to clients +when the local reference is active. The specified value is in the range 1 +through 15, and the default value is 10. It should be larger than the maximum +expected stratum in the network when external NTP servers are accessible. ++ +Stratum 1 indicates a computer that has a true real-time reference directly +connected to it (e.g. GPS, atomic clock, etc.), such computers are expected to +be very close to real time. Stratum 2 computers are those which have a stratum +1 server; stratum 3 computers have a stratum 2 server and so on. A value +of 10 indicates that the clock is so many hops away from a reference clock that +its time is fairly unreliable. +*distance* _distance_::: +This option sets the threshold for the root distance which will activate the local +reference. If *chronyd* was synchronised to some source, the local reference +will not be activated until its root distance reaches the specified value (the +rate at which the distance is increasing depends on how well the clock was +tracking the source). The default value is 1 second. ++ +The current root distance can be calculated from root delay and root dispersion +(reported by the <<chronyc.adoc#tracking,*tracking*>> command in *chronyc*) as: ++ +---- +distance = delay / 2 + dispersion +---- +*orphan*::: +This option enables a special '`orphan`' mode, where sources with stratum equal +to the local _stratum_ are assumed to not serve real time. They are ignored +unless no other source is selectable and their reference IDs are smaller than +the local reference ID. ++ +This allows multiple servers in the network to use the same *local* +configuration and to be synchronised to one another, without confusing clients +that poll more than one server. Each server needs to be configured to poll all +other servers with the *local* directive. This ensures only the server with the +smallest reference ID has the local reference active and others are +synchronised to it. If that server stops responding, the server with the second +smallest reference ID will take over when its local reference mode activates +(root distance reaches the threshold configured by the *distance* option). ++ +The *orphan* mode is compatible with the *ntpd*'s orphan mode (enabled by the +*tos orphan* command). +{blank}:: ++ +An example of the directive is: ++ +---- +local stratum 10 orphan distance 0.1 +---- + +[[ntpsigndsocket]]*ntpsigndsocket* _directory_:: +This directive specifies the location of the Samba *ntp_signd* socket when it +is running as a Domain Controller (DC). If *chronyd* is compiled with this +feature, responses to MS-SNTP clients will be signed by the *smbd* daemon. ++ +Note that MS-SNTP requests are not authenticated and any client that is allowed +to access the server by the <<allow,*allow*>> directive, or the +<<chronyc.adoc#allow,*allow*>> command in *chronyc*, can get an MS-SNTP +response signed with a trust account's password and try to crack the password +in a brute-force attack. Access to the server should be carefully controlled. ++ +An example of the directive is: ++ +---- +ntpsigndsocket /var/lib/samba/ntp_signd +---- + +[[ntsport]]*ntsport* _port_:: +This directive specifies the TCP port on which *chronyd* will provide the NTS +Key Establishment (NTS-KE) service. The default port is 4460. ++ +The port will be open only when a certificate and key is specified by the +*ntsservercert* and *ntsserverkey* directives. + +[[ntsservercert]]*ntsservercert* _file_:: +This directive specifies a file containing a certificate in the PEM format +for *chronyd* to operate as an NTS server. The file should also include +any intermediate certificates that the clients will need to validate the +server's certificate. The file needs to be readable by the user under which +*chronyd* is running after dropping root privileges. ++ +This directive can be used multiple times to specify multiple certificates for +different names of the server. ++ +The files are loaded only once. *chronyd* needs to be restarted in order to +load a renewed certificate. The <<ntsdumpdir,*ntsdumpdir*>> and +<<dumpdir,*dumpdir*>> directives with the *-r* option of *chronyd* are +recommended for a near-seamless server operation. + +[[ntsserverkey]]*ntsserverkey* _file_:: +This directive specifies a file containing a private key in the PEM format +for *chronyd* to operate as an NTS server. The file needs to be readable by +the user under which *chronyd* is running after dropping root privileges. For +security reasons, it should not be readable by other users. ++ +This directive can be used multiple times to specify multiple keys. The number +of keys must be the same as the number of certificates and the corresponding +files must be specified in the same order. + +[[ntsprocesses]]*ntsprocesses* _processes_:: +This directive specifies how many helper processes will *chronyd* operating +as an NTS server start for handling client NTS-KE requests in order to improve +performance with multi-core CPUs and multithreading. If set to 0, no helper +process will be started and all NTS-KE requests will be handled by the main +*chronyd* process. The default value is 1. + +[[maxntsconnections]]*maxntsconnections* _connections_:: +This directive specifies the maximum number of concurrent NTS-KE connections +per process that the NTS server will accept. The default value is 100. The +maximum practical value is half of the system *FD_SETSIZE* constant (usually +1024). + +[[ntsdumpdir2]]*ntsdumpdir* _directory_:: +This directive specifies a directory where *chronyd* operating as an NTS server +can save the keys which encrypt NTS cookies provided to clients. The keys are +saved to a single file named _ntskeys_. When *chronyd* is restarted, reloading +the keys allows the clients to continue using old cookies and avoids a storm of +NTS-KE requests. By default, the server does not save the keys. ++ +An example of the directive is: ++ +---- +ntsdumpdir @CHRONYVARDIR@ +---- ++ +This directory is used also by the <<ntsdumpdir1,NTS client>> to save NTS cookies. + +[[ntsntpserver]]*ntsntpserver* _hostname_:: +This directive specifies the hostname (as a fully qualified domain name) or +address of the NTP server(s) which is +provided in the NTS-KE response to the clients. It allows the NTS-KE server to +be separated from the NTP server. However, the servers need to share the keys, +i.e. external key management needs to be enabled by setting +<<ntsrotate,*ntsrotate*>> to 0. By default, no hostname or address is provided +to the clients, which means they should use the same server for NTS-KE and NTP. + +[[ntsrotate]]*ntsrotate* _interval_:: +This directive specifies the rotation interval (in seconds) of the server key +which encrypts the NTS cookies. New keys are generated automatically from the +_/dev/urandom_ device. The server keeps two previous keys to give the clients +time to get new cookies encrypted by the latest key. The interval is measured +as the server's operating time, i.e. the actual interval can be longer if +*chronyd* is not running continuously. The default interval is 604800 seconds +(1 week). The maximum value is 2^31-1 (68 years). ++ +The automatic rotation of the keys can be disabled by setting *ntsrotate* to 0. +In this case the keys are assumed to be managed externally. *chronyd* will not +save the keys to the _ntskeys_ file and will reload the keys from the file when +the <<chronyc.adoc#rekey,*rekey*>> command is issued in *chronyc*. The file can +be periodically copied from another server running *chronyd* (which does +not have *ntsrotate* set to 0) in order to have one or more servers dedicated +to NTS-KE. The file includes the subsequent key to which the NTS-KE server will +switch on the next rotation, i.e. the process copying and reloading the file +does not need to be timed precisely (it can be delayed by up to one rotation +interval). The NTS-KE servers need to be configured with the +<<ntsntpserver,*ntsntpserver*>> directive to point the clients to the right NTP +server. ++ +An example of the directive is: ++ +---- +ntsrotate 2592000 +---- + +[[port]]*port* _port_:: +This option allows you to configure the port on which *chronyd* will listen for +NTP requests. The port will be open only when an address is allowed by the +<<allow,*allow*>> directive or the <<chronyc.adoc#allow,*allow*>> command in +*chronyc*, an NTP peer is configured, or the broadcast server mode is enabled. ++ +The default value is 123, the standard NTP port. If set to 0, *chronyd* will +never open the server port and will operate strictly in a client-only mode. The +source port used in NTP client requests can be set by the +<<acquisitionport,*acquisitionport*>> directive. + +[[ratelimit]]*ratelimit* [_option_]...:: +This directive enables response rate limiting for NTP packets. Its purpose is +to reduce network traffic with misconfigured or broken NTP clients that are +polling the server too frequently. The limits are applied to individual IP +addresses. If multiple clients share one IP address (e.g. multiple hosts behind +NAT), the sum of their traffic will be limited. If a client that increases its +polling rate when it does not receive a reply is detected, its rate limiting +will be temporarily suspended to avoid increasing the overall amount of +traffic. The maximum number of IP addresses which can be monitored at the same +time depends on the memory limit set by the <<clientloglimit,*clientloglimit*>> +directive. ++ +The *ratelimit* directive supports a number of options (which can be defined +in any order): ++ +*interval* _interval_::: +This option sets the minimum interval between responses. It is defined as a +power of 2 in seconds. The default value is 3 (8 seconds). The minimum value +is -19 (524288 packets per second) and the maximum value is 12 (one packet per +4096 seconds). Note that with values below -4 the rate limiting is coarse +(responses are allowed in bursts, even if the interval between them is shorter +than the specified interval). +*burst* _responses_::: +This option sets the maximum number of responses that can be sent in a burst, +temporarily exceeding the limit specified by the *interval* option. This is +useful for clients that make rapid measurements on start (e.g. *chronyd* with +the *iburst* option). The default value is 8. The minimum value is 1 and the +maximum value is 255. +*leak* _rate_::: +This option sets the rate at which responses are randomly allowed even if the +limits specified by the *interval* and *burst* options are exceeded. This is +necessary to prevent an attacker who is sending requests with a spoofed +source address from completely blocking responses to that address. The leak +rate is defined as a power of 1/2 and it is 2 by default, i.e. on average at +least every fourth request has a response. The minimum value is 1 and the +maximum value is 4. +{blank}:: ++ +An example use of the directive is: ++ +---- +ratelimit interval 1 burst 16 +---- ++ +This would reduce the response rate for IP addresses sending packets on average +more than once per 2 seconds, or sending packets in bursts of more than 16 +packets, by up to 75% (with default *leak* of 2). + +[[ntsratelimit]]*ntsratelimit* [_option_]...:: +This directive enables rate limiting of NTS-KE requests. It is similar to the +<<ratelimit,*ratelimit*>> directive, except the default interval is 6 +(1 connection per 64 seconds). ++ +An example of the use of the directive is: ++ +---- +ntsratelimit interval 3 burst 1 +---- + +[[smoothtime]]*smoothtime* _max-freq_ _max-wander_ [*leaponly*]:: +The *smoothtime* directive can be used to enable smoothing of the time that +*chronyd* serves to its clients to make it easier for them to track it and keep +their clocks close together even when large offset or frequency corrections are +applied to the server's clock, for example after being offline for a longer +time. ++ +BE WARNED: The server is intentionally not serving its best estimate of the +true time. If a large offset has been accumulated, it can take a very long time +to smooth it out. This directive should be used only when the clients are not +configured to also poll another NTP server, because they could reject this +server as a falseticker or fail to select a source completely. ++ +The smoothing process is implemented with a quadratic spline function with two +or three pieces. It is independent from any slewing applied to the local system +clock, but the accumulated offset and frequency will be reset when the clock is +corrected by stepping, e.g. by the <<makestep,*makestep*>> directive or the +<<chronyc.adoc#makestep,*makestep*>> command in *chronyc*. The process can be +reset without stepping the clock by the <<chronyc.adoc#smoothtime,*smoothtime +reset*>> command. ++ +The first two arguments of the directive are the maximum frequency offset of +the smoothed time to the tracked NTP time (in ppm) and the maximum rate at +which the frequency offset is allowed to change (in ppm per second). *leaponly* +is an optional third argument which enables a mode where only leap seconds are +smoothed out and normal offset and frequency changes are ignored. The *leaponly* +option is useful in a combination with the <<leapsecmode,*leapsecmode slew*>> +directive to allow the clients to use multiple time smoothing servers safely. ++ +The smoothing process is activated automatically when 1/10000 of the estimated +skew of the local clock falls below the maximum rate of frequency change. It +can be also activated manually by the <<chronyc.adoc#smoothtime,*smoothtime +activate*>> command, which is particularly useful when the clock is +synchronised only with manual input and the skew is always larger than the +threshold. The <<chronyc.adoc#smoothing,*smoothing*>> command can be used to +monitor the process. ++ +An example suitable for clients using *ntpd* and 1024 second polling interval +could be: ++ +---- +smoothtime 400 0.001 +---- ++ +An example suitable for clients using *chronyd* on Linux could be: ++ +---- +smoothtime 50000 0.01 +---- + +=== Command and monitoring access + +[[bindcmdaddress]]*bindcmdaddress* _address_:: +The *bindcmdaddress* directive specifies a local IP address to which *chronyd* +will bind the UDP socket listening for monitoring command packets (issued +by *chronyc*). On systems other than Linux, the address of the interface needs +to be already configured when *chronyd* is started. ++ +This directive can also change the path of the Unix domain command socket, +which is used by *chronyc* to send configuration commands. The socket must be +in a directory that is accessible only by the root or _chrony_ user. The +directory will be created on start if it does not exist. The compiled-in default +path of the socket is _@CHRONYRUNDIR@/chronyd.sock_. The socket can be +disabled by setting the path to _/_. ++ +By default, *chronyd* binds the UDP sockets to the addresses _127.0.0.1_ and +_::1_ (i.e. the loopback interface). This blocks all access except from +localhost. To listen for command packets on all interfaces, you can add the +lines: ++ +---- +bindcmdaddress 0.0.0.0 +bindcmdaddress :: +---- ++ +to the configuration file. ++ +For each of the IPv4, IPv6, and Unix domain protocols, only one +*bindcmdaddress* directive can be specified. ++ +An example that sets the path of the Unix domain command socket is: ++ +---- +bindcmdaddress /var/run/chrony/chronyd.sock +---- + +[[bindcmddevice]]*bindcmddevice* _interface_:: +The *bindcmddevice* directive binds the UDP command sockets to a network device +specified by the interface name. This directive can specify only one interface +and it is supported on Linux only. ++ +An example of the directive is: ++ +---- +bindcmddevice eth0 +---- + +[[cmdallow]]*cmdallow* [*all*] [_subnet_]:: +This is similar to the <<allow,*allow*>> directive, except that it allows +monitoring access (rather than NTP client access) to a particular subnet or +host. (By '`monitoring access`' is meant that *chronyc* can be run on those +hosts and retrieve monitoring data from *chronyd* on this computer.) ++ +The syntax is identical to the *allow* directive. ++ +There is also a *cmdallow all* directive with similar behaviour to the *allow +all* directive (but applying to monitoring access in this case, of course). ++ +Note that *chronyd* has to be configured with the +<<bindcmdaddress,*bindcmdaddress*>> directive to not listen only on the +loopback interface to actually allow remote access. + +[[cmddeny]]*cmddeny* [*all*] [_subnet_]:: +This is similar to the <<cmdallow,*cmdallow*>> directive, except that it denies +monitoring access to a particular subnet or host, rather than allowing it. ++ +The syntax is identical. ++ +There is also a *cmddeny all* directive with similar behaviour to the *cmdallow +all* directive. + +[[cmdport]]*cmdport* _port_:: +The *cmdport* directive allows the port that is used for run-time monitoring +(via the *chronyc* program) to be altered from its default (323). If set to 0, +*chronyd* will not open the port, which disables remote *chronyc* access (with +a non-default *bindcmdaddress*) and local access for unprivileged users. It +does not disable the Unix domain command socket. ++ +An example shows the syntax: ++ +---- +cmdport 257 +---- ++ +This would make *chronyd* use UDP 257 as its command port. (*chronyc* would +need to be run with the *-p 257* option to inter-operate correctly.) + +[[cmdratelimit]]*cmdratelimit* [_option_]...:: +This directive enables response rate limiting for command packets. It is +similar to the <<ratelimit,*ratelimit*>> directive, except responses to +localhost are never limited and the default interval is -4 (16 packets per +second). ++ +An example of the use of the directive is: ++ +---- +cmdratelimit interval 2 +---- + +=== Real-time clock (RTC) + +[[hwclockfile]]*hwclockfile* _file_:: +The *hwclockfile* directive sets the location of the adjtime file which is +used by the *hwclock* program on Linux. *chronyd* parses the file to find out +if the RTC keeps local time or UTC. It overrides the <<rtconutc,*rtconutc*>> +directive. ++ +The compiled-in default value is '_@DEFAULT_HWCLOCK_FILE@_'. ++ +An example of the directive is: ++ +---- +hwclockfile /etc/adjtime +---- + +[[rtcautotrim]]*rtcautotrim* _threshold_:: +The *rtcautotrim* directive is used to keep the RTC close to the system clock +automatically. When the system clock is synchronised and the estimated error +between the two clocks is larger than the specified threshold, *chronyd* will +trim the RTC as if the <<chronyc.adoc#trimrtc,*trimrtc*>> command in *chronyc* +was issued. The trimming operation is accurate to only about 1 second, which is +the minimum effective threshold. ++ +This directive is effective only with the <<rtcfile,*rtcfile*>> directive. ++ +An example of the use of this directive is: ++ +---- +rtcautotrim 30 +---- ++ +This would set the threshold error to 30 seconds. + +[[rtcdevice]]*rtcdevice* _device_:: +The *rtcdevice* directive sets the path to the device file for accessing the +RTC. The default path is _@DEFAULT_RTC_DEVICE@_. + +[[rtcfile]]*rtcfile* _file_:: +The *rtcfile* directive defines the name of the file in which *chronyd* can +save parameters associated with tracking the accuracy of the RTC. ++ +An example of the directive is: ++ +---- +rtcfile @CHRONYVARDIR@/rtc +---- ++ +*chronyd* saves information in this file when it exits and when the *writertc* +command is issued in *chronyc*. The information saved is the RTC's error at +some epoch, that epoch (in seconds since January 1 1970), and the rate at which +the RTC gains or loses time. ++ +So far, the support for real-time clocks is limited; their code is even more +system-specific than the rest of the software. You can only use the RTC +facilities (the <<rtcfile,*rtcfile*>> directive and the *-s* command-line +option to *chronyd*) if the following three conditions apply: ++ +. You are running Linux. +. The kernel is compiled with extended real-time clock support (i.e. the + _/dev/rtc_ device is capable of doing useful things). +. You do not have other applications that need to make use of _/dev/rtc_ at all. + +[[rtconutc]]*rtconutc*:: +*chronyd* assumes by default that the RTC keeps local time (including any +daylight saving changes). This is convenient on PCs running Linux which are +dual-booted with Windows. ++ +If you keep the RTC on local time and your computer is off when daylight saving +(summer time) starts or ends, the computer's system time will be one hour in +error when you next boot and start chronyd. ++ +An alternative is for the RTC to keep Universal Coordinated Time (UTC). This +does not suffer from the 1 hour problem when daylight saving starts or ends. ++ +If the *rtconutc* directive appears, it means the RTC is required to keep UTC. +The directive takes no arguments. It is equivalent to specifying the *-u* +switch to the Linux *hwclock* program. ++ +Note that this setting is overridden by the <<hwclockfile,*hwclockfile*>> file +and is not relevant for the <<rtcsync,*rtcsync*>> directive. + +[[rtcsync]]*rtcsync*:: +The *rtcsync* directive enables a mode where the system time is periodically +copied to the RTC and *chronyd* does not try to track its drift. This directive +cannot be used with the <<rtcfile,*rtcfile*>> directive. ++ +On Linux, the RTC copy is performed by the kernel every 11 minutes. ++ +On macOS, <<chronyd,*chronyd*>> will perform the RTC copy every 60 minutes +when the system clock is in a synchronised state. ++ +On other systems this directive does nothing. + +=== Logging + +[[log]]*log* [_option_]...:: +The *log* directive indicates that certain information is to be logged. +The log files are written to the directory specified by the <<logdir,*logdir*>> +directive. A banner is periodically written to the files to indicate the +meanings of the columns. ++ +*rawmeasurements*::: +This option logs the raw NTP measurements and related information to a file +called _measurements.log_. An entry is made for each packet received from the +source. This can be useful when debugging a problem. An example line (which +actually appears as a single line in the file) from the log file is shown +below. ++ +---- +2016-11-09 05:40:50 203.0.113.15 N 2 111 111 1111 10 10 1.0 \ + -4.966e-03 2.296e-01 1.577e-05 1.615e-01 7.446e-03 CB00717B 4B D K +---- ++ +The columns are as follows (the quantities in square brackets are the values +from the example line above): ++ +. Date [2015-10-13] +. Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the + local time zone. [05:40:50] +. IP address of server or peer from which measurement came [203.0.113.15] +. Leap status (_N_ means normal, _+_ means that the last minute of the current + month has 61 seconds, _-_ means that the last minute of the month has 59 + seconds, _?_ means the remote computer is not currently synchronised.) [N] +. Stratum of remote computer. [2] +. RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111] +. RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111] +. Results of the *maxdelay*, *maxdelayratio*, and *maxdelaydevratio* (or + *maxdelayquant*) tests, and a test for synchronisation loop (1=pass, + 0=fail). The first test from these four also checks the server precision, + response time, and whether an interleaved response is acceptable for + synchronisation. [1111] +. Local poll [10] +. Remote poll [10] +. '`Score`' (an internal score within each polling level used to decide when to + increase or decrease the polling level. This is adjusted based on number of + measurements currently being used for the regression algorithm). [1.0] +. The estimated local clock error (_theta_ in RFC 5905). Positive indicates + that the local clock is slow of the remote source. [-4.966e-03] +. The peer delay (_delta_ in RFC 5905). [2.296e-01] +. The peer dispersion (_epsilon_ in RFC 5905). [1.577e-05] +. The root delay (_DELTA_ in RFC 5905). [1.615e-01] +. The root dispersion (_EPSILON_ in RFC 5905). [7.446e-03] +. Reference ID of the server's source as a hexadecimal number. [CB00717B] +. NTP mode of the received packet (_1_=active peer, _2_=passive peer, + _4_=server, _B_=basic, _I_=interleaved). [4B] +. Source of the local transmit timestamp + (_D_=daemon, _K_=kernel, _H_=hardware). [D] +. Source of the local receive timestamp + (_D_=daemon, _K_=kernel, _H_=hardware). [K] ++ +*measurements*::: +This option is identical to the *rawmeasurements* option, except it logs only +valid measurements from synchronised sources, i.e. measurements which passed +the RFC 5905 tests 1 through 7. This can be useful for producing graphs of the +source's performance. ++ +*statistics*::: +This option logs information about the regression processing to a file called +_statistics.log_. An example line (which actually appears as a single line in +the file) from the log file is shown below. ++ +---- +2016-08-10 05:40:50 203.0.113.15 6.261e-03 -3.247e-03 \ + 2.220e-03 1.874e-06 1.080e-06 7.8e-02 16 0 8 0.00 +---- ++ +The columns are as follows (the quantities in square brackets are the values +from the example line above): ++ +. Date [2015-07-22] +. Hour:Minute:Second. Note that the date-time pair is expressed in + UTC, not the local time zone. [05:40:50] +. IP address of server or peer from which measurement comes [203.0.113.15] +. The estimated standard deviation of the measurements from the source (in + seconds). [6.261e-03] +. The estimated offset of the source (in seconds, positive means the local + clock is estimated to be fast, in this case). [-3.247e-03] +. The estimated standard deviation of the offset estimate (in seconds). + [2.220e-03] +. The estimated rate at which the local clock is gaining or losing time + relative to the source (in seconds per second, positive means the local clock + is gaining). This is relative to the compensation currently being applied to + the local clock, _not_ to the local clock without any compensation. + [1.874e-06] +. The estimated error in the rate value (in seconds per second). [1.080e-06]. +. The ratio of |old_rate - new_rate| / old_rate_error. Large values + indicate the statistics are not modelling the source very well. [7.8e-02] +. The number of measurements currently being used for the regression + algorithm. [16] +. The new starting index (the oldest sample has index 0; this is the method + used to prune old samples when it no longer looks like the measurements fit a + linear model). [0, i.e. no samples discarded this time] +. The number of runs. The number of runs of regression residuals with the same + sign is computed. If this is too small it indicates that the measurements are + no longer represented well by a linear model and that some older samples need + to be discarded. The number of runs for the data that is being retained is + tabulated. Values of approximately half the number of samples are expected. + [8] +. The estimated or configured asymmetry of network jitter on the path to the + source which was used to correct the measured offsets. The asymmetry can be + between -0.5 and +0.5. A negative value means the delay of packets sent to + the source is more variable than the delay of packets sent from the source + back. [0.00, i.e. no correction for asymmetry] ++ +*selection*::: +This option logs information about selection of sources for synchronisation to +a file called _selection.log_. Note that the rate of entries written to this +file grows quadratically with the number of specified sources (each measurement +triggers the selection for all sources). An example line (which actually +appears as a single line in the file) from the log file is shown below. ++ +---- +2022-05-01 02:01:20 203.0.113.15 * ----- 377 1.00 \ + 4.228e+01 -1.575e-04 1.239e-04 +---- ++ +The columns are as follows (the quantities in square brackets are the values +from the example line above): ++ +. Date [2022-05-01] +. Hour:Minute:Second. Note that the date-time pair is expressed in + UTC, not the local time zone. [02:01:20] +. IP address or reference ID of the source. [203.0.113.15] +. State of the source indicated with one of the following symbols. [*] +{blank}:::: +Not considered selectable for synchronisation: +* _N_ - has the *noselect* option. +* _s_ - is not synchronised. +* _M_ - does not have enough measurements. +* _d_ - has a root distance larger than the maximum distance (configured by the + <<maxdistance,*maxdistance*>> directive). +* _~_ - has a jitter larger than the maximum jitter (configured by the + <<maxjitter,*maxjitter*>> directive). +* _w_ - waits for other sources to get out of the _M_ state. +* _S_ - has older measurements than other sources. +* _O_ - has a stratum equal or larger than the orphan stratum (configured by + the <<local,*local*>> directive). +* _T_ - does not fully agree with sources that have the *trust* option. +* _x_ - does not agree with other sources (falseticker). +{blank}:::: +Considered selectable for synchronisation, but not currently used: +* _W_ - waits for other sources to be selectable (required by the + <<minsources,*minsources*>> directive, or the *require* option of + another source). +* _P_ - another selectable source is preferred due to the *prefer* option. +* _U_ - waits for a new measurement (after selecting a different best source). +* _D_ - has, or recently had, a root distance which is too large to be combined + with other sources (configured by the <<combinelimit,*combinelimit*>> + directive). +{blank}:::: +Used for synchronisation of the local clock: +* _+_ - combined with the best source. +* _*_ - selected as the best source to update the reference data (e.g. root + delay, root dispersion). +. Current effective selection options of the source. which can be different + from the configured options due to the authentication selection mode + (configured by the <<authselectmode,*authselectmode*>> directive). [-----] +* _N_ indicates the *noselect* option. +* _P_ indicates the *prefer* option. +* _T_ indicates the *trust* option. +* _R_ indicates the *require* option. +. Reachability register printed as an octal number. The register has 8 bits and + is updated on every received or missed packet from the source. A value of 377 + indicates that a valid reply was received for all from the last eight + transmissions. [377] +. Current score against the source in the _*_ state. The scoring system avoids + frequent reselection when multiple sources have a similar root distance. A + value larger than 1 indicates this source was better than the _*_ source in + recent selections. If the score reaches 10, the best source will be reselected + and the scores will be reset to 1. [1.00] +. Interval since the last measurement of the source in seconds. [4.228e+01] +. Lower endpoint of the interval which was expected to contain the true offset + of the local clock determined by the root distance of the source. [-1.575e-04] +. Upper endpoint of the interval which was expected to contain the true offset + of the local clock determined by the root distance of the source. [1.239e-04] ++ +*tracking*::: +This option logs changes to the estimate of the system's gain or loss rate, and +any slews made, to a file called _tracking.log_. An example line (which +actually appears as a single line in the file) from the log file is shown +below. ++ +---- +2017-08-22 13:22:36 203.0.113.15 2 -3.541 0.075 -8.621e-06 N \ + 2 2.940e-03 -2.084e-04 1.534e-02 3.472e-04 8.304e-03 +---- ++ +The columns are as follows (the quantities in square brackets are the +values from the example line above) : ++ +. Date [2017-08-22] +. Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the + local time zone. [13:22:36] +. The IP address of the server or peer to which the local system is synchronised. + [203.0.113.15] +. The stratum of the local system. [2] +. The local system frequency (in ppm, positive means the local system runs fast + of UTC). [-3.541] +. The error bounds on the frequency (in ppm). [0.075] +. The estimated local offset at the epoch, which is normally corrected by + slewing the local clock (in seconds, positive indicates the clock is fast of + UTC). [-8.621e-06] +. Leap status (_N_ means normal, _+_ means that the last minute of this month + has 61 seconds, _-_ means that the last minute of the month has 59 seconds, + _?_ means the clock is not currently synchronised.) [N] +. The number of combined sources. [2] +. The estimated standard deviation of the combined offset (in seconds). + [2.940e-03] +. The remaining offset correction from the previous update (in seconds, + positive means the system clock is slow of UTC). [-2.084e-04] +. The total of the network path delays to the reference clock to which + the local clock is ultimately synchronised (in seconds). [1.534e-02] +. The total dispersion accumulated through all the servers back to the + reference clock to which the local clock is ultimately synchronised + (in seconds). [3.472e-04] +. The maximum estimated error of the system clock in the interval since the + previous update (in seconds). It includes the offset, remaining offset + correction, root delay, and dispersion from the previous update with the + dispersion which accumulated in the interval. [8.304e-03] ++ +*rtc*::: +This option logs information about the system's real-time clock. An example +line (which actually appears as a single line in the file) from the _rtc.log_ +file is shown below. ++ +---- +2015-07-22 05:40:50 -0.037360 1 -0.037434\ + -37.948 12 5 120 +---- ++ +The columns are as follows (the quantities in square brackets are the +values from the example line above): ++ +. Date [2015-07-22] +. Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the + local time zone. [05:40:50] +. The measured offset between the RTC and the system clock in seconds. + Positive indicates that the RTC is fast of the system time [-0.037360]. +. Flag indicating whether the regression has produced valid coefficients. + (1 for yes, 0 for no). [1] +. Offset at the current time predicted by the regression process. A large + difference between this value and the measured offset tends to indicate that + the measurement is an outlier with a serious measurement error. [-0.037434] +. The rate at which the RTC is losing or gaining time relative to the system + clock. In ppm, with positive indicating that the RTC is gaining time. + [-37.948] +. The number of measurements used in the regression. [12] +. The number of runs of regression residuals of the same sign. Low values + indicate that a straight line is no longer a good model of the measured data + and that older measurements should be discarded. [5] +. The measurement interval used prior to the measurement being made (in + seconds). [120] ++ +*refclocks*::: +This option logs the raw and filtered reference clock measurements to a file +called _refclocks.log_. An example line (which actually appears as a single +line in the file) from the log file is shown below. ++ +---- +2009-11-30 14:33:27.000000 PPS2 7 N 1 4.900000e-07 -6.741777e-07 1.000e-06 +---- ++ +The columns are as follows (the quantities in square brackets are the values +from the example line above): ++ +. Date [2009-11-30] +. Hour:Minute:Second.Microsecond. Note that the date-time pair is expressed in + UTC, not the local time zone. [14:33:27.000000] +. Reference ID of the reference clock from which the measurement came. [PPS2] +. Sequence number of driver poll within one polling interval for raw samples, + or _-_ for filtered samples. [7] +. Leap status (_N_ means normal, _+_ means that the last minute of the current + month has 61 seconds, _-_ means that the last minute of the month has 59 + seconds). [N] +. Flag indicating whether the sample comes from PPS source. (1 for yes, + 0 for no, or _-_ for filtered sample). [1] +. Local clock error measured by reference clock driver, or _-_ for filtered sample. + [4.900000e-07] +. Local clock error with applied corrections. Positive indicates that the local + clock is slow. [-6.741777e-07] +. Assumed dispersion of the sample. [1.000e-06] ++ +*tempcomp*::: +This option logs the temperature measurements and system rate compensations to +a file called _tempcomp.log_. An example line (which actually appears as a +single line in the file) from the log file is shown below. ++ +---- +2015-04-19 10:39:48 2.8000e+04 3.6600e-01 +---- ++ +The columns are as follows (the quantities in square brackets are the values +from the example line above): ++ +. Date [2015-04-19] +. Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the + local time zone. [10:39:48] +. Temperature read from the sensor. [2.8000e+04] +. Applied compensation in ppm, positive means the system clock is running + faster than it would be without the compensation. [3.6600e-01] ++ +{blank}:: +An example of the directive is: ++ +---- +log measurements statistics tracking +---- + +[[logbanner]]*logbanner* _entries_:: +A banner is periodically written to the log files enabled by the <<log,*log*>> +directive to indicate the meanings of the columns. ++ +The *logbanner* directive specifies after how many entries in the log file +should be the banner written. The default is 32, and 0 can be used to disable +it entirely. + +[[logchange]]*logchange* _threshold_:: +This directive sets the threshold for the adjustment of the system clock that +will generate a syslog message. Clock errors detected via NTP packets, +reference clocks, or timestamps entered via the +<<chronyc.adoc#settime,*settime*>> command of *chronyc* are logged. ++ +By default, the threshold is 1 second. ++ +An example of the use is: ++ +---- +logchange 0.1 +---- ++ +which would cause a syslog message to be generated if a system clock error of over +0.1 seconds starts to be compensated. + +[[logdir]]*logdir* _directory_:: +This directive specifies the directory for writing log files enabled by the +*log* directive. If the directory does not exist, it will be created +automatically. ++ +An example of the use of this directive is: ++ +---- +logdir /var/log/chrony +---- + +[[mailonchange]]*mailonchange* _email_ _threshold_:: +This directive defines an email address to which mail should be sent if +*chronyd* applies a correction exceeding a particular threshold to the system +clock. ++ +An example of the use of this directive is: ++ +---- +mailonchange root@localhost 0.5 +---- ++ +This would send a mail message to root if a change of more than 0.5 seconds +were applied to the system clock. ++ +This directive cannot be used when a system call filter is enabled by the *-F* +option as the *chronyd* process will not be allowed to fork and execute the +sendmail binary. + +=== Miscellaneous + +[[confdir]]*confdir* _directory_...:: +The *confdir* directive includes configuration files with the _.conf_ suffix +from a directory. The files are included in the lexicographical order of the +file names. ++ +Multiple directories (up to 10) can be specified with a single *confdir* +directive. In this case, if multiple directories contain a file with the same +name, only the first file in the order of the specified directories will be +included. This enables a fragmented configuration where existing fragments can +be replaced by adding files to a different directory. ++ +This directive can be used multiple times. ++ +An example of the directive is: ++ +---- +confdir @SYSCONFDIR@/chrony.d +---- + +[[sourcedir]]*sourcedir* _directory_...:: +The *sourcedir* directive is identical to the *confdir* directive, except the +configuration files have the _.sources_ suffix, they can only specify NTP +sources (i.e. the *server*, *pool*, and *peer* directives), they are expected +to have all lines terminated by the newline character, and they can be +reloaded by the <<chronyc.adoc#reload,*reload sources*>> command in +*chronyc*. It is particularly useful with dynamic sources like NTP servers +received from a DHCP server, which can be written to a file specific to the +network interface by a networking script. ++ +This directive can be used multiple times. ++ +An example of the directive is: ++ +---- +sourcedir /var/run/chrony-dhcp +---- + +[[include]]*include* _pattern_:: +The *include* directive includes a configuration file, or multiple configuration +files if a wildcard pattern is specified. Unlike with the *confdir* directive, +the full name of the files needs to be specified and at least one file is +required to exist. ++ +This directive can be used multiple times. ++ +An example of the directive is: ++ +---- +include @SYSCONFDIR@/chrony.d/*.conf +---- + +[[hwtimestamp]]*hwtimestamp* _interface_ [_option_]...:: +This directive enables hardware timestamping of NTP packets sent to and +received from the specified network interface. The network interface controller +(NIC) uses its own clock to accurately timestamp the actual transmissions and +receptions, avoiding processing and queueing delays in the kernel, network +driver, and hardware. This can significantly improve the accuracy of the +timestamps and the measured offset, which is used for synchronisation of the +system clock. In order to get the best results, both sides receiving and +sending NTP packets (i.e. server and client, or two peers) need to use HW +timestamping. If the server or peer supports the interleaved mode, it needs to +be enabled by the *xleave* option in the <<server,*server*>> or the +<<peer,*peer*>> directive. ++ +This directive is supported on Linux 3.19 and newer. The NIC must support HW +timestamping, which can be verified with the *ethtool -T* command. The list of +capabilities should include _hardware-raw-clock_, _hardware-transmit_, and +_hardware-receive_. The receive filter _all_, or _ntp_, is necessary for +timestamping of received NTP packets. Timestamping of packets received on +bridged and bonded interfaces is supported on Linux 4.13 and newer. If HW +timestamping does not work for received packets, *chronyd* will use kernel +receive timestamps instead. Transmit-only HW timestamping can still be useful +to improve stability of the synchronisation. ++ +*chronyd* does not synchronise the NIC clock. It assumes the clock is running +free. Multiple instances of *chronyd* can use the same interface with enabled +HW timestamping. Applications which need HW timestamping with a synchronised +clock (e.g. a PTP daemon) should use a virtual clock running on top of the +physical clock created by writing to _/sys/class/ptp/ptpX/n_vclocks_. This +feature is available on Linux 5.14 and newer. ++ +If the kernel supports software timestamping, it will be enabled for all +interfaces automatically. ++ +The source of timestamps (i.e. hardware, kernel, or daemon) is indicated on the +client side in the _measurements.log_ file (if enabled by the <<log,*log*>> +directive) and the <<chronyc.adoc#ntpdata,*ntpdata*>> report. On the server +side, the number of served timestamps from each source is provided in the +<<chronyc.adoc#serverstats,*serverstats*>> report. ++ +This directive can be used multiple times to enable HW timestamping on multiple +interfaces. If the specified interface is _*_, *chronyd* will try to enable HW +timestamping on all available interfaces. ++ +The *hwtimestamp* directive has the following options: ++ +*minpoll* _poll_::: +This option specifies the minimum interval between readings of the NIC clock. +It's defined as a power of 2. It should correspond to the minimum polling +interval of all NTP sources and the minimum expected polling interval of NTP +clients. The default value is 0 (1 second), the minimum value is -6 (1/64th +of a second), and the maximum value is 20 (about 12 days). +*maxpoll* _poll_::: +This option specifies the maximum interval between readings of the NIC clock, +as a power of 2. The default value is *minpoll* + 1, i.e. 1 (2 seconds) with +the default *minpoll* of 0. The minimum and maximum values are the same as with +the *minpoll* option. +*minsamples* _samples_::: +This option specifies the minimum number of readings kept for tracking of the +NIC clock. The default value is 2. +*maxsamples* _samples_::: +This option specifies the maximum number of readings kept for tracking of the +NIC clock. The default value is 16. +*precision* _precision_::: +This option specifies the assumed precision of reading of the NIC clock. The +default value is 100e-9 (100 nanoseconds). +*txcomp* _compensation_::: +This option specifies the difference in seconds between the actual transmission +time at the physical layer and the reported transmit timestamp. This value will +be added to transmit timestamps obtained from the NIC. The default value is 0. +*rxcomp* _compensation_::: +This option specifies the difference in seconds between the reported receive +timestamp and the actual reception time at the physical layer. This value will +be subtracted from receive timestamps obtained from the NIC. The default value +is 0. +*nocrossts*::: +Some hardware can precisely cross timestamp the NIC clock with the system +clock. This option disables the use of the cross timestamping. +*rxfilter* _filter_::: +This option selects the receive timestamping filter. The _filter_ can be one of +the following: +_all_:::: +Enables timestamping of all received packets. +_ntp_:::: +Enables timestamping of received NTP packets. +_ptp_:::: +Enables timestamping of received PTP packets. +_none_:::: +Disables timestamping of received packets. +{blank}::: +The most specific filter for timestamping of NTP packets supported by the NIC +is selected by default. Some NICs can timestamp PTP packets only. By default, +they will be configured with the _none_ filter and expected to provide hardware +timestamps for transmitted packets only. Timestamping of PTP packets is useful +with NTP-over-PTP enabled by the <<chrony.conf.adoc#ptpport,*ptpport*>> +directive, or when another application is receiving PTP packets on the +interface. Forcing timestamping of all packets with the _all_ filter could be +useful if the NIC supported both the _all_ and _ntp_ filters, and it should +timestamp both NTP and PTP packets, or NTP packets on a different UDP port. +{blank}:: ++ +Examples of the directive are: ++ +---- +hwtimestamp eth0 +hwtimestamp eth1 txcomp 300e-9 rxcomp 645e-9 +hwtimestamp * +---- + +[[hwtstimeout]]*hwtstimeout* _timeout_:: +If hardware timestamping is used with a close NTP server, or the NIC or its +driver is slow in providing the transmit timestamp of NTP requests, a response +from the server can be received before the transmit timestamp of the request. +To avoid calculating the offset with a less accurate transmit timestamp, +*chronyd* can save the response for later processing and wait for the hardware +transmit timestamp. There is no guarantee that the timestamp will be provided +(NICs typically have a limited rate of transmit timestamping). This directive +configures how long should *chronyd* wait for the timestamp after receiving a +valid response from the server. If a second valid response is received from the +server while waiting for the timestamp, they will be both processed +immediately. ++ +The default value is 0.001 seconds, which should be sufficient with most +hardware. If you frequently see kernel transmit timestamps in the +_measurements.log_ file or <<chronyc.adoc#ntpdata,*ntpdata*>> report, and it is +not a server handling a high rate of requests in the interleaved mode on the +same interface (which would compete with timestamping of the server's own +requests), increasing the timeout to 0.01 or possibly even longer might help. +Note that the maximum timeout is limited by the NTP polling interval. + +[[keyfile]]*keyfile* _file_:: +This directive is used to specify the location of the file containing symmetric +keys which are shared between NTP servers and clients, or peers, in order to +authenticate NTP packets with a message authentication code (MAC) using a +cryptographic hash function or cipher. ++ +The format of the directive is shown in the example below: ++ +---- +keyfile @SYSCONFDIR@/chrony.keys +---- ++ +The argument is simply the name of the file containing the ID-key pairs. The +format of the file is shown below: ++ +---- +10 tulip +11 hyacinth +20 MD5 ASCII:crocus +25 SHA1 HEX:933F62BE1D604E68A81B557F18CFA200483F5B70 +30 AES128 HEX:7EA62AE64D190114D46D5A082F948EC1 +31 AES256 HEX:37DDCBC67BB902BCB8E995977FAB4D2B5642F5B32EBCEEE421921D97E5CBFE39 + ... +---- ++ +Each line consists of an ID, optional type, and key. ++ +The ID can be any positive integer in the range 1 through 2^32-1. ++ +The type is a name of a cryptographic hash function or cipher which is used to +generate and verify the MAC. The default type is *MD5*, which is always +supported. +If *chronyd* was built with enabled support for hashing using a crypto library +(Nettle, GnuTLS, NSS, or LibTomCrypt), the following functions are available: *MD5*, +*SHA1*, *SHA256*, *SHA384*, *SHA512*. Depending on which library and version is +*chronyd* using, some of the following hash functions and ciphers may +also be available: +*SHA3-224*, *SHA3-256*, *SHA3-384*, *SHA3-512*, *TIGER*, *WHIRLPOOL*, *AES128*, +*AES256*. ++ +The key can be specified as a string of ASCII characters not containing white +space with an optional *ASCII:* prefix, or as a hexadecimal number with the +*HEX:* prefix. The maximum length of the line is 2047 characters. +If the type is a cipher, the length of the key must match the cipher (i.e. 128 +bits for AES128 and 256 bits for AES256). ++ +It is recommended to use randomly generated keys, specified in the hexadecimal +format, which are at least 128 bits long (i.e. they have at least 32 characters +after the *HEX:* prefix). *chronyd* will log a warning to syslog on start if a +source is specified in the configuration file with a key shorter than 80 bits. ++ +The recommended key types are AES ciphers and SHA3 hash functions. MD5 should +be avoided unless no other type is supported on the server and client, or +peers. ++ +The <<chronyc.adoc#keygen,*keygen*>> command of *chronyc* can be used to +generate random keys for the key file. By default, it generates 160-bit MD5 or +SHA1 keys. ++ +For security reasons, the file should be readable only by root and the user +under which *chronyd* is normally running (to allow *chronyd* to re-read the +file when the <<chronyc.adoc#rekey,*rekey*>> command is issued by *chronyc*). + +[[lock_all]]*lock_all*:: +The *lock_all* directive will lock the *chronyd* process into RAM so that it +will never be paged out. This can result in lower and more consistent latency. +The directive is supported on Linux, FreeBSD, NetBSD, and illumos. + +[[pidfile]]*pidfile* _file_:: +Unless *chronyd* is started with the *-Q* option, it writes its process ID +(PID) to a file, and checks this file on startup to see if another *chronyd* +might already be running on the system. By default, the file used is +_@DEFAULT_PID_FILE@_. The *pidfile* directive allows the name to be changed, +e.g.: ++ +---- +pidfile /run/chronyd.pid +---- + +[[ptpport]]*ptpport* _port_:: +The *ptpport* directive enables *chronyd* to send and receive NTP messages +contained in PTP event messages (NTP-over-PTP) to enable hardware timestamping +on NICs which cannot timestamp NTP packets, but can timestamp unicast PTP +packets, and also use corrections provided by PTP one-step end-to-end +transparent clocks in network switches and routers. The port recognized by the +NICs and PTP transparent clocks is 319 (PTP event port). The default value is 0 +(disabled). ++ +The NTP-over-PTP support is experimental. The protocol and configuration can +change in future. It should be used only in local networks. ++ +The PTP port will be open even if *chronyd* is not configured to operate as a +server or client. The directive does not change the default protocol of +specified NTP sources. Each NTP source that should use NTP-over-PTP needs to +be specified with the *port* option set to the PTP port. To actually enable +hardware timestamping on NICs which can timestamp PTP packets only, the +*rxfilter* option of the *hwtimestamp* directive needs to be set to _ptp_. The +extension field _F324_ needs to be enabled to use the corrections provided by +the PTP transparent clocks. ++ +An example of client configuration is: ++ +---- +server ntp1.example.net minpoll 0 maxpoll 0 xleave port 319 extfield F324 +hwtimestamp * rxfilter ptp +ptpport 319 +---- + +[[sched_priority]]*sched_priority* _priority_:: +On Linux, FreeBSD, NetBSD, and illumos, the *sched_priority* directive will +select the SCHED_FIFO real-time scheduler at the specified priority (which must +be between 0 and 100). On macOS, this option must have either a value of 0 (the +default) to disable the thread time constraint policy or 1 for the policy to be +enabled. ++ +On systems other than macOS, this directive uses the *pthread_setschedparam()* +system call to instruct the kernel to use the SCHED_FIFO first-in, first-out +real-time scheduling policy for *chronyd* with the specified priority. This +means that whenever *chronyd* is ready to run it will run, interrupting +whatever else is running unless it is a higher priority real-time process. This +should not impact performance as *chronyd* resource requirements are modest, +but it should result in lower and more consistent latency since *chronyd* will +not need to wait for the scheduler to get around to running it. You should not +use this unless you really need it. The *pthread_setschedparam(3)* man page has +more details. ++ +On macOS, this directive uses the *thread_policy_set()* kernel call to +specify real-time scheduling. As noted above, you should not use this directive +unless you really need it. + +[[user]]*user* _user_:: +The *user* directive sets the name of the system user to which *chronyd* will +switch after start in order to drop root privileges. ++ +On Linux, *chronyd* needs to be compiled with support for the *libcap* library. +On macOS, FreeBSD, NetBSD and illumos *chronyd* forks into two processes. +The child process retains root privileges, but can only perform a very limited +range of privileged system calls on behalf of the parent. ++ +The compiled-in default value is _@DEFAULT_USER@_. + +[[examples]] +== EXAMPLES + +=== NTP client with permanent connection to NTP servers + +This section shows how to configure *chronyd* for computers that are connected +to the Internet (or to any network containing true NTP servers which ultimately +derive their time from a reference clock) permanently or most of the time. + +To operate in this mode, you will need to know the names of the NTP servers +you want to use. You might be able to find names of suitable servers by one of +the following methods: + +* Your institution might already operate servers on its network. + Contact your system administrator to find out. +* Your ISP probably has one or more NTP servers available for its + customers. +* Somewhere under the NTP homepage there is a list of public + stratum 1 and stratum 2 servers. You should find one or more servers that are + near to you. Check that their access policy allows you to use their + facilities. +* Use public servers from the https://www.pool.ntp.org/[pool.ntp.org] project. + +Assuming that your NTP servers are called _ntp1.example.net_, _ntp2.example.net_ +and _ntp3.example.net_, your _chrony.conf_ file could contain as a minimum: + +---- +server ntp1.example.net +server ntp2.example.net +server ntp3.example.net +---- + +However, you will probably want to include some of the other directives. The +<<driftfile,*driftfile*>>, <<makestep,*makestep*>> and <<rtcsync,*rtcsync*>> +might be particularly useful. Also, the *iburst* option of the +<<server,*server*>> directive is useful to speed up the initial +synchronisation. The smallest useful configuration file would look something +like: + +---- +server ntp1.example.net iburst +server ntp2.example.net iburst +server ntp3.example.net iburst +driftfile @CHRONYVARDIR@/drift +makestep 1.0 3 +rtcsync +---- + +When using a pool of NTP servers (one name is used for multiple servers which +might change over time), it is better to specify them with the <<pool,*pool*>> +directive instead of multiple *server* directives. The configuration file could +in this case look like: + +---- +pool pool.ntp.org iburst +driftfile @CHRONYVARDIR@/drift +makestep 1.0 3 +rtcsync +---- + +If the servers (or pool) support the Network Time Security (NTS) +authentication mechanism and *chronyd* is compiled with NTS support, the *nts* +option will enable a secure synchronisation to the servers. The configuration +file could look like: + +---- +server ntp1.example.net iburst nts +server ntp2.example.net iburst nts +server ntp3.example.net iburst nts +driftfile @CHRONYVARDIR@/drift +makestep 1.0 3 +rtcsync +---- + +=== NTP client with infrequent connection to NTP servers + +This section shows how to configure *chronyd* for computers that have +occasional connections to NTP servers. In this case, you will need some +additional configuration to tell *chronyd* when the connection goes up and +down. This saves the program from continuously trying to poll the servers when +they are inaccessible. + +Again, assuming that your NTP servers are called _ntp1.example.net_, +_ntp2.example.net_ and _ntp3.example.net_, your _chrony.conf_ file would now +contain: + +---- +server ntp1.example.net offline +server ntp2.example.net offline +server ntp3.example.net offline +driftfile @CHRONYVARDIR@/drift +makestep 1.0 3 +rtcsync +---- + +The *offline* keyword indicates that the servers start in an offline state, and +that they should not be contacted until *chronyd* receives notification from +*chronyc* that the link to the Internet is present. To tell *chronyd* when to +start and finish sampling the servers, the <<chronyc.adoc#online,*online*>> and +<<chronyc.adoc#offline,*offline*>> commands of *chronyc* need to be used. + +To give an example of their use, assuming that *pppd* is the program being +used to connect to the Internet and that *chronyc* has been installed at +_@BINDIR@/chronyc_, the script _/etc/ppp/ip-up_ would include: + +---- +@BINDIR@/chronyc online +---- + +and the script _/etc/ppp/ip-down_ would include: + +---- +@BINDIR@/chronyc offline +---- + +*chronyd*'s polling of the servers would now only occur whilst the machine is +actually connected to the Internet. + +=== Isolated networks + +This section shows how to configure *chronyd* for computers that never have +network connectivity to any computer which ultimately derives its time from a +reference clock. + +In this situation, one computer is selected to be the primary timeserver. The +other computers are either direct clients of the server, or clients of clients. + +The <<local,*local*>> directive enables a local reference mode, which allows +*chronyd* to appear synchronised even when it is not. + +The rate value in the server's drift file needs to be set to the average rate +at which the server gains or loses time. *chronyd* includes support for this, +in the form of the <<manual,*manual*>> directive and the +<<chronyc.adoc#settime,*settime*>> command in the *chronyc* program. + +If the server is rebooted, *chronyd* can re-read the drift rate from the drift +file. However, the server has no accurate estimate of the current time. To get +around this, the system can be configured so that the server can initially set +itself to a '`majority-vote`' of selected clients' times; this allows the +clients to '`flywheel`' the server while it is rebooting. + +The <<smoothtime,*smoothtime*>> directive is useful when the clocks of the +clients need to stay close together when the local time is adjusted by the +<<chronyc.adoc#settime,*settime*>> command. The smoothing process needs to be +activated by the <<chronyc.adoc#smoothtime,*smoothtime activate*>> command when +the local time is ready to be served. After that point, any adjustments will be +smoothed out. + +A typical configuration file for the server (called _ntp.local_) might be +(assuming the clients and the server are in the _192.168.165.x_ subnet): + +---- +initstepslew 1 client1 client3 client6 +driftfile @CHRONYVARDIR@/drift +local stratum 8 +manual +allow 192.168.165.0/24 +smoothtime 400 0.01 +rtcsync +---- + +For the clients that have to resynchronise the server when it restarts, +the configuration file might be: + +---- +server ntp.local iburst +driftfile @CHRONYVARDIR@/drift +allow 192.168.165.0/24 +makestep 1.0 3 +rtcsync +---- + +The rest of the clients would be the same, except that the *allow* directive is +not required. + +If there is no suitable computer to be designated as the primary server, or +there is a requirement to keep the clients synchronised even when it fails, the +*orphan* option of the *local* directive enables a special mode where the +server is selected from multiple computers automatically. They all need to use +the same *local* configuration and poll one another. The server with the +smallest reference ID (which is based on its IP address) will take the role of +the primary server and others will be synchronised to it. When it fails, the +server with the second smallest reference ID will take over and so on. + +A configuration file for the first server might be (assuming there are three +servers called _ntp1.local_, _ntp2.local_, and _ntp3.local_): + +---- +initstepslew 1 ntp2.local ntp3.local +server ntp2.local +server ntp3.local +driftfile @CHRONYVARDIR@/drift +local stratum 8 orphan +manual +allow 192.168.165.0/24 +rtcsync +---- + +The other servers would be the same, except the hostnames in the *initstepslew* +and *server* directives would be modified to specify the other servers. Their +clients might be configured to poll all three servers. + +=== RTC tracking + +This section considers a computer which has occasional connections to the +Internet and is turned off between '`sessions`'. In this case, *chronyd* relies +on the computer's RTC to maintain the time between the periods when it is +powered up. It assumes that Linux is run exclusively on the computer. Dual-boot +systems might work; it depends what (if anything) the other system does to the +RTC. On 2.6 and later kernels, if your motherboard has a HPET, you will need to +enable the *HPET_EMULATE_RTC* option in your kernel configuration. Otherwise, +*chronyd* will not be able to interact with the RTC device and will give up +using it. + +When the computer is connected to the Internet, *chronyd* has access to +external NTP servers which it makes measurements from. These measurements are +saved, and straight-line fits are performed on them to provide an estimate of +the computer's time error and rate of gaining or losing time. + +When the computer is taken offline from the Internet, the best estimate of the +gain or loss rate is used to free-run the computer until it next goes online. + +Whilst the computer is running, *chronyd* makes measurements of the RTC (via +the _/dev/rtc_ interface, which must be compiled into the kernel). An estimate +is made of the RTC error at a particular RTC second, and the rate at which the +RTC gains or loses time relative to true time. + +When the computer is powered down, the measurement histories for all the NTP +servers are saved to files, and the RTC tracking information is also +saved to a file (if the <<rtcfile,*rtcfile*>> directive has been specified). +These pieces of information are also saved if the <<chronyc.adoc#dump,*dump*>> +and <<chronyc.adoc#writertc,*writertc*>> commands respectively are issued +through *chronyc*. + +When the computer is rebooted, *chronyd* reads the current RTC time and the RTC +information saved at the last shutdown. This information is used to set the +system clock to the best estimate of what its time would have been now, had it +been left running continuously. The measurement histories for the servers are +then reloaded. + +The next time the computer goes online, the previous sessions' measurements can +contribute to the line-fitting process, which gives a much better estimate of +the computer's gain or loss rate. + +One problem with saving the measurements and RTC data when the machine is shut +down is what happens if there is a power failure; the most recent data will not +be saved. Although *chronyd* is robust enough to cope with this, some +performance might be lost. (The main danger arises if the RTC has been changed +during the session, with the *trimrtc* command in *chronyc*. Because of this, +*trimrtc* will make sure that a meaningful RTC file is saved after the +change is completed). + +The easiest protection against power failure is to put the *dump* and +*writertc* commands in the same place as the *offline* command is issued to +take *chronyd* offline; because *chronyd* free-runs between online sessions, no +parameters will change significantly between going offline from the Internet +and any power failure. + +A final point regards computers which are left running for extended periods and +where it is desired to spin down the hard disc when it is not in use (e.g. when +not accessed for 15 minutes). *chronyd* has been planned so it supports such +operation; this is the reason why the RTC tracking parameters are not saved to +disc after every update, but only when the user requests such a write, or +during the shutdown sequence. The only other facility that will generate +periodic writes to the disc is the *log rtc* facility in the configuration +file; this option should not be used if you want your disc to spin down. + +To illustrate how a computer might be configured for this case, example +configuration files are shown. + +For the _chrony.conf_ file, the following can be used as an example. + +---- +server ntp1.example.net maxdelay 0.4 offline +server ntp2.example.net maxdelay 0.4 offline +server ntp3.example.net maxdelay 0.4 offline +logdir /var/log/chrony +log statistics measurements tracking +driftfile @CHRONYVARDIR@/drift +makestep 1.0 3 +maxupdateskew 100.0 +dumpdir @CHRONYVARDIR@ +rtcfile @CHRONYVARDIR@/rtc +---- + +*pppd* is used for connecting to the Internet. This runs two scripts +_/etc/ppp/ip-up_ and _/etc/ppp/ip-down_ when the link goes online and offline +respectively. + +The relevant part of the _/etc/ppp/ip-up_ file is: + +---- +@BINDIR@/chronyc online +---- + +and the relevant part of the _/etc/ppp/ip-down_ script is: + +---- +@BINDIR@/chronyc -m offline dump writertc +---- + +*chronyd* is started during the boot sequence with the *-r* and *-s* options. +It might need to be started before any software that depends on the system clock +not jumping or moving backwards, depending on the directives in *chronyd*'s +configuration file. + +For the system shutdown, *chronyd* should receive a SIGTERM several seconds +before the final SIGKILL; the SIGTERM causes the measurement histories and RTC +information to be saved. + +=== Public NTP server + +*chronyd* can be configured to operate as a public NTP server, e.g. to join the +https://www.pool.ntp.org/en/join.html[pool.ntp.org] project. The configuration +is similar to the NTP client with permanent connection, except it needs to +allow client access from all addresses. It is recommended to find at least four +good servers (e.g. from the pool, or on the NTP homepage). If the server has a +hardware reference clock (e.g. a GPS receiver), it can be specified by the +<<refclock,*refclock*>> directive. + +The amount of memory used for logging client accesses can be increased in order +to enable clients to use the interleaved mode even when the server has a large +number of clients, and better support rate limiting if it is enabled by the +<<ratelimit,*ratelimit*>> directive. The system timezone database, if it is +kept up to date and includes the _right/UTC_ timezone, can be used as a +reliable source to determine when a leap second will be applied to UTC. The +*-r* option with the <<dumpdir,*dumpdir*>> directive shortens the time in which +*chronyd* will not be able to serve time to its clients when it needs to be +restarted (e.g. after upgrading to a newer version, or a change in the +configuration). + +The configuration file could look like: + +---- +server ntp1.example.net iburst +server ntp2.example.net iburst +server ntp3.example.net iburst +server ntp4.example.net iburst +makestep 1.0 3 +rtcsync +allow +clientloglimit 100000000 +leapsectz right/UTC +driftfile @CHRONYVARDIR@/drift +dumpdir @CHRONYRUNDIR@ +---- + +== SEE ALSO + +<<chronyc.adoc#,*chronyc(1)*>>, <<chronyd.adoc#,*chronyd(8)*>> + +== BUGS + +For instructions on how to report bugs, please visit +https://chrony-project.org/. + +== AUTHORS + +chrony was written by Richard Curnow, Miroslav Lichvar, and others. diff --git a/doc/chrony.conf.man.in b/doc/chrony.conf.man.in new file mode 100644 index 0000000..66d2358 --- /dev/null +++ b/doc/chrony.conf.man.in @@ -0,0 +1,5043 @@ +'\" t +.\" Title: chrony.conf +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 2.0.20 +.\" Date: 2023-12-05 +.\" Manual: Configuration Files +.\" Source: chrony @CHRONY_VERSION@ +.\" Language: English +.\" +.TH "CHRONY.CONF" "5" "2023-12-05" "chrony @CHRONY_VERSION@" "Configuration Files" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +chrony.conf \- chronyd configuration file +.SH "SYNOPSIS" +.sp +\fBchrony.conf\fP +.SH "DESCRIPTION" +.sp +This file configures the \fBchronyd\fP daemon. The compiled\-in location is +\fI@SYSCONFDIR@/chrony.conf\fP. Other locations can be specified on the +\fBchronyd\fP command line with the \fB\-f\fP option. +.sp +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. +.sp +The configuration directives can also be specified directly on the \fBchronyd\fP +command line. In this case each argument is parsed as a new line and the +configuration file is ignored. +.sp +While the number of supported directives is large, only a few of them are +typically needed. See the \fBEXAMPLES\fP section for configuration in +typical operating scenarios. +.sp +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: \fB!\fP, \fB;\fP, \fB#\fP, \fB%\fP. Any line with this format will be ignored. +.SH "DIRECTIVES" +.SS "Time sources" +.sp +\fBserver\fP \fIhostname\fP [\fIoption\fP]... +.RS 4 +The \fBserver\fP 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\(cqs system time +will never be influenced by that of a client. +.sp +The server can be specified by its hostname or IP address. If the hostname cannot +be resolved on start, \fBchronyd\fP will try it again in increasing intervals, and +also when the \fBonline\fP command is issued in \fBchronyc\fP. +.sp +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 \fBmaxdistance\fP directive). The +automatic replacement happens at most once per 30 minutes. +.sp +This directive can be used multiple times to specify multiple servers. +.sp +The directive supports the following options: +.sp +\fBminpoll\fP \fIpoll\fP +.RS 4 +This option specifies the minimum interval between requests sent to the server +as a power of 2 in seconds. For example, \fBminpoll 5\fP 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. +.RE +.sp +\fBmaxpoll\fP \fIpoll\fP +.RS 4 +This option specifies the maximum interval between requests sent to the server +as a power of 2 in seconds. For example, \fBmaxpoll 9\fP 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). +.RE +.sp +\fBiburst\fP +.RS 4 +With this option, \fBchronyd\fP 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 +\fBonline\fP command in \fBchronyc\fP. +.RE +.sp +\fBburst\fP +.RS 4 +With this option, \fBchronyd\fP 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. +.RE +.sp +\fBkey\fP \fIID\fP +.RS 4 +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 \fBkeyfile\fP directive. +.sp +The \fBkey\fP option specifies which key (with an ID in the range 1 through 2^32\-1) +should \fBchronyd\fP 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. +.sp +If the server is running \fBntpd\fP and the output size of the hash function used +by the key is longer than 160 bits (e.g. SHA256), the \fBversion\fP option needs to +be set to 4 for compatibility. +.RE +.sp +\fBnts\fP +.RS 4 +This option enables authentication using the Network Time Security (NTS) +mechanism. Unlike with the \fBkey\fP 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. +.RE +.sp +\fBcertset\fP \fIID\fP +.RS 4 +This option specifies which set of trusted certificates should be used to verify +the server\(cqs certificate when the \fBnts\fP option is enabled. Sets of certificates +can be specified with the \fBntstrustedcerts\fP directive. The +default set is 0, which by default contains certificates of the system\(cqs +default trusted certificate authorities. +.RE +.sp +\fBmaxdelay\fP \fIdelay\fP +.RS 4 +\fBchronyd\fP 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. +.sp +For small variations in the round\-trip delay, \fBchronyd\fP 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). +.sp +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 \fBmaxdelay\fP +option. For example, \fBmaxdelay 0.3\fP 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. +.RE +.sp +\fBmaxdelayratio\fP \fIratio\fP +.RS 4 +This option is similar to the \fBmaxdelay\fP option above. \fBchronyd\fP 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. +.RE +.sp +\fBmaxdelaydevratio\fP \fIratio\fP +.RS 4 +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. +.RE +.sp +\fBmaxdelayquant\fP \fIp\fP +.RS 4 +This option disables the \fBmaxdelaydevratio\fP 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 \fIp\fP\-quantile, +it will be rejected. +.sp +The specified \fIp\fP value should be between 0.05 and 0.95. For example, +\fBmaxdelayquant 0.2\fP 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 \fBfilter\fP option. +By default, this test is disabled in favour of the \fBmaxdelaydevratio\fP test. +.RE +.sp +\fBmindelay\fP \fIdelay\fP +.RS 4 +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 \fBmaxdelayratio\fP and +\fBmaxdelaydevratio\fP tests. The value should be set accurately in order to have a +positive effect on the synchronisation. +.RE +.sp +\fBasymmetry\fP \fIratio\fP +.RS 4 +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, \fBchronyd\fP estimates the asymmetry automatically. +.RE +.sp +\fBoffset\fP \fIoffset\fP +.RS 4 +This option specifies a correction (in seconds) which will be applied to +offsets measured with this source. It\(cqs 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. +.RE +.sp +\fBminsamples\fP \fIsamples\fP +.RS 4 +Set the minimum number of samples kept for this source. This overrides the +\fBminsamples\fP directive. +.RE +.sp +\fBmaxsamples\fP \fIsamples\fP +.RS 4 +Set the maximum number of samples kept for this source. This overrides the +\fBmaxsamples\fP directive. +.RE +.sp +\fBfilter\fP \fIpolls\fP +.RS 4 +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. +.RE +.sp +\fBoffline\fP +.RS 4 +If the server will not be reachable when \fBchronyd\fP is started, the \fBoffline\fP +option can be specified. \fBchronyd\fP will not try to poll the server until it is +enabled to do so (by using the \fBonline\fP command in +\fBchronyc\fP). +.RE +.sp +\fBauto_offline\fP +.RS 4 +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 \fBoffline\fP command from \fBchronyc\fP +when disconnecting the network link. (It will still be necessary to use the +\fBonline\fP command when the link has been established, to +enable measurements to start.) +.RE +.sp +\fBprefer\fP +.RS 4 +Prefer this source over sources without the \fBprefer\fP option. +.RE +.sp +\fBnoselect\fP +.RS 4 +Never select this source. This is particularly useful for monitoring. +.RE +.sp +\fBtrust\fP +.RS 4 +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. +.RE +.sp +\fBrequire\fP +.RS 4 +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 \fBtrust\fP 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. +.RE +.sp +\fBxleave\fP +.RS 4 +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. +.sp +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. +\fBclientloglimit\fP 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). +.sp +The \fBxleave\fP option can be combined with the \fBpresend\fP 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. +.RE +.sp +\fBpolltarget\fP \fItarget\fP +.RS 4 +Target number of measurements to use for the regression algorithm which +\fBchronyd\fP will try to maintain by adjusting the polling interval between +\fBminpoll\fP and \fBmaxpoll\fP. A higher target makes \fBchronyd\fP prefer shorter polling +intervals. The default is 8 and a useful range is from 6 to 60. +.RE +.sp +\fBport\fP \fIport\fP +.RS 4 +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). +.RE +.sp +\fBntsport\fP \fIport\fP +.RS 4 +This option specifies the TCP port on which the server is listening for NTS\-KE +connections when the \fBnts\fP option is enabled. The default is 4460. +.RE +.sp +\fBpresend\fP \fIpoll\fP +.RS 4 +If the timing measurements being made by \fBchronyd\fP 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. +.sp +In order to avoid this problem, the \fBpresend\fP 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 \fBserver\fP directive: +.sp +.if n .RS 4 +.nf +.fam C +presend 9 +.fam +.fi +.if n .RE +.sp +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. +.sp +If the \fBpresend\fP option is used together with the \fBxleave\fP option, \fBchronyd\fP +will send two extra packets instead of one. +.RE +.sp +\fBminstratum\fP \fIstratum\fP +.RS 4 +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 \fBchronyd\fP 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. +.RE +.sp +\fBversion\fP \fIversion\fP +.RS 4 +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 \fBextfield\fP or \fBxleave\fP option is used, the default version is 4. If +those options are not used and the \fBkey\fP 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 \fBchronyd\fP servers. In other cases, +the default version is 4. +.RE +.sp +\fBcopy\fP +.RS 4 +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 \f(CRchronyd\fP 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 \fB\-x\fP +option to operate as NTP servers for other computers with their NTP clocks +synchronised to the first instance. +.RE +.sp +\fBextfield\fP \fItype\fP +.RS 4 +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 (\fBchronyd\fP as a server responded to such requests since +version 2.0). +.sp +This option can be used multiple times to enable multiple extension fields. +.sp +The following extension fields are supported: +.sp +\fIF323\fP +.RS 4 +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 \fBchronyd\fP version 4.2 or later. +.RE +.sp +\fIF324\fP +.RS 4 +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 \fBptpport\fP directive and setting the \fBport\fP option to +the PTP port. The corrections are applied only to NTP measurements with HW +timestamps (enabled by the \fBhwtimestamp\fP directive). This +field should be enabled only for servers known to be running \fBchronyd\fP version +4.5 or later. +.RE +.RE +.sp + +.RS 4 +.RE +.RE +.sp +\fBpool\fP \fIname\fP [\fIoption\fP]... +.RS 4 +The syntax of this directive is similar to that for the \fBserver\fP +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. +.sp +This directive can be used multiple times to specify multiple pools. +.sp +All options valid in the \fBserver\fP directive can be used in this +directive too. There is one option specific to the \fBpool\fP directive: +.sp +\fBmaxsources\fP \fIsources\fP +.RS 4 +This option sets the desired number of sources to be used from the pool. +\fBchronyd\fP 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. +.sp +An example of the \fBpool\fP directive is +.sp +.if n .RS 4 +.nf +.fam C +pool pool.ntp.org iburst maxsources 3 +.fam +.fi +.if n .RE +.RE +.RE +.sp +\fBpeer\fP \fIhostname\fP [\fIoption\fP]... +.RS 4 +The syntax of this directive is identical to that for the \fBserver\fP +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. \fBntpd\fP) supports +ephemeral symmetric associations and does not need to be configured with an +address of this host. \fBchronyd\fP does not support ephemeral associations. +.sp +This directive can be used multiple times to specify multiple peers. +.sp +The following options of the \fBserver\fP directive do not work in the \fBpeer\fP +directive: \fBiburst\fP, \fBburst\fP, \fBnts\fP, \fBpresend\fP, \fBcopy\fP. +.sp +When using the \fBxleave\fP 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 \fBkey\fP option to enable authentication, both +peers must use the same key and the same key number. +.sp +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 \fBkey\fP 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 \fBchronyd\fP, 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 +\fBserver\fP directive on both hosts) instead. +.RE +.sp +\fBinitstepslew\fP \fIstep\-threshold\fP [\fIhostname\fP]... +.RS 4 +(This directive is deprecated in favour of the \fBmakestep\fP +directive.) +.sp +The purpose of the \fBinitstepslew\fP directive is to allow \fBchronyd\fP 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. +.sp +If the correction required is less than a specified threshold, a slew is used +instead. This makes it safer to restart \fBchronyd\fP whilst the system is in +normal operation. +.sp +The \fBinitstepslew\fP 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. \fBchronyd\fP then enters its normal operating mode. +.sp +An example of the use of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +initstepslew 30 ntp1.example.net ntp2.example.net ntp3.example.net +.fam +.fi +.if n .RE +.sp +where 3 NTP servers are used to make the measurement. The \fI30\fP indicates that +if the system\(cqs 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. +.sp +The \fBinitstepslew\fP 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 \fBlocal\fP directive, the server can be set up +with an \fBinitstepslew\fP 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. +.sp +The \fBinitstepslew\fP directive is functionally similar to a combination of the +\fBmakestep\fP and \fBserver\fP directives with the \fBiburst\fP +option. The main difference is that the \fBinitstepslew\fP servers are used only +before normal operation begins and that the foreground \fBchronyd\fP process waits +for \fBinitstepslew\fP to finish before exiting. This prevent programs started in +the boot sequence after \fBchronyd\fP from reading the clock before it has been +stepped. With the \fBmakestep\fP directive, the +\fBwaitsync\fP command of \fBchronyc\fP can be used instead. +.RE +.sp +\fBrefclock\fP \fIdriver\fP \fIparameter\fP[:\fIoption\fP]... [\fIoption\fP]... +.RS 4 +The \fBrefclock\fP 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 \fB:\fP character. +.sp +This directive can be used multiple times to specify multiple reference clocks. +.sp +There are four drivers included in \fBchronyd\fP: +.sp +\fBPPS\fP +.RS 4 +Driver for the kernel PPS (pulse per second) API. The parameter is the path to +the PPS device (typically \fI/dev/pps?\fP). 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 +\fBlocal\fP directive to allow synchronisation with some unknown but +constant offset. The driver supports the following option: +.sp +\fBclear\fP +.RS 4 +By default, the PPS refclock uses assert events (rising edge) for +synchronisation. With this option, it will use clear events (falling edge) +instead. +.RE +.RE +.sp + +.RS 4 +Examples: +.sp +.if n .RS 4 +.nf +.fam C +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 +.fam +.fi +.if n .RE +.RE +.sp +\fBSOCK\fP +.RS 4 +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 \fBchronyd\fP will create on start. The format of the +messages is described in the \fIrefclock_sock.c\fP file in the chrony source code. +.sp +An application which supports the SOCK protocol is the \fBgpsd\fP daemon. It can +provide accurate measurements using the receiver\(cqs 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 \fBgpsd\fP +expects the sockets to be created by \fBchronyd\fP are described in the \fBgpsd(8)\fP +man page. Note that \fBgpsd\fP needs to be started after \fBchronyd\fP in order to +connect to the socket. +.sp +Examples: +.sp +.if n .RS 4 +.nf +.fam C +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 +.fam +.fi +.if n .RE +.RE +.sp +\fBSHM\fP +.RS 4 +NTP shared memory driver. This driver implements the protocol of the \fBntpd\fP +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. +.sp +The driver supports the following option: +.sp +\fBperm\fP=\fImode\fP +.RS 4 +This option specifies the permissions of the shared memory segment created by +\fBchronyd\fP. They are specified as a numeric mode. The default value is 0600 +(read\-write access for owner only). +.RE +.RE +.sp + +.RS 4 +.sp +Unlike with the SOCK driver, there is no prescribed order of starting \fBchronyd\fP +and the program providing measurements. Both are expected to create the memory +segment if it does not exist. \fBchronyd\fP will attach to an existing segment even +if it has a different owner than root or different permissions than the +permissions specified by the \fBperm\fP option. The segment needs to be created +before untrusted applications or users can execute code to prevent an attacker +from feeding \fBchronyd\fP with false measurements. The owner and permissions of +the segment can be verified with the \fBipcs \-m\fP command. For this reason, the +SHM driver is deprecated in favor of SOCK. +.sp +Examples: +.sp +.if n .RS 4 +.nf +.fam C +refclock SHM 0 poll 3 refid GPS1 +refclock SHM 1:perm=0644 refid GPS2 +.fam +.fi +.if n .RE +.RE +.sp +\fBPHC\fP +.RS 4 +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 \fBoffset\fP option. Alternatively, the +\fBpps\fP 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: +.sp +\fBnocrossts\fP +.RS 4 +This option disables use of precise cross timestamping. +.RE +.sp +\fBextpps\fP +.RS 4 +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 \fBwidth\fP option to filter wrong +PPS samples. +.RE +.sp +\fBpin\fP=\fIindex\fP +.RS 4 +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. +.RE +.sp +\fBchannel\fP=\fIindex\fP +.RS 4 +This option specifies the index of the channel for the PPS mode. The default +value is 0. +.RE +.sp +\fBclear\fP +.RS 4 +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. +.RE +.RE +.sp + +.RS 4 +.sp +Examples: +.sp +.if n .RS 4 +.nf +.fam C +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 +.fam +.fi +.if n .RE +.RE +.RE +.sp + +.RS 4 +The \fBrefclock\fP directive supports the following options: +.sp +\fBpoll\fP \fIpoll\fP +.RS 4 +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 +\fBchronyd\fP 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. +.RE +.sp +\fBdpoll\fP \fIdpoll\fP +.RS 4 +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). +.RE +.sp +\fBrefid\fP \fIrefid\fP +.RS 4 +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. +.RE +.sp +\fBlock\fP \fIrefid\fP +.RS 4 +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. +.RE +.sp +\fBrate\fP \fIrate\fP +.RS 4 +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 \fBdpoll\fP has to be specified (\-3 for +a 5Hz signal). The default is 1. +.RE +.sp +\fBmaxlockage\fP \fIpulses\fP +.RS 4 +This option specifies in number of pulses how old can be samples from the +refclock specified by the \fBlock\fP 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. +.RE +.sp +\fBwidth\fP \fIwidth\fP +.RS 4 +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. +.RE +.sp +\fBpps\fP +.RS 4 +This options forces \fBchronyd\fP 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. +.RE +.sp +\fBoffset\fP \fIoffset\fP +.RS 4 +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. +.RE +.sp +\fBdelay\fP \fIdelay\fP +.RS 4 +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). +.RE +.sp +\fBstratum\fP \fIstratum\fP +.RS 4 +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. +.RE +.sp +\fBprecision\fP \fIprecision\fP +.RS 4 +This option sets the precision of the reference clock (in seconds). The default +value is the estimated precision of the system clock. +.RE +.sp +\fBmaxdispersion\fP \fIdispersion\fP +.RS 4 +Maximum allowed dispersion for filtered samples (in seconds). Samples with +larger estimated dispersion are ignored. By default, this limit is disabled. +.RE +.sp +\fBfilter\fP \fIsamples\fP +.RS 4 +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^(\fIpoll\fP \- \fIdpoll\fP). +.RE +.sp +\fBprefer\fP +.RS 4 +Prefer this source over sources without the prefer option. +.RE +.sp +\fBnoselect\fP +.RS 4 +Never select this source. This is useful for monitoring or with sources which +are not very accurate, but are locked with a PPS refclock. +.RE +.sp +\fBtrust\fP +.RS 4 +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. +.RE +.sp +\fBrequire\fP +.RS 4 +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 \fBtrust\fP 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. +.RE +.sp +\fBtai\fP +.RS 4 +This option indicates that the reference clock keeps time in TAI instead of UTC +and that \fBchronyd\fP should correct its offset by the current TAI\-UTC offset. The +\fBleapsectz\fP 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. +.RE +.sp +\fBlocal\fP +.RS 4 +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. +.RE +.sp +\fBminsamples\fP \fIsamples\fP +.RS 4 +Set the minimum number of samples kept for this source. This overrides the +\fBminsamples\fP directive. +.RE +.sp +\fBmaxsamples\fP \fIsamples\fP +.RS 4 +Set the maximum number of samples kept for this source. This overrides the +\fBmaxsamples\fP directive. +.RE +.RE +.sp +\fBmanual\fP +.RS 4 +The \fBmanual\fP directive enables support at run\-time for the +\fBsettime\fP command in \fBchronyc\fP. If no \fBmanual\fP +directive is included, any attempt to use the \fBsettime\fP command in \fBchronyc\fP +will be met with an error message. +.sp +Note that the \fBsettime\fP command can be enabled at run\-time using +the \fBmanual\fP command in \fBchronyc\fP. (The idea of the two +commands is that the \fBmanual\fP command controls the manual clock driver\(cqs +behaviour, whereas the \fBsettime\fP command allows samples of manually entered +time to be provided.) +.RE +.sp +\fBacquisitionport\fP \fIport\fP +.RS 4 +By default, \fBchronyd\fP as an NTP client opens a new socket for each request with +the source port chosen randomly by the operating system. The \fBacquisitionport\fP +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. +.sp +It can be set to the same port as is used by the NTP server (which can be +configured with the \fBport\fP directive) to use only one socket for all +NTP packets. +.sp +An example of the \fBacquisitionport\fP directive is: +.sp +.if n .RS 4 +.nf +.fam C +acquisitionport 1123 +.fam +.fi +.if n .RE +.sp +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. +.RE +.sp +\fBbindacqaddress\fP \fIaddress\fP +.RS 4 +The \fBbindacqaddress\fP directive specifies a local IP address to which +\fBchronyd\fP will bind its NTP and NTS\-KE client sockets. The syntax is similar to +the \fBbindaddress\fP and \fBbindcmdaddress\fP +directives. +.sp +For each of the IPv4 and IPv6 protocols, only one \fBbindacqaddress\fP directive +can be specified. +.RE +.sp +\fBbindacqdevice\fP \fIinterface\fP +.RS 4 +The \fBbindacqdevice\fP 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. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +bindacqdevice eth0 +.fam +.fi +.if n .RE +.RE +.sp +\fBdscp\fP \fIpoint\fP +.RS 4 +The \fBdscp\fP 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. +.sp +An example of the directive (setting the Expedited Forwarding class) is: +.sp +.if n .RS 4 +.nf +.fam C +dscp 46 +.fam +.fi +.if n .RE +.RE +.sp +\fBdumpdir\fP \fIdirectory\fP +.RS 4 +To compute the rate of gain or loss of time, \fBchronyd\fP has to store a +measurement history for each of the time sources it uses. +.sp +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, \fBchronyd\fP 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.) +.sp +For such systems, it is possible to save the measurement history across +restarts of \fBchronyd\fP (assuming no changes are made to the system clock +behaviour whilst it is not running). The \fBdumpdir\fP directive defines the +directory where the measurement histories are saved when \fBchronyd\fP exits, +or the \fBdump\fP command in \fBchronyc\fP is issued. +.sp +If the directory does not exist, it will be created automatically. +.sp +The \fB\-r\fP option of \fBchronyd\fP enables loading of the dump files on start. All +dump files found in the directory will be removed after start, even if the \fB\-r\fP +option is not present. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +dumpdir @CHRONYRUNDIR@ +.fam +.fi +.if n .RE +.sp +A source whose IP address is \fI1.2.3.4\fP would have its measurement history saved +in the file \fI@CHRONYRUNDIR@/1.2.3.4.dat\fP. History of reference clocks is saved +to files named by their reference ID in form of \fIrefid:XXXXXXXX.dat\fP. +.RE +.sp +\fBmaxsamples\fP \fIsamples\fP +.RS 4 +The \fBmaxsamples\fP directive sets the default maximum number of samples that +\fBchronyd\fP should keep for each source. This setting can be overridden for +individual sources in the \fBserver\fP and \fBrefclock\fP +directives. The default value is 0, which disables the configurable limit. The +useful range is 4 to 64. +.sp +As a special case, setting \fBmaxsamples\fP to 1 disables frequency tracking in +order to make the sources immediately selectable with only one sample. This can +be useful when \fBchronyd\fP is started with the \fB\-q\fP or \fB\-Q\fP option. +.RE +.sp +\fBminsamples\fP \fIsamples\fP +.RS 4 +The \fBminsamples\fP directive sets the default minimum number of samples that +\fBchronyd\fP should keep for each source. This setting can be overridden for +individual sources in the \fBserver\fP and \fBrefclock\fP +directives. The default value is 6. The useful range is 4 to 64. +.sp +Forcing \fBchronyd\fP 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 +\fBtracking\fP and +\fBsourcestats\fP reports (and the \fItracking.log\fP and +\fIstatistics.log\fP files) may be smaller than the actual offsets. +.RE +.sp +\fBntsdumpdir\fP \fIdirectory\fP +.RS 4 +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 +\fBchronyd\fP 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. +\fI1.2.3.4.nts\fP). By default, the client does not save the cookies. +.sp +If the directory does not exist, it will be created automatically. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +ntsdumpdir @CHRONYVARDIR@ +.fam +.fi +.if n .RE +.sp +This directory is used also by the NTS server to save keys. +.RE +.sp +\fBntsrefresh\fP \fIinterval\fP +.RS 4 +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). +.sp +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. +.RE +.sp +\fBntstrustedcerts\fP [\fIset\-ID\fP] \fIfile\fP|\fIdirectory\fP +.RS 4 +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. +.sp +The optional \fIset\-ID\fP 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\(cqs default trusted CAs (unless the \fBnosystemcert\fP 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 \fBcertset\fP option in the \fBserver\fP or \fBpool\fP +directive. +.sp +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. +.sp +It is not necessary to restart \fBchronyd\fP in order to reload the certificates if +they change (e.g. after a renewal). +.sp +An example is: +.sp +.if n .RS 4 +.nf +.fam C +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 +.fam +.fi +.if n .RE +.RE +.sp +\fBnosystemcert\fP +.RS 4 +This directive disables the system\(cqs default trusted CAs. Only certificates +specified by the \fBntstrustedcerts\fP directive will be trusted. +.RE +.sp +\fBnocerttimecheck\fP \fIlimit\fP +.RS 4 +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. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +nocerttimecheck 1 +.fam +.fi +.if n .RE +.sp +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. +.RE +.sp +\fBrefresh\fP \fIinterval\fP +.RS 4 +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. +.sp +The \fBrefresh\fP command can be used to refresh all +sources immediately. +.RE +.SS "Source selection" +.sp +\fBauthselectmode\fP \fImode\fP +.RS 4 +NTP sources can be specified with the \fBkey\fP or \fBnts\fP 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 \fBmaxdelay\fP and +\fBmaxdistance\fP 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 \fBmaxdrift\fP limit). +.sp +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 \fBrequire\fP and \fBtrust\fP 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 \fBchronyd\fP to report false information, +e.g. a significantly smaller root delay and dispersion. +.sp +This directive determines the default selection options for authenticated and +unauthenticated sources in order to simplify the configuration with the +configuration file and \fBchronyc\fP commands. It sets a policy for authentication. +.sp +Sources specified with the \fBnoselect\fP option are ignored (not counted as either +authenticated or unauthenticated), and they always have only the selection +options specified in the configuration. +.sp +There are four modes: +.sp +\fBrequire\fP +.RS 4 +Authentication is strictly required for NTP sources in this mode. If any +unauthenticated NTP sources are specified, they will automatically get the +\fBnoselect\fP option to prevent them from being selected for synchronisation. +.RE +.sp +\fBprefer\fP +.RS 4 +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 \fBnoselect\fP +option. +.RE +.sp +\fBmix\fP +.RS 4 +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 \fBrequire\fP and \fBtrust\fP 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. +.RE +.sp +\fBignore\fP +.RS 4 +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 \fBchronyc\fP command. This was the behaviour of \fBchronyd\fP in versions +before 4.0. +.RE +.RE +.sp + +.RS 4 +.sp +As an example, the following configuration using the default \fBmix\fP mode: +.sp +.if n .RS 4 +.nf +.fam C +server ntp1.example.net nts +server ntp2.example.net nts +server ntp3.example.net +refclock SOCK /var/run/chrony.ttyS0.sock +.fam +.fi +.if n .RE +.sp +is equivalent to the following configuration using the \fBignore\fP mode: +.sp +.if n .RS 4 +.nf +.fam C +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 +.fam +.fi +.if n .RE +.RE +.sp +\fBcombinelimit\fP \fIlimit\fP +.RS 4 +When \fBchronyd\fP 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. +.sp +The \fBcombinelimit\fP 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 \fBprefer\fP option, it can be +combined only with other sources specified with this option. +.sp +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. +.RE +.sp +\fBmaxdistance\fP \fIdistance\fP +.RS 4 +The \fBmaxdistance\fP 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. +.sp +By default, the maximum root distance is 3 seconds. +.sp +Setting \fBmaxdistance\fP 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. +.RE +.sp +\fBmaxjitter\fP \fIjitter\fP +.RS 4 +The \fBmaxjitter\fP 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. +.sp +By default, the maximum jitter is 1 second. +.RE +.sp +\fBminsources\fP \fIsources\fP +.RS 4 +The \fBminsources\fP 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. +.sp +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. +.RE +.sp +\fBreselectdist\fP \fIdistance\fP +.RS 4 +When \fBchronyd\fP 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 \fBreselectdist\fP directive. By default, the +distance is 100 microseconds. +.RE +.sp +\fBstratumweight\fP \fIdistance\fP +.RS 4 +The \fBstratumweight\fP directive sets how much distance should be added per +stratum to the synchronisation distance when \fBchronyd\fP selects the +synchronisation source from available sources. +.sp +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. +.RE +.SS "System clock" +.sp +\fBclockprecision\fP \fIprecision\fP +.RS 4 +The \fBclockprecision\fP directive specifies the precision of the system clock (in +seconds). It is used by \fBchronyd\fP 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. +.sp +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\*(Aq +NTP measurements. The server\(cqs precision is reported on clients by the +\fBntpdata\fP command. +.sp +An example setting the precision to 8 nanoseconds is: +.sp +.if n .RS 4 +.nf +.fam C +clockprecision 8e\-9 +.fam +.fi +.if n .RE +.RE +.sp +\fBcorrtimeratio\fP \fIratio\fP +.RS 4 +When \fBchronyd\fP 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. +.sp +The \fBcorrtimeratio\fP 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. +.sp +Increasing \fBcorrtimeratio\fP improves the overall frequency error of the system +clock, but increases the overall time error as the corrections take longer. +.sp +By default, the ratio is set to 3, the time accuracy of the clock is preferred +over its frequency accuracy. +.sp +The maximum allowed slew rate can be set by the \fBmaxslewrate\fP +directive. The current remaining correction is shown in the +\fBtracking\fP report as the \fBSystem time\fP value. +.RE +.sp +\fBdriftfile\fP \fIfile\fP +.RS 4 +One of the main activities of the \fBchronyd\fP program is to work out the rate at +which the system clock gains or loses time relative to real time. +.sp +Whenever \fBchronyd\fP computes a new value of the gain or loss rate, it is desirable +to record it somewhere. This allows \fBchronyd\fP 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.) +.sp +The \fBdriftfile\fP directive allows a file to be specified into which \fBchronyd\fP +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. +.sp +An example of the driftfile directive is: +.sp +.if n .RS 4 +.nf +.fam C +driftfile @CHRONYVARDIR@/drift +.fam +.fi +.if n .RE +.RE +.sp +\fBfallbackdrift\fP \fImin\-interval\fP \fImax\-interval\fP +.RS 4 +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. +.sp +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: +.sp +.if n .RS 4 +.nf +.fam C +fallbackdrift 16 19 +.fam +.fi +.if n .RE +.sp +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 \(oqNot synchronised\(cq. +.sp +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. +.RE +.sp +\fBleapsecmode\fP \fImode\fP +.RS 4 +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. +.sp +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 \fBleapsecmode\fP directive selects how +that error is corrected. There are four options: +.sp +\fBsystem\fP +.RS 4 +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). +.RE +.sp +\fBstep\fP +.RS 4 +This is similar to the \fBsystem\fP mode, except the clock is stepped by +\fBchronyd\fP instead of the kernel. It can be useful to avoid bugs in the kernel +code that would be executed in the \fBsystem\fP mode. This is the default mode +when the system driver does not support leap seconds. +.RE +.sp +\fBslew\fP +.RS 4 +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 \fBsystem\fP and \fBstep\fP 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 +\fBmaxslewrate\fP value the correction takes 12 seconds. +.RE +.sp +\fBignore\fP +.RS 4 +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 \fBchronyd\fP instances are running on the system, one +controlling the system clock and others started with the \fB\-x\fP 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. +.RE +.RE +.sp + +.RS 4 +.sp +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 +\fBslew\fP mode can be combined with the \fBsmoothtime\fP directive to +enable a server leap smear. +.sp +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. +.sp +This feature must be used carefully, because the server is intentionally not +serving its best estimate of the true time. +.sp +A recommended configuration to enable a server leap smear is: +.sp +.if n .RS 4 +.nf +.fam C +leapsecmode slew +maxslewrate 1000 +smoothtime 400 0.001024 leaponly +.fam +.fi +.if n .RE +.sp +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 \fBleaponly\fP option makes the duration of the leap +smear constant and allows the clients to safely synchronise with multiple +identically configured leap smearing servers. +.sp +The duration of the leap smear can be calculated from the specified wander as +.sp +.if n .RS 4 +.nf +.fam C +duration = sqrt(4 / wander) +.fam +.fi +.if n .RE +.RE +.sp +\fBleapsectz\fP \fItimezone\fP +.RS 4 +This directive specifies a timezone in the system timezone database which +\fBchronyd\fP 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 +\fIright/UTC\fP timezone. +.sp +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 \fBchronyd\fP. +.sp +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. +.sp +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. \fBleapsecmode\fP is set to \fBsystem\fP. +.sp +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. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +leapsectz right/UTC +.fam +.fi +.if n .RE +.sp +The following shell command verifies that the timezone contains leap seconds +and can be used with this directive: +.sp +.if n .RS 4 +.nf +.fam C +$ TZ=right/UTC date \-d \*(AqDec 31 2008 23:59:60\*(Aq +Wed Dec 31 23:59:60 UTC 2008 +.fam +.fi +.if n .RE +.RE +.sp +\fBmakestep\fP \fIthreshold\fP \fIlimit\fP +.RS 4 +Normally \fBchronyd\fP 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 \fBchronyd\fP 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. +.sp +This directive forces \fBchronyd\fP to step the system clock if the adjustment is +larger than a threshold value, but only if there were no more clock updates +since \fBchronyd\fP was started than the specified limit. A negative value disables +the limit. +.sp +On most systems it is desirable to step the system clock only on boot, before +starting programs that rely on time advancing monotonically forwards. +.sp +An example of the use of this directive is: +.sp +.if n .RS 4 +.nf +.fam C +makestep 0.1 3 +.fam +.fi +.if n .RE +.sp +This would step the system clock if the adjustment is larger than 0.1 seconds, but +only in the first three clock updates. +.RE +.sp +\fBmaxchange\fP \fIoffset\fP \fIstart\fP \fIignore\fP +.RS 4 +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. +.sp +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 \fBchronyd\fP 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. +.sp +An example of the use of this directive is: +.sp +.if n .RS 4 +.nf +.fam C +maxchange 1000 1 2 +.fam +.fi +.if n .RE +.sp +After the first clock update, \fBchronyd\fP will check the offset on every clock +update, it will ignore two adjustments larger than 1000 seconds and exit on +another one. +.RE +.sp +\fBmaxclockerror\fP \fIerror\-in\-ppm\fP +.RS 4 +The \fBmaxclockerror\fP 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. +.sp +By default, the maximum error is 1 ppm. +.sp +Typical values for \fIerror\-in\-ppm\fP might be 10 for a low quality clock and 0.1 +for a high quality clock using a temperature compensated crystal oscillator. +.RE +.sp +\fBmaxdrift\fP \fIdrift\-in\-ppm\fP +.RS 4 +This directive specifies the maximum assumed drift (frequency error) of the +system clock. It limits the frequency adjustment that \fBchronyd\fP 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). +.sp +By default, the maximum assumed drift is 500000 ppm, i.e. the adjustment is +limited by the system driver rather than this directive. +.RE +.sp +\fBmaxupdateskew\fP \fIskew\-in\-ppm\fP +.RS 4 +One of \fBchronyd\fP\*(Aqs tasks is to work out how fast or slow the computer\(cqs clock +runs relative to its reference sources. In addition, it computes an estimate of +the error bounds around the estimated value. +.sp +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. +.sp +The \fBmaxupdateskew\fP 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. +.sp +Typical values for \fIskew\-in\-ppm\fP might be 100 for NTP sources polled over a +wireless network, and 10 or smaller for sources on a local wired network. +.sp +It should be noted that this is not the only means of protection against using +unreliable estimates. At all times, \fBchronyd\fP 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. +.RE +.sp +\fBmaxslewrate\fP \fIrate\-in\-ppm\fP +.RS 4 +The \fBmaxslewrate\fP directive sets the maximum rate at which \fBchronyd\fP is allowed +to slew the time. It limits the slew rate controlled by the correction time +ratio (which can be set by the \fBcorrtimeratio\fP directive) and +is effective only on systems where \fBchronyd\fP is able to control the rate (i.e. +all supported systems with the exception of macOS 12 or earlier). +.sp +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 \fBmaxslewrate\fP on FreeBSD, NetBSD, macOS 10.13+ to a value between 500 +ppm and 5000 ppm will effectively set it to 500 ppm. +.sp +By default, the maximum slew rate is set to 83333.333 ppm (one twelfth). +.RE +.sp +\fBtempcomp\fP \fIfile\fP \fIinterval\fP \fIT0\fP \fIk0\fP \fIk1\fP \fIk2\fP, \fBtempcomp\fP \fIfile\fP \fIinterval\fP \fIpoints\-file\fP +.RS 4 +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. +.sp +If there are temperature measurements available from a sensor close to the +oscillator, the \fBtempcomp\fP directive can be used to compensate for the changes +in the temperature and improve the stability and accuracy of the clock. +.sp +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 \fItracking.log\fP file is more stable and the maximum +reached offset is smaller. +.sp +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 \fIT0\fP, \fIk0\fP, \fIk1\fP, \fIk2\fP. +.sp +The frequency compensation is calculated (in ppm) as +.sp +.if n .RS 4 +.nf +.fam C +comp = k0 + (T \- T0) * k1 + (T \- T0)^2 * k2 +.fam +.fi +.if n .RE +.sp +The result has to be between \-10 ppm and 10 ppm, otherwise the measurement is +considered invalid and will be ignored. The \fIk0\fP coefficient can be adjusted to +keep the compensation in that range. +.sp +An example of the use is: +.sp +.if n .RS 4 +.nf +.fam C +tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 26000 0.0 0.000183 0.0 +.fam +.fi +.if n .RE +.sp +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. +.sp +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. +.sp +An example is: +.sp +.if n .RS 4 +.nf +.fam C +tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 /etc/chrony.tempcomp +.fam +.fi +.if n .RE +.sp +where the \fI/etc/chrony.tempcomp\fP file could have +.sp +.if n .RS 4 +.nf +.fam C +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 +.fam +.fi +.if n .RE +.sp +Valid measurements with corresponding compensations are logged to the +\fItempcomp.log\fP file if enabled by the \fBlog tempcomp\fP directive. +.RE +.SS "NTP server" +.sp +\fBallow\fP [\fBall\fP] [\fIsubnet\fP] +.RS 4 +The \fBallow\fP 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. +.sp +The default is that no clients are allowed access, i.e. \fBchronyd\fP operates +purely as an NTP client. If the \fBallow\fP directive is used, \fBchronyd\fP will be +both a client of its servers, and a server to other clients. +.sp +This directive can be used multiple times. +.sp +Examples of the use of the directive are as follows: +.sp +.if n .RS 4 +.nf +.fam C +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 +.fam +.fi +.if n .RE +.sp +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). +.sp +A second form of the directive, \fBallow all\fP, has a greater effect, depending on +the ordering of directives in the configuration file. To illustrate the effect, +consider the two examples: +.sp +.if n .RS 4 +.nf +.fam C +allow 1.2.3.4 +deny 1.2.3.0/24 +allow 1.2.0.0/16 +.fam +.fi +.if n .RE +.sp +and +.sp +.if n .RS 4 +.nf +.fam C +allow 1.2.3.4 +deny 1.2.3.0/24 +allow all 1.2.0.0/16 +.fam +.fi +.if n .RE +.sp +In the first example, the effect is the same regardless of what order the three +directives are given in. So the \fI1.2.0.0/16\fP subnet is allowed access, except +for the \fI1.2.3.0/24\fP subnet, which is denied access, however the host \fI1.2.3.4\fP +is allowed access. +.sp +In the second example, the \fBallow all 1.2.0.0/16\fP directive overrides the +effect of \fIany\fP 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 \fBchronyc\fP +with the \fBallow all\fP command. +.sp +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 \fBallow\fP and \fBdeny\fP +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, \fI1.2.3.0/28\fP and \fI1.2.3.0/29\fP are in different tables, but +\fI1.2.3.0/25\fP and \fI1.2.3.0/28\fP are in the same table. The configuration can be +verified for individual addresses with the \fBaccheck\fP +command in \fBchronyc\fP. +.sp +A hostname can be specified in the directives instead of the IP address, but +the name must be resolvable when \fBchronyd\fP 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. +.sp +Note, if the \fBinitstepslew\fP 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. +.RE +.sp +\fBdeny\fP [\fBall\fP] [\fIsubnet\fP] +.RS 4 +This is similar to the \fBallow\fP directive, except that it denies NTP +and NTS\-KE client access to a particular subnet or host, rather than allowing +it. +.sp +The syntax is identical and the directive can be used multiple times too. +.sp +There is also a \fBdeny all\fP directive with similar behaviour to the \fBallow all\fP +directive. +.RE +.sp +\fBbindaddress\fP \fIaddress\fP +.RS 4 +The \fBbindaddress\fP directive binds the sockets on which \fBchronyd\fP 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 +\fBchronyd\fP is started. +.sp +An example of the use of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +bindaddress 192.168.1.1 +.fam +.fi +.if n .RE +.sp +Currently, for each of the IPv4 and IPv6 protocols, only one \fBbindaddress\fP +directive can be specified. Therefore, it is not useful on computers which +should serve NTP on multiple network interfaces. +.RE +.sp +\fBbinddevice\fP \fIinterface\fP +.RS 4 +The \fBbinddevice\fP 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. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +binddevice eth0 +.fam +.fi +.if n .RE +.RE +.sp +\fBbroadcast\fP \fIinterval\fP \fIaddress\fP [\fIport\fP] +.RS 4 +The \fBbroadcast\fP directive is used to declare a broadcast address to which +chronyd should send packets in the NTP broadcast mode (i.e. make \fBchronyd\fP act +as a broadcast server). Broadcast clients on that subnet will be able to +synchronise. +.sp +This directive can be used multiple times to specify multiple addresses. +.sp +The syntax is as follows: +.sp +.if n .RS 4 +.nf +.fam C +broadcast 32 192.168.1.255 +broadcast 64 192.168.2.255 12123 +broadcast 64 ff02::101 +.fam +.fi +.if n .RE +.sp +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 +\fBchronyd\fP is running. +.sp +You can have more than 1 \fBbroadcast\fP directive if you have more than 1 network +interface onto which you want to send NTP broadcast packets. +.sp +\fBchronyd\fP 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. +.sp +If \fBntpd\fP 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 \fBallow\fP +directive. +.RE +.sp +\fBclientloglimit\fP \fIlimit\fP +.RS 4 +This directive specifies the maximum amount of memory that \fBchronyd\fP is allowed +to allocate for logging of client accesses and the state that \fBchronyd\fP 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. +.sp +An example of the use of this directive is: +.sp +.if n .RS 4 +.nf +.fam C +clientloglimit 1048576 +.fam +.fi +.if n .RE +.RE +.sp +\fBnoclientlog\fP +.RS 4 +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 \fBclients\fP command in \fBchronyc\fP. This option +also effectively disables server support for the NTP interleaved mode. +.RE +.sp +\fBlocal\fP [\fIoption\fP]... +.RS 4 +The \fBlocal\fP directive enables a local reference mode, which allows \fBchronyd\fP +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. +.sp +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. +.sp +The \fBlocal\fP directive has the following options: +.sp +\fBstratum\fP \fIstratum\fP +.RS 4 +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. +.sp +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. +.RE +.sp +\fBdistance\fP \fIdistance\fP +.RS 4 +This option sets the threshold for the root distance which will activate the local +reference. If \fBchronyd\fP 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. +.sp +The current root distance can be calculated from root delay and root dispersion +(reported by the \fBtracking\fP command in \fBchronyc\fP) as: +.sp +.if n .RS 4 +.nf +.fam C +distance = delay / 2 + dispersion +.fam +.fi +.if n .RE +.RE +.sp +\fBorphan\fP +.RS 4 +This option enables a special \(oqorphan\(cq mode, where sources with stratum equal +to the local \fIstratum\fP 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. +.sp +This allows multiple servers in the network to use the same \fBlocal\fP +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 \fBlocal\fP 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 \fBdistance\fP option). +.sp +The \fBorphan\fP mode is compatible with the \fBntpd\fP\*(Aqs orphan mode (enabled by the +\fBtos orphan\fP command). +.RE +.RE +.sp + +.RS 4 +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +local stratum 10 orphan distance 0.1 +.fam +.fi +.if n .RE +.RE +.sp +\fBntpsigndsocket\fP \fIdirectory\fP +.RS 4 +This directive specifies the location of the Samba \fBntp_signd\fP socket when it +is running as a Domain Controller (DC). If \fBchronyd\fP is compiled with this +feature, responses to MS\-SNTP clients will be signed by the \fBsmbd\fP daemon. +.sp +Note that MS\-SNTP requests are not authenticated and any client that is allowed +to access the server by the \fBallow\fP directive, or the +\fBallow\fP command in \fBchronyc\fP, can get an MS\-SNTP +response signed with a trust account\(cqs password and try to crack the password +in a brute\-force attack. Access to the server should be carefully controlled. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +ntpsigndsocket /var/lib/samba/ntp_signd +.fam +.fi +.if n .RE +.RE +.sp +\fBntsport\fP \fIport\fP +.RS 4 +This directive specifies the TCP port on which \fBchronyd\fP will provide the NTS +Key Establishment (NTS\-KE) service. The default port is 4460. +.sp +The port will be open only when a certificate and key is specified by the +\fBntsservercert\fP and \fBntsserverkey\fP directives. +.RE +.sp +\fBntsservercert\fP \fIfile\fP +.RS 4 +This directive specifies a file containing a certificate in the PEM format +for \fBchronyd\fP to operate as an NTS server. The file should also include +any intermediate certificates that the clients will need to validate the +server\(cqs certificate. The file needs to be readable by the user under which +\fBchronyd\fP is running after dropping root privileges. +.sp +This directive can be used multiple times to specify multiple certificates for +different names of the server. +.sp +The files are loaded only once. \fBchronyd\fP needs to be restarted in order to +load a renewed certificate. The \fBntsdumpdir\fP and +\fBdumpdir\fP directives with the \fB\-r\fP option of \fBchronyd\fP are +recommended for a near\-seamless server operation. +.RE +.sp +\fBntsserverkey\fP \fIfile\fP +.RS 4 +This directive specifies a file containing a private key in the PEM format +for \fBchronyd\fP to operate as an NTS server. The file needs to be readable by +the user under which \fBchronyd\fP is running after dropping root privileges. For +security reasons, it should not be readable by other users. +.sp +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. +.RE +.sp +\fBntsprocesses\fP \fIprocesses\fP +.RS 4 +This directive specifies how many helper processes will \fBchronyd\fP 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 +\fBchronyd\fP process. The default value is 1. +.RE +.sp +\fBmaxntsconnections\fP \fIconnections\fP +.RS 4 +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 \fBFD_SETSIZE\fP constant (usually +1024). +.RE +.sp +\fBntsdumpdir\fP \fIdirectory\fP +.RS 4 +This directive specifies a directory where \fBchronyd\fP 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 \fIntskeys\fP. When \fBchronyd\fP 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. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +ntsdumpdir @CHRONYVARDIR@ +.fam +.fi +.if n .RE +.sp +This directory is used also by the NTS client to save NTS cookies. +.RE +.sp +\fBntsntpserver\fP \fIhostname\fP +.RS 4 +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 +\fBntsrotate\fP 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. +.RE +.sp +\fBntsrotate\fP \fIinterval\fP +.RS 4 +This directive specifies the rotation interval (in seconds) of the server key +which encrypts the NTS cookies. New keys are generated automatically from the +\fI/dev/urandom\fP 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\(cqs operating time, i.e. the actual interval can be longer if +\fBchronyd\fP is not running continuously. The default interval is 604800 seconds +(1 week). The maximum value is 2^31\-1 (68 years). +.sp +The automatic rotation of the keys can be disabled by setting \fBntsrotate\fP to 0. +In this case the keys are assumed to be managed externally. \fBchronyd\fP will not +save the keys to the \fIntskeys\fP file and will reload the keys from the file when +the \fBrekey\fP command is issued in \fBchronyc\fP. The file can +be periodically copied from another server running \fBchronyd\fP (which does +not have \fBntsrotate\fP 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 +\fBntsntpserver\fP directive to point the clients to the right NTP +server. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +ntsrotate 2592000 +.fam +.fi +.if n .RE +.RE +.sp +\fBport\fP \fIport\fP +.RS 4 +This option allows you to configure the port on which \fBchronyd\fP will listen for +NTP requests. The port will be open only when an address is allowed by the +\fBallow\fP directive or the \fBallow\fP command in +\fBchronyc\fP, an NTP peer is configured, or the broadcast server mode is enabled. +.sp +The default value is 123, the standard NTP port. If set to 0, \fBchronyd\fP 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 +\fBacquisitionport\fP directive. +.RE +.sp +\fBratelimit\fP [\fIoption\fP]... +.RS 4 +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 \fBclientloglimit\fP +directive. +.sp +The \fBratelimit\fP directive supports a number of options (which can be defined +in any order): +.sp +\fBinterval\fP \fIinterval\fP +.RS 4 +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). +.RE +.sp +\fBburst\fP \fIresponses\fP +.RS 4 +This option sets the maximum number of responses that can be sent in a burst, +temporarily exceeding the limit specified by the \fBinterval\fP option. This is +useful for clients that make rapid measurements on start (e.g. \fBchronyd\fP with +the \fBiburst\fP option). The default value is 8. The minimum value is 1 and the +maximum value is 255. +.RE +.sp +\fBleak\fP \fIrate\fP +.RS 4 +This option sets the rate at which responses are randomly allowed even if the +limits specified by the \fBinterval\fP and \fBburst\fP 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. +.RE +.RE +.sp + +.RS 4 +.sp +An example use of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +ratelimit interval 1 burst 16 +.fam +.fi +.if n .RE +.sp +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 \fBleak\fP of 2). +.RE +.sp +\fBntsratelimit\fP [\fIoption\fP]... +.RS 4 +This directive enables rate limiting of NTS\-KE requests. It is similar to the +\fBratelimit\fP directive, except the default interval is 6 +(1 connection per 64 seconds). +.sp +An example of the use of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +ntsratelimit interval 3 burst 1 +.fam +.fi +.if n .RE +.RE +.sp +\fBsmoothtime\fP \fImax\-freq\fP \fImax\-wander\fP [\fBleaponly\fP] +.RS 4 +The \fBsmoothtime\fP directive can be used to enable smoothing of the time that +\fBchronyd\fP 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\(cqs clock, for example after being offline for a longer +time. +.sp +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. +.sp +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 \fBmakestep\fP directive or the +\fBmakestep\fP command in \fBchronyc\fP. The process can be +reset without stepping the clock by the \fBsmoothtime +reset\fP command. +.sp +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). \fBleaponly\fP +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 \fBleaponly\fP +option is useful in a combination with the \fBleapsecmode slew\fP +directive to allow the clients to use multiple time smoothing servers safely. +.sp +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 \fBsmoothtime +activate\fP command, which is particularly useful when the clock is +synchronised only with manual input and the skew is always larger than the +threshold. The \fBsmoothing\fP command can be used to +monitor the process. +.sp +An example suitable for clients using \fBntpd\fP and 1024 second polling interval +could be: +.sp +.if n .RS 4 +.nf +.fam C +smoothtime 400 0.001 +.fam +.fi +.if n .RE +.sp +An example suitable for clients using \fBchronyd\fP on Linux could be: +.sp +.if n .RS 4 +.nf +.fam C +smoothtime 50000 0.01 +.fam +.fi +.if n .RE +.RE +.SS "Command and monitoring access" +.sp +\fBbindcmdaddress\fP \fIaddress\fP +.RS 4 +The \fBbindcmdaddress\fP directive specifies a local IP address to which \fBchronyd\fP +will bind the UDP socket listening for monitoring command packets (issued +by \fBchronyc\fP). On systems other than Linux, the address of the interface needs +to be already configured when \fBchronyd\fP is started. +.sp +This directive can also change the path of the Unix domain command socket, +which is used by \fBchronyc\fP to send configuration commands. The socket must be +in a directory that is accessible only by the root or \fIchrony\fP user. The +directory will be created on start if it does not exist. The compiled\-in default +path of the socket is \fI@CHRONYRUNDIR@/chronyd.sock\fP. The socket can be +disabled by setting the path to \fI/\fP. +.sp +By default, \fBchronyd\fP binds the UDP sockets to the addresses \fI127.0.0.1\fP and +\fI::1\fP (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: +.sp +.if n .RS 4 +.nf +.fam C +bindcmdaddress 0.0.0.0 +bindcmdaddress :: +.fam +.fi +.if n .RE +.sp +to the configuration file. +.sp +For each of the IPv4, IPv6, and Unix domain protocols, only one +\fBbindcmdaddress\fP directive can be specified. +.sp +An example that sets the path of the Unix domain command socket is: +.sp +.if n .RS 4 +.nf +.fam C +bindcmdaddress /var/run/chrony/chronyd.sock +.fam +.fi +.if n .RE +.RE +.sp +\fBbindcmddevice\fP \fIinterface\fP +.RS 4 +The \fBbindcmddevice\fP 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. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +bindcmddevice eth0 +.fam +.fi +.if n .RE +.RE +.sp +\fBcmdallow\fP [\fBall\fP] [\fIsubnet\fP] +.RS 4 +This is similar to the \fBallow\fP directive, except that it allows +monitoring access (rather than NTP client access) to a particular subnet or +host. (By \(oqmonitoring access\(cq is meant that \fBchronyc\fP can be run on those +hosts and retrieve monitoring data from \fBchronyd\fP on this computer.) +.sp +The syntax is identical to the \fBallow\fP directive. +.sp +There is also a \fBcmdallow all\fP directive with similar behaviour to the \fBallow +all\fP directive (but applying to monitoring access in this case, of course). +.sp +Note that \fBchronyd\fP has to be configured with the +\fBbindcmdaddress\fP directive to not listen only on the +loopback interface to actually allow remote access. +.RE +.sp +\fBcmddeny\fP [\fBall\fP] [\fIsubnet\fP] +.RS 4 +This is similar to the \fBcmdallow\fP directive, except that it denies +monitoring access to a particular subnet or host, rather than allowing it. +.sp +The syntax is identical. +.sp +There is also a \fBcmddeny all\fP directive with similar behaviour to the \fBcmdallow +all\fP directive. +.RE +.sp +\fBcmdport\fP \fIport\fP +.RS 4 +The \fBcmdport\fP directive allows the port that is used for run\-time monitoring +(via the \fBchronyc\fP program) to be altered from its default (323). If set to 0, +\fBchronyd\fP will not open the port, which disables remote \fBchronyc\fP access (with +a non\-default \fBbindcmdaddress\fP) and local access for unprivileged users. It +does not disable the Unix domain command socket. +.sp +An example shows the syntax: +.sp +.if n .RS 4 +.nf +.fam C +cmdport 257 +.fam +.fi +.if n .RE +.sp +This would make \fBchronyd\fP use UDP 257 as its command port. (\fBchronyc\fP would +need to be run with the \fB\-p 257\fP option to inter\-operate correctly.) +.RE +.sp +\fBcmdratelimit\fP [\fIoption\fP]... +.RS 4 +This directive enables response rate limiting for command packets. It is +similar to the \fBratelimit\fP directive, except responses to +localhost are never limited and the default interval is \-4 (16 packets per +second). +.sp +An example of the use of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +cmdratelimit interval 2 +.fam +.fi +.if n .RE +.RE +.SS "Real\-time clock (RTC)" +.sp +\fBhwclockfile\fP \fIfile\fP +.RS 4 +The \fBhwclockfile\fP directive sets the location of the adjtime file which is +used by the \fBhwclock\fP program on Linux. \fBchronyd\fP parses the file to find out +if the RTC keeps local time or UTC. It overrides the \fBrtconutc\fP +directive. +.sp +The compiled\-in default value is \*(Aq\fI@DEFAULT_HWCLOCK_FILE@\fP\*(Aq. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +hwclockfile /etc/adjtime +.fam +.fi +.if n .RE +.RE +.sp +\fBrtcautotrim\fP \fIthreshold\fP +.RS 4 +The \fBrtcautotrim\fP 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, \fBchronyd\fP will +trim the RTC as if the \fBtrimrtc\fP command in \fBchronyc\fP +was issued. The trimming operation is accurate to only about 1 second, which is +the minimum effective threshold. +.sp +This directive is effective only with the \fBrtcfile\fP directive. +.sp +An example of the use of this directive is: +.sp +.if n .RS 4 +.nf +.fam C +rtcautotrim 30 +.fam +.fi +.if n .RE +.sp +This would set the threshold error to 30 seconds. +.RE +.sp +\fBrtcdevice\fP \fIdevice\fP +.RS 4 +The \fBrtcdevice\fP directive sets the path to the device file for accessing the +RTC. The default path is \fI@DEFAULT_RTC_DEVICE@\fP. +.RE +.sp +\fBrtcfile\fP \fIfile\fP +.RS 4 +The \fBrtcfile\fP directive defines the name of the file in which \fBchronyd\fP can +save parameters associated with tracking the accuracy of the RTC. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +rtcfile @CHRONYVARDIR@/rtc +.fam +.fi +.if n .RE +.sp +\fBchronyd\fP saves information in this file when it exits and when the \fBwritertc\fP +command is issued in \fBchronyc\fP. The information saved is the RTC\(cqs error at +some epoch, that epoch (in seconds since January 1 1970), and the rate at which +the RTC gains or loses time. +.sp +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 \fBrtcfile\fP directive and the \fB\-s\fP command\-line +option to \fBchronyd\fP) if the following three conditions apply: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +You are running Linux. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +The kernel is compiled with extended real\-time clock support (i.e. the +\fI/dev/rtc\fP device is capable of doing useful things). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +You do not have other applications that need to make use of \fI/dev/rtc\fP at all. +.RE +.RE +.sp +\fBrtconutc\fP +.RS 4 +\fBchronyd\fP 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. +.sp +If you keep the RTC on local time and your computer is off when daylight saving +(summer time) starts or ends, the computer\(cqs system time will be one hour in +error when you next boot and start chronyd. +.sp +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. +.sp +If the \fBrtconutc\fP directive appears, it means the RTC is required to keep UTC. +The directive takes no arguments. It is equivalent to specifying the \fB\-u\fP +switch to the Linux \fBhwclock\fP program. +.sp +Note that this setting is overridden by the \fBhwclockfile\fP file +and is not relevant for the \fBrtcsync\fP directive. +.RE +.sp +\fBrtcsync\fP +.RS 4 +The \fBrtcsync\fP directive enables a mode where the system time is periodically +copied to the RTC and \fBchronyd\fP does not try to track its drift. This directive +cannot be used with the \fBrtcfile\fP directive. +.sp +On Linux, the RTC copy is performed by the kernel every 11 minutes. +.sp +On macOS, \fBchronyd\fP will perform the RTC copy every 60 minutes +when the system clock is in a synchronised state. +.sp +On other systems this directive does nothing. +.RE +.SS "Logging" +.sp +\fBlog\fP [\fIoption\fP]... +.RS 4 +The \fBlog\fP directive indicates that certain information is to be logged. +The log files are written to the directory specified by the \fBlogdir\fP +directive. A banner is periodically written to the files to indicate the +meanings of the columns. +.sp +\fBrawmeasurements\fP +.RS 4 +This option logs the raw NTP measurements and related information to a file +called \fImeasurements.log\fP. 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. +.sp +.if n .RS 4 +.nf +.fam C +2016\-11\-09 05:40:50 203.0.113.15 N 2 111 111 1111 10 10 1.0 \(rs + \-4.966e\-03 2.296e\-01 1.577e\-05 1.615e\-01 7.446e\-03 CB00717B 4B D K +.fam +.fi +.if n .RE +.sp +The columns are as follows (the quantities in square brackets are the values +from the example line above): +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Date [2015\-10\-13] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Hour:Minute:Second. Note that the date\-time pair is expressed in UTC, not the +local time zone. [05:40:50] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +IP address of server or peer from which measurement came [203.0.113.15] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +Leap status (\fIN\fP means normal, \fI+\fP means that the last minute of the current +month has 61 seconds, \fI\-\fP means that the last minute of the month has 59 +seconds, \fI?\fP means the remote computer is not currently synchronised.) [N] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 5." 4.2 +.\} +Stratum of remote computer. [2] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 6." 4.2 +.\} +RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 7." 4.2 +.\} +RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 8.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 8." 4.2 +.\} +Results of the \fBmaxdelay\fP, \fBmaxdelayratio\fP, and \fBmaxdelaydevratio\fP (or +\fBmaxdelayquant\fP) 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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 9.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 9." 4.2 +.\} +Local poll [10] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 10.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 10." 4.2 +.\} +Remote poll [10] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 11.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 11." 4.2 +.\} +\(oqScore\(cq (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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 12.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 12." 4.2 +.\} +The estimated local clock error (\fItheta\fP in RFC 5905). Positive indicates +that the local clock is slow of the remote source. [\-4.966e\-03] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 13.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 13." 4.2 +.\} +The peer delay (\fIdelta\fP in RFC 5905). [2.296e\-01] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 14.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 14." 4.2 +.\} +The peer dispersion (\fIepsilon\fP in RFC 5905). [1.577e\-05] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 15.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 15." 4.2 +.\} +The root delay (\fIDELTA\fP in RFC 5905). [1.615e\-01] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 16.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 16." 4.2 +.\} +The root dispersion (\fIEPSILON\fP in RFC 5905). [7.446e\-03] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 17.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 17." 4.2 +.\} +Reference ID of the server\(cqs source as a hexadecimal number. [CB00717B] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 18.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 18." 4.2 +.\} +NTP mode of the received packet (\fI1\fP=active peer, \fI2\fP=passive peer, +\fI4\fP=server, \fIB\fP=basic, \fII\fP=interleaved). [4B] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 19.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 19." 4.2 +.\} +Source of the local transmit timestamp +(\fID\fP=daemon, \fIK\fP=kernel, \fIH\fP=hardware). [D] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 20.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 20." 4.2 +.\} +Source of the local receive timestamp +(\fID\fP=daemon, \fIK\fP=kernel, \fIH\fP=hardware). [K] +.RE +.RE +.sp +\fBmeasurements\fP +.RS 4 +This option is identical to the \fBrawmeasurements\fP 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\(cqs performance. +.RE +.sp +\fBstatistics\fP +.RS 4 +This option logs information about the regression processing to a file called +\fIstatistics.log\fP. An example line (which actually appears as a single line in +the file) from the log file is shown below. +.sp +.if n .RS 4 +.nf +.fam C +2016\-08\-10 05:40:50 203.0.113.15 6.261e\-03 \-3.247e\-03 \(rs + 2.220e\-03 1.874e\-06 1.080e\-06 7.8e\-02 16 0 8 0.00 +.fam +.fi +.if n .RE +.sp +The columns are as follows (the quantities in square brackets are the values +from the example line above): +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Date [2015\-07\-22] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Hour:Minute:Second. Note that the date\-time pair is expressed in +UTC, not the local time zone. [05:40:50] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +IP address of server or peer from which measurement comes [203.0.113.15] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +The estimated standard deviation of the measurements from the source (in +seconds). [6.261e\-03] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 5." 4.2 +.\} +The estimated offset of the source (in seconds, positive means the local +clock is estimated to be fast, in this case). [\-3.247e\-03] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 6." 4.2 +.\} +The estimated standard deviation of the offset estimate (in seconds). +[2.220e\-03] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 7." 4.2 +.\} +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, \fInot\fP to the local clock without any compensation. +[1.874e\-06] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 8.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 8." 4.2 +.\} +The estimated error in the rate value (in seconds per second). [1.080e\-06]. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 9.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 9." 4.2 +.\} +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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 10.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 10." 4.2 +.\} +The number of measurements currently being used for the regression +algorithm. [16] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 11.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 11." 4.2 +.\} +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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 12.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 12." 4.2 +.\} +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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 13.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 13." 4.2 +.\} +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] +.RE +.RE +.sp +\fBselection\fP +.RS 4 +This option logs information about selection of sources for synchronisation to +a file called \fIselection.log\fP. 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. +.sp +.if n .RS 4 +.nf +.fam C +2022\-05\-01 02:01:20 203.0.113.15 * \-\-\-\-\- 377 1.00 \(rs + 4.228e+01 \-1.575e\-04 1.239e\-04 +.fam +.fi +.if n .RE +.sp +The columns are as follows (the quantities in square brackets are the values +from the example line above): +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Date [2022\-05\-01] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Hour:Minute:Second. Note that the date\-time pair is expressed in +UTC, not the local time zone. [02:01:20] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +IP address or reference ID of the source. [203.0.113.15] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +State of the source indicated with one of the following symbols. [*] +.sp + +.RS 4 +Not considered selectable for synchronisation: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIN\fP \- has the \fBnoselect\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIs\fP \- is not synchronised. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIM\fP \- does not have enough measurements. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fId\fP \- has a root distance larger than the maximum distance (configured by the +\fBmaxdistance\fP directive). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI~\fP \- has a jitter larger than the maximum jitter (configured by the +\fBmaxjitter\fP directive). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIw\fP \- waits for other sources to get out of the \fIM\fP state. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIS\fP \- has older measurements than other sources. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIO\fP \- has a stratum equal or larger than the orphan stratum (configured by +the \fBlocal\fP directive). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIT\fP \- does not fully agree with sources that have the \fBtrust\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIx\fP \- does not agree with other sources (falseticker). +.RE +.RE +.sp + +.RS 4 +Considered selectable for synchronisation, but not currently used: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIW\fP \- waits for other sources to be selectable (required by the +\fBminsources\fP directive, or the \fBrequire\fP option of +another source). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIP\fP \- another selectable source is preferred due to the \fBprefer\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIU\fP \- waits for a new measurement (after selecting a different best source). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fID\fP \- has, or recently had, a root distance which is too large to be combined +with other sources (configured by the \fBcombinelimit\fP +directive). +.RE +.RE +.sp + +.RS 4 +Used for synchronisation of the local clock: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI+\fP \- combined with the best source. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI*\fP \- selected as the best source to update the reference data (e.g. root +delay, root dispersion). +.RE +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 5." 4.2 +.\} +Current effective selection options of the source. which can be different +from the configured options due to the authentication selection mode +(configured by the \fBauthselectmode\fP directive). [\-\-\-\-\-] +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIN\fP indicates the \fBnoselect\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIP\fP indicates the \fBprefer\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIT\fP indicates the \fBtrust\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIR\fP indicates the \fBrequire\fP option. +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 6." 4.2 +.\} +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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 7." 4.2 +.\} +Current score against the source in the \fI*\fP 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 \fI*\fP 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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 8.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 8." 4.2 +.\} +Interval since the last measurement of the source in seconds. [4.228e+01] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 9.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 9." 4.2 +.\} +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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 10.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 10." 4.2 +.\} +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] +.RE +.RE +.sp +\fBtracking\fP +.RS 4 +This option logs changes to the estimate of the system\(cqs gain or loss rate, and +any slews made, to a file called \fItracking.log\fP. An example line (which +actually appears as a single line in the file) from the log file is shown +below. +.sp +.if n .RS 4 +.nf +.fam C +2017\-08\-22 13:22:36 203.0.113.15 2 \-3.541 0.075 \-8.621e\-06 N \(rs + 2 2.940e\-03 \-2.084e\-04 1.534e\-02 3.472e\-04 8.304e\-03 +.fam +.fi +.if n .RE +.sp +The columns are as follows (the quantities in square brackets are the +values from the example line above) : +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Date [2017\-08\-22] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Hour:Minute:Second. Note that the date\-time pair is expressed in UTC, not the +local time zone. [13:22:36] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +The IP address of the server or peer to which the local system is synchronised. +[203.0.113.15] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +The stratum of the local system. [2] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 5." 4.2 +.\} +The local system frequency (in ppm, positive means the local system runs fast +of UTC). [\-3.541] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 6." 4.2 +.\} +The error bounds on the frequency (in ppm). [0.075] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 7." 4.2 +.\} +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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 8.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 8." 4.2 +.\} +Leap status (\fIN\fP means normal, \fI+\fP means that the last minute of this month +has 61 seconds, \fI\-\fP means that the last minute of the month has 59 seconds, +\fI?\fP means the clock is not currently synchronised.) [N] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 9.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 9." 4.2 +.\} +The number of combined sources. [2] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 10.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 10." 4.2 +.\} +The estimated standard deviation of the combined offset (in seconds). +[2.940e\-03] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 11.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 11." 4.2 +.\} +The remaining offset correction from the previous update (in seconds, +positive means the system clock is slow of UTC). [\-2.084e\-04] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 12.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 12." 4.2 +.\} +The total of the network path delays to the reference clock to which +the local clock is ultimately synchronised (in seconds). [1.534e\-02] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 13.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 13." 4.2 +.\} +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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 14.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 14." 4.2 +.\} +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] +.RE +.RE +.sp +\fBrtc\fP +.RS 4 +This option logs information about the system\(cqs real\-time clock. An example +line (which actually appears as a single line in the file) from the \fIrtc.log\fP +file is shown below. +.sp +.if n .RS 4 +.nf +.fam C +2015\-07\-22 05:40:50 \-0.037360 1 \-0.037434\(rs + \-37.948 12 5 120 +.fam +.fi +.if n .RE +.sp +The columns are as follows (the quantities in square brackets are the +values from the example line above): +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Date [2015\-07\-22] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Hour:Minute:Second. Note that the date\-time pair is expressed in UTC, not the +local time zone. [05:40:50] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +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]. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +Flag indicating whether the regression has produced valid coefficients. +(1 for yes, 0 for no). [1] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 5." 4.2 +.\} +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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 6." 4.2 +.\} +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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 7." 4.2 +.\} +The number of measurements used in the regression. [12] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 8.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 8." 4.2 +.\} +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] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 9.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 9." 4.2 +.\} +The measurement interval used prior to the measurement being made (in +seconds). [120] +.RE +.RE +.sp +\fBrefclocks\fP +.RS 4 +This option logs the raw and filtered reference clock measurements to a file +called \fIrefclocks.log\fP. An example line (which actually appears as a single +line in the file) from the log file is shown below. +.sp +.if n .RS 4 +.nf +.fam C +2009\-11\-30 14:33:27.000000 PPS2 7 N 1 4.900000e\-07 \-6.741777e\-07 1.000e\-06 +.fam +.fi +.if n .RE +.sp +The columns are as follows (the quantities in square brackets are the values +from the example line above): +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Date [2009\-11\-30] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Hour:Minute:Second.Microsecond. Note that the date\-time pair is expressed in +UTC, not the local time zone. [14:33:27.000000] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Reference ID of the reference clock from which the measurement came. [PPS2] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +Sequence number of driver poll within one polling interval for raw samples, +or \fI\-\fP for filtered samples. [7] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 5." 4.2 +.\} +Leap status (\fIN\fP means normal, \fI+\fP means that the last minute of the current +month has 61 seconds, \fI\-\fP means that the last minute of the month has 59 +seconds). [N] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 6." 4.2 +.\} +Flag indicating whether the sample comes from PPS source. (1 for yes, +0 for no, or \fI\-\fP for filtered sample). [1] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 7." 4.2 +.\} +Local clock error measured by reference clock driver, or \fI\-\fP for filtered sample. +[4.900000e\-07] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 8.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 8." 4.2 +.\} +Local clock error with applied corrections. Positive indicates that the local +clock is slow. [\-6.741777e\-07] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 9.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 9." 4.2 +.\} +Assumed dispersion of the sample. [1.000e\-06] +.RE +.RE +.sp +\fBtempcomp\fP +.RS 4 +This option logs the temperature measurements and system rate compensations to +a file called \fItempcomp.log\fP. An example line (which actually appears as a +single line in the file) from the log file is shown below. +.sp +.if n .RS 4 +.nf +.fam C +2015\-04\-19 10:39:48 2.8000e+04 3.6600e\-01 +.fam +.fi +.if n .RE +.sp +The columns are as follows (the quantities in square brackets are the values +from the example line above): +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Date [2015\-04\-19] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Hour:Minute:Second. Note that the date\-time pair is expressed in UTC, not the +local time zone. [10:39:48] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Temperature read from the sensor. [2.8000e+04] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +Applied compensation in ppm, positive means the system clock is running +faster than it would be without the compensation. [3.6600e\-01] +.RE +.RE +.RE +.sp + +.RS 4 +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +log measurements statistics tracking +.fam +.fi +.if n .RE +.RE +.sp +\fBlogbanner\fP \fIentries\fP +.RS 4 +A banner is periodically written to the log files enabled by the \fBlog\fP +directive to indicate the meanings of the columns. +.sp +The \fBlogbanner\fP 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. +.RE +.sp +\fBlogchange\fP \fIthreshold\fP +.RS 4 +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 +\fBsettime\fP command of \fBchronyc\fP are logged. +.sp +By default, the threshold is 1 second. +.sp +An example of the use is: +.sp +.if n .RS 4 +.nf +.fam C +logchange 0.1 +.fam +.fi +.if n .RE +.sp +which would cause a syslog message to be generated if a system clock error of over +0.1 seconds starts to be compensated. +.RE +.sp +\fBlogdir\fP \fIdirectory\fP +.RS 4 +This directive specifies the directory for writing log files enabled by the +\fBlog\fP directive. If the directory does not exist, it will be created +automatically. +.sp +An example of the use of this directive is: +.sp +.if n .RS 4 +.nf +.fam C +logdir /var/log/chrony +.fam +.fi +.if n .RE +.RE +.sp +\fBmailonchange\fP \fIemail\fP \fIthreshold\fP +.RS 4 +This directive defines an email address to which mail should be sent if +\fBchronyd\fP applies a correction exceeding a particular threshold to the system +clock. +.sp +An example of the use of this directive is: +.sp +.if n .RS 4 +.nf +.fam C +mailonchange root@localhost 0.5 +.fam +.fi +.if n .RE +.sp +This would send a mail message to root if a change of more than 0.5 seconds +were applied to the system clock. +.sp +This directive cannot be used when a system call filter is enabled by the \fB\-F\fP +option as the \fBchronyd\fP process will not be allowed to fork and execute the +sendmail binary. +.RE +.SS "Miscellaneous" +.sp +\fBconfdir\fP \fIdirectory\fP... +.RS 4 +The \fBconfdir\fP directive includes configuration files with the \fI.conf\fP suffix +from a directory. The files are included in the lexicographical order of the +file names. +.sp +Multiple directories (up to 10) can be specified with a single \fBconfdir\fP +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. +.sp +This directive can be used multiple times. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +confdir @SYSCONFDIR@/chrony.d +.fam +.fi +.if n .RE +.RE +.sp +\fBsourcedir\fP \fIdirectory\fP... +.RS 4 +The \fBsourcedir\fP directive is identical to the \fBconfdir\fP directive, except the +configuration files have the \fI.sources\fP suffix, they can only specify NTP +sources (i.e. the \fBserver\fP, \fBpool\fP, and \fBpeer\fP directives), they are expected +to have all lines terminated by the newline character, and they can be +reloaded by the \fBreload sources\fP command in +\fBchronyc\fP. 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. +.sp +This directive can be used multiple times. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +sourcedir /var/run/chrony\-dhcp +.fam +.fi +.if n .RE +.RE +.sp +\fBinclude\fP \fIpattern\fP +.RS 4 +The \fBinclude\fP directive includes a configuration file, or multiple configuration +files if a wildcard pattern is specified. Unlike with the \fBconfdir\fP directive, +the full name of the files needs to be specified and at least one file is +required to exist. +.sp +This directive can be used multiple times. +.sp +An example of the directive is: +.sp +.if n .RS 4 +.nf +.fam C +include @SYSCONFDIR@/chrony.d/*.conf +.fam +.fi +.if n .RE +.RE +.sp +\fBhwtimestamp\fP \fIinterface\fP [\fIoption\fP]... +.RS 4 +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 \fBxleave\fP option in the \fBserver\fP or the +\fBpeer\fP directive. +.sp +This directive is supported on Linux 3.19 and newer. The NIC must support HW +timestamping, which can be verified with the \fBethtool \-T\fP command. The list of +capabilities should include \fIhardware\-raw\-clock\fP, \fIhardware\-transmit\fP, and +\fIhardware\-receive\fP. The receive filter \fIall\fP, or \fIntp\fP, 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, \fBchronyd\fP will use kernel +receive timestamps instead. Transmit\-only HW timestamping can still be useful +to improve stability of the synchronisation. +.sp +\fBchronyd\fP does not synchronise the NIC clock. It assumes the clock is running +free. Multiple instances of \fBchronyd\fP 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 \fI/sys/class/ptp/ptpX/n_vclocks\fP. This +feature is available on Linux 5.14 and newer. +.sp +If the kernel supports software timestamping, it will be enabled for all +interfaces automatically. +.sp +The source of timestamps (i.e. hardware, kernel, or daemon) is indicated on the +client side in the \fImeasurements.log\fP file (if enabled by the \fBlog\fP +directive) and the \fBntpdata\fP report. On the server +side, the number of served timestamps from each source is provided in the +\fBserverstats\fP report. +.sp +This directive can be used multiple times to enable HW timestamping on multiple +interfaces. If the specified interface is \fI*\fP, \fBchronyd\fP will try to enable HW +timestamping on all available interfaces. +.sp +The \fBhwtimestamp\fP directive has the following options: +.sp +\fBminpoll\fP \fIpoll\fP +.RS 4 +This option specifies the minimum interval between readings of the NIC clock. +It\(cqs 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). +.RE +.sp +\fBmaxpoll\fP \fIpoll\fP +.RS 4 +This option specifies the maximum interval between readings of the NIC clock, +as a power of 2. The default value is \fBminpoll\fP + 1, i.e. 1 (2 seconds) with +the default \fBminpoll\fP of 0. The minimum and maximum values are the same as with +the \fBminpoll\fP option. +.RE +.sp +\fBminsamples\fP \fIsamples\fP +.RS 4 +This option specifies the minimum number of readings kept for tracking of the +NIC clock. The default value is 2. +.RE +.sp +\fBmaxsamples\fP \fIsamples\fP +.RS 4 +This option specifies the maximum number of readings kept for tracking of the +NIC clock. The default value is 16. +.RE +.sp +\fBprecision\fP \fIprecision\fP +.RS 4 +This option specifies the assumed precision of reading of the NIC clock. The +default value is 100e\-9 (100 nanoseconds). +.RE +.sp +\fBtxcomp\fP \fIcompensation\fP +.RS 4 +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. +.RE +.sp +\fBrxcomp\fP \fIcompensation\fP +.RS 4 +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. +.RE +.sp +\fBnocrossts\fP +.RS 4 +Some hardware can precisely cross timestamp the NIC clock with the system +clock. This option disables the use of the cross timestamping. +.RE +.sp +\fBrxfilter\fP \fIfilter\fP +.RS 4 +This option selects the receive timestamping filter. The \fIfilter\fP can be one of +the following: +.sp +\fIall\fP +.RS 4 +Enables timestamping of all received packets. +.RE +.sp +\fIntp\fP +.RS 4 +Enables timestamping of received NTP packets. +.RE +.sp +\fIptp\fP +.RS 4 +Enables timestamping of received PTP packets. +.RE +.sp +\fInone\fP +.RS 4 +Disables timestamping of received packets. +.RE +.RE +.sp + +.RS 4 +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 \fInone\fP filter and expected to provide hardware +timestamps for transmitted packets only. Timestamping of PTP packets is useful +with NTP\-over\-PTP enabled by the \fBptpport\fP +directive, or when another application is receiving PTP packets on the +interface. Forcing timestamping of all packets with the \fIall\fP filter could be +useful if the NIC supported both the \fIall\fP and \fIntp\fP filters, and it should +timestamp both NTP and PTP packets, or NTP packets on a different UDP port. +.RE +.RE +.sp + +.RS 4 +.sp +Examples of the directive are: +.sp +.if n .RS 4 +.nf +.fam C +hwtimestamp eth0 +hwtimestamp eth1 txcomp 300e\-9 rxcomp 645e\-9 +hwtimestamp * +.fam +.fi +.if n .RE +.RE +.sp +\fBhwtstimeout\fP \fItimeout\fP +.RS 4 +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, +\fBchronyd\fP 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 \fBchronyd\fP 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. +.sp +The default value is 0.001 seconds, which should be sufficient with most +hardware. If you frequently see kernel transmit timestamps in the +\fImeasurements.log\fP file or \fBntpdata\fP 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\(cqs 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. +.RE +.sp +\fBkeyfile\fP \fIfile\fP +.RS 4 +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. +.sp +The format of the directive is shown in the example below: +.sp +.if n .RS 4 +.nf +.fam C +keyfile @SYSCONFDIR@/chrony.keys +.fam +.fi +.if n .RE +.sp +The argument is simply the name of the file containing the ID\-key pairs. The +format of the file is shown below: +.sp +.if n .RS 4 +.nf +.fam C +10 tulip +11 hyacinth +20 MD5 ASCII:crocus +25 SHA1 HEX:933F62BE1D604E68A81B557F18CFA200483F5B70 +30 AES128 HEX:7EA62AE64D190114D46D5A082F948EC1 +31 AES256 HEX:37DDCBC67BB902BCB8E995977FAB4D2B5642F5B32EBCEEE421921D97E5CBFE39 + ... +.fam +.fi +.if n .RE +.sp +Each line consists of an ID, optional type, and key. +.sp +The ID can be any positive integer in the range 1 through 2^32\-1. +.sp +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 \fBMD5\fP, which is always +supported. +If \fBchronyd\fP was built with enabled support for hashing using a crypto library +(Nettle, GnuTLS, NSS, or LibTomCrypt), the following functions are available: \fBMD5\fP, +\fBSHA1\fP, \fBSHA256\fP, \fBSHA384\fP, \fBSHA512\fP. Depending on which library and version is +\fBchronyd\fP using, some of the following hash functions and ciphers may +also be available: +\fBSHA3\-224\fP, \fBSHA3\-256\fP, \fBSHA3\-384\fP, \fBSHA3\-512\fP, \fBTIGER\fP, \fBWHIRLPOOL\fP, \fBAES128\fP, +\fBAES256\fP. +.sp +The key can be specified as a string of ASCII characters not containing white +space with an optional \fBASCII:\fP prefix, or as a hexadecimal number with the +\fBHEX:\fP 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). +.sp +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 \fBHEX:\fP prefix). \fBchronyd\fP will log a warning to syslog on start if a +source is specified in the configuration file with a key shorter than 80 bits. +.sp +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. +.sp +The \fBkeygen\fP command of \fBchronyc\fP can be used to +generate random keys for the key file. By default, it generates 160\-bit MD5 or +SHA1 keys. +.sp +For security reasons, the file should be readable only by root and the user +under which \fBchronyd\fP is normally running (to allow \fBchronyd\fP to re\-read the +file when the \fBrekey\fP command is issued by \fBchronyc\fP). +.RE +.sp +\fBlock_all\fP +.RS 4 +The \fBlock_all\fP directive will lock the \fBchronyd\fP 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. +.RE +.sp +\fBpidfile\fP \fIfile\fP +.RS 4 +Unless \fBchronyd\fP is started with the \fB\-Q\fP option, it writes its process ID +(PID) to a file, and checks this file on startup to see if another \fBchronyd\fP +might already be running on the system. By default, the file used is +\fI@DEFAULT_PID_FILE@\fP. The \fBpidfile\fP directive allows the name to be changed, +e.g.: +.sp +.if n .RS 4 +.nf +.fam C +pidfile /run/chronyd.pid +.fam +.fi +.if n .RE +.RE +.sp +\fBptpport\fP \fIport\fP +.RS 4 +The \fBptpport\fP directive enables \fBchronyd\fP 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). +.sp +The NTP\-over\-PTP support is experimental. The protocol and configuration can +change in future. It should be used only in local networks. +.sp +The PTP port will be open even if \fBchronyd\fP 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 \fBport\fP option set to the PTP port. To actually enable +hardware timestamping on NICs which can timestamp PTP packets only, the +\fBrxfilter\fP option of the \fBhwtimestamp\fP directive needs to be set to \fIptp\fP. The +extension field \fIF324\fP needs to be enabled to use the corrections provided by +the PTP transparent clocks. +.sp +An example of client configuration is: +.sp +.if n .RS 4 +.nf +.fam C +server ntp1.example.net minpoll 0 maxpoll 0 xleave port 319 extfield F324 +hwtimestamp * rxfilter ptp +ptpport 319 +.fam +.fi +.if n .RE +.RE +.sp +\fBsched_priority\fP \fIpriority\fP +.RS 4 +On Linux, FreeBSD, NetBSD, and illumos, the \fBsched_priority\fP 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. +.sp +On systems other than macOS, this directive uses the \fBpthread_setschedparam()\fP +system call to instruct the kernel to use the SCHED_FIFO first\-in, first\-out +real\-time scheduling policy for \fBchronyd\fP with the specified priority. This +means that whenever \fBchronyd\fP 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 \fBchronyd\fP resource requirements are modest, +but it should result in lower and more consistent latency since \fBchronyd\fP 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 \fBpthread_setschedparam(3)\fP man page has +more details. +.sp +On macOS, this directive uses the \fBthread_policy_set()\fP kernel call to +specify real\-time scheduling. As noted above, you should not use this directive +unless you really need it. +.RE +.sp +\fBuser\fP \fIuser\fP +.RS 4 +The \fBuser\fP directive sets the name of the system user to which \fBchronyd\fP will +switch after start in order to drop root privileges. +.sp +On Linux, \fBchronyd\fP needs to be compiled with support for the \fBlibcap\fP library. +On macOS, FreeBSD, NetBSD and illumos \fBchronyd\fP 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. +.sp +The compiled\-in default value is \fI@DEFAULT_USER@\fP. +.RE +.SH "EXAMPLES" +.SS "NTP client with permanent connection to NTP servers" +.sp +This section shows how to configure \fBchronyd\fP 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. +.sp +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: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +Your institution might already operate servers on its network. +Contact your system administrator to find out. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +Your ISP probably has one or more NTP servers available for its +customers. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +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. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +Use public servers from the \c +.URL "https://www.pool.ntp.org/" "pool.ntp.org" "" +project. +.RE +.sp +Assuming that your NTP servers are called \fIntp1.example.net\fP, \fIntp2.example.net\fP +and \fIntp3.example.net\fP, your \fIchrony.conf\fP file could contain as a minimum: +.sp +.if n .RS 4 +.nf +.fam C +server ntp1.example.net +server ntp2.example.net +server ntp3.example.net +.fam +.fi +.if n .RE +.sp +However, you will probably want to include some of the other directives. The +\fBdriftfile\fP, \fBmakestep\fP and \fBrtcsync\fP +might be particularly useful. Also, the \fBiburst\fP option of the +\fBserver\fP directive is useful to speed up the initial +synchronisation. The smallest useful configuration file would look something +like: +.sp +.if n .RS 4 +.nf +.fam C +server ntp1.example.net iburst +server ntp2.example.net iburst +server ntp3.example.net iburst +driftfile @CHRONYVARDIR@/drift +makestep 1.0 3 +rtcsync +.fam +.fi +.if n .RE +.sp +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 \fBpool\fP +directive instead of multiple \fBserver\fP directives. The configuration file could +in this case look like: +.sp +.if n .RS 4 +.nf +.fam C +pool pool.ntp.org iburst +driftfile @CHRONYVARDIR@/drift +makestep 1.0 3 +rtcsync +.fam +.fi +.if n .RE +.sp +If the servers (or pool) support the Network Time Security (NTS) +authentication mechanism and \fBchronyd\fP is compiled with NTS support, the \fBnts\fP +option will enable a secure synchronisation to the servers. The configuration +file could look like: +.sp +.if n .RS 4 +.nf +.fam C +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 +.fam +.fi +.if n .RE +.SS "NTP client with infrequent connection to NTP servers" +.sp +This section shows how to configure \fBchronyd\fP for computers that have +occasional connections to NTP servers. In this case, you will need some +additional configuration to tell \fBchronyd\fP when the connection goes up and +down. This saves the program from continuously trying to poll the servers when +they are inaccessible. +.sp +Again, assuming that your NTP servers are called \fIntp1.example.net\fP, +\fIntp2.example.net\fP and \fIntp3.example.net\fP, your \fIchrony.conf\fP file would now +contain: +.sp +.if n .RS 4 +.nf +.fam C +server ntp1.example.net offline +server ntp2.example.net offline +server ntp3.example.net offline +driftfile @CHRONYVARDIR@/drift +makestep 1.0 3 +rtcsync +.fam +.fi +.if n .RE +.sp +The \fBoffline\fP keyword indicates that the servers start in an offline state, and +that they should not be contacted until \fBchronyd\fP receives notification from +\fBchronyc\fP that the link to the Internet is present. To tell \fBchronyd\fP when to +start and finish sampling the servers, the \fBonline\fP and +\fBoffline\fP commands of \fBchronyc\fP need to be used. +.sp +To give an example of their use, assuming that \fBpppd\fP is the program being +used to connect to the Internet and that \fBchronyc\fP has been installed at +\fI@BINDIR@/chronyc\fP, the script \fI/etc/ppp/ip\-up\fP would include: +.sp +.if n .RS 4 +.nf +.fam C +@BINDIR@/chronyc online +.fam +.fi +.if n .RE +.sp +and the script \fI/etc/ppp/ip\-down\fP would include: +.sp +.if n .RS 4 +.nf +.fam C +@BINDIR@/chronyc offline +.fam +.fi +.if n .RE +.sp +\fBchronyd\fP\*(Aqs polling of the servers would now only occur whilst the machine is +actually connected to the Internet. +.SS "Isolated networks" +.sp +This section shows how to configure \fBchronyd\fP for computers that never have +network connectivity to any computer which ultimately derives its time from a +reference clock. +.sp +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. +.sp +The \fBlocal\fP directive enables a local reference mode, which allows +\fBchronyd\fP to appear synchronised even when it is not. +.sp +The rate value in the server\(cqs drift file needs to be set to the average rate +at which the server gains or loses time. \fBchronyd\fP includes support for this, +in the form of the \fBmanual\fP directive and the +\fBsettime\fP command in the \fBchronyc\fP program. +.sp +If the server is rebooted, \fBchronyd\fP 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 \(oqmajority\-vote\(cq of selected clients\*(Aq times; this allows the +clients to \(oqflywheel\(cq the server while it is rebooting. +.sp +The \fBsmoothtime\fP directive is useful when the clocks of the +clients need to stay close together when the local time is adjusted by the +\fBsettime\fP command. The smoothing process needs to be +activated by the \fBsmoothtime activate\fP command when +the local time is ready to be served. After that point, any adjustments will be +smoothed out. +.sp +A typical configuration file for the server (called \fIntp.local\fP) might be +(assuming the clients and the server are in the \fI192.168.165.x\fP subnet): +.sp +.if n .RS 4 +.nf +.fam C +initstepslew 1 client1 client3 client6 +driftfile @CHRONYVARDIR@/drift +local stratum 8 +manual +allow 192.168.165.0/24 +smoothtime 400 0.01 +rtcsync +.fam +.fi +.if n .RE +.sp +For the clients that have to resynchronise the server when it restarts, +the configuration file might be: +.sp +.if n .RS 4 +.nf +.fam C +server ntp.local iburst +driftfile @CHRONYVARDIR@/drift +allow 192.168.165.0/24 +makestep 1.0 3 +rtcsync +.fam +.fi +.if n .RE +.sp +The rest of the clients would be the same, except that the \fBallow\fP directive is +not required. +.sp +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 +\fBorphan\fP option of the \fBlocal\fP directive enables a special mode where the +server is selected from multiple computers automatically. They all need to use +the same \fBlocal\fP 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. +.sp +A configuration file for the first server might be (assuming there are three +servers called \fIntp1.local\fP, \fIntp2.local\fP, and \fIntp3.local\fP): +.sp +.if n .RS 4 +.nf +.fam C +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 +.fam +.fi +.if n .RE +.sp +The other servers would be the same, except the hostnames in the \fBinitstepslew\fP +and \fBserver\fP directives would be modified to specify the other servers. Their +clients might be configured to poll all three servers. +.SS "RTC tracking" +.sp +This section considers a computer which has occasional connections to the +Internet and is turned off between \(oqsessions\(cq. In this case, \fBchronyd\fP relies +on the computer\(cqs 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 \fBHPET_EMULATE_RTC\fP option in your kernel configuration. Otherwise, +\fBchronyd\fP will not be able to interact with the RTC device and will give up +using it. +.sp +When the computer is connected to the Internet, \fBchronyd\fP 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\(cqs time error and rate of gaining or losing time. +.sp +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. +.sp +Whilst the computer is running, \fBchronyd\fP makes measurements of the RTC (via +the \fI/dev/rtc\fP 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. +.sp +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 \fBrtcfile\fP directive has been specified). +These pieces of information are also saved if the \fBdump\fP +and \fBwritertc\fP commands respectively are issued +through \fBchronyc\fP. +.sp +When the computer is rebooted, \fBchronyd\fP 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. +.sp +The next time the computer goes online, the previous sessions\*(Aq measurements can +contribute to the line\-fitting process, which gives a much better estimate of +the computer\(cqs gain or loss rate. +.sp +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 \fBchronyd\fP 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 \fBtrimrtc\fP command in \fBchronyc\fP. Because of this, +\fBtrimrtc\fP will make sure that a meaningful RTC file is saved after the +change is completed). +.sp +The easiest protection against power failure is to put the \fBdump\fP and +\fBwritertc\fP commands in the same place as the \fBoffline\fP command is issued to +take \fBchronyd\fP offline; because \fBchronyd\fP free\-runs between online sessions, no +parameters will change significantly between going offline from the Internet +and any power failure. +.sp +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). \fBchronyd\fP 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 \fBlog rtc\fP facility in the configuration +file; this option should not be used if you want your disc to spin down. +.sp +To illustrate how a computer might be configured for this case, example +configuration files are shown. +.sp +For the \fIchrony.conf\fP file, the following can be used as an example. +.sp +.if n .RS 4 +.nf +.fam C +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 +.fam +.fi +.if n .RE +.sp +\fBpppd\fP is used for connecting to the Internet. This runs two scripts +\fI/etc/ppp/ip\-up\fP and \fI/etc/ppp/ip\-down\fP when the link goes online and offline +respectively. +.sp +The relevant part of the \fI/etc/ppp/ip\-up\fP file is: +.sp +.if n .RS 4 +.nf +.fam C +@BINDIR@/chronyc online +.fam +.fi +.if n .RE +.sp +and the relevant part of the \fI/etc/ppp/ip\-down\fP script is: +.sp +.if n .RS 4 +.nf +.fam C +@BINDIR@/chronyc \-m offline dump writertc +.fam +.fi +.if n .RE +.sp +\fBchronyd\fP is started during the boot sequence with the \fB\-r\fP and \fB\-s\fP 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 \fBchronyd\fP\*(Aqs +configuration file. +.sp +For the system shutdown, \fBchronyd\fP should receive a SIGTERM several seconds +before the final SIGKILL; the SIGTERM causes the measurement histories and RTC +information to be saved. +.SS "Public NTP server" +.sp +\fBchronyd\fP can be configured to operate as a public NTP server, e.g. to join the +.URL "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 +\fBrefclock\fP directive. +.sp +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 +\fBratelimit\fP directive. The system timezone database, if it is +kept up to date and includes the \fIright/UTC\fP timezone, can be used as a +reliable source to determine when a leap second will be applied to UTC. The +\fB\-r\fP option with the \fBdumpdir\fP directive shortens the time in which +\fBchronyd\fP 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). +.sp +The configuration file could look like: +.sp +.if n .RS 4 +.nf +.fam C +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@ +.fam +.fi +.if n .RE +.SH "SEE ALSO" +.sp +\fBchronyc(1)\fP, \fBchronyd(8)\fP +.SH "BUGS" +.sp +For instructions on how to report bugs, please visit +.URL "https://chrony\-project.org/" "" "." +.SH "AUTHORS" +.sp +chrony was written by Richard Curnow, Miroslav Lichvar, and others.
\ No newline at end of file diff --git a/doc/chronyc.adoc b/doc/chronyc.adoc new file mode 100644 index 0000000..96a0551 --- /dev/null +++ b/doc/chronyc.adoc @@ -0,0 +1,1559 @@ +// This file is part of chrony +// +// Copyright (C) Richard P. Curnow 1997-2003 +// Copyright (C) Stephen Wadeley 2016 +// Copyright (C) Miroslav Lichvar 2009-2017, 2019-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. + += chronyc(1) +:doctype: manpage +:man manual: User manual +:man source: chrony @CHRONY_VERSION@ + +== NAME + +chronyc - command-line interface for chrony daemon + +== SYNOPSIS + +*chronyc* [_OPTION_]... [_COMMAND_]... + +== DESCRIPTION + +*chronyc* is a command-line interface program which can be used to monitor +*chronyd*'s performance and to change various operating parameters whilst it is +running. + +If no commands are specified on the command line, *chronyc* will expect input +from the user. The prompt _chronyc>_ will be displayed when it is being run +from a terminal. If *chronyc*'s input or output are redirected from or to a file, +the prompt will not be shown. + +There are two ways *chronyc* can access *chronyd*. One is the Internet +Protocol (IPv4 or IPv6) and the other is a Unix domain socket, which is +accessible locally by the root or _chrony_ user. By default, *chronyc* first +tries to connect to the Unix domain socket. The compiled-in default path is +_@CHRONYRUNDIR@/chronyd.sock_. If that fails (e.g. because *chronyc* is +running under a non-root user), it will try to connect to 127.0.0.1 and then +::1. + +Only the following monitoring commands, which do not affect the behaviour of +*chronyd*, are allowed from the network: *activity*, *manual list*, +*rtcdata*, *smoothing*, *sourcename*, *sources*, *sourcestats*, *tracking*, +*waitsync*. The +set of hosts from which *chronyd* will accept these commands can be configured +with the <<chrony.conf.adoc#cmdallow,*cmdallow*>> directive in the *chronyd*'s +configuration file or the <<cmdallow,*cmdallow*>> command in *chronyc*. By +default, the commands are accepted only from localhost (127.0.0.1 or ::1). + +All other commands are allowed only through the Unix domain socket. When sent +over the network, *chronyd* will respond with a '`Not authorised`' error, even +if it is from localhost. + +Having full access to *chronyd* via *chronyc* is more or less equivalent to +being able to modify the *chronyd*'s configuration file and restart it. + +== OPTIONS + +*-4*:: +With this option hostnames will be resolved only to IPv4 addresses. + +*-6*:: +With this option hostnames will be resolved only to IPv6 addresses. + +*-n*:: +This option disables resolving of IP addresses to hostnames, e.g. to avoid slow +DNS lookups. Long addresses will not be truncated to fit into the column. + +*-N*:: +This option enables printing of original hostnames or IP addresses of NTP +sources that were specified in the configuration file, or *chronyc* commands. +Without the *-n* and *-N* option, the printed hostnames are obtained from +reverse DNS lookups and can be different from the specified hostnames. + +*-c*:: +This option enables printing of reports in a comma-separated values (CSV) +format. Reverse DNS lookups will be disabled, time will be printed as number of +seconds since the epoch, and values in seconds will not be converted to other +units. + +*-e*:: +With this option each *chronyc* response will end with a line containing a +single dot. + +*-d*:: +This option enables printing of debugging messages if *chronyc* was compiled +with debugging support. + +*-m*:: +Normally, all arguments on the command line are interpreted as one command. +With this option multiple commands can be specified. Each argument will be +interpreted as a whole command. + +*-h* _host_:: +This option specifies the host to be contacted by *chronyc*. It can be +specified with a hostname, IP address, or path to the local Unix domain socket. +Multiple values can be specified as a comma-separated list to provide a +fallback. ++ +The default value is _@CHRONYRUNDIR@/chronyd.sock,127.0.0.1,::1_, i.e. the host +where *chronyc* is being run. First, it tries to connect to the Unix domain +socket and if that fails (e.g. due to running under a non-root user), it +will try to connect to 127.0.0.1 and then ::1. + +*-p* _port_:: +This option allows the user to specify the UDP port number which the target +*chronyd* is using for its monitoring connections. This defaults to 323; there +would rarely be a need to change this. + +*-f* _file_:: +This option is ignored and is provided only for compatibility. + +*-a*:: +This option is ignored and is provided only for compatibility. + +*-v*, *--version*:: +With this option *chronyc* displays its version number on the terminal and +exits. + +*--help*:: +With this option *chronyc* displays a help message on the terminal and +exits. + +== COMMANDS + +This section describes each of the commands available within the *chronyc* +program. + +=== System clock + +[[tracking]]*tracking*:: +The *tracking* command displays parameters about the system's clock +performance. An example of the output is shown below. ++ +---- +Reference ID : CB00710F (ntp1.example.net) +Stratum : 3 +Ref time (UTC) : Fri Jan 27 09:49:17 2017 +System time : 0.000006523 seconds slow of NTP time +Last offset : -0.000006747 seconds +RMS offset : 0.000035822 seconds +Frequency : 3.225 ppm slow +Residual freq : -0.000 ppm +Skew : 0.129 ppm +Root delay : 0.013639022 seconds +Root dispersion : 0.001100737 seconds +Update interval : 64.2 seconds +Leap status : Normal +---- ++ +The fields are explained as follows: ++ +*Reference ID*::: +This is the reference ID and name (or IP address) of the server to which the +computer is currently synchronised. For IPv4 addresses, the reference ID is +equal to the address and for IPv6 addresses it is the first 32 bits of the MD5 +sum of the address. ++ +If the reference ID is _7F7F0101_ and there is no name or IP address, it means +the computer is not synchronised to any external source and that you have the +_local_ mode operating (via the <<local,*local*>> command in *chronyc*, or the +<<chrony.conf.adoc#local,*local*>> directive in the configuration file). ++ +The reference ID is printed as a hexadecimal number. Note that in older +versions it used to be printed in quad-dotted notation and could be confused +with an IPv4 address. +*Stratum*::: +The stratum indicates how many hops away from a computer with an attached +reference clock we are. Such a computer is a stratum-1 computer, so the +computer in the example is two hops away (i.e. _ntp1.example.net_ is a +stratum-2 and is synchronised from a stratum-1). +*Ref time*::: +This is the time (UTC) at which the last measurement from the reference +source was processed. +*System time*::: +This is the current offset between the NTP clock and system clock. The NTP +clock is a software (virtual) clock maintained by *chronyd*, which is +synchronised to the configured time sources and provides time to NTP clients. +The system clock is synchronised to the NTP clock. To avoid steps in the +system time, which might have adverse consequences for certain applications, +the system clock is normally corrected only by speeding up or slowing down (up +to the rate configured by the <<chrony.conf.adoc#maxslewrate,*maxslewrate*>> +directive). If the offset is too large, this correction will take a very long +time. A step can be forced by the <<makestep,*makestep*>> command, or the +<<chrony.conf.adoc#makestep,*makestep*>> directive in the configuration file. ++ +Note that all other offsets reported by *chronyc* and most offsets in the log +files are relative to the NTP clock, not the system clock. +*Last offset*::: +This is the estimated local offset on the last clock update. A positive value +indicates the local time (as previously estimated true time) was ahead of the +time sources. +*RMS offset*::: +This is a long-term average of the offset value. +*Frequency*::: +The '`frequency`' is the rate by which the system's clock would be wrong if +*chronyd* was not correcting it. It is expressed in ppm (parts per million). +For example, a value of 1 ppm would mean that when the system's clock thinks it +has advanced 1 second, it has actually advanced by 1.000001 seconds relative to +true time. +*Residual freq*::: +This shows the '`residual frequency`' for the currently selected reference +source. This reflects any difference between what the measurements from the +reference source indicate the frequency should be and the frequency currently +being used. ++ +The reason this is not always zero is that a smoothing procedure is +applied to the frequency. Each time a measurement from the reference +source is obtained and a new residual frequency computed, the estimated +accuracy of this residual is compared with the estimated accuracy (see +'`skew`' next) of the existing frequency value. A weighted average is +computed for the new frequency, with weights depending on these accuracies. +If the measurements from the reference source follow a consistent trend, the +residual will be driven to zero over time. +*Skew*::: +This is the estimated error bound on the frequency. +*Root delay*::: +This is the total of the network path delays to the stratum-1 computer from +which the computer is ultimately synchronised. +*Root dispersion*::: +This is the total dispersion accumulated through all the computers back to +the stratum-1 computer from which the computer is ultimately synchronised. +Dispersion is due to system clock resolution, statistical measurement +variations, etc. ++ +An absolute bound on the computer's clock accuracy (assuming the stratum-1 +computer is correct) is given by: ++ +---- +clock_error <= |system_time_offset| + root_dispersion + (0.5 * root_delay) +---- +*Update interval*::: +This is the interval between the last two clock updates. +*Leap status*::: +This is the leap status, which can be _Normal_, _Insert second_, _Delete +second_ or _Not synchronised_. + +[[makestep]]*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, +the system clock might be so far adrift that this slewing process would take a +very long time to correct the system clock. ++ +The *makestep* command can be used in this situation. There are two forms of +the command. The first form has no parameters. It tells *chronyd* to cancel any +remaining correction that was being slewed and jump the system clock by the +equivalent amount, making it correct immediately. ++ +The second form configures the automatic stepping, similarly to the +<<chrony.conf.adoc#makestep,*makestep*>> directive. It has two parameters, +stepping threshold (in seconds) and number of future clock updates for which +the threshold will be active. This can be used with the <<burst,*burst*>> +command to quickly make a new measurement and correct the clock by stepping if +needed, without waiting for *chronyd* to complete the measurement and update +the clock. ++ +---- +makestep 0.1 1 +burst 1/2 +---- ++ +BE WARNED: Certain software will be seriously affected by such jumps in the +system time. (That is the reason why *chronyd* uses slewing normally.) + +[[maxupdateskew]]*maxupdateskew* _skew-in-ppm_:: +This command has the same effect as the +<<chrony.conf.adoc#maxupdateskew,*maxupdateskew*>> directive in the +configuration file. + +[[waitsync]]*waitsync* [_max-tries_ [_max-correction_ [_max-skew_ [_interval_]]]]:: +The *waitsync* command waits for *chronyd* to synchronise. ++ +Up to four optional arguments can be specified. The first is the maximum number +of tries before giving up and returning a non-zero error code. When 0 is +specified, or there are no arguments, the number of tries will not be limited. ++ +The second and third arguments are the maximum allowed remaining correction of +the system clock and the maximum allowed skew (in ppm) as reported by the +<<tracking,*tracking*>> command in the *System time* and *Skew* fields. If not +specified or zero, the value will not be checked. ++ +The fourth argument is the interval specified in seconds in which the check is +repeated. The interval is 10 seconds by default. ++ +An example is: ++ +---- +waitsync 60 0.01 +---- ++ +which will wait up to about 10 minutes (60 times 10 seconds) for *chronyd* to +synchronise to a source and the remaining correction to be less than 10 +milliseconds. + +=== Time sources + +[[sources]]*sources* [*-a*] [*-v*]:: +This command displays information about the current time sources that *chronyd* +is accessing. ++ +If the *-a* option is specified, all sources are displayed, including those that +do not have a known address yet. Such sources have an identifier in the format +_ID#XXXXXXXXXX_, which can be used in other commands expecting a source address. ++ +The *-v* option enables a verbose output. In this case, +extra caption lines are shown as a reminder of the meanings of the columns. ++ +---- +MS Name/IP address Stratum Poll Reach LastRx Last sample +=============================================================================== +#* GPS0 0 4 377 11 -479ns[ -621ns] +/- 134ns +^? ntp1.example.net 2 6 377 23 -923us[ -924us] +/- 43ms +^+ ntp2.example.net 1 6 377 21 -2629us[-2619us] +/- 86ms +---- ++ +The columns are as follows: ++ +*M*::: +This indicates the mode of the source. _^_ means a server, _=_ means a peer +and _#_ indicates a locally connected reference clock. +*S*::: +This column indicates the selection state of the source. +* _*_ indicates the best source which is currently selected for + synchronisation. +* _+_ indicates other sources selected for synchronisation, which are combined + with the best source. +* _-_ indicates a source which is considered to be selectable for + synchronisation, but not currently selected. +* _x_ indicates a source which *chronyd* thinks is a falseticker (i.e. its + time is inconsistent with a majority of other sources, or sources specified + with the *trust* option). +* _~_ indicates a source whose time appears to have too much variability. +* _?_ indicates a source which is not considered to be selectable for + synchronisation for other reasons (e.g. unreachable, not synchronised, or + does not have enough measurements). +{blank}::: +The <<selectdata,*selectdata*>> command can be used to get more details about +the selection state. +*Name/IP address*::: +This shows the name or the IP address of the source, or reference ID for reference +clocks. +*Stratum*::: +This shows the stratum of the source, as reported in its most recently +received sample. Stratum 1 indicates a computer with a locally attached +reference clock. A computer that is synchronised to a stratum 1 computer is +at stratum 2. A computer that is synchronised to a stratum 2 computer is at +stratum 3, and so on. +*Poll*::: +This shows the rate at which the source is being polled, as a base-2 +logarithm of the interval in seconds. Thus, a value of 6 would indicate that +a measurement is being made every 64 seconds. *chronyd* automatically varies +the polling rate in response to prevailing conditions. +*Reach*::: +This shows the source's 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. +*LastRx*::: +This column shows how long ago the last good sample (which is shown in the next +column) was received from the source. Measurements that failed some tests are +ignored. This is normally in seconds. The letters _m_, _h_, _d_ or _y_ indicate +minutes, hours, days, or years. +*Last sample*::: +This column shows the offset between the local clock and the source at the +last measurement. The number in the square brackets shows the actual measured +offset. This can be suffixed by _ns_ (indicating nanoseconds), _us_ +(indicating microseconds), _ms_ (indicating milliseconds), or _s_ (indicating +seconds). The number to the left of the square brackets shows the original +measurement, adjusted to allow for any slews applied to the local clock +since. Positive offsets indicate that the local clock is ahead of the source. +The number following the _+/-_ indicator shows the margin of error in the +measurement (NTP root distance). + +[[sourcestats]]*sourcestats* [*-a*] [*-v*]:: +The *sourcestats* command displays information about the drift rate and offset +estimation process for each of the sources currently being examined by +*chronyd*. ++ +If the *-a* option is specified, all sources are displayed, including those that +do not have a known address yet. Such sources have an identifier in the format +_ID#XXXXXXXXXX_, which can be used in other commands expecting a source address. ++ +The *-v* option enables a verbose output. In this case, +extra caption lines are shown as a reminder of the meanings of the columns. ++ +An example report is: ++ +---- +Name/IP Address NP NR Span Frequency Freq Skew Offset Std Dev +=============================================================================== +ntp1.example.net 11 5 46m -0.001 0.045 1us 25us +---- ++ +The columns are as follows: ++ +*Name/IP Address*::: +This is the name or IP address of the NTP server (or peer) or reference ID of the +reference clock to which the rest of the line relates. +*NP*::: +This is the number of sample points currently being retained for the server. +The drift rate and current offset are estimated by performing a linear +regression through these points. +*NR*::: +This is the number of runs of residuals having the same sign following the +last regression. If this number starts to become too small relative to the +number of samples, it indicates that a straight line is no longer a good fit +to the data. If the number of runs is too low, *chronyd* discards older +samples and re-runs the regression until the number of runs becomes +acceptable. +*Span*::: +This is the interval between the oldest and newest samples. If no unit is +shown the value is in seconds. In the example, the interval is 46 minutes. +*Frequency*::: +This is the estimated residual frequency for the server, in parts per +million. In this case, the computer's clock is estimated to be running 1 part +in 10^9 slow relative to the server. +*Freq Skew*::: +This is the estimated error bounds on *Freq* (again in parts per million). +*Offset*::: +This is the estimated offset of the source. +*Std Dev*::: +This is the estimated sample standard deviation. + +[[selectdata]]*selectdata* [*-a*] [*-v*]:: +The *selectdata* command displays information specific to the selection of time +sources. If the *-a* option is specified, all sources are displayed, including +those that do not have a known address yet. With the *-v* option, extra caption +lines are shown as a reminder of the meanings of the columns. ++ +An example of the output is shown below. ++ +---- +S Name/IP Address Auth COpts EOpts Last Score Interval Leap +======================================================================= +D ntp1.example.net Y ----- --TR- 4 1.0 -61ms +62ms N +* ntp2.example.net N ----- ----- 0 1.0 -6846us +7305us N ++ ntp3.example.net N ----- ----- 10 1.0 -7381us +7355us N +---- ++ +The columns are as follows: ++ +*S*::: +This column indicates the state of the source after the last source selection. +It is similar to the state reported by the *sources* command, but more +states are reported. +{blank}::: +The following states indicate the source is 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 + <<chrony.conf.adoc#maxdistance,*maxdistance*>> directive). +* _~_ - has a jitter larger than the maximum jitter (configured by the + <<chrony.conf.adoc#maxjitter,*maxjitter*>> directive). +* _w_ - waits for other sources to get out of the _M_ state. +* _S_ - has older measurements than other sources. +* _O_ - has a stratum equal or larger than the orphan stratum (configured by + the <<chrony.conf.adoc#local,*local*>> directive). +* _T_ - does not fully agree with sources that have the *trust* option. +* _x_ - does not agree with other sources (falseticker). +{blank}::: +The following states indicate the source is considered selectable, but it is +not currently used for synchronisation: +* _W_ - waits for other sources to be selectable (required by the + <<chrony.conf.adoc#minsources,*minsources*>> directive, or + the *require* option of another source). +* _P_ - another selectable source is preferred due to the *prefer* option. +* _U_ - waits for a new measurement (after selecting a different best source). +* _D_ - has, or recently had, a root distance which is too large to be combined + with other sources (configured by the + <<chrony.conf.adoc#combinelimit,*combinelimit*>> directive). +{blank}::: +The following states indicate the source is 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). +*Name/IP address*::: +This column shows the name or IP address of the source if it is an NTP server, +or the reference ID if it is a reference clock. +*Auth*::: +This column indicites whether an authentication mechanism is enabled for the +source. _Y_ means yes and _N_ means no. +*COpts*::: +This column displays the configured selection options of the source. +* _N_ indicates the *noselect* option. +* _P_ indicates the *prefer* option. +* _T_ indicates the *trust* option. +* _R_ indicates the *require* option. +*EOpts*::: +This column displays the current effective selection options of the source, +which can be different from the configured options due to the authentication +selection mode (configured by the +<<chrony.conf.adoc#authselectmode,*authselectmode*>> directive). The symbols +are the same as in the *COpts* column. +*Last*::: +This column displays how long ago was the last measurement of the source made +when the selection was performed. +*Score*::: +This column displays the 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. +*Interval*::: +This column displays the lower and upper endpoint of the interval which was +expected to contain the true offset of the local clock considering the root +distance at the time of the selection. +*Leap*::: +This column displays the current leap status of the source. +* _N_ indicates the normal status (no leap second). +* _+_ indicates that a leap second will be inserted at the end of the month. +* _-_ indicates that a leap second will be deleted at the end of the month. +* _?_ indicates the unknown status (i.e. no valid measurement was made). + +[[selectopts]]*selectopts* _address|refid_ [_+|-option_]...:: +The *selectopts* command modifies the configured selection options of an NTP +source specified by IP address (or the _ID#XXXXXXXXXX_ identifier used for +unknown addresses), or a reference clock specified by reference ID as a string. ++ +The selection options can be added with the *+* symbol or removed with the *-* +symbol. The *selectdata* command can be used to verify the configuration. The +modified options will be applied in the next source selection, e.g. when a new +measurement is made, or the *reselect* command is executed. ++ +An example of using this command is shown below. ++ +---- +selectopts 1.2.3.4 -noselect +prefer +selectopts GPS +trust +---- + +[[reselect]]*reselect*:: +To avoid excessive switching between sources, *chronyd* can stay synchronised +to a source even when it is not currently the best one among the available +sources. ++ +The *reselect* command can be used to force *chronyd* to reselect the best +synchronisation source. + +[[reselectdist]]*reselectdist* _distance_:: +The *reselectdist* command sets the reselection distance. It is equivalent to +the <<chrony.conf.adoc#reselectdist,*reselectdist*>> directive in the +configuration file. + +=== NTP sources + +[[activity]]*activity*:: +This command reports the number of servers and peers that are online and +offline. If the *auto_offline* option is used in specifying some of the servers +or peers, the *activity* command can be useful for detecting when all of them +have entered the offline state after the network link has been disconnected. ++ +The report shows the number of servers and peers in 5 states: ++ +*online*::: +the server or peer is currently online (i.e. assumed by *chronyd* to be reachable) +*offline*::: +the server or peer is currently offline (i.e. assumed by *chronyd* to be +unreachable, and no measurements from it will be attempted.) +*burst_online*::: +a burst command has been initiated for the server or peer and is being +performed; after the burst is complete, the server or peer will be returned to +the online state. +*burst_offline*::: +a burst command has been initiated for the server or peer and is being +performed; after the burst is complete, the server or peer will be returned to +the offline state. +*unresolved*::: +the name of the server or peer was not resolved to an address yet; this source is +not visible in the *sources* and *sourcestats* reports. + +[[authdata]]*authdata* [*-a*]:: +The *authdata* command displays information specific to authentication of NTP +sources. If the *-a* option is specified, all sources are displayed, including +those that do not have a known address yet. An example of the output is +shown below. ++ +---- +Name/IP address Mode KeyID Type KLen Last Atmp NAK Cook CLen +========================================================================= +ntp1.example.net NTS 1 15 256 135m 0 0 8 100 +ntp2.example.net SK 30 13 128 - 0 0 0 0 +ntp3.example.net - 0 0 0 - 0 0 0 0 +---- ++ +The columns are as follows: ++ +*Name/IP address*::: +This column shows the name or the IP address of the source. +*Mode*::: +This column shows which mechanism authenticates NTP packets received from the +source. _NTS_ means Network Time Security, _SK_ means a symmetric key, and _-_ +means authentication is disabled. +*KeyID*::: +This column shows an identifier of the key used for authentication. With a +symmetric key, it is the ID from the <<chrony.conf.adoc#keyfile,key file>>. +With NTS, it is a number starting at zero and incremented by one with each +successful key establishment using the NTS-KE protocol, i.e. it shows how many +times the key establishment was performed with this source. +*Type*::: +This columns shows an identifier of the algorithm used for authentication. +With a symmetric key, it is the hash function or cipher specified in the key +file. With NTS, it is an authenticated encryption with associated data (AEAD) +algorithm, which is negotiated in the NTS-KE protocol. The following values can +be reported: +* 1: MD5 +* 2: SHA1 +* 3: SHA256 +* 4: SHA384 +* 5: SHA512 +* 6: SHA3-224 +* 7: SHA3-256 +* 8: SHA3-384 +* 9: SHA3-512 +* 10: TIGER +* 11: WHIRLPOOL +* 13: AES128 +* 14: AES256 +* 15: AEAD-AES-SIV-CMAC-256 +* 30: AEAD-AES-128-GCM-SIV +*KLen*::: +This column shows the length of the key in bits. +*Last*::: +This column shows how long ago the last successful key establishment was +performed. It is in seconds, or letters _m_, _h_, _d_ or _y_ indicate minutes, +hours, days, or years. +*Atmp*::: +This column shows the number of attempts to perform the key establishment since +the last successful key establishment. A number larger than 1 indicates a +problem with the network or server. +*NAK*::: +This column shows whether an NTS NAK was received since the last request. +A NAK indicates that authentication failed on the server side due to +*chronyd* using a cookie which is no longer valid and that it needs to perform +the key establishment again in order to get new cookies. +*Cook*::: +This column shows the number of NTS cookies that *chronyd* currently has. If +the key establishment was successful, a number smaller than 8 indicates a +problem with the network or server. +*CLen*::: +This column shows the length in bytes of the NTS cookie which will be used in +the next request. + +[[ntpdata]]*ntpdata* [_address_]:: +The *ntpdata* command displays the last valid measurement and other +NTP-specific information about the specified NTP source, or all NTP sources +(with a known address) if no address was specified. An example of the output is +shown below. ++ +---- +Remote address : 203.0.113.15 (CB00710F) +Remote port : 123 +Local address : 203.0.113.74 (CB00714A) +Leap status : Normal +Version : 4 +Mode : Server +Stratum : 1 +Poll interval : 10 (1024 seconds) +Precision : -24 (0.000000060 seconds) +Root delay : 0.000015 seconds +Root dispersion : 0.000015 seconds +Reference ID : 47505300 (GPS) +Reference time : Fri Nov 25 15:22:12 2016 +Offset : -0.000060878 seconds +Peer delay : 0.000175634 seconds +Peer dispersion : 0.000000681 seconds +Response time : 0.000053050 seconds +Jitter asymmetry: +0.00 +NTP tests : 111 111 1111 +Interleaved : No +Authenticated : No +TX timestamping : Kernel +RX timestamping : Kernel +Total TX : 24 +Total RX : 24 +Total valid RX : 24 +Total good RX : 22 +---- ++ +The fields are explained as follows: ++ +*Remote address*::: +The IP address of the NTP server or peer, and the corresponding reference ID. +*Remote port*::: +The UDP port number to which the request was sent. The standard NTP port is +123. +*Local address*::: +The local IP address which received the response, and the corresponding +reference ID. +*Leap status*::: +*Version*::: +*Mode*::: +*Stratum*::: +*Poll interval*::: +*Precision*::: +*Root delay*::: +*Root dispersion*::: +*Reference ID*::: +*Reference time*::: +The NTP values from the last valid response. +*Offset*::: +*Peer delay*::: +*Peer dispersion*::: +The measured values. +*Response time*::: +The time the server or peer spent in processing of the request and waiting +before sending the response. +*Jitter asymmetry*::: +The estimated asymmetry of network jitter on the path to the source. 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. +*NTP tests*::: +Results of RFC 5905 tests 1 through 3, 5 through 7, and tests for maximum +delay, delay ratio, delay dev ratio (or delay quantile), and synchronisation +loop. +*Interleaved*::: +This shows if the response was in the interleaved mode. +*Authenticated*::: +This shows if the response was authenticated. +*TX timestamping*::: +The source of the local transmit timestamp. Valid values are _Daemon_, +_Kernel_, and _Hardware_. +*RX timestamping*::: +The source of the local receive timestamp. +*Total TX*::: +The number of packets sent to the source. +*Total RX*::: +The number of all packets received from the source. +*Total valid RX*::: +The number of packets which passed the first two groups of NTP tests. +*Total good RX*::: +The number of packets which passed all three groups of NTP tests, i.e. the NTP +measurement was accepted. + +[[add_peer]]*add peer* _name_ [_option_]...:: +The *add peer* command allows a new NTP peer to be added whilst +*chronyd* is running. ++ +Following the words *add peer*, the syntax of the following +parameters and options is identical to that for the +<<chrony.conf.adoc#peer,*peer*>> directive in the configuration file. ++ +An example of using this command is shown below. ++ +---- +add peer ntp1.example.net minpoll 6 maxpoll 10 key 25 +---- + +[[add_pool]]*add pool* _name_ [_option_]...:: +The *add pool* command allows a pool of NTP servers to be added whilst +*chronyd* is running. ++ +Following the words *add pool*, the syntax of the following parameters and +options is identical to that for the <<chrony.conf.adoc#pool,*pool*>> +directive in the configuration file. ++ +An example of using this command is shown below: ++ +---- +add pool ntp1.example.net maxsources 3 iburst +---- + +[[add_server]]*add server* _name_ [_option_]...:: +The *add server* command allows a new NTP server to be added whilst +*chronyd* is running. ++ +Following the words *add server*, the syntax of the following parameters and +options is identical to that for the <<chrony.conf.adoc#server,*server*>> +directive in the configuration file. ++ +An example of using this command is shown below: ++ +---- +add server ntp1.example.net minpoll 6 maxpoll 10 key 25 +---- + +[[delete]]*delete* _address_:: +The *delete* command allows an NTP server or peer to be removed +from the current set of sources. + +[[burst]] +*burst* _good_/_max_ [_mask_/_masked-address_]:: +*burst* _good_/_max_ [_masked-address_/_masked-bits_]:: +*burst* _good_/_max_ [_address_]:: +The *burst* command tells *chronyd* to make a set of measurements to each of +its NTP sources over a short duration (rather than the usual periodic +measurements that it makes). After such a burst, *chronyd* will revert to the +previous state for each source. This might be either online, if the source was +being periodically measured in the normal way, or offline, if the source had +been indicated as being offline. (A source can be switched between the online +and offline states with the <<online,*online*>> and <<offline,*offline*>> +commands.) ++ +The _mask_ and _masked-address_ arguments are optional, in which case *chronyd* +will initiate a burst for all of its currently defined sources. ++ +The arguments have the following meaning and format: ++ +_good_::: +This defines the number of good measurements that *chronyd* will want to +obtain from each source. A measurement is good if it passes certain tests, +for example, the round trip time to the source must be acceptable. (This +allows *chronyd* to reject measurements that are likely to be bogus.) +_max_::: +This defines the maximum number of measurements that *chronyd* will attempt +to make, even if the required number of good measurements has not been +obtained. +_mask_::: +This is an IP address with which the IP address of each of *chronyd*'s +sources is to be masked. +_masked-address_::: +This is an IP address. If the masked IP address of a source matches this +value then the burst command is applied to that source. +_masked-bits_::: +This can be used with _masked-address_ for CIDR notation, which is a shorter +alternative to the form with mask. +_address_::: +This is an IP address or a hostname. The burst command is applied only to +that source. +{blank}:: ++ +If no _mask_ or _masked-address_ arguments are provided, every source will be +matched. ++ +An example of the two-argument form of the command is: ++ +---- +burst 2/10 +---- ++ +This will cause *chronyd* to attempt to get two good measurements from each +source, stopping after two have been obtained, but in no event will it try more +than ten probes to the source. ++ +Examples of the four-argument form of the command are: ++ +---- +burst 2/10 255.255.0.0/1.2.0.0 +burst 2/10 2001:db8:789a::/48 +---- ++ +In the first case, the two out of ten sampling will only be applied to sources +whose IPv4 addresses are of the form _1.2.x.y_, where _x_ and _y_ are +arbitrary. In the second case, the sampling will be applied to sources whose +IPv6 addresses have first 48 bits equal to _2001:db8:789a_. ++ +Example of the three-argument form of the command is: ++ +---- +burst 2/10 ntp1.example.net +---- + +[[maxdelay]]*maxdelay* _address_ _delay_:: +This allows the *maxdelay* option for one of the sources to be modified, in the +same way as specifying the *maxdelay* option for the +<<chrony.conf.adoc#server,*server*>> directive in the configuration file. + +[[maxdelaydevratio]]*maxdelaydevratio* _address_ _ratio_:: +This allows the *maxdelaydevratio* option for one of the sources to be +modified, in the same way as specifying the *maxdelaydevratio* option for the +<<chrony.conf.adoc#server,*server*>> directive in the configuration file. + +[[maxdelayratio]]*maxdelayratio* _address_ _ratio_:: +This allows the *maxdelayratio* option for one of the sources to be modified, +in the same way as specifying the *maxdelayratio* option for the +<<chrony.conf.adoc#server,*server*>> directive in the configuration file. + +[[maxpoll]]*maxpoll* _address_ _maxpoll_:: +The *maxpoll* command is used to modify the maximum polling interval for one of +the current set of sources. It is equivalent to the *maxpoll* option in the +<<chrony.conf.adoc#server,*server*>> directive in the configuration file. ++ +Note that the new maximum polling interval only takes effect after the next +measurement has been made. + +[[minpoll]]*minpoll* _address_ _minpoll_:: +The *minpoll* command is used to modify the minimum polling interval for one of +the current set of sources. It is equivalent to the *minpoll* option in the +<<chrony.conf.adoc#server,*server*>> directive in the configuration file. ++ +Note that the new minimum polling interval only takes effect after the next +measurement has been made. + +[[minstratum]]*minstratum* _address_ _minstratum_:: +The *minstratum* command is used to modify the minimum stratum for one of the +current set of sources. It is equivalent to the *minstratum* option in the +<<chrony.conf.adoc#server,*server*>> directive in the configuration file. + +[[offline]] +*offline* [_address_]:: +*offline* [_masked-address_/_masked-bits_]:: +*offline* [_mask_/_masked-address_]:: +The *offline* command is used to warn *chronyd* that the network connection to +a particular host or hosts is about to be lost, e.g. on computers with +intermittent connection to their time sources. ++ +Another case where *offline* could be used is where a computer serves time to a +local group of computers, and has a permanent connection to true time servers +outside the organisation. However, the external connection is heavily loaded at +certain times of the day and the measurements obtained are less reliable at +those times. In this case, it is probably most useful to determine the +gain or loss rate during the quiet periods and let the whole network coast through +the loaded periods. The *offline* and *online* commands can be used to achieve +this. ++ +There are four forms of the *offline* command. The first form is a wildcard, +meaning all sources (including sources that do not have a known address yet). +The second form allows an IP address mask and a masked +address to be specified. The third form uses CIDR notation. The fourth form +uses an IP address or a hostname. These forms are illustrated below. ++ +---- +offline +offline 255.255.255.0/1.2.3.0 +offline 2001:db8:789a::/48 +offline ntp1.example.net +---- ++ +The second form means that the *offline* command is to be applied to any source +whose IPv4 address is in the _1.2.3_ subnet. (The host's address is logically +and-ed with the mask, and if the result matches the _masked-address_ the host +is processed.) The third form means that the command is to be applied to all +sources whose IPv6 addresses have their first 48 bits equal to _2001:db8:789a_. The +fourth form means that the command is to be applied only to that one source. ++ +The wildcard form of the address is equivalent to: ++ +---- +offline 0.0.0.0/0.0.0.0 +offline ::/0 +---- + +[[online]] +*online* [_address_]:: +*online* [_masked-address_/_masked-bits_]:: +*online* [_mask_/_masked-address_]:: +The *online* command is opposite in function to the <<offline,*offline*>> +command. It is used to advise *chronyd* that network connectivity to a +particular source or sources has been restored. ++ +The syntax is identical to that of the <<offline,*offline*>> command. + +[[onoffline]] +*onoffline*:: +The *onoffline* command tells *chronyd* to switch all sources that have a known +address to the online or +offline status according to the current network configuration. A source is +considered online if it is possible to send requests to it, i.e. a network +route to the source is present. + +[[polltarget]]*polltarget* _address_ _polltarget_:: +The *polltarget* command is used to modify the poll target for one of the +current set of sources. It is equivalent to the *polltarget* option in the +<<chrony.conf.adoc#server,*server*>> directive in the configuration file. + +[[refresh]]*refresh*:: +The *refresh* command can be used to force *chronyd* to resolve the names of +configured NTP sources to IP addresses again and replace any addresses missing +in the list of resolved addresses. ++ +Sources that stop responding are replaced with newly resolved addresses +automatically after 8 polling intervals. This command can be used to replace +them immediately, e.g. after suspending and resuming the machine in a different +network. ++ +Note that with pools which have more than 16 addresses, or not all IPv4 or IPv6 +addresses are included in a single DNS response (e.g. pool.ntp.org), this +command might replace the addresses even if they are still in the pool. + +[[reload]]*reload* *sources*:: +The *reload sources* command causes *chronyd* to re-read all _*.sources_ files +from the directories specified by the +<<chrony.conf.adoc#sourcedir,*sourcedir*>> directive. ++ +Note that modified sources (e.g. specified with a new option) are not modified +in memory. They are removed and added again, which causes them to lose old +measurements and reset the selection state. + +[[sourcename]]*sourcename* _address_:: +The *sourcename* command prints the original hostname or address that was +specified for an NTP source in the configuration file, or the *add* command. +This command is an alternative to the *-N* option, which can be useful in +scripts. ++ +Note that different NTP sources can share the same name, e.g. servers from a +pool. + +=== Manual time input + +[[manual]] +*manual* *on*:: +*manual* *off*:: +*manual* *delete* _index_:: +*manual* *list*:: +*manual* *reset*:: +The manual command enables and disables use of the <<settime,*settime*>> +command, and is used to modify the behaviour of the manual clock driver. ++ +The *on* form of the command enables use of the *settime* command. ++ +The *off* form of the command disables use of the *settime* command. ++ +The *list* form of the command lists all the samples currently stored in +*chronyd*. The output is illustrated below. ++ +---- +210 n_samples = 1 +# Date Time(UTC) Slewed Original Residual +==================================================== + 0 27Jan99 22:09:20 0.00 0.97 0.00 +---- ++ +The columns are as as follows: ++ +. The sample index (used for the *manual delete* command). +. The date and time of the sample. +. The system clock error when the timestamp was entered, adjusted to allow + for changes made to the system clock since. +. The system clock error when the timestamp was entered, as it originally was + (without allowing for changes to the system clock since). +. The regression residual at this point, in seconds. This allows '`outliers`' + to be easily spotted, so that they can be deleted using the *manual delete* + command. +{blank}:: ++ +The *delete* form of the command deletes a single sample. The parameter is the +index of the sample, as shown in the first column of the output from *manual +list*. Following deletion of the data point, the current error and drift rate +are re-estimated from the remaining data points and the system clock trimmed if +necessary. This option is intended to allow '`outliers`' to be discarded, i.e. +samples where the administrator realises they have entered a very poor +timestamp. ++ +The *reset* form of the command deletes all samples at once. The system clock +is left running as it was before the command was entered. + +[[settime]]*settime* _time_:: +The *settime* command allows the current time to be entered manually, if this +option has been configured into *chronyd*. (It can be configured either with +the <<chrony.conf.adoc#manual,*manual*>> directive in the configuration file, +or with the <<manual,*manual*>> command of *chronyc*.) ++ +It should be noted that the computer's sense of time will only be as accurate +as the reference you use for providing this input (e.g. your watch), as well as +how well you can time the press of the return key. ++ +Providing your computer's time zone is set up properly, you will be able to +enter a local time (rather than UTC). ++ +The response to a successful *settime* command indicates the amount that the +computer's clock was wrong. It should be apparent from this if you have entered +the time wrongly, e.g. with the wrong time zone. ++ +The rate of drift of the system clock is estimated by a regression process +using the entered measurement and all previous measurements entered during the +present run of *chronyd*. However, the entered measurement is used for +adjusting the current clock offset (rather than the estimated intercept from +the regression, which is ignored). Contrast what happens with the +<<manual,*manual delete*>> command, where the intercept is used to set the +current offset (since there is no measurement that has just been entered in +that case). ++ +The time is parsed by the public domain _getdate_ algorithm. Consequently, you +can only specify time to the nearest second. ++ +Examples of inputs that are valid are shown below: ++ +---- +settime 16:30 +settime 16:30:05 +settime Nov 21, 2015 16:30:05 +---- ++ +For a full description of getdate, see the getdate documentation +(bundled, for example, with the source for GNU tar). + +=== NTP access + +[[accheck]]*accheck* _address_:: +This command allows you to check whether client NTP access is allowed from a +particular host. ++ +Examples of use, showing a named host and a numeric IP address, are as follows: ++ +---- +accheck ntp1.example.net +accheck 1.2.3.4 +accheck 2001:db8::1 +---- ++ +This command can be used to examine the effect of a series of *allow*, *allow +all*, *deny*, and *deny all* commands specified either via *chronyc*, or in +*chronyd*'s configuration file. + +[[clients]]*clients* [*-p* _packets_] [*-k*] [*-r*]:: +This command shows a list of clients that have accessed the server, through +the NTP, command, or NTS-KE port. It does not include accesses over the Unix +domain command socket. ++ +The *-p* option specifies the minimum number of received NTP or command +packets, or accepted NTS-KE connections, needed to include a client in the +list. The default value is 0, i.e. all clients are reported. With the *-k* +option the last four columns will show the NTS-KE accesses instead of command +accesses. If the *-r* option is specified, *chronyd* will reset the counters of +received and dropped packets or connections after reporting the current values. ++ +An example of the output is: ++ +---- +Hostname NTP Drop Int IntL Last Cmd Drop Int Last +=============================================================================== +localhost 2 0 2 - 133 15 0 -1 7 +ntp1.example.net 12 0 6 - 23 0 0 - - +---- ++ +Each row shows the data for a single host. Only hosts that have passed the host +access checks (set with the <<allow,*allow*>>, <<deny,*deny*>>, +<<cmdallow,*cmdallow*>> and <<cmddeny,*cmddeny*>> commands or configuration +file directives) are logged. The intervals are displayed as a power of 2 in +seconds. ++ +The columns are as follows: ++ +. The hostname of the client. +. The number of NTP packets received from the client. +. The number of NTP packets dropped to limit the response rate. +. The average interval between NTP packets. +. The average interval between NTP packets after limiting the response rate. +. Time since the last NTP packet was received +. The number of command packets or NTS-KE connections received/accepted from + the client. +. The number of command packets or NTS-KE connections dropped to limit the + response rate. +. The average interval between command packets or NTS-KE connections. +. Time since the last command packet or NTS-KE connection was + received/accepted. + +[[serverstats]]*serverstats*:: +The *serverstats* command displays NTP and command server statistics. ++ +An example of the output is shown below. ++ +---- +NTP packets received : 1598 +NTP packets dropped : 8 +Command packets received : 19 +Command packets dropped : 0 +Client log records dropped : 0 +NTS-KE connections accepted: 3 +NTS-KE connections dropped : 0 +Authenticated NTP packets : 189 +Interleaved NTP packets : 43 +NTP timestamps held : 44 +NTP timestamp span : 120 +NTP daemon RX timestamps : 0 +NTP daemon TX timestamps : 1537 +NTP kernel RX timestamps : 1590 +NTP kernel TX timestamps : 43 +NTP hardware RX timestamps : 0 +NTP hardware TX timestamps : 0 +---- ++ +The fields have the following meaning: ++ +*NTP packets received*::: +The number of valid NTP requests received by the server. +*NTP packets dropped*::: +The number of NTP requests dropped by the server due to rate limiting +(configured by the <<chrony.conf.adoc#ratelimit,*ratelimit*>> directive). +*Command packets received*::: +The number of command requests received by the server. +*Command packets dropped*::: +The number of command requests dropped by the server due to rate limiting +(configured by the <<chrony.conf.adoc#cmdratelimit,*cmdratelimit*>> directive). +*Client log records dropped*::: +The number of client log records dropped by the server to limit the memory use +(configured by the <<chrony.conf.adoc#clientloglimit,*clientloglimit*>> +directive). +*NTS-KE connections accepted*::: +The number of NTS-KE connections accepted by the server. +*NTS-KE connections dropped*::: +The number of NTS-KE connections dropped by the server due to rate limiting +(configured by the <<chrony.conf.adoc#ntsratelimit,*ntsratelimit*>> directive). +*Authenticated NTP packets*::: +The number of received NTP requests that were authenticated (with a symmetric +key or NTS). +*Interleaved NTP packets*::: +The number of received NTP requests that were detected to be in the interleaved +mode. +*NTP timestamps held*::: +The number of pairs of receive and transmit timestamps that the server is +currently holding in memory for clients using the interleaved mode. +*NTP timestamp span*::: +The interval (in seconds) covered by the currently held NTP timestamps. +*NTP daemon RX timestamps*::: +The number of NTP responses which included a receive timestamp captured by the +daemon. +*NTP daemon TX timestamps*::: +The number of NTP responses which included a transmit timestamp captured by the +daemon. +*NTP kernel RX timestamps*::: +The number of NTP responses which included a receive timestamp captured by the +kernel. +*NTP kernel TX timestamps*::: +The number of NTP responses (in the interleaved mode) which included a transmit +timestamp captured by the kernel. +*NTP hardware RX timestamps*::: +The number of NTP responses which included a receive timestamp captured by the +NIC. +*NTP hardware TX timestamps*::: +The number of NTP responses (in the interleaved mode) which included a transmit +timestamp captured by the NIC. + +[[allow]]*allow* [*all*] [_subnet_]:: +The effect of the allow command is identical to the +<<chrony.conf.adoc#allow,*allow*>> directive in the configuration file. ++ +The syntax is illustrated in the following examples: ++ +---- +allow 1.2.3.4 +allow all 3.4.5.0/24 +allow 2001:db8:789a::/48 +allow 0/0 +allow ::/0 +allow +allow all +---- + +[[deny]]*deny* [*all*] [_subnet_]:: +The effect of the allow command is identical to the +<<chrony.conf.adoc#deny,*deny*>> directive in the configuration file. ++ +The syntax is illustrated in the following examples: ++ +---- +deny 1.2.3.4 +deny all 3.4.5.0/24 +deny 2001:db8:789a::/48 +deny 0/0 +deny ::/0 +deny +deny all +---- + +[[local]] +*local* [_option_]...:: +*local* *off*:: +The *local* command allows *chronyd* to be told that it is to appear as a +reference source, even if it is not itself properly synchronised to an external +source. This can be used on isolated networks, to allow a computer to be the +primary time server for other computers. ++ +The first form enables the local reference mode on the host. The syntax is +identical to the <<chrony.conf.adoc#local,*local*>> directive in the +configuration file. ++ +The second form disables the local reference mode. + +[[smoothing]]*smoothing*:: +The *smoothing* command displays the current state of the NTP server time +smoothing, which can be enabled with the +<<chrony.conf.adoc#smoothtime,*smoothtime*>> directive. An example of the +output is shown below. ++ +---- +Active : Yes +Offset : +1.000268817 seconds +Frequency : -0.142859 ppm +Wander : -0.010000 ppm per second +Last update : 17.8 seconds ago +Remaining time : 19988.4 seconds +---- ++ +The fields are explained as follows: ++ +*Active*::: +This shows if the server time smoothing is currently active. Possible values +are _Yes_ and _No_. If the *leaponly* option is included in the *smoothtime* +directive, _(leap second only)_ will be shown on the line. +*Offset*::: +This is the current offset applied to the time sent to NTP clients. Positive +value means the clients are getting time that's ahead of true time. +*Frequency*::: +The current frequency offset of the served time. Negative value means the +time observed by clients is running slower than true time. +*Wander*::: +The current frequency wander of the served time. Negative value means the +time observed by clients is slowing down. +*Last update*::: +This field shows how long ago the time smoothing process was updated, e.g. +*chronyd* accumulated a new measurement. +*Remaining time*::: +The time it would take for the smoothing process to get to zero offset and +frequency if there were no more updates. + +[[smoothtime]] +*smoothtime* *activate*:: +*smoothtime* *reset*:: +The *smoothtime* command can be used to activate or reset the server time +smoothing process if it is configured with the +<<chrony.conf.adoc#smoothtime,*smoothtime*>> directive. + +=== Monitoring access + +[[cmdaccheck]]*cmdaccheck* _address_:: +This command is similar to the <<accheck,*accheck*>> command, except that it is +used to check whether monitoring access is permitted from a named host. ++ +Examples of use are as follows: ++ +---- +cmdaccheck ntp1.example.net +cmdaccheck 1.2.3.4 +cmdaccheck 2001:db8::1 +---- + +[[cmdallow]]*cmdallow* [*all*] [_subnet_]:: +This is similar to the <<allow,*allow*>> command, except that it is used to +allow particular hosts or subnets to use *chronyc* to monitor with *chronyd* on +the current host. + +[[cmddeny]]*cmddeny* [*all*] [_subnet_]:: +This is similar to the <<deny,*deny*>> command, except that it is used to allow +particular hosts or subnets to use *chronyc* to monitor *chronyd* on the +current host. + +=== Real-time clock (RTC) + +[[rtcdata]]*rtcdata*:: +The *rtcdata* command displays the current RTC parameters. ++ +An example output is shown below. ++ +---- +RTC ref time (GMT) : Sat May 30 07:25:56 2015 +Number of samples : 10 +Number of runs : 5 +Sample span period : 549 +RTC is fast by : -1.632736 seconds +RTC gains time at : -107.623 ppm +---- ++ +The fields have the following meaning: ++ +*RTC ref time (GMT)*::: +This is the RTC reading the last time its error was measured. +*Number of samples*::: +This is the number of previous measurements being used to determine the RTC +gain or loss rate. +*Number of runs*::: +This is the number of runs of residuals of the same sign following the +regression fit for (RTC error) versus (RTC time). A value which is small +indicates that the measurements are not well approximated by a linear model, +and that the algorithm will tend to delete the older measurements to improve +the fit. +*Sample span period*::: +This is the period that the measurements span (from the oldest to the +newest). Without a unit the value is in seconds; suffixes _m_ for minutes, +_h_ for hours, _d_ for days or _y_ for years can be used. +*RTC is fast by*::: +This is the estimate of how many seconds fast the RTC when it thought +the time was at the reference time (above). If this value is large, you +might (or might not) want to use the <<trimrtc,*trimrtc*>> command to bring the +RTC into line with the system clock. (Note, a large error will not affect +*chronyd*'s operation, unless it becomes so big as to start causing rounding +errors.) +*RTC gains time at*::: +This is the amount of time gained (positive) or lost (negative) by the real +time clock for each second that it ticks. It is measured in parts per +million. So if the value shown was +1, suppose the RTC was exactly right when +it crosses a particular second boundary. Then it would be 1 microsecond fast +when it crosses its next second boundary. + +[[trimrtc]]*trimrtc*:: +The *trimrtc* command is used to correct the system's real-time clock (RTC) to +the main system clock. It has no effect if the error between the two clocks is +currently estimated at less than a second. ++ +The command takes no arguments. It performs the following steps (if the RTC is +more than 1 second away from the system clock): ++ +. Remember the currently estimated gain or loss rate of the RTC and flush the + previous measurements. +. Step the real-time clock to bring it within a second of the system clock. +. Make several measurements to accurately determine the new offset between + the RTC and the system clock (i.e. the remaining fraction of a second + error). +. Save the RTC parameters to the RTC file (specified with the + <<chrony.conf.adoc#rtcfile,*rtcfile*>> directive in the configuration file). +{blank}:: ++ +The last step is done as a precaution against the computer suffering a power +failure before either the daemon exits or the <<writertc,*writertc*>> command +is issued. ++ +*chronyd* will still work perfectly well both whilst operating and across +machine reboots even if the *trimrtc* command is never used (and the RTC is +allowed to drift away from true time). The *trimrtc* command is provided as a +method by which it can be corrected, in a manner compatible with *chronyd* +using it to maintain accurate time across machine reboots. ++ +The *trimrtc* command can be executed automatically by *chronyd* with the +<<chrony.conf.adoc#rtcautotrim,*rtcautotrim*>> directive in the configuration +file. + +[[writertc]]*writertc*:: +The *writertc* command writes the currently estimated error and gain or loss rate +parameters for the RTC to the RTC file (specified with the +<<chrony.conf.adoc#rtcfile,*rtcfile*>> directive). This information is also +written automatically when *chronyd* is killed (by the SIGHUP, SIGINT, SIGQUIT +or SIGTERM signals) or when the <<trimrtc,*trimrtc*>> command is issued. + +=== Other daemon commands + +[[cyclelogs]]*cyclelogs*:: +The *cyclelogs* command causes all of *chronyd*'s open log files to be closed +and re-opened. This allows them to be renamed so that they can be periodically +purged. An example of how to do this is shown below. ++ +---- +# mv /var/log/chrony/measurements.log /var/log/chrony/measurements1.log +# chronyc cyclelogs +# rm /var/log/chrony/measurements1.log +---- + +[[dump]]*dump*:: +The *dump* command causes *chronyd* to write its current history of +measurements for each of its sources to dump files in the directory specified +in the configuration file by the <<chrony.conf.adoc#dumpdir,*dumpdir*>> +directive and also write server NTS keys and client NTS cookies to the +directory specified by the <<chrony.conf.adoc#ntsdumpdir1,*ntsdumpdir*>> +directive. Note that *chronyd* does this automatically when it exits. This +command is mainly useful for inspection whilst *chronyd* is running. + +[[rekey]]*rekey*:: +The *rekey* command causes *chronyd* to re-read the key file specified in the +configuration file by the <<chrony.conf.adoc#keyfile,*keyfile*>> directive. It +also re-reads the server NTS keys if +<<chrony.conf.adoc#ntsdumpdir2,*ntsdumpdir*>> is specified and +<<chrony.conf.adoc#ntsrotate,automatic rotation>> is disabled in the +configuration file. + +[[reset]]*reset* *sources*:: +The *reset sources* command causes *chronyd* to drop all measurements and +switch to the unsynchronised state. This command can help *chronyd* with +recovery when the measurements are known to be no longer valid or accurate, +e.g. due to moving the computer to a different network, or resuming the +computer from a low-power state (which resets the system clock). *chronyd* will +drop the measurements automatically when it detects the clock has made an +unexpected jump, but the detection is not completely reliable. + +[[shutdown]]*shutdown*:: +The *shutdown* command causes *chronyd* to exit. This is equivalent to sending +the process the SIGTERM signal. + +=== Client commands + +[[dns]]*dns* _option_:: +The *dns* command configures how hostnames and IP addresses are resolved in +*chronyc*. IP addresses can be resolved to hostnames when printing results of +<<sources,*sources*>>, <<sourcestats,*sourcestats*>>, <<tracking,*tracking*>> +and <<clients,*clients*>> commands. Hostnames are resolved in commands that +take an address as argument. ++ +There are five options: ++ +*dns -n*::: +Disables resolving IP addresses to hostnames. Raw IP addresses will be +displayed. +*dns +n*::: +Enables resolving IP addresses to hostnames. This is the default unless +*chronyc* was started with *-n* option. +*dns -4*::: +Resolves hostnames only to IPv4 addresses. +*dns -6*::: +Resolves hostnames only to IPv6 addresses. +*dns -46*::: +Resolves hostnames to both address families. This is the default behaviour +unless *chronyc* was started with the *-4* or *-6* option. + +[[timeout]]*timeout* _timeout_:: +The *timeout* command sets the initial timeout for *chronyc* requests in +milliseconds. If no response is received from *chronyd*, the timeout is doubled +and the request is resent. The maximum number of retries is configured with the +<<retries,*retries*>> command. ++ +By default, the timeout is 1000 milliseconds. + +[[retries]]*retries* _retries_:: +The *retries* command sets the maximum number of retries for *chronyc* requests +before giving up. The response timeout is controlled by the +<<timeout,*timeout*>> command. ++ +The default is 2. + +[[keygen]]*keygen* [_id_ [_type_ [_bits_]]]:: +The *keygen* command generates a key that can be added to the +key file (specified with the <<chrony.conf.adoc#keyfile,*keyfile*>> directive) +to allow NTP authentication between server and client, or peers. The key is +generated from the _/dev/urandom_ device and it is printed to standard output. ++ +The command has three optional arguments. The first argument is the key number +(by default 1), which will be specified with the *key* option of the *server* +or *peer* directives in the configuration file. The second argument is the name +of the hash function or cipher (by default SHA1, or MD5 if SHA1 is not +available). The third argument is the length of the key in bits if a hash +function was selected, between 80 and 4096 bits (by default 160 bits). ++ +An example is: ++ +---- +keygen 73 SHA1 256 +---- ++ +which generates a 256-bit SHA1 key with number 73. The printed line should +then be securely transferred and added to the key files on both server and +client, or peers. A different key should be generated for each client or peer. ++ +An example using the AES128 cipher is: ++ +---- +keygen 151 AES128 +---- + +[[exit]]*exit*:: +[[quit]]*quit*:: +The *exit* and *quit* commands exit from *chronyc* and return the user to the shell. + +[[help]]*help*:: +The *help* command displays a summary of the commands and their arguments. + +== SEE ALSO + +<<chrony.conf.adoc#,*chrony.conf(5)*>>, <<chronyd.adoc#,*chronyd(8)*>> + +== BUGS + +For instructions on how to report bugs, please visit +https://chrony-project.org/. + +== AUTHORS + +chrony was written by Richard Curnow, Miroslav Lichvar, and others. diff --git a/doc/chronyc.man.in b/doc/chronyc.man.in new file mode 100644 index 0000000..4541fc6 --- /dev/null +++ b/doc/chronyc.man.in @@ -0,0 +1,2756 @@ +'\" t +.\" Title: chronyc +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 2.0.20 +.\" Date: 2023-12-05 +.\" Manual: User manual +.\" Source: chrony @CHRONY_VERSION@ +.\" Language: English +.\" +.TH "CHRONYC" "1" "2023-12-05" "chrony @CHRONY_VERSION@" "User manual" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +chronyc \- command\-line interface for chrony daemon +.SH "SYNOPSIS" +.sp +\fBchronyc\fP [\fIOPTION\fP]... [\fICOMMAND\fP]... +.SH "DESCRIPTION" +.sp +\fBchronyc\fP is a command\-line interface program which can be used to monitor +\fBchronyd\fP\*(Aqs performance and to change various operating parameters whilst it is +running. +.sp +If no commands are specified on the command line, \fBchronyc\fP will expect input +from the user. The prompt \fIchronyc>\fP will be displayed when it is being run +from a terminal. If \fBchronyc\fP\*(Aqs input or output are redirected from or to a file, +the prompt will not be shown. +.sp +There are two ways \fBchronyc\fP can access \fBchronyd\fP. One is the Internet +Protocol (IPv4 or IPv6) and the other is a Unix domain socket, which is +accessible locally by the root or \fIchrony\fP user. By default, \fBchronyc\fP first +tries to connect to the Unix domain socket. The compiled\-in default path is +\fI@CHRONYRUNDIR@/chronyd.sock\fP. If that fails (e.g. because \fBchronyc\fP is +running under a non\-root user), it will try to connect to 127.0.0.1 and then +::1. +.sp +Only the following monitoring commands, which do not affect the behaviour of +\fBchronyd\fP, are allowed from the network: \fBactivity\fP, \fBmanual list\fP, +\fBrtcdata\fP, \fBsmoothing\fP, \fBsourcename\fP, \fBsources\fP, \fBsourcestats\fP, \fBtracking\fP, +\fBwaitsync\fP. The +set of hosts from which \fBchronyd\fP will accept these commands can be configured +with the \fBcmdallow\fP directive in the \fBchronyd\fP\*(Aqs +configuration file or the \fBcmdallow\fP command in \fBchronyc\fP. By +default, the commands are accepted only from localhost (127.0.0.1 or ::1). +.sp +All other commands are allowed only through the Unix domain socket. When sent +over the network, \fBchronyd\fP will respond with a \(oqNot authorised\(cq error, even +if it is from localhost. +.sp +Having full access to \fBchronyd\fP via \fBchronyc\fP is more or less equivalent to +being able to modify the \fBchronyd\fP\*(Aqs configuration file and restart it. +.SH "OPTIONS" +.sp +\fB\-4\fP +.RS 4 +With this option hostnames will be resolved only to IPv4 addresses. +.RE +.sp +\fB\-6\fP +.RS 4 +With this option hostnames will be resolved only to IPv6 addresses. +.RE +.sp +\fB\-n\fP +.RS 4 +This option disables resolving of IP addresses to hostnames, e.g. to avoid slow +DNS lookups. Long addresses will not be truncated to fit into the column. +.RE +.sp +\fB\-N\fP +.RS 4 +This option enables printing of original hostnames or IP addresses of NTP +sources that were specified in the configuration file, or \fBchronyc\fP commands. +Without the \fB\-n\fP and \fB\-N\fP option, the printed hostnames are obtained from +reverse DNS lookups and can be different from the specified hostnames. +.RE +.sp +\fB\-c\fP +.RS 4 +This option enables printing of reports in a comma\-separated values (CSV) +format. Reverse DNS lookups will be disabled, time will be printed as number of +seconds since the epoch, and values in seconds will not be converted to other +units. +.RE +.sp +\fB\-e\fP +.RS 4 +With this option each \fBchronyc\fP response will end with a line containing a +single dot. +.RE +.sp +\fB\-d\fP +.RS 4 +This option enables printing of debugging messages if \fBchronyc\fP was compiled +with debugging support. +.RE +.sp +\fB\-m\fP +.RS 4 +Normally, all arguments on the command line are interpreted as one command. +With this option multiple commands can be specified. Each argument will be +interpreted as a whole command. +.RE +.sp +\fB\-h\fP \fIhost\fP +.RS 4 +This option specifies the host to be contacted by \fBchronyc\fP. It can be +specified with a hostname, IP address, or path to the local Unix domain socket. +Multiple values can be specified as a comma\-separated list to provide a +fallback. +.sp +The default value is \fI@CHRONYRUNDIR@/chronyd.sock,127.0.0.1,::1\fP, i.e. the host +where \fBchronyc\fP is being run. First, it tries to connect to the Unix domain +socket and if that fails (e.g. due to running under a non\-root user), it +will try to connect to 127.0.0.1 and then ::1. +.RE +.sp +\fB\-p\fP \fIport\fP +.RS 4 +This option allows the user to specify the UDP port number which the target +\fBchronyd\fP is using for its monitoring connections. This defaults to 323; there +would rarely be a need to change this. +.RE +.sp +\fB\-f\fP \fIfile\fP +.RS 4 +This option is ignored and is provided only for compatibility. +.RE +.sp +\fB\-a\fP +.RS 4 +This option is ignored and is provided only for compatibility. +.RE +.sp +\fB\-v\fP, \fB\-\-version\fP +.RS 4 +With this option \fBchronyc\fP displays its version number on the terminal and +exits. +.RE +.sp +\fB\-\-help\fP +.RS 4 +With this option \fBchronyc\fP displays a help message on the terminal and +exits. +.RE +.SH "COMMANDS" +.sp +This section describes each of the commands available within the \fBchronyc\fP +program. +.SS "System clock" +.sp +\fBtracking\fP +.RS 4 +The \fBtracking\fP command displays parameters about the system\(cqs clock +performance. An example of the output is shown below. +.sp +.if n .RS 4 +.nf +.fam C +Reference ID : CB00710F (ntp1.example.net) +Stratum : 3 +Ref time (UTC) : Fri Jan 27 09:49:17 2017 +System time : 0.000006523 seconds slow of NTP time +Last offset : \-0.000006747 seconds +RMS offset : 0.000035822 seconds +Frequency : 3.225 ppm slow +Residual freq : \-0.000 ppm +Skew : 0.129 ppm +Root delay : 0.013639022 seconds +Root dispersion : 0.001100737 seconds +Update interval : 64.2 seconds +Leap status : Normal +.fam +.fi +.if n .RE +.sp +The fields are explained as follows: +.sp +\fBReference ID\fP +.RS 4 +This is the reference ID and name (or IP address) of the server to which the +computer is currently synchronised. For IPv4 addresses, the reference ID is +equal to the address and for IPv6 addresses it is the first 32 bits of the MD5 +sum of the address. +.sp +If the reference ID is \fI7F7F0101\fP and there is no name or IP address, it means +the computer is not synchronised to any external source and that you have the +\fIlocal\fP mode operating (via the \fBlocal\fP command in \fBchronyc\fP, or the +\fBlocal\fP directive in the configuration file). +.sp +The reference ID is printed as a hexadecimal number. Note that in older +versions it used to be printed in quad\-dotted notation and could be confused +with an IPv4 address. +.RE +.sp +\fBStratum\fP +.RS 4 +The stratum indicates how many hops away from a computer with an attached +reference clock we are. Such a computer is a stratum\-1 computer, so the +computer in the example is two hops away (i.e. \fIntp1.example.net\fP is a +stratum\-2 and is synchronised from a stratum\-1). +.RE +.sp +\fBRef time\fP +.RS 4 +This is the time (UTC) at which the last measurement from the reference +source was processed. +.RE +.sp +\fBSystem time\fP +.RS 4 +This is the current offset between the NTP clock and system clock. The NTP +clock is a software (virtual) clock maintained by \fBchronyd\fP, which is +synchronised to the configured time sources and provides time to NTP clients. +The system clock is synchronised to the NTP clock. To avoid steps in the +system time, which might have adverse consequences for certain applications, +the system clock is normally corrected only by speeding up or slowing down (up +to the rate configured by the \fBmaxslewrate\fP +directive). If the offset is too large, this correction will take a very long +time. A step can be forced by the \fBmakestep\fP command, or the +\fBmakestep\fP directive in the configuration file. +.sp +Note that all other offsets reported by \fBchronyc\fP and most offsets in the log +files are relative to the NTP clock, not the system clock. +.RE +.sp +\fBLast offset\fP +.RS 4 +This is the estimated local offset on the last clock update. A positive value +indicates the local time (as previously estimated true time) was ahead of the +time sources. +.RE +.sp +\fBRMS offset\fP +.RS 4 +This is a long\-term average of the offset value. +.RE +.sp +\fBFrequency\fP +.RS 4 +The \(oqfrequency\(cq is the rate by which the system\(cqs clock would be wrong if +\fBchronyd\fP was not correcting it. It is expressed in ppm (parts per million). +For example, a value of 1 ppm would mean that when the system\(cqs clock thinks it +has advanced 1 second, it has actually advanced by 1.000001 seconds relative to +true time. +.RE +.sp +\fBResidual freq\fP +.RS 4 +This shows the \(oqresidual frequency\(cq for the currently selected reference +source. This reflects any difference between what the measurements from the +reference source indicate the frequency should be and the frequency currently +being used. +.sp +The reason this is not always zero is that a smoothing procedure is +applied to the frequency. Each time a measurement from the reference +source is obtained and a new residual frequency computed, the estimated +accuracy of this residual is compared with the estimated accuracy (see +\(oqskew\(cq next) of the existing frequency value. A weighted average is +computed for the new frequency, with weights depending on these accuracies. +If the measurements from the reference source follow a consistent trend, the +residual will be driven to zero over time. +.RE +.sp +\fBSkew\fP +.RS 4 +This is the estimated error bound on the frequency. +.RE +.sp +\fBRoot delay\fP +.RS 4 +This is the total of the network path delays to the stratum\-1 computer from +which the computer is ultimately synchronised. +.RE +.sp +\fBRoot dispersion\fP +.RS 4 +This is the total dispersion accumulated through all the computers back to +the stratum\-1 computer from which the computer is ultimately synchronised. +Dispersion is due to system clock resolution, statistical measurement +variations, etc. +.sp +An absolute bound on the computer\(cqs clock accuracy (assuming the stratum\-1 +computer is correct) is given by: +.sp +.if n .RS 4 +.nf +.fam C +clock_error <= |system_time_offset| + root_dispersion + (0.5 * root_delay) +.fam +.fi +.if n .RE +.RE +.sp +\fBUpdate interval\fP +.RS 4 +This is the interval between the last two clock updates. +.RE +.sp +\fBLeap status\fP +.RS 4 +This is the leap status, which can be \fINormal\fP, \fIInsert second\fP, \fIDelete +second\fP or \fINot synchronised\fP. +.RE +.RE +.sp +\fBmakestep\fP, \fBmakestep\fP \fIthreshold\fP \fIlimit\fP +.RS 4 +Normally \fBchronyd\fP will cause the system to gradually correct any time offset, +by slowing down or speeding up the clock as required. In certain situations, +the system clock might be so far adrift that this slewing process would take a +very long time to correct the system clock. +.sp +The \fBmakestep\fP command can be used in this situation. There are two forms of +the command. The first form has no parameters. It tells \fBchronyd\fP to cancel any +remaining correction that was being slewed and jump the system clock by the +equivalent amount, making it correct immediately. +.sp +The second form configures the automatic stepping, similarly to the +\fBmakestep\fP directive. It has two parameters, +stepping threshold (in seconds) and number of future clock updates for which +the threshold will be active. This can be used with the \fBburst\fP +command to quickly make a new measurement and correct the clock by stepping if +needed, without waiting for \fBchronyd\fP to complete the measurement and update +the clock. +.sp +.if n .RS 4 +.nf +.fam C +makestep 0.1 1 +burst 1/2 +.fam +.fi +.if n .RE +.sp +BE WARNED: Certain software will be seriously affected by such jumps in the +system time. (That is the reason why \fBchronyd\fP uses slewing normally.) +.RE +.sp +\fBmaxupdateskew\fP \fIskew\-in\-ppm\fP +.RS 4 +This command has the same effect as the +\fBmaxupdateskew\fP directive in the +configuration file. +.RE +.sp +\fBwaitsync\fP [\fImax\-tries\fP [\fImax\-correction\fP [\fImax\-skew\fP [\fIinterval\fP]]]] +.RS 4 +The \fBwaitsync\fP command waits for \fBchronyd\fP to synchronise. +.sp +Up to four optional arguments can be specified. The first is the maximum number +of tries before giving up and returning a non\-zero error code. When 0 is +specified, or there are no arguments, the number of tries will not be limited. +.sp +The second and third arguments are the maximum allowed remaining correction of +the system clock and the maximum allowed skew (in ppm) as reported by the +\fBtracking\fP command in the \fBSystem time\fP and \fBSkew\fP fields. If not +specified or zero, the value will not be checked. +.sp +The fourth argument is the interval specified in seconds in which the check is +repeated. The interval is 10 seconds by default. +.sp +An example is: +.sp +.if n .RS 4 +.nf +.fam C +waitsync 60 0.01 +.fam +.fi +.if n .RE +.sp +which will wait up to about 10 minutes (60 times 10 seconds) for \fBchronyd\fP to +synchronise to a source and the remaining correction to be less than 10 +milliseconds. +.RE +.SS "Time sources" +.sp +\fBsources\fP [\fB\-a\fP] [\fB\-v\fP] +.RS 4 +This command displays information about the current time sources that \fBchronyd\fP +is accessing. +.sp +If the \fB\-a\fP option is specified, all sources are displayed, including those that +do not have a known address yet. Such sources have an identifier in the format +\fIID#XXXXXXXXXX\fP, which can be used in other commands expecting a source address. +.sp +The \fB\-v\fP option enables a verbose output. In this case, +extra caption lines are shown as a reminder of the meanings of the columns. +.sp +.if n .RS 4 +.nf +.fam C +MS Name/IP address Stratum Poll Reach LastRx Last sample +=============================================================================== +#* GPS0 0 4 377 11 \-479ns[ \-621ns] +/\- 134ns +^? ntp1.example.net 2 6 377 23 \-923us[ \-924us] +/\- 43ms +^+ ntp2.example.net 1 6 377 21 \-2629us[\-2619us] +/\- 86ms +.fam +.fi +.if n .RE +.sp +The columns are as follows: +.sp +\fBM\fP +.RS 4 +This indicates the mode of the source. \fI^\fP means a server, \fI=\fP means a peer +and \fI#\fP indicates a locally connected reference clock. +.RE +.sp +\fBS\fP +.RS 4 +This column indicates the selection state of the source. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI*\fP indicates the best source which is currently selected for +synchronisation. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI+\fP indicates other sources selected for synchronisation, which are combined +with the best source. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI\-\fP indicates a source which is considered to be selectable for +synchronisation, but not currently selected. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIx\fP indicates a source which \fBchronyd\fP thinks is a falseticker (i.e. its +time is inconsistent with a majority of other sources, or sources specified +with the \fBtrust\fP option). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI~\fP indicates a source whose time appears to have too much variability. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI?\fP indicates a source which is not considered to be selectable for +synchronisation for other reasons (e.g. unreachable, not synchronised, or +does not have enough measurements). +.RE +.RE +.sp + +.RS 4 +The \fBselectdata\fP command can be used to get more details about +the selection state. +.RE +.sp +\fBName/IP address\fP +.RS 4 +This shows the name or the IP address of the source, or reference ID for reference +clocks. +.RE +.sp +\fBStratum\fP +.RS 4 +This shows the stratum of the source, as reported in its most recently +received sample. Stratum 1 indicates a computer with a locally attached +reference clock. A computer that is synchronised to a stratum 1 computer is +at stratum 2. A computer that is synchronised to a stratum 2 computer is at +stratum 3, and so on. +.RE +.sp +\fBPoll\fP +.RS 4 +This shows the rate at which the source is being polled, as a base\-2 +logarithm of the interval in seconds. Thus, a value of 6 would indicate that +a measurement is being made every 64 seconds. \fBchronyd\fP automatically varies +the polling rate in response to prevailing conditions. +.RE +.sp +\fBReach\fP +.RS 4 +This shows the source\(cqs 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. +.RE +.sp +\fBLastRx\fP +.RS 4 +This column shows how long ago the last good sample (which is shown in the next +column) was received from the source. Measurements that failed some tests are +ignored. This is normally in seconds. The letters \fIm\fP, \fIh\fP, \fId\fP or \fIy\fP indicate +minutes, hours, days, or years. +.RE +.sp +\fBLast sample\fP +.RS 4 +This column shows the offset between the local clock and the source at the +last measurement. The number in the square brackets shows the actual measured +offset. This can be suffixed by \fIns\fP (indicating nanoseconds), \fIus\fP +(indicating microseconds), \fIms\fP (indicating milliseconds), or \fIs\fP (indicating +seconds). The number to the left of the square brackets shows the original +measurement, adjusted to allow for any slews applied to the local clock +since. Positive offsets indicate that the local clock is ahead of the source. +The number following the \fI+/\-\fP indicator shows the margin of error in the +measurement (NTP root distance). +.RE +.RE +.sp +\fBsourcestats\fP [\fB\-a\fP] [\fB\-v\fP] +.RS 4 +The \fBsourcestats\fP command displays information about the drift rate and offset +estimation process for each of the sources currently being examined by +\fBchronyd\fP. +.sp +If the \fB\-a\fP option is specified, all sources are displayed, including those that +do not have a known address yet. Such sources have an identifier in the format +\fIID#XXXXXXXXXX\fP, which can be used in other commands expecting a source address. +.sp +The \fB\-v\fP option enables a verbose output. In this case, +extra caption lines are shown as a reminder of the meanings of the columns. +.sp +An example report is: +.sp +.if n .RS 4 +.nf +.fam C +Name/IP Address NP NR Span Frequency Freq Skew Offset Std Dev +=============================================================================== +ntp1.example.net 11 5 46m \-0.001 0.045 1us 25us +.fam +.fi +.if n .RE +.sp +The columns are as follows: +.sp +\fBName/IP Address\fP +.RS 4 +This is the name or IP address of the NTP server (or peer) or reference ID of the +reference clock to which the rest of the line relates. +.RE +.sp +\fBNP\fP +.RS 4 +This is the number of sample points currently being retained for the server. +The drift rate and current offset are estimated by performing a linear +regression through these points. +.RE +.sp +\fBNR\fP +.RS 4 +This is the number of runs of residuals having the same sign following the +last regression. If this number starts to become too small relative to the +number of samples, it indicates that a straight line is no longer a good fit +to the data. If the number of runs is too low, \fBchronyd\fP discards older +samples and re\-runs the regression until the number of runs becomes +acceptable. +.RE +.sp +\fBSpan\fP +.RS 4 +This is the interval between the oldest and newest samples. If no unit is +shown the value is in seconds. In the example, the interval is 46 minutes. +.RE +.sp +\fBFrequency\fP +.RS 4 +This is the estimated residual frequency for the server, in parts per +million. In this case, the computer\(cqs clock is estimated to be running 1 part +in 10^9 slow relative to the server. +.RE +.sp +\fBFreq Skew\fP +.RS 4 +This is the estimated error bounds on \fBFreq\fP (again in parts per million). +.RE +.sp +\fBOffset\fP +.RS 4 +This is the estimated offset of the source. +.RE +.sp +\fBStd Dev\fP +.RS 4 +This is the estimated sample standard deviation. +.RE +.RE +.sp +\fBselectdata\fP [\fB\-a\fP] [\fB\-v\fP] +.RS 4 +The \fBselectdata\fP command displays information specific to the selection of time +sources. If the \fB\-a\fP option is specified, all sources are displayed, including +those that do not have a known address yet. With the \fB\-v\fP option, extra caption +lines are shown as a reminder of the meanings of the columns. +.sp +An example of the output is shown below. +.sp +.if n .RS 4 +.nf +.fam C +S Name/IP Address Auth COpts EOpts Last Score Interval Leap +======================================================================= +D ntp1.example.net Y \-\-\-\-\- \-\-TR\- 4 1.0 \-61ms +62ms N +* ntp2.example.net N \-\-\-\-\- \-\-\-\-\- 0 1.0 \-6846us +7305us N ++ ntp3.example.net N \-\-\-\-\- \-\-\-\-\- 10 1.0 \-7381us +7355us N +.fam +.fi +.if n .RE +.sp +The columns are as follows: +.sp +\fBS\fP +.RS 4 +This column indicates the state of the source after the last source selection. +It is similar to the state reported by the \fBsources\fP command, but more +states are reported. +.RE +.sp + +.RS 4 +The following states indicate the source is not considered selectable for +synchronisation: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIN\fP \- has the \fBnoselect\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIs\fP \- is not synchronised. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIM\fP \- does not have enough measurements. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fId\fP \- has a root distance larger than the maximum distance (configured by the +\fBmaxdistance\fP directive). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI~\fP \- has a jitter larger than the maximum jitter (configured by the +\fBmaxjitter\fP directive). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIw\fP \- waits for other sources to get out of the \fIM\fP state. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIS\fP \- has older measurements than other sources. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIO\fP \- has a stratum equal or larger than the orphan stratum (configured by +the \fBlocal\fP directive). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIT\fP \- does not fully agree with sources that have the \fBtrust\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIx\fP \- does not agree with other sources (falseticker). +.RE +.RE +.sp + +.RS 4 +The following states indicate the source is considered selectable, but it is +not currently used for synchronisation: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIW\fP \- waits for other sources to be selectable (required by the +\fBminsources\fP directive, or +the \fBrequire\fP option of another source). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIP\fP \- another selectable source is preferred due to the \fBprefer\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIU\fP \- waits for a new measurement (after selecting a different best source). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fID\fP \- has, or recently had, a root distance which is too large to be combined +with other sources (configured by the +\fBcombinelimit\fP directive). +.RE +.RE +.sp + +.RS 4 +The following states indicate the source is used for synchronisation of the +local clock: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI+\fP \- combined with the best source. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI*\fP \- selected as the best source to update the reference data (e.g. root +delay, root dispersion). +.RE +.RE +.sp +\fBName/IP address\fP +.RS 4 +This column shows the name or IP address of the source if it is an NTP server, +or the reference ID if it is a reference clock. +.RE +.sp +\fBAuth\fP +.RS 4 +This column indicites whether an authentication mechanism is enabled for the +source. \fIY\fP means yes and \fIN\fP means no. +.RE +.sp +\fBCOpts\fP +.RS 4 +This column displays the configured selection options of the source. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIN\fP indicates the \fBnoselect\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIP\fP indicates the \fBprefer\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIT\fP indicates the \fBtrust\fP option. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIR\fP indicates the \fBrequire\fP option. +.RE +.RE +.sp +\fBEOpts\fP +.RS 4 +This column displays the current effective selection options of the source, +which can be different from the configured options due to the authentication +selection mode (configured by the +\fBauthselectmode\fP directive). The symbols +are the same as in the \fBCOpts\fP column. +.RE +.sp +\fBLast\fP +.RS 4 +This column displays how long ago was the last measurement of the source made +when the selection was performed. +.RE +.sp +\fBScore\fP +.RS 4 +This column displays the current score against the source in the \fI*\fP 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 +\fI*\fP source in recent selections. If the score reaches 10, the best source will +be reselected and the scores will be reset to 1. +.RE +.sp +\fBInterval\fP +.RS 4 +This column displays the lower and upper endpoint of the interval which was +expected to contain the true offset of the local clock considering the root +distance at the time of the selection. +.RE +.sp +\fBLeap\fP +.RS 4 +This column displays the current leap status of the source. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fIN\fP indicates the normal status (no leap second). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI+\fP indicates that a leap second will be inserted at the end of the month. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI\-\fP indicates that a leap second will be deleted at the end of the month. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fI?\fP indicates the unknown status (i.e. no valid measurement was made). +.RE +.RE +.RE +.sp +\fBselectopts\fP \fIaddress|refid\fP [\fI+|\-option\fP]... +.RS 4 +The \fBselectopts\fP command modifies the configured selection options of an NTP +source specified by IP address (or the \fIID#XXXXXXXXXX\fP identifier used for +unknown addresses), or a reference clock specified by reference ID as a string. +.sp +The selection options can be added with the \fB+\fP symbol or removed with the \fB\-\fP +symbol. The \fBselectdata\fP command can be used to verify the configuration. The +modified options will be applied in the next source selection, e.g. when a new +measurement is made, or the \fBreselect\fP command is executed. +.sp +An example of using this command is shown below. +.sp +.if n .RS 4 +.nf +.fam C +selectopts 1.2.3.4 \-noselect +prefer +selectopts GPS +trust +.fam +.fi +.if n .RE +.RE +.sp +\fBreselect\fP +.RS 4 +To avoid excessive switching between sources, \fBchronyd\fP can stay synchronised +to a source even when it is not currently the best one among the available +sources. +.sp +The \fBreselect\fP command can be used to force \fBchronyd\fP to reselect the best +synchronisation source. +.RE +.sp +\fBreselectdist\fP \fIdistance\fP +.RS 4 +The \fBreselectdist\fP command sets the reselection distance. It is equivalent to +the \fBreselectdist\fP directive in the +configuration file. +.RE +.SS "NTP sources" +.sp +\fBactivity\fP +.RS 4 +This command reports the number of servers and peers that are online and +offline. If the \fBauto_offline\fP option is used in specifying some of the servers +or peers, the \fBactivity\fP command can be useful for detecting when all of them +have entered the offline state after the network link has been disconnected. +.sp +The report shows the number of servers and peers in 5 states: +.sp +\fBonline\fP +.RS 4 +the server or peer is currently online (i.e. assumed by \fBchronyd\fP to be reachable) +.RE +.sp +\fBoffline\fP +.RS 4 +the server or peer is currently offline (i.e. assumed by \fBchronyd\fP to be +unreachable, and no measurements from it will be attempted.) +.RE +.sp +\fBburst_online\fP +.RS 4 +a burst command has been initiated for the server or peer and is being +performed; after the burst is complete, the server or peer will be returned to +the online state. +.RE +.sp +\fBburst_offline\fP +.RS 4 +a burst command has been initiated for the server or peer and is being +performed; after the burst is complete, the server or peer will be returned to +the offline state. +.RE +.sp +\fBunresolved\fP +.RS 4 +the name of the server or peer was not resolved to an address yet; this source is +not visible in the \fBsources\fP and \fBsourcestats\fP reports. +.RE +.RE +.sp +\fBauthdata\fP [\fB\-a\fP] +.RS 4 +The \fBauthdata\fP command displays information specific to authentication of NTP +sources. If the \fB\-a\fP option is specified, all sources are displayed, including +those that do not have a known address yet. An example of the output is +shown below. +.sp +.if n .RS 4 +.nf +.fam C +Name/IP address Mode KeyID Type KLen Last Atmp NAK Cook CLen +========================================================================= +ntp1.example.net NTS 1 15 256 135m 0 0 8 100 +ntp2.example.net SK 30 13 128 \- 0 0 0 0 +ntp3.example.net \- 0 0 0 \- 0 0 0 0 +.fam +.fi +.if n .RE +.sp +The columns are as follows: +.sp +\fBName/IP address\fP +.RS 4 +This column shows the name or the IP address of the source. +.RE +.sp +\fBMode\fP +.RS 4 +This column shows which mechanism authenticates NTP packets received from the +source. \fINTS\fP means Network Time Security, \fISK\fP means a symmetric key, and \fI\-\fP +means authentication is disabled. +.RE +.sp +\fBKeyID\fP +.RS 4 +This column shows an identifier of the key used for authentication. With a +symmetric key, it is the ID from the key file. +With NTS, it is a number starting at zero and incremented by one with each +successful key establishment using the NTS\-KE protocol, i.e. it shows how many +times the key establishment was performed with this source. +.RE +.sp +\fBType\fP +.RS 4 +This columns shows an identifier of the algorithm used for authentication. +With a symmetric key, it is the hash function or cipher specified in the key +file. With NTS, it is an authenticated encryption with associated data (AEAD) +algorithm, which is negotiated in the NTS\-KE protocol. The following values can +be reported: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +1: MD5 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +2: SHA1 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +3: SHA256 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +4: SHA384 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +5: SHA512 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +6: SHA3\-224 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +7: SHA3\-256 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +8: SHA3\-384 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +9: SHA3\-512 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +10: TIGER +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +11: WHIRLPOOL +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +13: AES128 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +14: AES256 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +15: AEAD\-AES\-SIV\-CMAC\-256 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +30: AEAD\-AES\-128\-GCM\-SIV +.RE +.RE +.sp +\fBKLen\fP +.RS 4 +This column shows the length of the key in bits. +.RE +.sp +\fBLast\fP +.RS 4 +This column shows how long ago the last successful key establishment was +performed. It is in seconds, or letters \fIm\fP, \fIh\fP, \fId\fP or \fIy\fP indicate minutes, +hours, days, or years. +.RE +.sp +\fBAtmp\fP +.RS 4 +This column shows the number of attempts to perform the key establishment since +the last successful key establishment. A number larger than 1 indicates a +problem with the network or server. +.RE +.sp +\fBNAK\fP +.RS 4 +This column shows whether an NTS NAK was received since the last request. +A NAK indicates that authentication failed on the server side due to +\fBchronyd\fP using a cookie which is no longer valid and that it needs to perform +the key establishment again in order to get new cookies. +.RE +.sp +\fBCook\fP +.RS 4 +This column shows the number of NTS cookies that \fBchronyd\fP currently has. If +the key establishment was successful, a number smaller than 8 indicates a +problem with the network or server. +.RE +.sp +\fBCLen\fP +.RS 4 +This column shows the length in bytes of the NTS cookie which will be used in +the next request. +.RE +.RE +.sp +\fBntpdata\fP [\fIaddress\fP] +.RS 4 +The \fBntpdata\fP command displays the last valid measurement and other +NTP\-specific information about the specified NTP source, or all NTP sources +(with a known address) if no address was specified. An example of the output is +shown below. +.sp +.if n .RS 4 +.nf +.fam C +Remote address : 203.0.113.15 (CB00710F) +Remote port : 123 +Local address : 203.0.113.74 (CB00714A) +Leap status : Normal +Version : 4 +Mode : Server +Stratum : 1 +Poll interval : 10 (1024 seconds) +Precision : \-24 (0.000000060 seconds) +Root delay : 0.000015 seconds +Root dispersion : 0.000015 seconds +Reference ID : 47505300 (GPS) +Reference time : Fri Nov 25 15:22:12 2016 +Offset : \-0.000060878 seconds +Peer delay : 0.000175634 seconds +Peer dispersion : 0.000000681 seconds +Response time : 0.000053050 seconds +Jitter asymmetry: +0.00 +NTP tests : 111 111 1111 +Interleaved : No +Authenticated : No +TX timestamping : Kernel +RX timestamping : Kernel +Total TX : 24 +Total RX : 24 +Total valid RX : 24 +Total good RX : 22 +.fam +.fi +.if n .RE +.sp +The fields are explained as follows: +.sp +\fBRemote address\fP +.RS 4 +The IP address of the NTP server or peer, and the corresponding reference ID. +.RE +.sp +\fBRemote port\fP +.RS 4 +The UDP port number to which the request was sent. The standard NTP port is +123. +.RE +.sp +\fBLocal address\fP +.RS 4 +The local IP address which received the response, and the corresponding +reference ID. +.RE +.sp +\fBLeap status\fP, \fBVersion\fP, \fBMode\fP, \fBStratum\fP, \fBPoll interval\fP, \fBPrecision\fP, \fBRoot delay\fP, \fBRoot dispersion\fP, \fBReference ID\fP, \fBReference time\fP +.RS 4 +The NTP values from the last valid response. +.RE +.sp +\fBOffset\fP, \fBPeer delay\fP, \fBPeer dispersion\fP +.RS 4 +The measured values. +.RE +.sp +\fBResponse time\fP +.RS 4 +The time the server or peer spent in processing of the request and waiting +before sending the response. +.RE +.sp +\fBJitter asymmetry\fP +.RS 4 +The estimated asymmetry of network jitter on the path to the source. 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. +.RE +.sp +\fBNTP tests\fP +.RS 4 +Results of RFC 5905 tests 1 through 3, 5 through 7, and tests for maximum +delay, delay ratio, delay dev ratio (or delay quantile), and synchronisation +loop. +.RE +.sp +\fBInterleaved\fP +.RS 4 +This shows if the response was in the interleaved mode. +.RE +.sp +\fBAuthenticated\fP +.RS 4 +This shows if the response was authenticated. +.RE +.sp +\fBTX timestamping\fP +.RS 4 +The source of the local transmit timestamp. Valid values are \fIDaemon\fP, +\fIKernel\fP, and \fIHardware\fP. +.RE +.sp +\fBRX timestamping\fP +.RS 4 +The source of the local receive timestamp. +.RE +.sp +\fBTotal TX\fP +.RS 4 +The number of packets sent to the source. +.RE +.sp +\fBTotal RX\fP +.RS 4 +The number of all packets received from the source. +.RE +.sp +\fBTotal valid RX\fP +.RS 4 +The number of packets which passed the first two groups of NTP tests. +.RE +.sp +\fBTotal good RX\fP +.RS 4 +The number of packets which passed all three groups of NTP tests, i.e. the NTP +measurement was accepted. +.RE +.RE +.sp +\fBadd peer\fP \fIname\fP [\fIoption\fP]... +.RS 4 +The \fBadd peer\fP command allows a new NTP peer to be added whilst +\fBchronyd\fP is running. +.sp +Following the words \fBadd peer\fP, the syntax of the following +parameters and options is identical to that for the +\fBpeer\fP directive in the configuration file. +.sp +An example of using this command is shown below. +.sp +.if n .RS 4 +.nf +.fam C +add peer ntp1.example.net minpoll 6 maxpoll 10 key 25 +.fam +.fi +.if n .RE +.RE +.sp +\fBadd pool\fP \fIname\fP [\fIoption\fP]... +.RS 4 +The \fBadd pool\fP command allows a pool of NTP servers to be added whilst +\fBchronyd\fP is running. +.sp +Following the words \fBadd pool\fP, the syntax of the following parameters and +options is identical to that for the \fBpool\fP +directive in the configuration file. +.sp +An example of using this command is shown below: +.sp +.if n .RS 4 +.nf +.fam C +add pool ntp1.example.net maxsources 3 iburst +.fam +.fi +.if n .RE +.RE +.sp +\fBadd server\fP \fIname\fP [\fIoption\fP]... +.RS 4 +The \fBadd server\fP command allows a new NTP server to be added whilst +\fBchronyd\fP is running. +.sp +Following the words \fBadd server\fP, the syntax of the following parameters and +options is identical to that for the \fBserver\fP +directive in the configuration file. +.sp +An example of using this command is shown below: +.sp +.if n .RS 4 +.nf +.fam C +add server ntp1.example.net minpoll 6 maxpoll 10 key 25 +.fam +.fi +.if n .RE +.RE +.sp +\fBdelete\fP \fIaddress\fP +.RS 4 +The \fBdelete\fP command allows an NTP server or peer to be removed +from the current set of sources. +.RE +.sp +\fBburst\fP \fIgood\fP/\fImax\fP [\fImask\fP/\fImasked\-address\fP], \fBburst\fP \fIgood\fP/\fImax\fP [\fImasked\-address\fP/\fImasked\-bits\fP], \fBburst\fP \fIgood\fP/\fImax\fP [\fIaddress\fP] +.RS 4 +The \fBburst\fP command tells \fBchronyd\fP to make a set of measurements to each of +its NTP sources over a short duration (rather than the usual periodic +measurements that it makes). After such a burst, \fBchronyd\fP will revert to the +previous state for each source. This might be either online, if the source was +being periodically measured in the normal way, or offline, if the source had +been indicated as being offline. (A source can be switched between the online +and offline states with the \fBonline\fP and \fBoffline\fP +commands.) +.sp +The \fImask\fP and \fImasked\-address\fP arguments are optional, in which case \fBchronyd\fP +will initiate a burst for all of its currently defined sources. +.sp +The arguments have the following meaning and format: +.sp +\fIgood\fP +.RS 4 +This defines the number of good measurements that \fBchronyd\fP will want to +obtain from each source. A measurement is good if it passes certain tests, +for example, the round trip time to the source must be acceptable. (This +allows \fBchronyd\fP to reject measurements that are likely to be bogus.) +.RE +.sp +\fImax\fP +.RS 4 +This defines the maximum number of measurements that \fBchronyd\fP will attempt +to make, even if the required number of good measurements has not been +obtained. +.RE +.sp +\fImask\fP +.RS 4 +This is an IP address with which the IP address of each of \fBchronyd\fP\*(Aqs +sources is to be masked. +.RE +.sp +\fImasked\-address\fP +.RS 4 +This is an IP address. If the masked IP address of a source matches this +value then the burst command is applied to that source. +.RE +.sp +\fImasked\-bits\fP +.RS 4 +This can be used with \fImasked\-address\fP for CIDR notation, which is a shorter +alternative to the form with mask. +.RE +.sp +\fIaddress\fP +.RS 4 +This is an IP address or a hostname. The burst command is applied only to +that source. +.RE +.RE +.sp + +.RS 4 +.sp +If no \fImask\fP or \fImasked\-address\fP arguments are provided, every source will be +matched. +.sp +An example of the two\-argument form of the command is: +.sp +.if n .RS 4 +.nf +.fam C +burst 2/10 +.fam +.fi +.if n .RE +.sp +This will cause \fBchronyd\fP to attempt to get two good measurements from each +source, stopping after two have been obtained, but in no event will it try more +than ten probes to the source. +.sp +Examples of the four\-argument form of the command are: +.sp +.if n .RS 4 +.nf +.fam C +burst 2/10 255.255.0.0/1.2.0.0 +burst 2/10 2001:db8:789a::/48 +.fam +.fi +.if n .RE +.sp +In the first case, the two out of ten sampling will only be applied to sources +whose IPv4 addresses are of the form \fI1.2.x.y\fP, where \fIx\fP and \fIy\fP are +arbitrary. In the second case, the sampling will be applied to sources whose +IPv6 addresses have first 48 bits equal to \fI2001:db8:789a\fP. +.sp +Example of the three\-argument form of the command is: +.sp +.if n .RS 4 +.nf +.fam C +burst 2/10 ntp1.example.net +.fam +.fi +.if n .RE +.RE +.sp +\fBmaxdelay\fP \fIaddress\fP \fIdelay\fP +.RS 4 +This allows the \fBmaxdelay\fP option for one of the sources to be modified, in the +same way as specifying the \fBmaxdelay\fP option for the +\fBserver\fP directive in the configuration file. +.RE +.sp +\fBmaxdelaydevratio\fP \fIaddress\fP \fIratio\fP +.RS 4 +This allows the \fBmaxdelaydevratio\fP option for one of the sources to be +modified, in the same way as specifying the \fBmaxdelaydevratio\fP option for the +\fBserver\fP directive in the configuration file. +.RE +.sp +\fBmaxdelayratio\fP \fIaddress\fP \fIratio\fP +.RS 4 +This allows the \fBmaxdelayratio\fP option for one of the sources to be modified, +in the same way as specifying the \fBmaxdelayratio\fP option for the +\fBserver\fP directive in the configuration file. +.RE +.sp +\fBmaxpoll\fP \fIaddress\fP \fImaxpoll\fP +.RS 4 +The \fBmaxpoll\fP command is used to modify the maximum polling interval for one of +the current set of sources. It is equivalent to the \fBmaxpoll\fP option in the +\fBserver\fP directive in the configuration file. +.sp +Note that the new maximum polling interval only takes effect after the next +measurement has been made. +.RE +.sp +\fBminpoll\fP \fIaddress\fP \fIminpoll\fP +.RS 4 +The \fBminpoll\fP command is used to modify the minimum polling interval for one of +the current set of sources. It is equivalent to the \fBminpoll\fP option in the +\fBserver\fP directive in the configuration file. +.sp +Note that the new minimum polling interval only takes effect after the next +measurement has been made. +.RE +.sp +\fBminstratum\fP \fIaddress\fP \fIminstratum\fP +.RS 4 +The \fBminstratum\fP command is used to modify the minimum stratum for one of the +current set of sources. It is equivalent to the \fBminstratum\fP option in the +\fBserver\fP directive in the configuration file. +.RE +.sp +\fBoffline\fP [\fIaddress\fP], \fBoffline\fP [\fImasked\-address\fP/\fImasked\-bits\fP], \fBoffline\fP [\fImask\fP/\fImasked\-address\fP] +.RS 4 +The \fBoffline\fP command is used to warn \fBchronyd\fP that the network connection to +a particular host or hosts is about to be lost, e.g. on computers with +intermittent connection to their time sources. +.sp +Another case where \fBoffline\fP could be used is where a computer serves time to a +local group of computers, and has a permanent connection to true time servers +outside the organisation. However, the external connection is heavily loaded at +certain times of the day and the measurements obtained are less reliable at +those times. In this case, it is probably most useful to determine the +gain or loss rate during the quiet periods and let the whole network coast through +the loaded periods. The \fBoffline\fP and \fBonline\fP commands can be used to achieve +this. +.sp +There are four forms of the \fBoffline\fP command. The first form is a wildcard, +meaning all sources (including sources that do not have a known address yet). +The second form allows an IP address mask and a masked +address to be specified. The third form uses CIDR notation. The fourth form +uses an IP address or a hostname. These forms are illustrated below. +.sp +.if n .RS 4 +.nf +.fam C +offline +offline 255.255.255.0/1.2.3.0 +offline 2001:db8:789a::/48 +offline ntp1.example.net +.fam +.fi +.if n .RE +.sp +The second form means that the \fBoffline\fP command is to be applied to any source +whose IPv4 address is in the \fI1.2.3\fP subnet. (The host\(cqs address is logically +and\-ed with the mask, and if the result matches the \fImasked\-address\fP the host +is processed.) The third form means that the command is to be applied to all +sources whose IPv6 addresses have their first 48 bits equal to \fI2001:db8:789a\fP. The +fourth form means that the command is to be applied only to that one source. +.sp +The wildcard form of the address is equivalent to: +.sp +.if n .RS 4 +.nf +.fam C +offline 0.0.0.0/0.0.0.0 +offline ::/0 +.fam +.fi +.if n .RE +.RE +.sp +\fBonline\fP [\fIaddress\fP], \fBonline\fP [\fImasked\-address\fP/\fImasked\-bits\fP], \fBonline\fP [\fImask\fP/\fImasked\-address\fP] +.RS 4 +The \fBonline\fP command is opposite in function to the \fBoffline\fP +command. It is used to advise \fBchronyd\fP that network connectivity to a +particular source or sources has been restored. +.sp +The syntax is identical to that of the \fBoffline\fP command. +.RE +.sp +\fBonoffline\fP +.RS 4 +The \fBonoffline\fP command tells \fBchronyd\fP to switch all sources that have a known +address to the online or +offline status according to the current network configuration. A source is +considered online if it is possible to send requests to it, i.e. a network +route to the source is present. +.RE +.sp +\fBpolltarget\fP \fIaddress\fP \fIpolltarget\fP +.RS 4 +The \fBpolltarget\fP command is used to modify the poll target for one of the +current set of sources. It is equivalent to the \fBpolltarget\fP option in the +\fBserver\fP directive in the configuration file. +.RE +.sp +\fBrefresh\fP +.RS 4 +The \fBrefresh\fP command can be used to force \fBchronyd\fP to resolve the names of +configured NTP sources to IP addresses again and replace any addresses missing +in the list of resolved addresses. +.sp +Sources that stop responding are replaced with newly resolved addresses +automatically after 8 polling intervals. This command can be used to replace +them immediately, e.g. after suspending and resuming the machine in a different +network. +.sp +Note that with pools which have more than 16 addresses, or not all IPv4 or IPv6 +addresses are included in a single DNS response (e.g. pool.ntp.org), this +command might replace the addresses even if they are still in the pool. +.RE +.sp +\fBreload\fP \fBsources\fP +.RS 4 +The \fBreload sources\fP command causes \fBchronyd\fP to re\-read all \fI*.sources\fP files +from the directories specified by the +\fBsourcedir\fP directive. +.sp +Note that modified sources (e.g. specified with a new option) are not modified +in memory. They are removed and added again, which causes them to lose old +measurements and reset the selection state. +.RE +.sp +\fBsourcename\fP \fIaddress\fP +.RS 4 +The \fBsourcename\fP command prints the original hostname or address that was +specified for an NTP source in the configuration file, or the \fBadd\fP command. +This command is an alternative to the \fB\-N\fP option, which can be useful in +scripts. +.sp +Note that different NTP sources can share the same name, e.g. servers from a +pool. +.RE +.SS "Manual time input" +.sp +\fBmanual\fP \fBon\fP, \fBmanual\fP \fBoff\fP, \fBmanual\fP \fBdelete\fP \fIindex\fP, \fBmanual\fP \fBlist\fP, \fBmanual\fP \fBreset\fP +.RS 4 +The manual command enables and disables use of the \fBsettime\fP +command, and is used to modify the behaviour of the manual clock driver. +.sp +The \fBon\fP form of the command enables use of the \fBsettime\fP command. +.sp +The \fBoff\fP form of the command disables use of the \fBsettime\fP command. +.sp +The \fBlist\fP form of the command lists all the samples currently stored in +\fBchronyd\fP. The output is illustrated below. +.sp +.if n .RS 4 +.nf +.fam C +210 n_samples = 1 +# Date Time(UTC) Slewed Original Residual +==================================================== + 0 27Jan99 22:09:20 0.00 0.97 0.00 +.fam +.fi +.if n .RE +.sp +The columns are as as follows: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +The sample index (used for the \fBmanual delete\fP command). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +The date and time of the sample. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +The system clock error when the timestamp was entered, adjusted to allow +for changes made to the system clock since. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +The system clock error when the timestamp was entered, as it originally was +(without allowing for changes to the system clock since). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 5." 4.2 +.\} +The regression residual at this point, in seconds. This allows \(oqoutliers\(cq +to be easily spotted, so that they can be deleted using the \fBmanual delete\fP +command. +.RE +.RE +.sp + +.RS 4 +.sp +The \fBdelete\fP form of the command deletes a single sample. The parameter is the +index of the sample, as shown in the first column of the output from \fBmanual +list\fP. Following deletion of the data point, the current error and drift rate +are re\-estimated from the remaining data points and the system clock trimmed if +necessary. This option is intended to allow \(oqoutliers\(cq to be discarded, i.e. +samples where the administrator realises they have entered a very poor +timestamp. +.sp +The \fBreset\fP form of the command deletes all samples at once. The system clock +is left running as it was before the command was entered. +.RE +.sp +\fBsettime\fP \fItime\fP +.RS 4 +The \fBsettime\fP command allows the current time to be entered manually, if this +option has been configured into \fBchronyd\fP. (It can be configured either with +the \fBmanual\fP directive in the configuration file, +or with the \fBmanual\fP command of \fBchronyc\fP.) +.sp +It should be noted that the computer\(cqs sense of time will only be as accurate +as the reference you use for providing this input (e.g. your watch), as well as +how well you can time the press of the return key. +.sp +Providing your computer\(cqs time zone is set up properly, you will be able to +enter a local time (rather than UTC). +.sp +The response to a successful \fBsettime\fP command indicates the amount that the +computer\(cqs clock was wrong. It should be apparent from this if you have entered +the time wrongly, e.g. with the wrong time zone. +.sp +The rate of drift of the system clock is estimated by a regression process +using the entered measurement and all previous measurements entered during the +present run of \fBchronyd\fP. However, the entered measurement is used for +adjusting the current clock offset (rather than the estimated intercept from +the regression, which is ignored). Contrast what happens with the +\fBmanual delete\fP command, where the intercept is used to set the +current offset (since there is no measurement that has just been entered in +that case). +.sp +The time is parsed by the public domain \fIgetdate\fP algorithm. Consequently, you +can only specify time to the nearest second. +.sp +Examples of inputs that are valid are shown below: +.sp +.if n .RS 4 +.nf +.fam C +settime 16:30 +settime 16:30:05 +settime Nov 21, 2015 16:30:05 +.fam +.fi +.if n .RE +.sp +For a full description of getdate, see the getdate documentation +(bundled, for example, with the source for GNU tar). +.RE +.SS "NTP access" +.sp +\fBaccheck\fP \fIaddress\fP +.RS 4 +This command allows you to check whether client NTP access is allowed from a +particular host. +.sp +Examples of use, showing a named host and a numeric IP address, are as follows: +.sp +.if n .RS 4 +.nf +.fam C +accheck ntp1.example.net +accheck 1.2.3.4 +accheck 2001:db8::1 +.fam +.fi +.if n .RE +.sp +This command can be used to examine the effect of a series of \fBallow\fP, \fBallow +all\fP, \fBdeny\fP, and \fBdeny all\fP commands specified either via \fBchronyc\fP, or in +\fBchronyd\fP\*(Aqs configuration file. +.RE +.sp +\fBclients\fP [\fB\-p\fP \fIpackets\fP] [\fB\-k\fP] [\fB\-r\fP] +.RS 4 +This command shows a list of clients that have accessed the server, through +the NTP, command, or NTS\-KE port. It does not include accesses over the Unix +domain command socket. +.sp +The \fB\-p\fP option specifies the minimum number of received NTP or command +packets, or accepted NTS\-KE connections, needed to include a client in the +list. The default value is 0, i.e. all clients are reported. With the \fB\-k\fP +option the last four columns will show the NTS\-KE accesses instead of command +accesses. If the \fB\-r\fP option is specified, \fBchronyd\fP will reset the counters of +received and dropped packets or connections after reporting the current values. +.sp +An example of the output is: +.sp +.if n .RS 4 +.nf +.fam C +Hostname NTP Drop Int IntL Last Cmd Drop Int Last +=============================================================================== +localhost 2 0 2 \- 133 15 0 \-1 7 +ntp1.example.net 12 0 6 \- 23 0 0 \- \- +.fam +.fi +.if n .RE +.sp +Each row shows the data for a single host. Only hosts that have passed the host +access checks (set with the \fBallow\fP, \fBdeny\fP, +\fBcmdallow\fP and \fBcmddeny\fP commands or configuration +file directives) are logged. The intervals are displayed as a power of 2 in +seconds. +.sp +The columns are as follows: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +The hostname of the client. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +The number of NTP packets received from the client. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +The number of NTP packets dropped to limit the response rate. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +The average interval between NTP packets. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 5." 4.2 +.\} +The average interval between NTP packets after limiting the response rate. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 6." 4.2 +.\} +Time since the last NTP packet was received +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 7." 4.2 +.\} +The number of command packets or NTS\-KE connections received/accepted from +the client. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 8.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 8." 4.2 +.\} +The number of command packets or NTS\-KE connections dropped to limit the +response rate. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 9.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 9." 4.2 +.\} +The average interval between command packets or NTS\-KE connections. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 10.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 10." 4.2 +.\} +Time since the last command packet or NTS\-KE connection was +received/accepted. +.RE +.RE +.sp +\fBserverstats\fP +.RS 4 +The \fBserverstats\fP command displays NTP and command server statistics. +.sp +An example of the output is shown below. +.sp +.if n .RS 4 +.nf +.fam C +NTP packets received : 1598 +NTP packets dropped : 8 +Command packets received : 19 +Command packets dropped : 0 +Client log records dropped : 0 +NTS\-KE connections accepted: 3 +NTS\-KE connections dropped : 0 +Authenticated NTP packets : 189 +Interleaved NTP packets : 43 +NTP timestamps held : 44 +NTP timestamp span : 120 +NTP daemon RX timestamps : 0 +NTP daemon TX timestamps : 1537 +NTP kernel RX timestamps : 1590 +NTP kernel TX timestamps : 43 +NTP hardware RX timestamps : 0 +NTP hardware TX timestamps : 0 +.fam +.fi +.if n .RE +.sp +The fields have the following meaning: +.sp +\fBNTP packets received\fP +.RS 4 +The number of valid NTP requests received by the server. +.RE +.sp +\fBNTP packets dropped\fP +.RS 4 +The number of NTP requests dropped by the server due to rate limiting +(configured by the \fBratelimit\fP directive). +.RE +.sp +\fBCommand packets received\fP +.RS 4 +The number of command requests received by the server. +.RE +.sp +\fBCommand packets dropped\fP +.RS 4 +The number of command requests dropped by the server due to rate limiting +(configured by the \fBcmdratelimit\fP directive). +.RE +.sp +\fBClient log records dropped\fP +.RS 4 +The number of client log records dropped by the server to limit the memory use +(configured by the \fBclientloglimit\fP +directive). +.RE +.sp +\fBNTS\-KE connections accepted\fP +.RS 4 +The number of NTS\-KE connections accepted by the server. +.RE +.sp +\fBNTS\-KE connections dropped\fP +.RS 4 +The number of NTS\-KE connections dropped by the server due to rate limiting +(configured by the \fBntsratelimit\fP directive). +.RE +.sp +\fBAuthenticated NTP packets\fP +.RS 4 +The number of received NTP requests that were authenticated (with a symmetric +key or NTS). +.RE +.sp +\fBInterleaved NTP packets\fP +.RS 4 +The number of received NTP requests that were detected to be in the interleaved +mode. +.RE +.sp +\fBNTP timestamps held\fP +.RS 4 +The number of pairs of receive and transmit timestamps that the server is +currently holding in memory for clients using the interleaved mode. +.RE +.sp +\fBNTP timestamp span\fP +.RS 4 +The interval (in seconds) covered by the currently held NTP timestamps. +.RE +.sp +\fBNTP daemon RX timestamps\fP +.RS 4 +The number of NTP responses which included a receive timestamp captured by the +daemon. +.RE +.sp +\fBNTP daemon TX timestamps\fP +.RS 4 +The number of NTP responses which included a transmit timestamp captured by the +daemon. +.RE +.sp +\fBNTP kernel RX timestamps\fP +.RS 4 +The number of NTP responses which included a receive timestamp captured by the +kernel. +.RE +.sp +\fBNTP kernel TX timestamps\fP +.RS 4 +The number of NTP responses (in the interleaved mode) which included a transmit +timestamp captured by the kernel. +.RE +.sp +\fBNTP hardware RX timestamps\fP +.RS 4 +The number of NTP responses which included a receive timestamp captured by the +NIC. +.RE +.sp +\fBNTP hardware TX timestamps\fP +.RS 4 +The number of NTP responses (in the interleaved mode) which included a transmit +timestamp captured by the NIC. +.RE +.RE +.sp +\fBallow\fP [\fBall\fP] [\fIsubnet\fP] +.RS 4 +The effect of the allow command is identical to the +\fBallow\fP directive in the configuration file. +.sp +The syntax is illustrated in the following examples: +.sp +.if n .RS 4 +.nf +.fam C +allow 1.2.3.4 +allow all 3.4.5.0/24 +allow 2001:db8:789a::/48 +allow 0/0 +allow ::/0 +allow +allow all +.fam +.fi +.if n .RE +.RE +.sp +\fBdeny\fP [\fBall\fP] [\fIsubnet\fP] +.RS 4 +The effect of the allow command is identical to the +\fBdeny\fP directive in the configuration file. +.sp +The syntax is illustrated in the following examples: +.sp +.if n .RS 4 +.nf +.fam C +deny 1.2.3.4 +deny all 3.4.5.0/24 +deny 2001:db8:789a::/48 +deny 0/0 +deny ::/0 +deny +deny all +.fam +.fi +.if n .RE +.RE +.sp +\fBlocal\fP [\fIoption\fP]..., \fBlocal\fP \fBoff\fP +.RS 4 +The \fBlocal\fP command allows \fBchronyd\fP to be told that it is to appear as a +reference source, even if it is not itself properly synchronised to an external +source. This can be used on isolated networks, to allow a computer to be the +primary time server for other computers. +.sp +The first form enables the local reference mode on the host. The syntax is +identical to the \fBlocal\fP directive in the +configuration file. +.sp +The second form disables the local reference mode. +.RE +.sp +\fBsmoothing\fP +.RS 4 +The \fBsmoothing\fP command displays the current state of the NTP server time +smoothing, which can be enabled with the +\fBsmoothtime\fP directive. An example of the +output is shown below. +.sp +.if n .RS 4 +.nf +.fam C +Active : Yes +Offset : +1.000268817 seconds +Frequency : \-0.142859 ppm +Wander : \-0.010000 ppm per second +Last update : 17.8 seconds ago +Remaining time : 19988.4 seconds +.fam +.fi +.if n .RE +.sp +The fields are explained as follows: +.sp +\fBActive\fP +.RS 4 +This shows if the server time smoothing is currently active. Possible values +are \fIYes\fP and \fINo\fP. If the \fBleaponly\fP option is included in the \fBsmoothtime\fP +directive, \fI(leap second only)\fP will be shown on the line. +.RE +.sp +\fBOffset\fP +.RS 4 +This is the current offset applied to the time sent to NTP clients. Positive +value means the clients are getting time that\(cqs ahead of true time. +.RE +.sp +\fBFrequency\fP +.RS 4 +The current frequency offset of the served time. Negative value means the +time observed by clients is running slower than true time. +.RE +.sp +\fBWander\fP +.RS 4 +The current frequency wander of the served time. Negative value means the +time observed by clients is slowing down. +.RE +.sp +\fBLast update\fP +.RS 4 +This field shows how long ago the time smoothing process was updated, e.g. +\fBchronyd\fP accumulated a new measurement. +.RE +.sp +\fBRemaining time\fP +.RS 4 +The time it would take for the smoothing process to get to zero offset and +frequency if there were no more updates. +.RE +.RE +.sp +\fBsmoothtime\fP \fBactivate\fP, \fBsmoothtime\fP \fBreset\fP +.RS 4 +The \fBsmoothtime\fP command can be used to activate or reset the server time +smoothing process if it is configured with the +\fBsmoothtime\fP directive. +.RE +.SS "Monitoring access" +.sp +\fBcmdaccheck\fP \fIaddress\fP +.RS 4 +This command is similar to the \fBaccheck\fP command, except that it is +used to check whether monitoring access is permitted from a named host. +.sp +Examples of use are as follows: +.sp +.if n .RS 4 +.nf +.fam C +cmdaccheck ntp1.example.net +cmdaccheck 1.2.3.4 +cmdaccheck 2001:db8::1 +.fam +.fi +.if n .RE +.RE +.sp +\fBcmdallow\fP [\fBall\fP] [\fIsubnet\fP] +.RS 4 +This is similar to the \fBallow\fP command, except that it is used to +allow particular hosts or subnets to use \fBchronyc\fP to monitor with \fBchronyd\fP on +the current host. +.RE +.sp +\fBcmddeny\fP [\fBall\fP] [\fIsubnet\fP] +.RS 4 +This is similar to the \fBdeny\fP command, except that it is used to allow +particular hosts or subnets to use \fBchronyc\fP to monitor \fBchronyd\fP on the +current host. +.RE +.SS "Real\-time clock (RTC)" +.sp +\fBrtcdata\fP +.RS 4 +The \fBrtcdata\fP command displays the current RTC parameters. +.sp +An example output is shown below. +.sp +.if n .RS 4 +.nf +.fam C +RTC ref time (GMT) : Sat May 30 07:25:56 2015 +Number of samples : 10 +Number of runs : 5 +Sample span period : 549 +RTC is fast by : \-1.632736 seconds +RTC gains time at : \-107.623 ppm +.fam +.fi +.if n .RE +.sp +The fields have the following meaning: +.sp +\fBRTC ref time (GMT)\fP +.RS 4 +This is the RTC reading the last time its error was measured. +.RE +.sp +\fBNumber of samples\fP +.RS 4 +This is the number of previous measurements being used to determine the RTC +gain or loss rate. +.RE +.sp +\fBNumber of runs\fP +.RS 4 +This is the number of runs of residuals of the same sign following the +regression fit for (RTC error) versus (RTC time). A value which is small +indicates that the measurements are not well approximated by a linear model, +and that the algorithm will tend to delete the older measurements to improve +the fit. +.RE +.sp +\fBSample span period\fP +.RS 4 +This is the period that the measurements span (from the oldest to the +newest). Without a unit the value is in seconds; suffixes \fIm\fP for minutes, +\fIh\fP for hours, \fId\fP for days or \fIy\fP for years can be used. +.RE +.sp +\fBRTC is fast by\fP +.RS 4 +This is the estimate of how many seconds fast the RTC when it thought +the time was at the reference time (above). If this value is large, you +might (or might not) want to use the \fBtrimrtc\fP command to bring the +RTC into line with the system clock. (Note, a large error will not affect +\fBchronyd\fP\*(Aqs operation, unless it becomes so big as to start causing rounding +errors.) +.RE +.sp +\fBRTC gains time at\fP +.RS 4 +This is the amount of time gained (positive) or lost (negative) by the real +time clock for each second that it ticks. It is measured in parts per +million. So if the value shown was +1, suppose the RTC was exactly right when +it crosses a particular second boundary. Then it would be 1 microsecond fast +when it crosses its next second boundary. +.RE +.RE +.sp +\fBtrimrtc\fP +.RS 4 +The \fBtrimrtc\fP command is used to correct the system\(cqs real\-time clock (RTC) to +the main system clock. It has no effect if the error between the two clocks is +currently estimated at less than a second. +.sp +The command takes no arguments. It performs the following steps (if the RTC is +more than 1 second away from the system clock): +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Remember the currently estimated gain or loss rate of the RTC and flush the +previous measurements. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Step the real\-time clock to bring it within a second of the system clock. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Make several measurements to accurately determine the new offset between +the RTC and the system clock (i.e. the remaining fraction of a second +error). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +Save the RTC parameters to the RTC file (specified with the +\fBrtcfile\fP directive in the configuration file). +.RE +.RE +.sp + +.RS 4 +.sp +The last step is done as a precaution against the computer suffering a power +failure before either the daemon exits or the \fBwritertc\fP command +is issued. +.sp +\fBchronyd\fP will still work perfectly well both whilst operating and across +machine reboots even if the \fBtrimrtc\fP command is never used (and the RTC is +allowed to drift away from true time). The \fBtrimrtc\fP command is provided as a +method by which it can be corrected, in a manner compatible with \fBchronyd\fP +using it to maintain accurate time across machine reboots. +.sp +The \fBtrimrtc\fP command can be executed automatically by \fBchronyd\fP with the +\fBrtcautotrim\fP directive in the configuration +file. +.RE +.sp +\fBwritertc\fP +.RS 4 +The \fBwritertc\fP command writes the currently estimated error and gain or loss rate +parameters for the RTC to the RTC file (specified with the +\fBrtcfile\fP directive). This information is also +written automatically when \fBchronyd\fP is killed (by the SIGHUP, SIGINT, SIGQUIT +or SIGTERM signals) or when the \fBtrimrtc\fP command is issued. +.RE +.SS "Other daemon commands" +.sp +\fBcyclelogs\fP +.RS 4 +The \fBcyclelogs\fP command causes all of \fBchronyd\fP\*(Aqs open log files to be closed +and re\-opened. This allows them to be renamed so that they can be periodically +purged. An example of how to do this is shown below. +.sp +.if n .RS 4 +.nf +.fam C +# mv /var/log/chrony/measurements.log /var/log/chrony/measurements1.log +# chronyc cyclelogs +# rm /var/log/chrony/measurements1.log +.fam +.fi +.if n .RE +.RE +.sp +\fBdump\fP +.RS 4 +The \fBdump\fP command causes \fBchronyd\fP to write its current history of +measurements for each of its sources to dump files in the directory specified +in the configuration file by the \fBdumpdir\fP +directive and also write server NTS keys and client NTS cookies to the +directory specified by the \fBntsdumpdir\fP +directive. Note that \fBchronyd\fP does this automatically when it exits. This +command is mainly useful for inspection whilst \fBchronyd\fP is running. +.RE +.sp +\fBrekey\fP +.RS 4 +The \fBrekey\fP command causes \fBchronyd\fP to re\-read the key file specified in the +configuration file by the \fBkeyfile\fP directive. It +also re\-reads the server NTS keys if +\fBntsdumpdir\fP is specified and +automatic rotation is disabled in the +configuration file. +.RE +.sp +\fBreset\fP \fBsources\fP +.RS 4 +The \fBreset sources\fP command causes \fBchronyd\fP to drop all measurements and +switch to the unsynchronised state. This command can help \fBchronyd\fP with +recovery when the measurements are known to be no longer valid or accurate, +e.g. due to moving the computer to a different network, or resuming the +computer from a low\-power state (which resets the system clock). \fBchronyd\fP will +drop the measurements automatically when it detects the clock has made an +unexpected jump, but the detection is not completely reliable. +.RE +.sp +\fBshutdown\fP +.RS 4 +The \fBshutdown\fP command causes \fBchronyd\fP to exit. This is equivalent to sending +the process the SIGTERM signal. +.RE +.SS "Client commands" +.sp +\fBdns\fP \fIoption\fP +.RS 4 +The \fBdns\fP command configures how hostnames and IP addresses are resolved in +\fBchronyc\fP. IP addresses can be resolved to hostnames when printing results of +\fBsources\fP, \fBsourcestats\fP, \fBtracking\fP +and \fBclients\fP commands. Hostnames are resolved in commands that +take an address as argument. +.sp +There are five options: +.sp +\fBdns \-n\fP +.RS 4 +Disables resolving IP addresses to hostnames. Raw IP addresses will be +displayed. +.RE +.sp +\fBdns +n\fP +.RS 4 +Enables resolving IP addresses to hostnames. This is the default unless +\fBchronyc\fP was started with \fB\-n\fP option. +.RE +.sp +\fBdns \-4\fP +.RS 4 +Resolves hostnames only to IPv4 addresses. +.RE +.sp +\fBdns \-6\fP +.RS 4 +Resolves hostnames only to IPv6 addresses. +.RE +.sp +\fBdns \-46\fP +.RS 4 +Resolves hostnames to both address families. This is the default behaviour +unless \fBchronyc\fP was started with the \fB\-4\fP or \fB\-6\fP option. +.RE +.RE +.sp +\fBtimeout\fP \fItimeout\fP +.RS 4 +The \fBtimeout\fP command sets the initial timeout for \fBchronyc\fP requests in +milliseconds. If no response is received from \fBchronyd\fP, the timeout is doubled +and the request is resent. The maximum number of retries is configured with the +\fBretries\fP command. +.sp +By default, the timeout is 1000 milliseconds. +.RE +.sp +\fBretries\fP \fIretries\fP +.RS 4 +The \fBretries\fP command sets the maximum number of retries for \fBchronyc\fP requests +before giving up. The response timeout is controlled by the +\fBtimeout\fP command. +.sp +The default is 2. +.RE +.sp +\fBkeygen\fP [\fIid\fP [\fItype\fP [\fIbits\fP]]] +.RS 4 +The \fBkeygen\fP command generates a key that can be added to the +key file (specified with the \fBkeyfile\fP directive) +to allow NTP authentication between server and client, or peers. The key is +generated from the \fI/dev/urandom\fP device and it is printed to standard output. +.sp +The command has three optional arguments. The first argument is the key number +(by default 1), which will be specified with the \fBkey\fP option of the \fBserver\fP +or \fBpeer\fP directives in the configuration file. The second argument is the name +of the hash function or cipher (by default SHA1, or MD5 if SHA1 is not +available). The third argument is the length of the key in bits if a hash +function was selected, between 80 and 4096 bits (by default 160 bits). +.sp +An example is: +.sp +.if n .RS 4 +.nf +.fam C +keygen 73 SHA1 256 +.fam +.fi +.if n .RE +.sp +which generates a 256\-bit SHA1 key with number 73. The printed line should +then be securely transferred and added to the key files on both server and +client, or peers. A different key should be generated for each client or peer. +.sp +An example using the AES128 cipher is: +.sp +.if n .RS 4 +.nf +.fam C +keygen 151 AES128 +.fam +.fi +.if n .RE +.RE +.sp +\fBexit\fP, \fBquit\fP +.RS 4 +The \fBexit\fP and \fBquit\fP commands exit from \fBchronyc\fP and return the user to the shell. +.RE +.sp +\fBhelp\fP +.RS 4 +The \fBhelp\fP command displays a summary of the commands and their arguments. +.RE +.SH "SEE ALSO" +.sp +\fBchrony.conf(5)\fP, \fBchronyd(8)\fP +.SH "BUGS" +.sp +For instructions on how to report bugs, please visit +.URL "https://chrony\-project.org/" "" "." +.SH "AUTHORS" +.sp +chrony was written by Richard Curnow, Miroslav Lichvar, and others.
\ No newline at end of file diff --git a/doc/chronyd.adoc b/doc/chronyd.adoc new file mode 100644 index 0000000..887be48 --- /dev/null +++ b/doc/chronyd.adoc @@ -0,0 +1,235 @@ +// This file is part of chrony +// +// Copyright (C) Richard P. Curnow 1997-2003 +// Copyright (C) Miroslav Lichvar 2009-2017 +// +// 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. + += chronyd(8) +:doctype: manpage +:man manual: System Administration +:man source: chrony @CHRONY_VERSION@ + +== NAME + +chronyd - chrony daemon + +== SYNOPSIS + +*chronyd* [_OPTION_]... [_DIRECTIVE_]... + +== DESCRIPTION + +*chronyd* is a daemon for synchronisation of the system clock. It can +synchronise the clock with NTP servers, reference clocks (e.g. a GPS receiver), +and manual input using wristwatch and keyboard via *chronyc*. It can also +operate as an NTPv4 (RFC 5905) server and peer to provide a time service to +other computers in the network. + +If no configuration directives are specified on the command line, *chronyd* +will read them from a configuration file. The compiled-in default location of +the file is _@SYSCONFDIR@/chrony.conf_. + +Informational messages, warnings, and errors will be logged to syslog. + +== OPTIONS + +*-4*:: +With this option hostnames will be resolved only to IPv4 addresses and only +IPv4 sockets will be created. + +*-6*:: +With this option hostnames will be resolved only to IPv6 addresses and only +IPv6 sockets will be created. + +*-f* _file_:: +This option can be used to specify an alternate location for the configuration +file. The compiled-in default value is _@SYSCONFDIR@/chrony.conf_. + +*-n*:: +When run in this mode, the program will not detach itself from the terminal. + +*-d*:: +When run in this mode, the program will not detach itself from the terminal, +and all messages will be written to the terminal instead of syslog. If +*chronyd* was compiled with enabled support for debugging, this option can be +used twice to enable debug messages. + +*-l* _file_:: +This option enables writing of log messages to a file instead of syslog or the +terminal. + +*-L* _level_:: +This option specifies the minimum severity level of messages to be written to +the log file, syslog, or terminal. The following levels can be specified: -1 +(debug, if compiled with enabled support for debugging), 0 (informational), 1 +(warning), 2 (non-fatal error), and 3 (fatal error). The default value is 0. + +*-p*:: +When run in this mode, *chronyd* will print the configuration and exit. It will +not detach from the terminal. This option can be used to verify the syntax of +the configuration and get the whole configuration, even if it is split into +multiple files and read by the *include* or *confdir* directive. + +*-q*:: +When run in this mode, *chronyd* will set the system clock once and exit. It +will not detach from the terminal. + +*-Q*:: +This option is similar to the *-q* option, except it only prints the offset +without making any corrections of the clock and disables server ports to allow +*chronyd* to be started without root privileges, assuming the configuration +does not have any directives which would require them (e.g. *refclock*, +*hwtimestamp*, *rtcfile*, etc). + +*-r*:: +This option will try to reload and then delete files containing sample +histories for each of the servers and reference clocks being used. The +files are expected to be in the directory specified by the +<<chrony.conf.adoc#dumpdir,*dumpdir*>> +directive in the configuration file. This option is useful if you want to stop +and restart *chronyd* briefly for any reason, e.g. to install a new version. +However, it should be used only on systems where the kernel can maintain clock +compensation whilst not under *chronyd*'s control (i.e. Linux, FreeBSD, NetBSD, +illumos, and macOS 10.13 or later). + +*-R*:: +When this option is used, the <<chrony.conf.adoc#initstepslew,*initstepslew*>> +directive and the <<chrony.conf.adoc#makestep,*makestep*>> directive used with +a positive limit will be ignored. This option is useful when restarting +*chronyd* and can be used in conjunction with the *-r* option. + +*-s*:: +This option will set the system clock from the computer's real-time clock (RTC) +or to the last modification time of the file specified by the +<<chrony.conf.adoc#driftfile,*driftfile*>> directive. Real-time clocks are +supported only on Linux. ++ +If used in conjunction with the *-r* flag, *chronyd* will attempt to preserve +the old samples after setting the system clock from the RTC. This can be used +to allow *chronyd* to perform long term averaging of the gain or loss rate +across system reboots, and is useful for systems with intermittent access to +network that are shut down when not in use. For this to work well, it relies +on *chronyd* having been able to determine accurate statistics for the +difference between the RTC and system clock last time the computer was on. ++ +If the last modification time of the drift file is later than both the current +time and the RTC time, the system time will be set to it to restore the time +when *chronyd* was previously stopped. This is useful on computers that have no +RTC or the RTC is broken (e.g. it has no battery). + +*-t* _timeout_:: +This option sets a timeout (in seconds) after which *chronyd* will exit. If the +clock is not synchronised, it will exit with a non-zero status. This is useful +with the *-q* or *-Q* option to shorten the maximum time waiting for +measurements, or with the *-r* option to limit the time when *chronyd* is +running, but still allow it to adjust the frequency of the system clock. + +*-u* _user_:: +This option sets the name of the system user to which *chronyd* will switch +after start in order to drop root privileges. It overrides the +<<chrony.conf.adoc#user,*user*>> directive. The compiled-in default value is +_@DEFAULT_USER@_. ++ +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. + +*-U*:: +This option disables a check for root privileges to allow *chronyd* to be +started under a non-root user, assuming the process will have all capabilities +(e.g. provided by the service manager) and access to all files, directories, +and devices, needed to operate correctly in the specified configuration. Note +that different capabilities might be needed with different configurations and +different Linux kernel versions. Starting *chronyd* under a non-root user is +not recommended when the configuration is not known, or at least limited to +specific directives. + +*-F* _level_:: +This option configures system call filters loaded by *chronyd* processes if it +was compiled with support for the Linux secure computing (seccomp) facility. +Three levels are defined: 0, 1, 2. The filters are disabled at level 0. At +levels 1 and 2, *chronyd* will be killed if it makes a system call which is +blocked by the filters. The level can be specified as a negative number to +trigger the SIGSYS signal instead of SIGKILL, which can be useful for +debugging. The default value is 0. ++ +At level 1, the filters allow only selected system calls that are normally +expected to be made by *chronyd*. Other system calls are blocked. This level is +recommended only if it is known to work on the version of the system where +*chrony* is installed. The filters need to allow also system calls made by +libraries that *chronyd* is using (e.g. libc), but different versions or +implementations of the libraries might make different system calls. If the +filters are missing a system call, *chronyd* could be killed even in normal +operation. ++ +At level 2, the filters block only a small number of specific system calls +(e.g. fork and exec). This approach should avoid false positives, but the +protection of the system against a compromised *chronyd* process is much more +limited. ++ +The filters cannot be enabled with the *mailonchange* directive. + +*-P* _priority_:: +On Linux, FreeBSD, NetBSD, and illumos this option 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 to disable the thread +time constraint policy or 1 for the policy to be enabled. Other systems do not +support this option. The default value is 0. + +*-m*:: +This option will lock *chronyd* into RAM so that it will never be paged out. +This mode is only supported on Linux, FreeBSD, NetBSD, and illumos. + +*-x*:: +This option disables the control of the system clock. *chronyd* will not try to +make any adjustments of the clock. It will assume the clock is free running and +still track its offset and frequency relative to the estimated true time. This +option allows *chronyd* to be started without the capability to adjust or set +the system clock (e.g. in some containers) to operate as an NTP server. + +*-v*, *--version*:: +With this option *chronyd* will print version number to the terminal and exit. + +*-h*, *--help*:: +With this option *chronyd* will print a help message to the terminal and exit. + +== ENVIRONMENT VARIABLES + +*LISTEN_FDS*:: +On Linux systems, the systemd service manager may pass file descriptors for +pre-initialised sockets to *chronyd*. The service manager allocates and binds +the file descriptors, and passes a copy to each spawned instance of the +service. This allows for zero-downtime service restarts as the sockets buffer +client requests until the service is able to handle them. The service manager +sets the LISTEN_FDS environment variable to the number of passed file +descriptors. + +== FILES + +_@SYSCONFDIR@/chrony.conf_ + +== SEE ALSO + +<<chronyc.adoc#,*chronyc(1)*>>, <<chrony.conf.adoc#,*chrony.conf(5)*>> + +== 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. diff --git a/doc/chronyd.man.in b/doc/chronyd.man.in new file mode 100644 index 0000000..96e87a0 --- /dev/null +++ b/doc/chronyd.man.in @@ -0,0 +1,278 @@ +'\" t +.\" Title: chronyd +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 2.0.20 +.\" Date: 2023-12-05 +.\" Manual: System Administration +.\" Source: chrony @CHRONY_VERSION@ +.\" Language: English +.\" +.TH "CHRONYD" "8" "2023-12-05" "chrony @CHRONY_VERSION@" "System Administration" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +chronyd \- chrony daemon +.SH "SYNOPSIS" +.sp +\fBchronyd\fP [\fIOPTION\fP]... [\fIDIRECTIVE\fP]... +.SH "DESCRIPTION" +.sp +\fBchronyd\fP is a daemon for synchronisation of the system clock. It can +synchronise the clock with NTP servers, reference clocks (e.g. a GPS receiver), +and manual input using wristwatch and keyboard via \fBchronyc\fP. It can also +operate as an NTPv4 (RFC 5905) server and peer to provide a time service to +other computers in the network. +.sp +If no configuration directives are specified on the command line, \fBchronyd\fP +will read them from a configuration file. The compiled\-in default location of +the file is \fI@SYSCONFDIR@/chrony.conf\fP. +.sp +Informational messages, warnings, and errors will be logged to syslog. +.SH "OPTIONS" +.sp +\fB\-4\fP +.RS 4 +With this option hostnames will be resolved only to IPv4 addresses and only +IPv4 sockets will be created. +.RE +.sp +\fB\-6\fP +.RS 4 +With this option hostnames will be resolved only to IPv6 addresses and only +IPv6 sockets will be created. +.RE +.sp +\fB\-f\fP \fIfile\fP +.RS 4 +This option can be used to specify an alternate location for the configuration +file. The compiled\-in default value is \fI@SYSCONFDIR@/chrony.conf\fP. +.RE +.sp +\fB\-n\fP +.RS 4 +When run in this mode, the program will not detach itself from the terminal. +.RE +.sp +\fB\-d\fP +.RS 4 +When run in this mode, the program will not detach itself from the terminal, +and all messages will be written to the terminal instead of syslog. If +\fBchronyd\fP was compiled with enabled support for debugging, this option can be +used twice to enable debug messages. +.RE +.sp +\fB\-l\fP \fIfile\fP +.RS 4 +This option enables writing of log messages to a file instead of syslog or the +terminal. +.RE +.sp +\fB\-L\fP \fIlevel\fP +.RS 4 +This option specifies the minimum severity level of messages to be written to +the log file, syslog, or terminal. The following levels can be specified: \-1 +(debug, if compiled with enabled support for debugging), 0 (informational), 1 +(warning), 2 (non\-fatal error), and 3 (fatal error). The default value is 0. +.RE +.sp +\fB\-p\fP +.RS 4 +When run in this mode, \fBchronyd\fP will print the configuration and exit. It will +not detach from the terminal. This option can be used to verify the syntax of +the configuration and get the whole configuration, even if it is split into +multiple files and read by the \fBinclude\fP or \fBconfdir\fP directive. +.RE +.sp +\fB\-q\fP +.RS 4 +When run in this mode, \fBchronyd\fP will set the system clock once and exit. It +will not detach from the terminal. +.RE +.sp +\fB\-Q\fP +.RS 4 +This option is similar to the \fB\-q\fP option, except it only prints the offset +without making any corrections of the clock and disables server ports to allow +\fBchronyd\fP to be started without root privileges, assuming the configuration +does not have any directives which would require them (e.g. \fBrefclock\fP, +\fBhwtimestamp\fP, \fBrtcfile\fP, etc). +.RE +.sp +\fB\-r\fP +.RS 4 +This option will try to reload and then delete files containing sample +histories for each of the servers and reference clocks being used. The +files are expected to be in the directory specified by the +\fBdumpdir\fP +directive in the configuration file. This option is useful if you want to stop +and restart \fBchronyd\fP briefly for any reason, e.g. to install a new version. +However, it should be used only on systems where the kernel can maintain clock +compensation whilst not under \fBchronyd\fP\*(Aqs control (i.e. Linux, FreeBSD, NetBSD, +illumos, and macOS 10.13 or later). +.RE +.sp +\fB\-R\fP +.RS 4 +When this option is used, the \fBinitstepslew\fP +directive and the \fBmakestep\fP directive used with +a positive limit will be ignored. This option is useful when restarting +\fBchronyd\fP and can be used in conjunction with the \fB\-r\fP option. +.RE +.sp +\fB\-s\fP +.RS 4 +This option will set the system clock from the computer\(cqs real\-time clock (RTC) +or to the last modification time of the file specified by the +\fBdriftfile\fP directive. Real\-time clocks are +supported only on Linux. +.sp +If used in conjunction with the \fB\-r\fP flag, \fBchronyd\fP will attempt to preserve +the old samples after setting the system clock from the RTC. This can be used +to allow \fBchronyd\fP to perform long term averaging of the gain or loss rate +across system reboots, and is useful for systems with intermittent access to +network that are shut down when not in use. For this to work well, it relies +on \fBchronyd\fP having been able to determine accurate statistics for the +difference between the RTC and system clock last time the computer was on. +.sp +If the last modification time of the drift file is later than both the current +time and the RTC time, the system time will be set to it to restore the time +when \fBchronyd\fP was previously stopped. This is useful on computers that have no +RTC or the RTC is broken (e.g. it has no battery). +.RE +.sp +\fB\-t\fP \fItimeout\fP +.RS 4 +This option sets a timeout (in seconds) after which \fBchronyd\fP will exit. If the +clock is not synchronised, it will exit with a non\-zero status. This is useful +with the \fB\-q\fP or \fB\-Q\fP option to shorten the maximum time waiting for +measurements, or with the \fB\-r\fP option to limit the time when \fBchronyd\fP is +running, but still allow it to adjust the frequency of the system clock. +.RE +.sp +\fB\-u\fP \fIuser\fP +.RS 4 +This option sets the name of the system user to which \fBchronyd\fP will switch +after start in order to drop root privileges. It overrides the +\fBuser\fP directive. The compiled\-in default value is +\fI@DEFAULT_USER@\fP. +.sp +On Linux, \fBchronyd\fP needs to be compiled with support for the \fBlibcap\fP library. +On macOS, FreeBSD, NetBSD, and illumos \fBchronyd\fP 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. +.RE +.sp +\fB\-U\fP +.RS 4 +This option disables a check for root privileges to allow \fBchronyd\fP to be +started under a non\-root user, assuming the process will have all capabilities +(e.g. provided by the service manager) and access to all files, directories, +and devices, needed to operate correctly in the specified configuration. Note +that different capabilities might be needed with different configurations and +different Linux kernel versions. Starting \fBchronyd\fP under a non\-root user is +not recommended when the configuration is not known, or at least limited to +specific directives. +.RE +.sp +\fB\-F\fP \fIlevel\fP +.RS 4 +This option configures system call filters loaded by \fBchronyd\fP processes if it +was compiled with support for the Linux secure computing (seccomp) facility. +Three levels are defined: 0, 1, 2. The filters are disabled at level 0. At +levels 1 and 2, \fBchronyd\fP will be killed if it makes a system call which is +blocked by the filters. The level can be specified as a negative number to +trigger the SIGSYS signal instead of SIGKILL, which can be useful for +debugging. The default value is 0. +.sp +At level 1, the filters allow only selected system calls that are normally +expected to be made by \fBchronyd\fP. Other system calls are blocked. This level is +recommended only if it is known to work on the version of the system where +\fBchrony\fP is installed. The filters need to allow also system calls made by +libraries that \fBchronyd\fP is using (e.g. libc), but different versions or +implementations of the libraries might make different system calls. If the +filters are missing a system call, \fBchronyd\fP could be killed even in normal +operation. +.sp +At level 2, the filters block only a small number of specific system calls +(e.g. fork and exec). This approach should avoid false positives, but the +protection of the system against a compromised \fBchronyd\fP process is much more +limited. +.sp +The filters cannot be enabled with the \fBmailonchange\fP directive. +.RE +.sp +\fB\-P\fP \fIpriority\fP +.RS 4 +On Linux, FreeBSD, NetBSD, and illumos this option 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 to disable the thread +time constraint policy or 1 for the policy to be enabled. Other systems do not +support this option. The default value is 0. +.RE +.sp +\fB\-m\fP +.RS 4 +This option will lock \fBchronyd\fP into RAM so that it will never be paged out. +This mode is only supported on Linux, FreeBSD, NetBSD, and illumos. +.RE +.sp +\fB\-x\fP +.RS 4 +This option disables the control of the system clock. \fBchronyd\fP will not try to +make any adjustments of the clock. It will assume the clock is free running and +still track its offset and frequency relative to the estimated true time. This +option allows \fBchronyd\fP to be started without the capability to adjust or set +the system clock (e.g. in some containers) to operate as an NTP server. +.RE +.sp +\fB\-v\fP, \fB\-\-version\fP +.RS 4 +With this option \fBchronyd\fP will print version number to the terminal and exit. +.RE +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +With this option \fBchronyd\fP will print a help message to the terminal and exit. +.RE +.SH "ENVIRONMENT VARIABLES" +.sp +\fBLISTEN_FDS\fP +.RS 4 +On Linux systems, the systemd service manager may pass file descriptors for +pre\-initialised sockets to \fBchronyd\fP. The service manager allocates and binds +the file descriptors, and passes a copy to each spawned instance of the +service. This allows for zero\-downtime service restarts as the sockets buffer +client requests until the service is able to handle them. The service manager +sets the LISTEN_FDS environment variable to the number of passed file +descriptors. +.RE +.SH "FILES" +.sp +\fI@SYSCONFDIR@/chrony.conf\fP +.SH "SEE ALSO" +.sp +\fBchronyc(1)\fP, \fBchrony.conf(5)\fP +.SH "BUGS" +.sp +For instructions on how to report bugs, please visit +.URL "https://chrony\-project.org/" "" "." +.SH "AUTHORS" +.sp +chrony was written by Richard Curnow, Miroslav Lichvar, and others.
\ No newline at end of file diff --git a/doc/faq.adoc b/doc/faq.adoc new file mode 100644 index 0000000..8fd350f --- /dev/null +++ b/doc/faq.adoc @@ -0,0 +1,1172 @@ +// This file is part of chrony +// +// Copyright (C) Richard P. Curnow 1997-2003 +// Copyright (C) Luke Valenta 2023 +// Copyright (C) Miroslav Lichvar 2014-2016, 2020-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. + += Frequently Asked Questions +:toc: +:numbered: + +== `chrony` compared to other programs + +=== How does `chrony` compare to `ntpd`? + +`chrony` and `ntpd` are two different implementations of the Network Time +Protocol (NTP). + +`chrony` is a newer implementation, which was designed to work well in a wider +range of conditions. It can usually synchronise the system clock faster and +with better time accuracy. It has many features, but it does not implement some +of the less useful NTP modes like broadcast client or multicast server/client. + +If your computer is connected to the Internet only for few minutes at a time, +the network connection is often congested, you turn your computer off or +suspend it frequently, the clock is not very stable (e.g. there are rapid +changes in the temperature or it is a virtual machine), or you want to use NTP +on an isolated network with no hardware reference clocks in sight, `chrony` +will probably work better for you. + +For a more detailed comparison of features and performance, see the +https://chrony-project.org/comparison.html[comparison page] on the `chrony` +website. + +=== Should I prefer `chrony` over `timesyncd` if I do not need to run a server? + +Generally, yes. + +`systemd-timesyncd` is a very simple NTP client included in the `systemd` +suite. It lacks almost all features of `chrony` and other advanced client +implementations listed on the +https://chrony-project.org/comparison.html[comparison page]. One of its main +limitations is that it cannot poll multiple servers at the same time and detect +servers having incorrect time (falsetickers in the NTP terminology). It should +be used only with trusted reliable servers, ideally in local network. + +Using `timesyncd` with `pool.ntp.org` is problematic. The pool is very +robust as a whole, but the individual servers run by volunteers cannot be +relied on. Occasionally, servers drift away or make a step to distant past or +future due to misconfiguration, problematic implementation, and other bugs +(e.g. in firmware of a GPS receiver). The pool monitoring system detects such +servers and quickly removes them from the pool DNS, but clients like +`timesyncd` cannot recover from that. They follow the server as long as it +claims to be synchronised. They need to be restarted in order to get a new +address from the pool DNS. + +Note that the complexity of NTP and clock synchronisation is on the client +side. The amount of code in `chrony` specific to NTP server is very small and +it is disabled by default. If it was removed, it would not significantly reduce +the amount of memory or storage needed. + +== Configuration issues + +=== What is the minimum recommended configuration for an NTP client? + +First, the client needs to know which NTP servers it should ask for the current +time. They are specified by the `server` or `pool` directive. The `pool` +directive is used with names that resolve to multiple addresses of different +servers. For reliable operation, the client should have at least three servers. + +The `iburst` option enables a burst of requests to speed up the initial +synchronisation. + +To stabilise the initial synchronisation on the next start, the estimated drift +of the system clock is saved to a file specified by the `driftfile` directive. + +If the system clock can be far from the true time after boot for any reason, +`chronyd` should be allowed to correct it quickly by stepping instead of +slewing, which would take a very long time. The `makestep` directive does +that. + +In order to keep the real-time clock (RTC) close to the true time, so the +system time is reasonably close to the true time when it is initialised on the +next boot from the RTC, the `rtcsync` directive enables a mode in which the +system time is periodically copied to the RTC. It is supported on Linux and +macOS. + +If you wanted to use public NTP servers from the +https://www.pool.ntp.org/[pool.ntp.org] project, the minimal _chrony.conf_ file +could be: + +---- +pool pool.ntp.org iburst +driftfile /var/lib/chrony/drift +makestep 1 3 +rtcsync +---- + +=== How do I make an NTP server? + +By default, `chronyd` does not operate as an NTP server. You need to add an +`allow` directive to the _chrony.conf_ file in order for `chronyd` to open the +server NTP port and respond to client requests. + +---- +allow 192.168.1.0/24 +---- + +An `allow` directive with no specified subnet allows access from all IPv4 and +IPv6 addresses. + +=== Should all computers on a LAN be clients of an external server? + +It depends on the requirements. Usually, the best configuration is to make one +computer the server, with the others as clients of it. Add a `local` directive +to the server's _chrony.conf_ file. This configuration will be better because + +* the load on the external connection is less +* the load on the external NTP server(s) is less +* if your external connection goes down, the computers on the LAN + will maintain a common time with each other. + +=== Must I specify servers by IP address if DNS is not available on `chronyd` start? + +No, `chronyd` will keep trying to resolve +the names specified by the `server`, `pool`, and `peer` directives in an +increasing interval until it succeeds. The `online` command can be issued from +`chronyc` to force `chronyd` to try to resolve the names immediately. + +=== How can I make `chronyd` more secure? + +If you do not need to use `chronyc`, or you want to run `chronyc` only +under the root or _chrony_ user (which can access `chronyd` through a Unix +domain socket), you can disable the IPv4 and IPv6 command sockets (by default +listening on localhost) by adding `cmdport 0` to the configuration file. + +You can specify an unprivileged user with the `-u` option, or the `user` +directive in the _chrony.conf_ file, to which `chronyd` will switch after start +in order to drop root privileges. The configure script has a `--with-user` +option, which sets the default user. On Linux, `chronyd` needs to be compiled +with support for the `libcap` library. On other systems, `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. + +Also, if `chronyd` is compiled with support for the Linux secure computing +(seccomp) facility, you can enable a system call filter with the `-F` option. +It will significantly reduce the kernel attack surface and possibly prevent +kernel exploits from the `chronyd` process if it is compromised. It is +recommended to enable the filter only when it is known to work on the version of +the system where `chrony` is installed as the filter needs to allow also system +calls made from libraries that `chronyd` is using (e.g. libc) and different +versions or implementations of the libraries might make different system calls. +If the filter is missing some system call, `chronyd` could be killed even in +normal operation. + +=== How can I make the system clock more secure? + +An NTP client synchronising the system clock to an NTP server is susceptible to +various attacks, which can break applications and network protocols relying on +accuracy of the clock (e.g. DNSSEC, Kerberos, TLS, WireGuard). + +Generally, a man-in-the-middle (MITM) attacker between the client and server +can + +* make fake responses, or modify real responses from the server, to create an + arbitrarily large time and frequency offset, make the server appear more + accurate, insert a leap second, etc. +* delay the requests and/or responses to create a limited time offset and + temporarily also a limited frequency offset +* drop the requests or responses to prevent updates of the clock with new + measurements +* redirect the requests to a different server + +The attacks can be combined for a greater effect. The attacker can delay +packets to create a significant frequency offset first and then drop all +subsequent packets to let the clock quickly drift away from the true time. +The attacker might also be able to control the server's clock. + +Some attacks cannot be prevented. Monitoring is needed for detection, e.g. the +reachability register in the `sources` report shows missing packets. The extent +to which the attacker can control the client's clock depends on its +configuration. + +Enable authentication to prevent `chronyd` from accepting modified, fake, or +redirected packets. It can be enabled with a symmetric key specified by the +`key` option, or Network Time Security (NTS) by the `nts` option (supported +since `chrony` version 4.0). The server needs to support the selected +authentication mechanism. Symmetric keys have to be configured on both client +and server, and each client must have its own key (one per server). + +The maximum offset that the attacker can insert in an NTP measurement by +delaying packets can be limited by the `maxdelay` option. The default value is +3 seconds. The measured delay is reported as the peer delay in the `ntpdata` +report and `measurements` log. Set the `maxdelay` option to a value larger than +the maximum value that is normally observed. Note that the delay can increase +significantly even when not under an attack, e.g. when the network is congested +or the routing has changed. + +The maximum accepted change in time offset between clock updates can be limited +by the `maxchange` directive. Larger changes in the offset will be ignored or +cause `chronyd` to exit. Note that the attacker can get around this limit by +splitting the offset into multiple smaller offsets and/or creating a large +frequency offset. When this directive is used, `chronyd` will have to be +restarted after a successful attack. It will not be able to recover on its own. +It must not be restarted automatically (e.g. by the service manager). + +The impact of a large accepted time offset can be reduced by disabling clock +steps, i.e. by not using the `makestep` and `initstepslew` directives. The +offset will be slowly corrected by speeding up or slowing down the clock at a +rate which can be limited by the `maxslewrate` directive. Disabling clock steps +completely is practical only if the clock cannot gain a larger error on its +own, e.g. when the computer is shut down or suspended, and the `maxslewrate` +limit is large enough to correct an expected error in an acceptable time. The +`rtcfile` directive with the `-s` option can be used to compensate for the RTC +drift. + +A more practical approach is to enable `makestep` for a limited number of clock +updates (the 2nd argument of the directive) and limit the offset change in all +updates by the `maxchange` directive. The attacker will be able to make only a +limited step and only if the attack starts in a short window after booting the +computer, or when `chronyd` is restarted without the `-R` option. + +The frequency offset can be limited by the `maxdrift` directive. The measured +frequency offset is reported in the drift file, `tracking` report, and +`tracking` log. Set `maxdrift` to a value larger than the maximum absolute +value that is normally observed. Note that the frequency of the clock can +change due to aging of the crystal, differences in calibration of the clock +source between reboots, migrated virtual machine, etc. A typical computer clock +has a drift smaller than 100 parts per million (ppm), but much larger drifts +are possible (e.g. in some virtual machines). + +Use only trusted servers, which you expect to be well configured and managed, +using authentication for their own servers, etc. Use multiple servers, ideally +in different locations. The attacker will have to deal with a majority of the +servers in order to pass the source selection and update the clock with a large +offset. Use the `minsources` directive to increase the required number of +selectable sources to make the selection more robust. + +Do not specify servers as peers. The symmetric mode is less secure than the +client/server mode. If not authenticated, it is vulnerable to off-path +denial-of-service attacks, and even when it is authenticated, it is still +susceptible to replay attacks. + +Mixing of authenticated and unauthenticated servers should generally be +avoided. If mixing is necessary (e.g. for a more accurate and stable +synchronisation to a closer server which does not support authentication), the +authenticated servers should be configured as trusted and required to not allow +the unauthenticated servers to override the authenticated servers in the source +selection. Since `chrony` version 4.0, the selection options are enabled in +such a case automatically. This behaviour can be disabled or modified by the +`authselectmode` directive. + +An example of a client configuration limiting the impact of the attacks could +be + +---- +server ntp1.example.net iburst nts maxdelay 0.1 +server ntp2.example.net iburst nts maxdelay 0.2 +server ntp3.example.net iburst nts maxdelay 0.05 +server ntp4.example.net iburst nts maxdelay 0.1 +server ntp5.example.net iburst nts maxdelay 0.1 +minsources 3 +maxchange 100 0 0 +makestep 0.001 1 +maxdrift 100 +maxslewrate 100 +driftfile /var/lib/chrony/drift +ntsdumpdir /var/lib/chrony +rtcsync +---- + +=== How can I improve the accuracy of the system clock with NTP sources? + +Select NTP servers that are well synchronised, stable and close to your +network. It is better to use more than one server. Three or four is usually +recommended as the minimum, so `chronyd` can detect servers that serve false +time and combine measurements from multiple sources. + +If you have a network card with hardware timestamping supported on Linux, it +can be enabled by the `hwtimestamp` directive. It should make local receive and +transmit timestamps of NTP packets much more stable and accurate. + +The `server` directive has some useful options: `minpoll`, `maxpoll`, +`polltarget`, `maxdelay`, `maxdelayratio`, `maxdelaydevratio`, `xleave`, +`filter`. + +The first three options set the minimum and maximum allowed polling interval, +and how should be the actual interval adjusted in the specified range. Their +default values are 6 (64 seconds) for `minpoll`, 10 (1024 seconds) for +`maxpoll` and 8 (samples) for `polltarget`. The default values should be used +for general servers on the Internet. With your own NTP servers, or if you have +permission to poll some servers more frequently, setting these options for +shorter polling intervals might significantly improve the accuracy of the +system clock. + +The optimal polling interval depends mainly on two factors, stability of the +network latency and stability of the system clock (which mainly depends on the +temperature sensitivity of the crystal oscillator and the maximum rate of the +temperature change). + +Generally, if the `sourcestats` command usually reports a small number of +samples retained for a source (e.g. fewer than 16), a shorter polling interval +should be considered. If the number of samples is usually at the maximum of 64, +a longer polling interval might work better. + +An example of the directive for an NTP server on the Internet that you are +allowed to poll frequently could be + +---- +server ntp.example.net minpoll 4 maxpoll 6 polltarget 16 +---- + +An example using shorter polling intervals with a server located in the same +LAN could be + +---- +server ntp.local minpoll 2 maxpoll 4 polltarget 30 +---- + +The maxdelay options are useful to ignore measurements with an unusually large +delay (e.g. due to congestion in the network) and improve the stability of the +synchronisation. The `maxdelaydevratio` option could be added to the example +with local NTP server + +---- +server ntp.local minpoll 2 maxpoll 4 polltarget 30 maxdelaydevratio 2 +---- + +If your server supports the interleaved mode (e.g. it is running `chronyd`), +the `xleave` option should be added to the `server` directive to enable the +server to provide the client with more accurate transmit timestamps (kernel or +preferably hardware). For example: + +---- +server ntp.local minpoll 2 maxpoll 4 xleave +---- + +When combined with local hardware timestamping, good network switches, and even +shorter polling intervals, a sub-microsecond accuracy and stability of a few +tens of nanoseconds might be possible. For example: + +---- +server ntp.local minpoll 0 maxpoll 0 xleave +hwtimestamp eth0 +---- + +For best stability, the CPU should be running at a constant frequency (i.e. +disabled power saving and performance boosting). Energy-Efficient Ethernet +(EEE) should be disabled in the network. The switches should be configured to +prioritize NTP packets, especially if the network is expected to be heavily +loaded. The `dscp` directive can be used to set the Differentiated Services +Code Point in transmitted NTP packets if needed. + +If it is acceptable for NTP clients in the network to send requests at a high +rate, a sub-second polling interval can be specified. A median filter +can be enabled in order to update the clock at a reduced rate with more stable +measurements. For example: + +---- +server ntp.local minpoll -6 maxpoll -6 filter 15 xleave +hwtimestamp eth0 minpoll -6 +---- + +Since `chrony` version 4.3, the minimum `minpoll` is -7 and a filter using a +long-term estimate of a delay quantile can be enabled by the `maxdelayquant` +option to replace the default `maxdelaydevratio` filter, which is sensitive to +outliers corrupting the minimum delay. For example: + +---- +server ntp.local minpoll -7 maxpoll -7 filter 31 maxdelayquant 0.3 xleave +---- + +Since version 4.2, `chronyd` supports an NTPv4 +extension field containing an additional timestamp to enable frequency transfer +and significantly improve stability of synchronisation. It can be enabled by +the `extfield F323` option. For example: + +---- +server ntp.local minpoll 0 maxpoll 0 xleave extfield F323 +---- + +Since version 4.5, `chronyd` can apply corrections from PTP one-step end-to-end +transparent clocks (e.g. network switches) to significantly improve accuracy of +synchronisation in local networks. It requires the PTP transport to be enabled +by the `ptpport` directive, HW timestamping, and the `extfield F324` option. +For example: + +---- +server ntp.local minpoll -4 maxpoll -4 xleave extfield F323 extfield F324 port 319 +ptpport 319 +hwtimestamp eth0 minpoll -4 +---- + +=== Does `chronyd` have an ntpdate mode? + +Yes. With the `-q` option `chronyd` will set the system clock once and exit. +With the `-Q` option it will print the measured offset without setting the +clock. If you do not want to use a configuration file, NTP servers can be +specified on the command line. For example: + +---- +# chronyd -q 'pool pool.ntp.org iburst' +---- + +The command above would normally take about 5 seconds if the servers were +well synchronised and responding to all requests. If not synchronised or +responding, it would take about 10 seconds for `chronyd` to give up and exit +with a non-zero status. A faster configuration is possible. A single server can +be used instead of four servers, the number of measurements can be reduced with +the `maxsamples` option to one (supported since `chrony` version 4.0), and a +timeout can be specified with the `-t` option. The following command would take +only up to about one second. + +---- +# chronyd -q -t 1 'server pool.ntp.org iburst maxsamples 1' +---- + +It is not recommended to run `chronyd` with the `-q` option periodically (e.g. +from a cron job) as a replacement for the daemon mode, because it performs +significantly worse (e.g. the clock is stepped and its frequency is not +corrected). If you must run it this way and you are using a public NTP server, +make sure `chronyd` does not always start around the first second of a minute, +e.g. by adding a random sleep before the `chronyd` command. Public servers +typically receive large bursts of requests around the first second as there is +a large number of NTP clients started from cron with no delay. + +=== Can `chronyd` be configured to control the clock like `ntpd`? + +It is not possible to perfectly emulate `ntpd`, but there are some options that +can configure `chronyd` to behave more like `ntpd` if there is a reason to +prefer that. + +In the following example the `minsamples` directive slows down the response to +changes in the frequency and offset of the clock. The `maxslewrate` and +`corrtimeratio` directives reduce the maximum frequency error due to an offset +correction and the `maxdrift` directive reduces the maximum assumed frequency +error of the clock. The `makestep` directive enables a step threshold and the +`maxchange` directive enables a panic threshold. The `maxclockerror` directive +increases the minimum dispersion rate. + +---- +minsamples 32 +maxslewrate 500 +corrtimeratio 100 +maxdrift 500 +makestep 0.128 -1 +maxchange 1000 1 1 +maxclockerror 15 +---- + +Note that increasing `minsamples` might cause the offsets in the `tracking` and +`sourcestats` reports/logs to be significantly smaller than the actual offsets +and be unsuitable for monitoring. + +=== Can NTP server be separated from NTP client? + +Yes, it is possible to run multiple instances of `chronyd` on a computer at the +same time. One can operate primarily as an NTP client to synchronise the system +clock and another as a server for other computers. If they use the same +filesystem, they need to be configured with different pidfiles, Unix domain +command sockets, and any other file or directory specified in the configuration +file. If they run in the same network namespace, they need to use different NTP +and command ports, or bind the ports to different addresses or interfaces. + +The server instance should be started with the `-x` option to prevent it from +adjusting the system clock and interfering with the client instance. It can be +configured as a client to synchronise its NTP clock to other servers, or the +client instance running on the same computer. In the latter case, the `copy` +option (added in `chrony` version 4.1) can be used to assume the reference ID +and stratum of the client instance, which enables detection of synchronisation +loops with its own clients. + +On Linux, starting with `chrony` version 4.0, it is possible to run multiple +server instances sharing a port to better utilise multiple cores of the CPU. +Note that for rate limiting and client/server interleaved mode to work well +it is necessary that all packets received from the same address are handled by +the same server instance. + +An example configuration of the client instance could be + +---- +pool pool.ntp.org iburst +allow 127.0.0.1 +port 11123 +driftfile /var/lib/chrony/drift +makestep 1 3 +rtcsync +---- + +and configuration of the first server instance could be + +---- +server 127.0.0.1 port 11123 minpoll 0 maxpoll 0 copy +allow +cmdport 11323 +bindcmdaddress /var/run/chrony/chronyd-server1.sock +pidfile /var/run/chronyd-server1.pid +driftfile /var/lib/chrony/drift-server1 +---- + +=== How can `chronyd` be configured to minimise downtime during restarts? + +The `dumpdir` directive in _chrony.conf_ provides `chronyd` a location to save +a measurement history of the sources it uses when the service exits. The `-r` +option then enables `chronyd` to load state from the dump files, reducing the +synchronisation time after a restart. + +Similarly, the `ntsdumpdir` directive provides a location for `chronyd` to save +NTS cookies received from the server to avoid making a NTS-KE request when +`chronyd` is started. When operating as an NTS server, `chronyd` also saves +cookies keys to this directory to allow clients to continue to use the old keys +after a server restart for a more seamless experience. + +On Linux systems, +https://www.freedesktop.org/software/systemd/man/latest/sd_listen_fds.html[systemd +socket activation] provides a mechanism to reuse server sockets across +`chronyd` restarts, so that client requests will be buffered until the service +is again able to handle the requests. This allows for zero-downtime service +restarts, simplified dependency logic at boot, and on-demand service spawning +(for instance, for separated server `chronyd` instances run with the `-x` +flag). + +Socket activation is supported since `chrony` version 4.5. +The service manager (systemd) creates sockets and +passes file descriptors to them to the process via the `LISTEN_FDS` environment +variable. Before opening new sockets, `chronyd` first checks for and attempts +to reuse matching sockets passed from the service manager. For instance, if an +IPv4 datagram socket bound on `bindaddress` and `port` is available, it will be +used by the NTP server to accept incoming IPv4 requests. + +An example systemd socket unit is below, where `chronyd` is configured with +`bindaddress 0.0.0.0`, `bindaddress ::`, `port 123`, and `ntsport 4460`. + +---- +[Unit] +Description=chronyd server sockets + +[Socket] +Service=chronyd.service +# IPv4 NTP server +ListenDatagram=0.0.0.0:123 +# IPv6 NTP server +ListenDatagram=[::]:123 +# IPv4 NTS-KE server +ListenStream=0.0.0.0:4460 +# IPv6 NTS-KE server +ListenStream=[::]:4460 +BindIPv6Only=ipv6-only + +[Install] +WantedBy=sockets.target +---- + +=== Should be a leap smear enabled on NTP server? + +With the `smoothtime` and `leapsecmode` directives it is possible to enable a +server leap smear in order to hide leap seconds from clients and force them to +follow a slow server's adjustment instead. + +This feature should be used only in local networks and only when necessary, +e.g. when the clients cannot be configured to handle the leap seconds as +needed, or their number is so large that configuring them all would be +impractical. The clients should use only one leap-smearing server, or multiple +identically configured leap-smearing servers. Note that some clients can get +leap seconds from other sources (e.g. with the `leapsectz` directive in +`chrony`) and they will not work correctly with a leap smearing server. + +=== How should `chronyd` be configured with `gpsd`? + +A GPS or other GNSS receiver can be used as a reference clock with `gpsd`. It +can work as one or two separate time sources for each connected receiver. The +first time source is based on timestamping of messages sent by the receiver. +Typically, it is accurate to milliseconds. The other source is much more +accurate. It is timestamping a pulse-per-second (PPS) signal, usually connected +to a serial port (e.g. DCD pin) or GPIO pin. + +If the PPS signal is connected to the serial port which is receiving messages +from the GPS/GNSS receiver, `gpsd` should detect and use it automatically. If +it is connected to a GPIO pin, or another serial port, the PPS device needs to +be specified on the command line as an additional data source. On Linux, the +`ldattach` utility can be used to create a PPS device for a serial device. + +The PPS-based time source provided by `gpsd` is available as a `SHM 1` +refclock, or other odd number if `gpsd` is configured with multiple receivers, +and also as `SOCK /var/run/chrony.DEV.sock` where `DEV` is the name of the +serial device (e.g. ttyS0). + +The message-based time source is available as a `SHM 0` refclock (or other even +number) and since `gpsd` version 3.25 also as +`SOCK /var/run/chrony.clk.DEV.sock` where `DEV` is the name of the serial +device. + +The SOCK refclocks should be preferred over SHM for better security +(the shared memory segment needs to be created by `chronyd` or `gpsd` with an +expected owner and permissions before an untrusted application or user has a +chance to create its own in order to feed `chronyd` with false measurements). +`gpsd` needs to be started after `chronyd` in order to connect to the socket. + +With `chronyd` and `gpsd` both supporting PPS, there are two different +recommended configurations: + +---- +# First option +refclock SOCK /var/run/chrony.ttyS0.sock refid GPS + +# Second option +refclock PPS /dev/pps0 lock NMEA refid GPS +refclock SOCK /var/run/chrony.clk.ttyS0.sock offset 0.5 delay 0.1 refid NMEA noselect +---- + +They both have some advantages: + +* `SOCK` can be more accurate than `PPS` if `gpsd` corrects for the + sawtooth error provided by the receiver in serial data +* `PPS` can be used with higher PPS rates (specified by the `rate` option), + but it requires a second refclock or another time source to pair pulses + with seconds, and the `SOCK` offset needs to be specified + <<using-pps-refclock,correctly>> to compensate for the message delay, while + `gpsd` can apply HW-specific information + +If the PPS signal is not available, or cannot be used for some reason, the only +option is the message-based timing + +---- +refclock SOCK /var/run/chrony.clk.ttyS0.sock offset 0.5 delay 0.1 refid GPS +---- + +or the SHM equivalent if using `gpsd` version before 3.25 + +---- +refclock SHM 0 offset 0.5 delay 0.1 refid GPS +---- + +=== Does `chrony` support PTP? + +No, the Precision Time Protocol (PTP) is not supported as a protocol for +synchronisation of clocks and there are no plans +to support it. It is a complex protocol, which shares some issues with the +NTP broadcast mode. One of the main differences between NTP and PTP is that PTP +was designed to be easily supported in hardware (e.g. network switches and +routers) in order to make more stable and accurate measurements. PTP relies on +the hardware support. NTP does not rely on any support in the hardware, but if +it had the same support as PTP, it could perform equally well. + +On Linux, `chrony` supports hardware clocks that some NICs have for PTP. They +are called PTP hardware clocks (PHC). They can be used as reference clocks +(specified by the `refclock` directive) and for hardware timestamping of NTP +packets (enabled by the `hwtimestamp` directive) if the NIC can timestamp other +packets than PTP, which is usually the case at least for transmitted packets. +The `ethtool -T` command can be used to verify the timestamping support. + +As an experimental feature added in version 4.2, `chrony` can use PTP as a +transport for NTP messages (NTP over PTP) to enable hardware timestamping on +hardware which can timestamp PTP packets only. It can be enabled by the +`ptpport` directive. Since version 4.5, `chrony` can also apply corrections +provided by PTP one-step end-to-end transparent clocks to reach the accuracy of +ordinary PTP clocks. The application of PTP corrections can be enabled by the +`extfield F324` option. + +=== How can I avoid using wrong PHC refclock? + +If your system has multiple PHC devices, normally named by `udev` as +_/dev/ptp0_, _/dev/ptp1_, and so on, their order can change randomly across +reboots depending on the order of initialisation of their drivers. If a PHC +refclock is specified by this name, `chronyd` could be using a wrong refclock +after reboot. To prevent that, you can configure `udev` to create a stable +symlink for `chronyd` with a rule like this (e.g. written to +_/etc/udev/rules.d/80-phc.rules_): + +---- +KERNEL=="ptp[0-9]*", DEVPATH=="/devices/pci0000:00/0000:00:01.2/0000:02:00.0/ptp/*", SYMLINK+="ptp-i350-1" +---- + +You can get the full _DEVPATH_ of an existing PHC device with the `udevadm +info` command. You will need to execute the `udevadm trigger` command, or +reboot the system, for these changes to take effect. + +=== Why are client log records dropped before reaching `clientloglimit`? + +The number of dropped client log records reported by the `serverstats` command +can be increasing before the number of clients reported by the `clients` command +reaches the maximum value corresponding to the memory limit set by the +`clientloglimit` directive. + +This is due to the design of the data structure keeping the client records. It +is a hash table which can store only up to 16 colliding addresses per slot. If +a slot has more collisions and the table already has the maximum size, the +oldest record will be dropped and replaced by the new client. + +Note that the size of the table is always a power of two and it can only grow. +The limit set by the `clientloglimit` directive takes into account that two +copies of the table exist when it is being resized. This means the actual +memory usage reported by `top` and other utilities can be significantly smaller +than the limit even when the maximum number of records is used. + +The absolute maximum number of client records kept at the same time is +16777216. + +=== What happened to the `commandkey` and `generatecommandkey` directives? + +They were removed in version 2.2. Authentication is no longer supported in the +command protocol. Commands that required authentication are now allowed only +through a Unix domain socket, which is accessible only by the root and _chrony_ +users. If you need to configure `chronyd` remotely or locally without the root +password, please consider using ssh and/or sudo to run `chronyc` under the root +or _chrony_ user on the host where `chronyd` is running. + +== Computer is not synchronising + +This is the most common problem. There are a number of reasons, see the +following questions. + +=== Behind a firewall? + +Check the `Reach` value printed by the ``chronyc``'s `sources` command. If it +is zero, it means `chronyd` did not get any valid responses from the NTP server +you are trying to use. If there is a firewall between you and the server, the +requests sent to the UDP port 123 of the server or responses sent back from +the port might be blocked. Try using a tool like `wireshark` or `tcpdump` to +see if you are getting any responses from the server. + +When `chronyd` is receiving responses from the servers, the output of the +`sources` command issued few minutes after `chronyd` start might look like +this: + +---- +MS Name/IP address Stratum Poll Reach LastRx Last sample +=============================================================================== +^* ntp1.example.net 2 6 377 34 +484us[ -157us] +/- 30ms +^- ntp2.example.net 2 6 377 34 +33ms[ +32ms] +/- 47ms +^+ ntp3.example.net 3 6 377 35 -1397us[-2033us] +/- 60ms +---- + +=== Are NTP servers specified with the `offline` option? + +Check that the ``chronyc``'s `online` and `offline` commands are used +appropriately (e.g. in the system networking scripts). The `activity` command +prints the number of sources that are currently online and offline. For +example: + +---- +200 OK +3 sources online +0 sources offline +0 sources doing burst (return to online) +0 sources doing burst (return to offline) +0 sources with unknown address +---- + +=== Is name resolution working correctly? + +NTP servers specified by their hostname (instead of an IP address) have to have +their names resolved before `chronyd` can send any requests to them. If the +`activity` command prints a non-zero number of sources with unknown address, +there is an issue with the resolution. Typically, a DNS server is specified in +_/etc/resolv.conf_. Make sure it is working correctly. + +Since `chrony` version 4.0, you can run `chronyc -N sources -a` command to +print all sources, even those that do not have a known address yet, with their +names as they were specified in the configuration. This can be useful to verify +that the names specified in the configuration are used as expected. + +=== Is `chronyd` allowed to step the system clock? + +By default, `chronyd` adjusts the clock gradually by slowing it down or +speeding it up. If the clock is too far from the true time, it will take +a long time to correct the error. The `System time` value printed by the +``chronyc``'s `tracking` command is the remaining correction that needs to be +applied to the system clock. + +The `makestep` directive can be used to allow `chronyd` to step the clock. For +example, if _chrony.conf_ had + +---- +makestep 1 3 +---- + +the clock would be stepped in the first three updates if its offset was larger +than one second. Normally, it is recommended to allow the step only in the first +few updates, but in some cases (e.g. a computer without an RTC or virtual +machine which can be suspended and resumed with an incorrect time) it might be +necessary to allow the step on any clock update. The example above would change +to + +---- +makestep 1 -1 +---- + +=== Using NTS? + +The Network Time Security (NTS) mechanism uses Transport Layer Security (TLS) +to establish the keys needed for authentication of NTP packets. + +Run the `authdata` command to check whether the key establishment was +successful: + +---- +# chronyc -N authdata +Name/IP address Mode KeyID Type KLen Last Atmp NAK Cook CLen +========================================================================= +ntp1.example.net NTS 1 15 256 33m 0 0 8 100 +ntp2.example.net NTS 1 15 256 33m 0 0 8 100 +ntp3.example.net NTS 1 15 256 33m 0 0 8 100 +---- + +The KeyID, Type, and KLen columns should have non-zero values. If they are +zero, check the system log for error messages from `chronyd`. One possible +cause of failure is a firewall blocking the client's connection to the server's +TCP port 4460. + +Another possible cause of failure is a certificate that is failing to verify +because the client's clock is wrong. This is a chicken-and-egg problem with NTS. +You might need to manually correct the date, or temporarily disable NTS, in +order to get NTS working. If your computer has an RTC and it is backed up by a +good battery, this operation should be needed only once, assuming the RTC will +be set periodically with the `rtcsync` directive, or compensated with the +`rtcfile` directive and the `-s` option. + +If the computer does not have an RTC or battery, you can use the `-s` option +without `rtcfile` directive to restore time of the last shutdown or reboot from +the drift file. The clock will start behind the true time, but if the computer +was not shut down for too long and the server's certificate was not renewed too +close to its expiration, it should be sufficient for the time checks to +succeed. + +If you run your own server, you can use a self-signed certificate covering +all dates where the client can start (e.g. years 1970-2100). The certificate +needs to be installed on the client and specified with the `ntstrustedcerts` +directive. The server can have multiple names and certificates. To avoid +trusting a certificate for too long, a new certificate can be added to the +server periodically (e.g. once per year) and the client can have the server +name and trusted certificate updated automatically (e.g. using a package +repository, or a cron script downloading the files directly from the server +over HTTPS). A client that was shut down for years will still be able to +synchronise its clock and perform the update as long as the server keeps +the old certificate. + +As a last resort, you can disable the time checks by the `nocerttimecheck` +directive. This has some important security implications. To reduce the +security risk, you can use the `nosystemcert` and `ntstrustedcerts` directives +to disable the system's default trusted certificate authorities and trust only +a minimal set of selected authorities needed to validate the certificates of +used NTP servers. + +=== Using a Windows NTP server? + +A common issue with Windows NTP servers is that they report a very large root +dispersion (e.g. three seconds or more), which causes `chronyd` to ignore the +server for being too inaccurate. The `sources` command might show a valid +measurement, but the server is not selected for synchronisation. You can check +the root dispersion of the server with the ``chronyc``'s `ntpdata` command. + +The `maxdistance` value needs to be increased in _chrony.conf_ to enable +synchronisation to such a server. For example: + +---- +maxdistance 16.0 +---- + +=== An unreachable source is selected? + +When `chronyd` is configured with multiple time sources, it tries to select the +most accurate and stable sources for synchronisation of the system clock. They +are marked with the _*_ or _+_ symbol in the report printed by the `sources` +command. + +When the best source (marked with the _*_ symbol) becomes unreachable (e.g. NTP +server stops responding), `chronyd` will not immediately switch +to the second best source in an attempt to minimise the error of the clock. It +will let the clock run free for as long as its estimated error (in terms of +root distance) based on previous measurements is smaller than the estimated +error of the second source, and there is still an interval which contains some +measurements from both sources. + +If the first source was significantly better than the second source, it can +take many hours before the second source is selected, depending on its polling +interval. You can force a faster reselection by increasing the clock error rate +(`maxclockerror` directive), shortening the polling interval (`maxpoll` +option), or reducing the number of samples (`maxsamples` option). + +=== Does selected source drop new measurements? + +`chronyd` can drop a large number of successive NTP measurements if they are +not passing some of the NTP tests. The `sources` command can report for a +selected source the fully-reachable value of 377 in the Reach column and at the +same time a LastRx value that is much larger than the current polling interval. +If the source is online, this indicates that a number of measurements was +dropped. You can use the `ntpdata` command to check the NTP tests for the last +measurement. Usually, it is the test C which fails. + +This can be an issue when there is a long-lasting increase in the measured +delay, e.g. due to a routing change in the network. Unfortunately, `chronyd` +does not know for how long it should wait for the delay to come back to the +original values, or whether it is a permanent increase and it should start from +scratch. + +The test C is an adaptive filter. It can take many hours before it accepts +a measurement with the larger delay, and even much longer before it drops all +measurements with smaller delay, which determine an expected delay used by the +test. You can use the `reset sources` command to drop all measurements +immediately (available in chrony 4.0 and later). If this issue happens +frequently, you can effectively disable the test by setting the +`maxdelaydevratio` option to a very large value (e.g. 1000000), or speed up the +recovery by increasing the clock error rate with the `maxclockerror` directive. + +[[using-pps-refclock]] +=== Using a PPS reference clock? + +A pulse-per-second (PPS) reference clock requires a non-PPS time source to +determine which second of UTC corresponds to each pulse. If it is another +reference clock specified with the `lock` option in the `refclock` directive, +the offset between the two reference clocks must be smaller than 0.4 seconds +(0.2 seconds with `chrony` versions before 4.1) in +order for the PPS reference clock to work. With NMEA reference clocks it is +common to have a larger offset. It needs to be corrected with the `offset` +option. + +One approach to find out a good value of the `offset` option is to configure +the reference clocks with the `noselect` option and compare them to an NTP +server. For example, if the `sourcestats` command showed + +---- +Name/IP Address NP NR Span Frequency Freq Skew Offset Std Dev +============================================================================== +PPS0 0 0 0 +0.000 2000.000 +0ns 4000ms +NMEA 58 30 231 -96.494 38.406 +504ms 6080us +ntp1.example.net 7 3 200 -2.991 16.141 -107us 492us +---- + +the offset of the NMEA source would need to be increased by about 0.504 +seconds. It does not have to be very accurate. As long as the offset of the +NMEA reference clock stays below the limit, the PPS reference clock should be +able to determine the seconds corresponding to the pulses and allow the samples +to be used for synchronisation. + +== Issues with `chronyc` + +=== I keep getting the error `506 Cannot talk to daemon` + +When accessing `chronyd` remotely, make sure that the _chrony.conf_ file (on +the computer where `chronyd` is running) has a `cmdallow` entry for the +computer you are running `chronyc` on and an appropriate `bindcmdaddress` +directive. This is not necessary for localhost. + +Perhaps `chronyd` is not running. Try using the `ps` command (e.g. on Linux, +`ps -auxw`) to see if it is running. Or try `netstat -a` and see if the UDP +port 323 is listening. If `chronyd` is not running, you might have a problem +with the way you are trying to start it (e.g. at boot time). + +Perhaps you have a firewall set up in a way that blocks packets on the UDP +port 323. You need to amend the firewall configuration in this case. + +=== I keep getting the error `501 Not authorised` + +This error indicates that `chronyc` sent the command to `chronyd` using a UDP +socket instead of the Unix domain socket (e.g. _/var/run/chrony/chronyd.sock_), +which is required for some commands. For security reasons, only the root and +_chrony_ users are allowed to access the socket. + +It is also possible that the socket does not exist. `chronyd` will not create +the socket if the directory has a wrong owner or permissions. In this case +there should be an error message from `chronyd` in the system log. + +=== What is the reference ID reported by the `tracking` command? + +The reference ID is a 32-bit value used in NTP to prevent synchronisation +loops. + +In `chrony` versions before 3.0 it was printed in the +quad-dotted notation, even if the reference source did not actually have an +IPv4 address. For IPv4 addresses, the reference ID is equal to the address, but +for IPv6 addresses it is the first 32 bits of the MD5 sum of the address. For +reference clocks, the reference ID is the value specified with the `refid` +option in the `refclock` directive. + +Since version 3.0, the reference ID is printed as a hexadecimal number to avoid +confusion with IPv4 addresses. + +If you need to get the IP address of the current reference source, use the `-n` +option to disable resolving of IP addresses and read the second field (printed +in parentheses) on the `Reference ID` line. + +=== Is the `chronyc` / `chronyd` protocol documented anywhere? + +Only by the source code. See _cmdmon.c_ (`chronyd` side) and _client.c_ +(`chronyc` side). + +Note that this protocol is not compatible with the mode 6 or mode 7 protocol +supported by `ntpd`, i.e. the `ntpq` or `ntpdc` utility cannot be used to +monitor `chronyd`, and `chronyc` cannot be used to monitor `ntpd`. + +== Real-time clock issues + +=== What is the real-time clock (RTC)? + +This is the clock which keeps the time even when your computer is turned off. +It is used to initialise the system clock on boot. It normally does not drift +more than few seconds per day. + +There are two approaches how `chronyd` can work with it. One is to use the +`rtcsync` directive, which tells `chronyd` to enable a kernel mode which sets +the RTC from the system clock every 11 minutes. `chronyd` itself will not touch +the RTC. If the computer is not turned off for a long time, the RTC should +still be close to the true time when the system clock will be initialised from +it on the next boot. + +The other option is to use the `rtcfile` directive, which tells `chronyd` to +monitor the rate at which the RTC gains or loses time. When `chronyd` is +started with the `-s` option on the next boot, it will set the system time from +the RTC and also compensate for the drift it has measured previously. The +`rtcautotrim` directive can be used to keep the RTC close to the true time, but +it is not strictly necessary if its only purpose is to set the system clock when +`chronyd` is started on boot. See the documentation for details. + +=== Does `hwclock` have to be disabled? + +The `hwclock` program is run by default in the boot and/or shutdown +scripts in some Linux installations. With the kernel RTC synchronisation +(`rtcsync` directive), the RTC will be set also every 11 minutes as long as the +system clock is synchronised. If you want to use ``chronyd``'s RTC monitoring +(`rtcfile` directive), it is important to disable `hwclock` in the shutdown +procedure. If you do not do that, it will overwrite the RTC with a new value, unknown +to `chronyd`. At the next reboot, `chronyd` started with the `-s` option will +compensate this (wrong) time with its estimate of how far the RTC has drifted +whilst the power was off, giving a meaningless initial system time. + +There is no need to remove `hwclock` from the boot process, as long as `chronyd` +is started after it has run. + +=== I just keep getting the `513 RTC driver not running` message + +For the real-time clock support to work, you need the following three +things + +* an RTC in your computer +* a Linux kernel with enabled RTC support +* an `rtcfile` directive in your _chrony.conf_ file + +=== I get `Could not open /dev/rtc, Device or resource busy` in my syslog file + +Some other program running on the system might be using the device. + +=== When I start `chronyd`, the log says `Could not enable RTC interrupt : Invalid argument` (or it may say `disable`) + +Your real-time clock hardware might not support the required ioctl requests: + +* `RTC_UIE_ON` +* `RTC_UIE_OFF` + +A possible solution could be to build the Linux kernel with support for software +emulation instead; try enabling the following configuration option when building +the Linux kernel: + +* `CONFIG_RTC_INTF_DEV_UIE_EMUL` + +=== What if my computer does not have an RTC or backup battery? + +In this case you can still use the `-s` option to set the system clock to the +last modification time of the drift file, which should correspond to the system +time when `chronyd` was previously stopped. The initial system time will be +increasing across reboots and applications started after `chronyd` will not +observe backward steps. + +== NTP-specific issues + +=== Can `chronyd` be driven from broadcast/multicast NTP servers? + +No, the broadcast/multicast client mode is not supported and there is currently +no plan to implement it. While this mode can simplify configuration +of clients in large networks, it is inherently less accurate and less secure +(even with authentication) than the ordinary client/server mode. + +When configuring a large number of clients in a network, it is recommended to +use the `pool` directive with a DNS name which resolves to addresses of +multiple NTP servers. The clients will automatically replace the servers when +they become unreachable, or otherwise unsuitable for synchronisation, with new +servers from the pool. + +Even with very modest hardware, an NTP server can serve time to hundreds of +thousands of clients using the ordinary client/server mode. + +=== Can `chronyd` transmit broadcast NTP packets? + +Yes, the `broadcast` directive can be used to enable the broadcast server mode +to serve time to clients in the network which support the broadcast client mode +(it is not supported in `chronyd`). Note that this mode should generally be +avoided. See the previous question. + +=== Can `chronyd` keep the system clock a fixed offset away from real time? + +Yes. Starting from version 3.0, an offset can be specified by the `offset` +option for all time sources in the _chrony.conf_ file. + +=== What happens if the network connection is dropped without using ``chronyc``'s `offline` command first? + +`chronyd` will keep trying to access the sources that it thinks are online, and +it will take longer before new measurements are actually made and the clock is +corrected when the network is connected again. If the sources were set to +offline, `chronyd` would make new measurements immediately after issuing the +`online` command. + +Unless the network connection lasts only few minutes (less than the maximum +polling interval), the delay is usually not a problem, and it might be acceptable +to keep all sources online all the time. + +=== Why is an offset measured between two computers synchronised to each another? + +When two computers are synchronised to each other using the client/server or +symmetric NTP mode, there is an expectation that NTP measurements between the +two computers made on both ends show an average offset close to zero. + +With `chronyd` that can be expected only when the interleaved mode is enabled +by the `xleave` option. Otherwise, `chronyd` will use different transmit +timestamps (e.g. daemon timestamp vs kernel timestamp) for serving time and +synchronisation of its own clock, which will cause the other computer to +measure a significant offset. + +== Operation + +=== What clocks does `chronyd` use? + +There are several different clocks used by `chronyd`: + +* *System clock:* software clock maintained by the kernel. It is the main clock + used by applications running on the computer. It is synchronised by `chronyd` + to its NTP clock, unless started with the *-x* option. +* *NTP clock:* software clock (virtual) based on the system clock and internal + to `chronyd`. It keeps the best estimate of the true time according to the + configured time sources, which is served to NTP clients unless time smoothing + is enabled by the *smoothtime* directive. The *System time* value in the + `tracking` report is the current offset between the system and NTP clock. +* *Real-time clock (RTC):* hardware clock keeping time even when the + computer is turned off. It is used by the kernel to initialise the system + clock on boot and also by `chronyd` to compensate for its measured drift if + configured with the `rtcfile` directive and started with the `-s` option. + The clock can be kept accurate only by stepping enabled by the `rtcsync` or + `rtcautotrim` directive. +* *Reference clock:* hardware clock used as a time source. It is specified by + the `refclock` directive. +* *NIC clock (also known as PTP hardware clock):* hardware clock timestamping + packets received and transmitted by a network device specified by the + *hwtimestamp* directive. The clock is expected to be running free. It is not + synchronised by `chronyd`. Its offset is tracked relative to the NTP clock in + order to convert the hardware timestamps. + +== Operating systems + +=== Does `chrony` support Windows? + +No. The `chronyc` program (the command-line client used for configuring +`chronyd` while it is running) has been successfully built and run under +Cygwin in the past. `chronyd` is not portable, because part of it is +very system-dependent. It needs adapting to work with Windows' +equivalent of the adjtimex() call, and it needs to be made to work as a +service. + +=== Are there any plans to support Windows? + +We have no plans to do this. Anyone is welcome to pick this work up and +contribute it back to the project. diff --git a/doc/installation.adoc b/doc/installation.adoc new file mode 100644 index 0000000..b683911 --- /dev/null +++ b/doc/installation.adoc @@ -0,0 +1,200 @@ +// This file is part of chrony +// +// Copyright (C) Richard P. Curnow 1997-2003 +// Copyright (C) Miroslav Lichvar 2009-2016 +// +// 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. + += Installation + +The software is distributed as source code which has to be compiled. The source +code is supplied in the form of a gzipped tar file, which unpacks to a +subdirectory identifying the name and version of the program. + +A C compiler (e.g. `gcc` or `clang`) and GNU Make are needed to build `chrony`. +The following libraries with their development files, and programs, are needed +to enable optional features: + +* pkg-config: detection of development libraries +* Nettle, GnuTLS, NSS, or LibTomCrypt: secure hash functions (`SECHASH`) +* libcap: dropping root privileges on Linux (`DROPROOT`) +* libseccomp: system call filter on Linux (`SCFILTER`) +* GnuTLS and Nettle: Network Time Security (`NTS`) +* Editline: line editing in `chronyc` (`READLINE`) +* timepps.h header: PPS reference clock +* Asciidoctor: documentation in HTML format +* Bash: test suite + +The following programs are needed when building `chrony` from the git +repository instead of a released tar file: + +* Asciidoctor: manual pages +* Bison: parser for chronyc settime command + +After unpacking the source code, change directory into it, and type + +---- +./configure +---- + +This is a shell script that automatically determines the system type. There is +an optional parameter `--prefix`, which indicates the directory tree where the +software should be installed. For example, + +---- +./configure --prefix=/opt/free +---- + +will install the `chronyd` daemon into `/opt/free/sbin` and the `chronyc` +control program into `/opt/free/bin`. The default value for the prefix is +`/usr/local`. + +The `configure` script assumes you want to use `gcc` as your compiler. If you +want to use a different compiler, you can configure this way: + +---- +CC=cc ./configure --prefix=/opt/free +---- + +for Bourne-family shells, or + +---- +setenv CC cc +setenv CFLAGS -O +./configure --prefix=/opt/free +---- + +for C-family shells. + +If the software cannot (yet) be built on your system, an error message will be +shown. Otherwise, `Makefile` will be generated. + +On Linux, if development files for the libcap library are available, `chronyd` +will be built with support for dropping root privileges. On other systems no +extra library is needed. The default user which `chronyd` should run as can be +specified with the `--with-user` option of the `configure` script. + +If development files for the POSIX threads library are available, `chronyd` +will be built with support for asynchronous resolving of hostnames specified in +the `server`, `peer`, and `pool` directives. This allows `chronyd` operating as +a server to respond to client requests when resolving a hostname. If you don't +want to enable the support, specify the `--disable-asyncdns` flag to +`configure`. + +If development files for the https://www.lysator.liu.se/~nisse/nettle/[Nettle], +https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS[NSS], or +https://www.libtom.net/LibTomCrypt/[libtomcrypt] library are available, +`chronyd` will be built with support for other cryptographic hash functions +than MD5, which can be used for NTP authentication with a symmetric key. If you +don't want to enable the support, specify the `--disable-sechash` flag to +`configure`. + +If development files for the editline library are available, +`chronyc` will be built with line editing support. If you don't want this, +specify the `--disable-readline` flag to `configure`. + +If a `timepps.h` header is available (e.g. from the +http://linuxpps.org[LinuxPPS project]), `chronyd` will be built with PPS API +reference clock driver. If the header is installed in a location that isn't +normally searched by the compiler, you can add it to the searched locations by +setting the `CPPFLAGS` variable to `-I/path/to/timepps`. + +The `--help` option can be specified to `configure` to print all options +supported by the script. + +Now type + +---- +make +---- + +to build the programs. + +If you want to build the manual in HTML, type + +---- +make docs +---- + +Once the programs have been successfully compiled, they need to be installed in +their target locations. This step normally needs to be performed by the +superuser, and requires the following command to be entered. + +---- +make install +---- + +This will install the binaries and man pages. + +To install the HTML version of the manual, enter the command + +---- +make install-docs +---- + +Now that the software is successfully installed, the next step is to set up a +configuration file. The default location of the file is _/etc/chrony.conf_. +Several examples of configuration with comments are included in the examples +directory. Suppose you want to use public NTP servers from the pool.ntp.org +project as your time reference. A minimal useful configuration file could be + +---- +pool pool.ntp.org iburst +makestep 1.0 3 +rtcsync +---- + +Then, `chronyd` can be run. For security reasons, it's recommended to create an +unprivileged user for `chronyd` and specify it with the `-u` command-line +option or the `user` directive in the configuration file, or set the default +user with the `--with-user` configure option before building. + +== Support for system call filtering + +`chronyd` can be built with support for the Linux secure computing (seccomp) +facility. This requires development files for the +https://github.com/seccomp/libseccomp[libseccomp] library and the +`--enable-scfilter` option specified to `configure`. The `-F` option of +`chronyd` will enable a system call filter, which should significantly reduce +the kernel attack surface and possibly prevent kernel exploits from `chronyd` +if it is compromised. + +== Extra options for package builders + +The `configure` and `make` procedures have some extra options that may be +useful if you are building a distribution package for `chrony`. + +The `--mandir=DIR` option to `configure` specifies an installation directory +for the man pages. This overrides the `man` subdirectory of the argument to the +`--prefix` option. + +---- +./configure --prefix=/usr --mandir=/usr/share/man +---- + +to set both options together. + +The final option is the `DESTDIR` option to the `make` command. For example, +you could use the commands + +---- +./configure --prefix=/usr --mandir=/usr/share/man +make all docs +make install DESTDIR=./tmp +cd tmp +tar cvf - . | gzip -9 > chrony.tar.gz +---- + +to build a package. When untarred within the root directory, this will install +the files to the intended final locations. |