diff options
Diffstat (limited to 'doc/faq.adoc')
| -rw-r--r-- | doc/faq.adoc | 1172 |
1 files changed, 1172 insertions, 0 deletions
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. |