diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/faq.adoc | 547 |
1 files changed, 547 insertions, 0 deletions
diff --git a/doc/faq.adoc b/doc/faq.adoc new file mode 100644 index 0000000..b07c550 --- /dev/null +++ b/doc/faq.adoc @@ -0,0 +1,547 @@ +// This file is part of chrony +// +// Copyright (C) Richard P. Curnow 1997-2003 +// Copyright (C) Miroslav Lichvar 2014-2016 +// +// This program is free software; you can redistribute it and/or modify +// it under the terms of version 2 of the GNU General Public License as +// published by the Free Software Foundation. +// +// This program is distributed in the hope that it will be useful, but +// WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +// General Public License for more details. +// +// You should have received a copy of the GNU General Public License along +// with this program; if not, write to the Free Software Foundation, Inc., +// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + += Frequently Asked Questions +:toc: +:numbered: + +== `chrony` compared to other programs + +=== How does `chrony` compare to `ntpd`? + +`chronyd` was designed to work well in a wide range of conditions and it can +usually synchronise the system clock faster and with better time accuracy. It +doesn't 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's a virtual machine), or you want to use NTP +on an isolated network with no hardware reference clocks in sight, `chrony` +will probably work much better for you. + +For a more detailed comparison of features and performance, see the +https://chrony.tuxfamily.org/comparison.html[comparison page] on the `chrony` +website. + +== 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 can be used for names that resolve to multiple addresses. For good +reliability the client should have at least three servers. The `iburst` option +speeds 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's 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 want to use public NTP servers from the +http://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 from an NTP client? + +You need to add an `allow` directive to the _chrony.conf_ file in order to open +the NTP port and allow `chronyd` to reply to client requests. `allow` with no +specified subnet allows access from all IPv4 and IPv6 addresses. + +=== I have several computers on a LAN. Should be all clients of an external server? + +The best configuration is usually 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. Starting from version 1.25, `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 don't need to serve time to NTP clients or peers, you can add `port 0` +to the _chrony.conf_ file to completely disable the NTP server functionality +and prevent NTP requests from reaching `chronyd`. Starting from version 2.0, +the NTP server port is open only when client access is allowed by the `allow` +directive or command, an NTP peer is configured, or the `broadcast` directive +is used. + +If you don't need to use `chronyc` remotely, you can add the following +directives to the configuration file to bind the command sockets to the +loopback interface. This is done by default since version 2.0. + +---- +bindcmdaddress 127.0.0.1 +bindcmdaddress ::1 +---- + +If you don't need to use `chronyc` at all or you need to run `chronyc` only +under the root or _chrony_ user (which can access `chronyd` through a Unix +domain socket since version 2.2), you can disable the internet command sockets +completely 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's compromised. It's +recommended to enable the filter only when it's 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 may make different system calls. +If the filter is missing some system call, `chronyd` could be killed even in +normal operation. + +=== 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's 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 in the _chrony.conf_ file. It +should make local receive and transmit timestamps of NTP packets much more +accurate. + +There are also useful options which can be set in the `server` directive, they +are `minpoll`, `maxpoll`, `polltarget`, `maxdelay`, `maxdelayratio`, +`maxdelaydevratio`, and `xleave`. + +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 may 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 may work better. + +An example of the directive for an NTP server on the Internet that you are +allowed to poll frequently could be + +---- +server foo.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 unusally 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 in order to allow +the server to send the client 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 may be possible. For example: + +---- +server ntp.local minpoll 0 maxpoll 0 xleave +hwtimestamp eth0 +---- + +If it is acceptable for NTP clients in the network to send requests at an +excessive rate, a sub-second polling interval may 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 +---- + +=== 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 don't want to use a configuration file, NTP servers can be +specified on the command line. For example: + +---- +# chronyd -q 'pool pool.ntp.org iburst' +---- + +=== 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`. + +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 +---- + +=== 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's +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 +packets may be blocked. Try using a tool like `wireshark` or `tcpdump` to see +if you're 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: + +---- +210 Number of sources = 3 +MS Name/IP address Stratum Poll Reach LastRx Last sample +=============================================================================== +^* foo.example.net 2 6 377 34 +484us[ -157us] +/- 30ms +^- bar.example.net 2 6 377 34 +33ms[ +32ms] +/- 47ms +^+ baz.example.net 3 6 377 35 -1397us[-2033us] +/- 60ms +---- + +=== Are NTP servers specified with the `offline` option? + +Check that you're using ``chronyc``'s `online` and `offline` commands +appropriately. 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 `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's 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 may be +necessary to allow the step on any clock update. The example above would change +to + +---- +makestep 1 -1 +---- + +=== 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 may 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 +---- + +=== 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.2 seconds 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 +foo.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 0.2 seconds, 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 isn't necessary for localhost. + +Perhaps `chronyd` is not running. Try using the `ps` command (e.g. on Linux, +`ps -auxw`) to see if it's running. Or try `netstat -a` and see if the ports +123/udp and 323/udp are listening. If `chronyd` is not running, you may 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 port +323/udp. You need to amend the firewall configuration in this case. + +=== I keep getting the error `501 Not authorised` + +Since version 2.2, the `password` command doesn't do anything and `chronyc` +needs to run locally under the root or _chrony_ user, which are allowed to +access the ``chronyd``'s Unix domain command socket. + +With older versions, you need to authenticate with the `password` command first +or use the `-a` option to authenticate automatically on start. The +configuration file needs to specify a file which contains keys (`keyfile` +directive) and which key in the key file should be used for `chronyc` +authentication (`commandkey` directive). + +=== Why does `chronyc tracking` always print an IPv4 address as reference ID? + +The reference ID is a 32-bit value and in versions before 3.0 it was printed in +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). + +== 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 doesn't 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 won't 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's not strictly necessary if its only purpose is to set the system clock when +`chronyd` is started on boot. See the documentation for details. + +=== I want to use ``chronyd``'s RTC support. Must I disable `hwclock`? + +The `hwclock` program is often set-up by default in the boot and shutdown +scripts with many 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's important to disable `hwclock` in the shutdown +procedure. If you don't, it will over-write 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 may be using the device. + +=== 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 the mode may be useful to 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's not supported in `chronyd`, 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 may be acceptable +to keep all sources online all the time. + +== 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. |