Adding upstream version 4.5.upstream/4.5

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

1 files changed, 1159 insertions, 0 deletions

diff --git a/FAQ b/FAQ
new file mode 100644
index 0000000..c96acfa
--- /dev/null
+++ b/FAQ
@@ -0,0 +1,1159 @@
+Frequently Asked Questions
+
+Table of Contents
+
+  o 1. chrony compared to other programs
+      ? 1.1. How does chrony compare to ntpd?
+      ? 1.2. Should I prefer chrony over timesyncd if I do not need to run a
+        server?
+  o 2. Configuration issues
+      ? 2.1. What is the minimum recommended configuration for an NTP client?
+      ? 2.2. How do I make an NTP server?
+      ? 2.3. Should all computers on a LAN be clients of an external server?
+      ? 2.4. Must I specify servers by IP address if DNS is not available on
+        chronyd start?
+      ? 2.5. How can I make chronyd more secure?
+      ? 2.6. How can I make the system clock more secure?
+      ? 2.7. How can I improve the accuracy of the system clock with NTP
+        sources?
+      ? 2.8. Does chronyd have an ntpdate mode?
+      ? 2.9. Can chronyd be configured to control the clock like ntpd?
+      ? 2.10. Can NTP server be separated from NTP client?
+      ? 2.11. How can chronyd be configured to minimise downtime during
+        restarts?
+      ? 2.12. Should be a leap smear enabled on NTP server?
+      ? 2.13. How should chronyd be configured with gpsd?
+      ? 2.14. Does chrony support PTP?
+      ? 2.15. How can I avoid using wrong PHC refclock?
+      ? 2.16. Why are client log records dropped before reaching
+        clientloglimit?
+      ? 2.17. What happened to the commandkey and generatecommandkey
+        directives?
+  o 3. Computer is not synchronising
+      ? 3.1. Behind a firewall?
+      ? 3.2. Are NTP servers specified with the offline option?
+      ? 3.3. Is name resolution working correctly?
+      ? 3.4. Is chronyd allowed to step the system clock?
+      ? 3.5. Using NTS?
+      ? 3.6. Using a Windows NTP server?
+      ? 3.7. An unreachable source is selected?
+      ? 3.8. Does selected source drop new measurements?
+      ? 3.9. Using a PPS reference clock?
+  o 4. Issues with chronyc
+      ? 4.1. I keep getting the error 506 Cannot talk to daemon
+      ? 4.2. I keep getting the error 501 Not authorised
+      ? 4.3. What is the reference ID reported by the tracking command?
+      ? 4.4. Is the chronyc / chronyd protocol documented anywhere?
+  o 5. Real-time clock issues
+      ? 5.1. What is the real-time clock (RTC)?
+      ? 5.2. Does hwclock have to be disabled?
+      ? 5.3. I just keep getting the 513 RTC driver not running message
+      ? 5.4. I get Could not open /dev/rtc, Device or resource busy in my
+        syslog file
+      ? 5.5. When I start chronyd, the log says Could not enable RTC interrupt
+        : Invalid argument (or it may say disable)
+      ? 5.6. What if my computer does not have an RTC or backup battery?
+  o 6. NTP-specific issues
+      ? 6.1. Can chronyd be driven from broadcast/multicast NTP servers?
+      ? 6.2. Can chronyd transmit broadcast NTP packets?
+      ? 6.3. Can chronyd keep the system clock a fixed offset away from real
+        time?
+      ? 6.4. What happens if the network connection is dropped without using
+        chronyc's offline command first?
+      ? 6.5. Why is an offset measured between two computers synchronised to
+        each another?
+  o 7. Operation
+      ? 7.1. What clocks does chronyd use?
+  o 8. Operating systems
+      ? 8.1. Does chrony support Windows?
+      ? 8.2. Are there any plans to support Windows?
+
+1. chrony compared to other programs
+
+1.1. 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 comparison
+page on the chrony website.
+
+1.2. 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 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.
+
+2. Configuration issues
+
+2.1. 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 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
+
+2.2. 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.
+
+2.3. 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
+
+  o the load on the external connection is less
+
+  o the load on the external NTP server(s) is less
+
+  o if your external connection goes down, the computers on the LAN will
+    maintain a common time with each other.
+
+2.4. 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.
+
+2.5. 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.
+
+2.6. 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
+
+  o 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.
+
+  o delay the requests and/or responses to create a limited time offset and
+    temporarily also a limited frequency offset
+
+  o drop the requests or responses to prevent updates of the clock with new
+    measurements
+
+  o 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
+
+2.7. 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
+
+2.8. 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.
+
+2.9. 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.
+
+2.10. 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
+
+2.11. 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, 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
+
+2.12. 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.
+
+2.13. 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:
+
+  o SOCK can be more accurate than PPS if gpsd corrects for the sawtooth error
+    provided by the receiver in serial data
+
+  o 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 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
+
+2.14. 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.
+
+2.15. 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.
+
+2.16. 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.
+
+2.17. 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.
+
+3. Computer is not synchronising
+
+This is the most common problem. There are a number of reasons, see the
+following questions.
+
+3.1. 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
+
+3.2. 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
+
+3.3. 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.
+
+3.4. 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
+
+3.5. 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.
+
+3.6. 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
+
+3.7. 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).
+
+3.8. 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.
+
+3.9. 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.
+
+4. Issues with chronyc
+
+4.1. 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.
+
+4.2. 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.
+
+4.3. 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.
+
+4.4. 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.
+
+5. Real-time clock issues
+
+5.1. 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.
+
+5.2. 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.
+
+5.3. 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
+
+  o an RTC in your computer
+
+  o a Linux kernel with enabled RTC support
+
+  o an rtcfile directive in your chrony.conf file
+
+5.4. 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.
+
+5.5. 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:
+
+  o RTC_UIE_ON
+
+  o 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:
+
+  o CONFIG_RTC_INTF_DEV_UIE_EMUL
+
+5.6. 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.
+
+6. NTP-specific issues
+
+6.1. 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.
+
+6.2. 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.
+
+6.3. 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.
+
+6.4. 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.
+
+6.5. 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.
+
+7. Operation
+
+7.1. What clocks does chronyd use?
+
+There are several different clocks used by chronyd:
+
+  o 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.
+
+  o 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.
+
+  o 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.
+
+  o Reference clock: hardware clock used as a time source. It is specified by
+    the refclock directive.
+
+  o 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.
+
+8. Operating systems
+
+8.1. 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.
+
+8.2. 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.
+
+Last updated 2023-12-05 14:22:10 +0100