1// This file is part of chrony 2// 3// Copyright (C) Richard P. Curnow 1997-2003 4// Copyright (C) Miroslav Lichvar 2014-2016, 2020-2021 5// 6// This program is free software; you can redistribute it and/or modify 7// it under the terms of version 2 of the GNU General Public License as 8// published by the Free Software Foundation. 9// 10// This program is distributed in the hope that it will be useful, but 11// WITHOUT ANY WARRANTY; without even the implied warranty of 12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13// General Public License for more details. 14// 15// You should have received a copy of the GNU General Public License along 16// with this program; if not, write to the Free Software Foundation, Inc., 17// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 18 19= Frequently Asked Questions 20:toc: 21:numbered: 22 23== `chrony` compared to other programs 24 25=== How does `chrony` compare to `ntpd`? 26 27`chrony` and `ntpd` are two different implementations of the Network Time 28Protocol (NTP). 29 30`chrony` is a newer implementation, which was designed to work well in a wider 31range of conditions. It can usually synchronise the system clock faster and 32with better time accuracy. It has many features, but it does not implement some 33of the less useful NTP modes like broadcast client or multicast server/client. 34 35If your computer is connected to the Internet only for few minutes at a time, 36the network connection is often congested, you turn your computer off or 37suspend it frequently, the clock is not very stable (e.g. there are rapid 38changes in the temperature or it is a virtual machine), or you want to use NTP 39on an isolated network with no hardware reference clocks in sight, `chrony` 40will probably work better for you. 41 42For a more detailed comparison of features and performance, see the 43https://chrony.tuxfamily.org/comparison.html[comparison page] on the `chrony` 44website. 45 46== Configuration issues 47 48=== What is the minimum recommended configuration for an NTP client? 49 50First, the client needs to know which NTP servers it should ask for the current 51time. They are specified by the `server` or `pool` directive. The `pool` 52directive is used with names that resolve to multiple addresses of different 53servers. For reliable operation, the client should have at least three servers. 54 55The `iburst` option enables a burst of requests to speed up the initial 56synchronisation. 57 58To stabilise the initial synchronisation on the next start, the estimated drift 59of the system clock is saved to a file specified by the `driftfile` directive. 60 61If the system clock can be far from the true time after boot for any reason, 62`chronyd` should be allowed to correct it quickly by stepping instead of 63slewing, which would take a very long time. The `makestep` directive does 64that. 65 66In order to keep the real-time clock (RTC) close to the true time, so the 67system time is reasonably close to the true time when it is initialised on the 68next boot from the RTC, the `rtcsync` directive enables a mode in which the 69system time is periodically copied to the RTC. It is supported on Linux and 70macOS. 71 72If you wanted to use public NTP servers from the 73https://www.pool.ntp.org/[pool.ntp.org] project, the minimal _chrony.conf_ file 74could be: 75 76---- 77pool pool.ntp.org iburst 78driftfile /var/lib/chrony/drift 79makestep 1 3 80rtcsync 81---- 82 83=== How do I make an NTP server? 84 85By default, `chronyd` does not operate as an NTP server. You need to add an 86`allow` directive to the _chrony.conf_ file in order for `chronyd` to open the 87server NTP port and respond to client requests. 88 89---- 90allow 192.168.1.0/24 91---- 92 93An `allow` directive with no specified subnet allows access from all IPv4 and 94IPv6 addresses. 95 96=== Should all computers on a LAN be clients of an external server? 97 98It depends on the requirements. Usually, the best configuration is to make one 99computer the server, with the others as clients of it. Add a `local` directive 100to the server's _chrony.conf_ file. This configuration will be better because 101 102* the load on the external connection is less 103* the load on the external NTP server(s) is less 104* if your external connection goes down, the computers on the LAN 105 will maintain a common time with each other. 106 107=== Must I specify servers by IP address if DNS is not available on `chronyd` start? 108 109No, `chronyd` will keep trying to resolve 110the names specified by the `server`, `pool`, and `peer` directives in an 111increasing interval until it succeeds. The `online` command can be issued from 112`chronyc` to force `chronyd` to try to resolve the names immediately. 113 114=== How can I make `chronyd` more secure? 115 116If you do not need to use `chronyc`, or you want to run `chronyc` only 117under the root or _chrony_ user (which can access `chronyd` through a Unix 118domain socket), you can disable the IPv4 and IPv6 command sockets (by default 119listening on localhost) by adding `cmdport 0` to the configuration file. 120 121You can specify an unprivileged user with the `-u` option, or the `user` 122directive in the _chrony.conf_ file, to which `chronyd` will switch after start 123in order to drop root privileges. The configure script has a `--with-user` 124option, which sets the default user. On Linux, `chronyd` needs to be compiled 125with support for the `libcap` library. On other systems, `chronyd` forks into 126two processes. The child process retains root privileges, but can only perform 127a very limited range of privileged system calls on behalf of the parent. 128 129Also, if `chronyd` is compiled with support for the Linux secure computing 130(seccomp) facility, you can enable a system call filter with the `-F` option. 131It will significantly reduce the kernel attack surface and possibly prevent 132kernel exploits from the `chronyd` process if it is compromised. It is 133recommended to enable the filter only when it is known to work on the version of 134the system where `chrony` is installed as the filter needs to allow also system 135calls made from libraries that `chronyd` is using (e.g. libc) and different 136versions or implementations of the libraries might make different system calls. 137If the filter is missing some system call, `chronyd` could be killed even in 138normal operation. 139 140=== How can I make the system clock more secure? 141 142An NTP client synchronising the system clock to an NTP server is susceptible to 143various attacks, which can break applications and network protocols relying on 144accuracy of the clock (e.g. DNSSEC, Kerberos, TLS, WireGuard). 145 146Generally, a man-in-the-middle (MITM) attacker between the client and server 147can 148 149* make fake responses, or modify real responses from the server, to create an 150 arbitrarily large time and frequency offset, make the server appear more 151 accurate, insert a leap second, etc. 152* delay the requests and/or responses to create a limited time offset and 153 temporarily also a limited frequency offset 154* drop the requests or responses to prevent updates of the clock with new 155 measurements 156* redirect the requests to a different server 157 158The attacks can be combined for a greater effect. The attacker can delay 159packets to create a significant frequency offset first and then drop all 160subsequent packets to let the clock quickly drift away from the true time. 161The attacker might also be able to control the server's clock. 162 163Some attacks cannot be prevented. Monitoring is needed for detection, e.g. the 164reachability register in the `sources` report shows missing packets. The extent 165to which the attacker can control the client's clock depends on its 166configuration. 167 168Enable authentication to prevent `chronyd` from accepting modified, fake, or 169redirected packets. It can be enabled with a symmetric key specified by the 170`key` option, or Network Time Security (NTS) by the `nts` option (supported 171since `chrony` version 4.0). The server needs to support the selected 172authentication mechanism. Symmetric keys have to be configured on both client 173and server, and each client must have its own key (one per server). 174 175The maximum offset that the attacker can insert in an NTP measurement by 176delaying packets can be limited by the `maxdelay` option. The default value is 1773 seconds. The measured delay is reported as the peer delay in the `ntpdata` 178report and `measurements` log. Set the `maxdelay` option to a value larger than 179the maximum value that is normally observed. Note that the delay can increase 180significantly even when not under an attack, e.g. when the network is congested 181or the routing has changed. 182 183The maximum accepted change in time offset between clock updates can be limited 184by the `maxchange` directive. Larger changes in the offset will be ignored or 185cause `chronyd` to exit. Note that the attacker can get around this limit by 186splitting the offset into multiple smaller offsets and/or creating a large 187frequency offset. When this directive is used, `chronyd` will have to be 188restarted after a successful attack. It will not be able to recover on its own. 189It must not be restarted automatically (e.g. by the service manager). 190 191The impact of a large accepted time offset can be reduced by disabling clock 192steps, i.e. by not using the `makestep` and `initstepslew` directives. The 193offset will be slowly corrected by speeding up or slowing down the clock at a 194rate which can be limited by the `maxslewrate` directive. Disabling clock steps 195completely is practical only if the clock cannot gain a larger error on its 196own, e.g. when the computer is shut down or suspended, and the `maxslewrate` 197limit is large enough to correct an expected error in an acceptable time. The 198`rtcfile` directive with the `-s` option can be used to compensate for the RTC 199drift. 200 201A more practical approach is to enable `makestep` for a limited number of clock 202updates (the 2nd argument of the directive) and limit the offset change in all 203updates by the `maxchange` directive. The attacker will be able to make only a 204limited step and only if the attack starts in a short window after booting the 205computer, or when `chronyd` is restarted without the `-R` option. 206 207The frequency offset can be limited by the `maxdrift` directive. The measured 208frequency offset is reported in the drift file, `tracking` report, and 209`tracking` log. Set `maxdrift` to a value larger than the maximum absolute 210value that is normally observed. Note that the frequency of the clock can 211change due to aging of the crystal, differences in calibration of the clock 212source between reboots, migrated virtual machine, etc. A typical computer clock 213has a drift smaller than 100 parts per million (ppm), but much larger drifts 214are possible (e.g. in some virtual machines). 215 216Use only trusted servers, which you expect to be well configured and managed, 217using authentication for their own servers, etc. Use multiple servers, ideally 218in different locations. The attacker will have to deal with a majority of the 219servers in order to pass the source selection and update the clock with a large 220offset. Use the `minsources` directive to increase the required number of 221selectable sources to make the selection more robust. 222 223Do not specify servers as peers. The symmetric mode is less secure than the 224client/server mode. If not authenticated, it is vulnerable to off-path 225denial-of-service attacks, and even when it is authenticated, it is still 226susceptible to replay attacks. 227 228Mixing of authenticated and unauthenticated servers should generally be 229avoided. If mixing is necessary (e.g. for a more accurate and stable 230synchronisation to a closer server which does not support authentication), the 231authenticated servers should be configured as trusted and required to not allow 232the unauthenticated servers to override the authenticated servers in the source 233selection. Since `chrony` version 4.0, the selection options are enabled in 234such a case automatically. This behaviour can be disabled or modified by the 235`authselmode` directive. 236 237An example of a client configuration limiting the impact of the attacks could 238be 239 240---- 241server foo.example.net iburst nts maxdelay 0.1 242server bar.example.net iburst nts maxdelay 0.2 243server baz.example.net iburst nts maxdelay 0.05 244server qux.example.net iburst nts maxdelay 0.1 245server quux.example.net iburst nts maxdelay 0.1 246minsources 3 247maxchange 100 0 0 248makestep 0.001 1 249maxdrift 100 250maxslewrate 100 251driftfile /var/lib/chrony/drift 252ntsdumpdir /var/lib/chrony 253rtcsync 254---- 255 256=== How can I improve the accuracy of the system clock with NTP sources? 257 258Select NTP servers that are well synchronised, stable and close to your 259network. It is better to use more than one server. Three or four is usually 260recommended as the minimum, so `chronyd` can detect servers that serve false 261time and combine measurements from multiple sources. 262 263If you have a network card with hardware timestamping supported on Linux, it 264can be enabled by the `hwtimestamp` directive. It should make local receive and 265transmit timestamps of NTP packets much more stable and accurate. 266 267The `server` directive has some useful options: `minpoll`, `maxpoll`, 268`polltarget`, `maxdelay`, `maxdelayratio`, `maxdelaydevratio`, `xleave`, 269`filter`. 270 271The first three options set the minimum and maximum allowed polling interval, 272and how should be the actual interval adjusted in the specified range. Their 273default values are 6 (64 seconds) for `minpoll`, 10 (1024 seconds) for 274`maxpoll` and 8 (samples) for `polltarget`. The default values should be used 275for general servers on the Internet. With your own NTP servers, or if you have 276permission to poll some servers more frequently, setting these options for 277shorter polling intervals might significantly improve the accuracy of the 278system clock. 279 280The optimal polling interval depends mainly on two factors, stability of the 281network latency and stability of the system clock (which mainly depends on the 282temperature sensitivity of the crystal oscillator and the maximum rate of the 283temperature change). 284 285Generally, if the `sourcestats` command usually reports a small number of 286samples retained for a source (e.g. fewer than 16), a shorter polling interval 287should be considered. If the number of samples is usually at the maximum of 64, 288a longer polling interval might work better. 289 290An example of the directive for an NTP server on the Internet that you are 291allowed to poll frequently could be 292 293---- 294server foo.example.net minpoll 4 maxpoll 6 polltarget 16 295---- 296 297An example using shorter polling intervals with a server located in the same 298LAN could be 299 300---- 301server ntp.local minpoll 2 maxpoll 4 polltarget 30 302---- 303 304The maxdelay options are useful to ignore measurements with an unusually large 305delay (e.g. due to congestion in the network) and improve the stability of the 306synchronisation. The `maxdelaydevratio` option could be added to the example 307with local NTP server 308 309---- 310server ntp.local minpoll 2 maxpoll 4 polltarget 30 maxdelaydevratio 2 311---- 312 313If your server supports the interleaved mode (e.g. it is running `chronyd`), 314the `xleave` option should be added to the `server` directive to enable the 315server to provide the client with more accurate transmit timestamps (kernel or 316preferably hardware). For example: 317 318---- 319server ntp.local minpoll 2 maxpoll 4 xleave 320---- 321 322When combined with local hardware timestamping, good network switches, and even 323shorter polling intervals, a sub-microsecond accuracy and stability of a few 324tens of nanoseconds might be possible. For example: 325 326---- 327server ntp.local minpoll 0 maxpoll 0 xleave 328hwtimestamp eth0 329---- 330 331For best stability, the CPU should be running at a constant frequency (i.e. 332disabled power saving and performance boosting). Energy-Efficient Ethernet 333(EEE) should be disabled in the network. The switches should be configured to 334prioritize NTP packets, especially if the network is expected to be heavily 335loaded. The `dscp` directive can be used to set the Differentiated Services 336Code Point in transmitted NTP packets if needed. 337 338If it is acceptable for NTP clients in the network to send requests at a high 339rate, a sub-second polling interval can be specified. A median filter 340can be enabled in order to update the clock at a reduced rate with more stable 341measurements. For example: 342 343---- 344server ntp.local minpoll -6 maxpoll -6 filter 15 xleave 345hwtimestamp eth0 minpoll -6 346---- 347 348As an experimental feature added in version 4.2, `chronyd` supports an NTPv4 349extension field containing an additional timestamp to enable frequency transfer 350and significantly improve stability of synchronisation. It can be enabled by 351the `extfield F323` option. For example: 352 353---- 354server ntp.local minpoll 0 maxpoll 0 xleave extfield F323 355---- 356 357=== Does `chronyd` have an ntpdate mode? 358 359Yes. With the `-q` option `chronyd` will set the system clock once and exit. 360With the `-Q` option it will print the measured offset without setting the 361clock. If you do not want to use a configuration file, NTP servers can be 362specified on the command line. For example: 363 364---- 365# chronyd -q 'pool pool.ntp.org iburst' 366---- 367 368The command above would normally take about 5 seconds if the servers were 369well synchronised and responding to all requests. If not synchronised or 370responding, it would take about 10 seconds for `chronyd` to give up and exit 371with a non-zero status. A faster configuration is possible. A single server can 372be used instead of four servers, the number of measurements can be reduced with 373the `maxsamples` option to one (supported since `chrony` version 4.0), and a 374timeout can be specified with the `-t` option. The following command would take 375only up to about one second. 376 377---- 378# chronyd -q -t 1 'server pool.ntp.org iburst maxsamples 1' 379---- 380 381It is not recommended to run `chronyd` with the `-q` option periodically (e.g. 382from a cron job) as a replacement for the daemon mode, because it performs 383significantly worse (e.g. the clock is stepped and its frequency is not 384corrected). If you must run it this way and you are using a public NTP server, 385make sure `chronyd` does not always start around the first second of a minute, 386e.g. by adding a random sleep before the `chronyd` command. Public servers 387typically receive large bursts of requests around the first second as there is 388a large number of NTP clients started from cron with no delay. 389 390=== Can `chronyd` be configured to control the clock like `ntpd`? 391 392It is not possible to perfectly emulate `ntpd`, but there are some options that 393can configure `chronyd` to behave more like `ntpd` if there is a reason to 394prefer that. 395 396In the following example the `minsamples` directive slows down the response to 397changes in the frequency and offset of the clock. The `maxslewrate` and 398`corrtimeratio` directives reduce the maximum frequency error due to an offset 399correction and the `maxdrift` directive reduces the maximum assumed frequency 400error of the clock. The `makestep` directive enables a step threshold and the 401`maxchange` directive enables a panic threshold. The `maxclockerror` directive 402increases the minimum dispersion rate. 403 404---- 405minsamples 32 406maxslewrate 500 407corrtimeratio 100 408maxdrift 500 409makestep 0.128 -1 410maxchange 1000 1 1 411maxclockerror 15 412---- 413 414Note that increasing `minsamples` might cause the offsets in the `tracking` and 415`sourcestats` reports/logs to be significantly smaller than the actual offsets 416and be unsuitable for monitoring. 417 418=== Can NTP server be separated from NTP client? 419 420Yes, it is possible to run multiple instances of `chronyd` on a computer at the 421same time. One can operate primarily as an NTP client to synchronise the system 422clock and another as a server for other computers. If they use the same 423filesystem, they need to be configured with different pidfiles, Unix domain 424command sockets, and any other file or directory specified in the configuration 425file. If they run in the same network namespace, they need to use different NTP 426and command ports, or bind the ports to different addresses or interfaces. 427 428The server instance should be started with the `-x` option to prevent it from 429adjusting the system clock and interfering with the client instance. It can be 430configured as a client to synchronise its NTP clock to other servers, or the 431client instance running on the same computer. In the latter case, the `copy` 432option (added in `chrony` version 4.1) can be used to assume the reference ID 433and stratum of the client instance, which enables detection of synchronisation 434loops with its own clients. 435 436On Linux, starting with `chrony` version 4.0, it is possible to run multiple 437server instances sharing a port to better utilise multiple cores of the CPU. 438Note that for rate limiting and client/server interleaved mode to work well 439it is necessary that all packets received from the same address are handled by 440the same server instance. 441 442An example configuration of the client instance could be 443 444---- 445pool pool.ntp.org iburst 446allow 127.0.0.1 447port 11123 448driftfile /var/lib/chrony/drift 449makestep 1 3 450rtcsync 451---- 452 453and configuration of the first server instance could be 454 455---- 456server 127.0.0.1 port 11123 minpoll 0 maxpoll 0 copy 457allow 458cmdport 11323 459bindcmdaddress /var/run/chrony/chronyd-server1.sock 460pidfile /var/run/chronyd-server1.pid 461driftfile /var/lib/chrony/drift-server1 462---- 463 464=== Should be a leap smear enabled on NTP server? 465 466With the `smoothtime` and `leapsecmode` directives it is possible to enable a 467server leap smear in order to hide leap seconds from clients and force them to 468follow a slow server's adjustment instead. 469 470This feature should be used only in local networks and only when necessary, 471e.g. when the clients cannot be configured to handle the leap seconds as 472needed, or their number is so large that configuring them all would be 473impractical. The clients should use only one leap-smearing server, or multiple 474identically configured leap-smearing servers. Note that some clients can get 475leap seconds from other sources (e.g. with the `leapsectz` directive in 476`chrony`) and they will not work correctly with a leap smearing server. 477 478=== Does `chrony` support PTP? 479 480No, the Precision Time Protocol (PTP) is not supported as a protocol for 481synchronisation of clocks and there are no plans 482to support it. It is a complex protocol, which shares some issues with the 483NTP broadcast mode. One of the main differences between NTP and PTP is that PTP 484was designed to be easily supported in hardware (e.g. network switches and 485routers) in order to make more stable and accurate measurements. PTP relies on 486the hardware support. NTP does not rely on any support in the hardware, but if 487it had the same support as PTP, it could perform equally well. 488 489On Linux, `chrony` supports hardware clocks that some NICs have for PTP. They 490are called PTP hardware clocks (PHC). They can be used as reference clocks 491(specified by the `refclock` directive) and for hardware timestamping of NTP 492packets (enabled by the `hwtimestamp` directive) if the NIC can timestamp other 493packets than PTP, which is usually the case at least for transmitted packets. 494The `ethtool -T` command can be used to verify the timestamping support. 495 496As an experimental feature added in version 4.2, `chrony` can use PTP as a 497transport for NTP messages (NTP over PTP) to enable hardware timestamping on 498hardware which can timestamp PTP packets only. It can be enabled by the 499`ptpport` directive. 500 501=== What happened to the `commandkey` and `generatecommandkey` directives? 502 503They were removed in version 2.2. Authentication is no longer supported in the 504command protocol. Commands that required authentication are now allowed only 505through a Unix domain socket, which is accessible only by the root and _chrony_ 506users. If you need to configure `chronyd` remotely or locally without the root 507password, please consider using ssh and/or sudo to run `chronyc` under the root 508or _chrony_ user on the host where `chronyd` is running. 509 510== Computer is not synchronising 511 512This is the most common problem. There are a number of reasons, see the 513following questions. 514 515=== Behind a firewall? 516 517Check the `Reach` value printed by the ``chronyc``'s `sources` command. If it 518is zero, it means `chronyd` did not get any valid responses from the NTP server 519you are trying to use. If there is a firewall between you and the server, the 520packets might be blocked. Try using a tool like `wireshark` or `tcpdump` to see 521if you are getting any responses from the server. 522 523When `chronyd` is receiving responses from the servers, the output of the 524`sources` command issued few minutes after `chronyd` start might look like 525this: 526 527---- 528MS Name/IP address Stratum Poll Reach LastRx Last sample 529=============================================================================== 530^* foo.example.net 2 6 377 34 +484us[ -157us] +/- 30ms 531^- bar.example.net 2 6 377 34 +33ms[ +32ms] +/- 47ms 532^+ baz.example.net 3 6 377 35 -1397us[-2033us] +/- 60ms 533---- 534 535=== Are NTP servers specified with the `offline` option? 536 537Check that the ``chronyc``'s `online` and `offline` commands are used 538appropriately (e.g. in the system networking scripts). The `activity` command 539prints the number of sources that are currently online and offline. For 540example: 541 542---- 543200 OK 5443 sources online 5450 sources offline 5460 sources doing burst (return to online) 5470 sources doing burst (return to offline) 5480 sources with unknown address 549---- 550 551=== Is name resolution working correctly? 552 553NTP servers specified by their hostname (instead of an IP address) have to have 554their names resolved before `chronyd` can send any requests to them. If the 555`activity` command prints a non-zero number of sources with unknown address, 556there is an issue with the resolution. Typically, a DNS server is specified in 557_/etc/resolv.conf_. Make sure it is working correctly. 558 559Since `chrony` version 4.0, you can run `chronyc -N sources -a` command to 560print all sources, even those that do not have a known address yet, with their 561names as they were specified in the configuration. This can be useful to verify 562that the names specified in the configuration are used as expected. 563 564=== Is `chronyd` allowed to step the system clock? 565 566By default, `chronyd` adjusts the clock gradually by slowing it down or 567speeding it up. If the clock is too far from the true time, it will take 568a long time to correct the error. The `System time` value printed by the 569``chronyc``'s `tracking` command is the remaining correction that needs to be 570applied to the system clock. 571 572The `makestep` directive can be used to allow `chronyd` to step the clock. For 573example, if _chrony.conf_ had 574 575---- 576makestep 1 3 577---- 578 579the clock would be stepped in the first three updates if its offset was larger 580than one second. Normally, it is recommended to allow the step only in the first 581few updates, but in some cases (e.g. a computer without an RTC or virtual 582machine which can be suspended and resumed with an incorrect time) it might be 583necessary to allow the step on any clock update. The example above would change 584to 585 586---- 587makestep 1 -1 588---- 589 590=== Using NTS? 591 592The Network Time Security (NTS) mechanism uses Transport Layer Security (TLS) 593to establish the keys needed for authentication of NTP packets. 594 595Run the `authdata` command to check whether the key establishment was 596successful: 597 598---- 599# chronyc -N authdata 600Name/IP address Mode KeyID Type KLen Last Atmp NAK Cook CLen 601========================================================================= 602foo.example.net NTS 1 15 256 33m 0 0 8 100 603bar.example.net NTS 1 15 256 33m 0 0 8 100 604baz.example.net NTS 1 15 256 33m 0 0 8 100 605---- 606 607The KeyID, Type, and KLen columns should have non-zero values. If they are 608zero, check the system log for error messages from `chronyd`. One possible 609cause of failure is a firewall blocking the client's connection to the server's 610TCP port 4460. 611 612Another possible cause of failure is a certificate that is failing to verify 613because the client's clock is wrong. This is a chicken-and-egg problem with NTS. 614You might need to manually correct the date, or temporarily disable NTS, in 615order to get NTS working. If your computer has an RTC and it is backed up by a 616good battery, this operation should be needed only once, assuming the RTC will 617be set periodically with the `rtcsync` directive, or compensated with the 618`rtcfile` directive and the `-s` option. 619 620If the computer does not have an RTC or battery, you can use the `-s` option 621without `rtcfile` directive to restore time of the last shutdown or reboot from 622the drift file. The clock will start behind the true time, but if the computer 623was not shut down for too long and the server's certificate was not renewed too 624close to its expiration, it should be sufficient for the time checks to 625succeed. 626 627As a last resort, you can disable the time checks by the `nocerttimecheck` 628directive. This has some important security implications. To reduce the 629security risk, you can use the `nosystemcert` and `ntstrustedcerts` directives 630to disable the system's default trusted certificate authorities and trust only 631a minimal set of selected authorities needed to validate the certificates of 632used NTP servers. 633 634=== Using a Windows NTP server? 635 636A common issue with Windows NTP servers is that they report a very large root 637dispersion (e.g. three seconds or more), which causes `chronyd` to ignore the 638server for being too inaccurate. The `sources` command might show a valid 639measurement, but the server is not selected for synchronisation. You can check 640the root dispersion of the server with the ``chronyc``'s `ntpdata` command. 641 642The `maxdistance` value needs to be increased in _chrony.conf_ to enable 643synchronisation to such a server. For example: 644 645---- 646maxdistance 16.0 647---- 648 649=== An unreachable source is selected? 650 651When `chronyd` is configured with multiple time sources, it tries to select the 652most accurate and stable sources for synchronisation of the system clock. They 653are marked with the _*_ or _+_ symbol in the report printed by the `sources` 654command. 655 656When the best source (marked with the _*_ symbol) becomes unreachable (e.g. NTP 657server stops responding), `chronyd` will not immediately switch 658to the second best source in an attempt to minimise the error of the clock. It 659will let the clock run free for as long as its estimated error (in terms of 660root distance) based on previous measurements is smaller than the estimated 661error of the second source, and there is still an interval which contains some 662measurements from both sources. 663 664If the first source was significantly better than the second source, it can 665take many hours before the second source is selected, depending on its polling 666interval. You can force a faster reselection by increasing the clock error rate 667(`maxclockerror` directive), shortening the polling interval (`maxpoll` 668option), or reducing the number of samples (`maxsamples` option). 669 670=== Does selected source drop new measurements? 671 672`chronyd` can drop a large number of successive NTP measurements if they are 673not passing some of the NTP tests. The `sources` command can report for a 674selected source the fully-reachable value of 377 in the Reach column and at the 675same time a LastRx value that is much larger than the current polling interval. 676If the source is online, this indicates that a number of measurements was 677dropped. You can use the `ntpdata` command to check the NTP tests for the last 678measurement. Usually, it is the test C which fails. 679 680This can be an issue when there is a long-lasting increase in the measured 681delay, e.g. due to a routing change in the network. Unfortunately, `chronyd` 682does not know for how long it should wait for the delay to come back to the 683original values, or whether it is a permanent increase and it should start from 684scratch. 685 686The test C is an adaptive filter. It can take many hours before it accepts 687a measurement with the larger delay, and even much longer before it drops all 688measurements with smaller delay, which determine an expected delay used by the 689test. You can use the `reset sources` command to drop all measurements 690immediately (available in chrony 4.0 and later). If this issue happens 691frequently, you can effectively disable the test by setting the 692`maxdelaydevratio` option to a very large value (e.g. 1000000), or speed up the 693recovery by increasing the clock error rate with the `maxclockerror` directive. 694 695=== Using a PPS reference clock? 696 697A pulse-per-second (PPS) reference clock requires a non-PPS time source to 698determine which second of UTC corresponds to each pulse. If it is another 699reference clock specified with the `lock` option in the `refclock` directive, 700the offset between the two reference clocks must be smaller than 0.2 seconds in 701order for the PPS reference clock to work. With NMEA reference clocks it is 702common to have a larger offset. It needs to be corrected with the `offset` 703option. 704 705One approach to find out a good value of the `offset` option is to configure 706the reference clocks with the `noselect` option and compare them to an NTP 707server. For example, if the `sourcestats` command showed 708 709---- 710Name/IP Address NP NR Span Frequency Freq Skew Offset Std Dev 711============================================================================== 712PPS0 0 0 0 +0.000 2000.000 +0ns 4000ms 713NMEA 58 30 231 -96.494 38.406 +504ms 6080us 714foo.example.net 7 3 200 -2.991 16.141 -107us 492us 715---- 716 717the offset of the NMEA source would need to be increased by about 0.504 718seconds. It does not have to be very accurate. As long as the offset of the 719NMEA reference clock stays below 0.2 seconds, the PPS reference clock should be 720able to determine the seconds corresponding to the pulses and allow the samples 721to be used for synchronisation. 722 723== Issues with `chronyc` 724 725=== I keep getting the error `506 Cannot talk to daemon` 726 727When accessing `chronyd` remotely, make sure that the _chrony.conf_ file (on 728the computer where `chronyd` is running) has a `cmdallow` entry for the 729computer you are running `chronyc` on and an appropriate `bindcmdaddress` 730directive. This is not necessary for localhost. 731 732Perhaps `chronyd` is not running. Try using the `ps` command (e.g. on Linux, 733`ps -auxw`) to see if it is running. Or try `netstat -a` and see if the UDP 734port 323 is listening. If `chronyd` is not running, you might have a problem 735with the way you are trying to start it (e.g. at boot time). 736 737Perhaps you have a firewall set up in a way that blocks packets on the UDP 738port 323. You need to amend the firewall configuration in this case. 739 740=== I keep getting the error `501 Not authorised` 741 742This error indicates that `chronyc` sent the command to `chronyd` using a UDP 743socket instead of the Unix domain socket (e.g. _/var/run/chrony/chronyd.sock_), 744which is required for some commands. For security reasons, only the root and 745_chrony_ users are allowed to access the socket. 746 747It is also possible that the socket does not exist. `chronyd` will not create 748the socket if the directory has a wrong owner or permissions. In this case 749there should be an error message from `chronyd` in the system log. 750 751=== What is the reference ID reported by the `tracking` command? 752 753The reference ID is a 32-bit value used in NTP to prevent synchronisation 754loops. 755 756In `chrony` versions before 3.0 it was printed in the 757quad-dotted notation, even if the reference source did not actually have an 758IPv4 address. For IPv4 addresses, the reference ID is equal to the address, but 759for IPv6 addresses it is the first 32 bits of the MD5 sum of the address. For 760reference clocks, the reference ID is the value specified with the `refid` 761option in the `refclock` directive. 762 763Since version 3.0, the reference ID is printed as a hexadecimal number to avoid 764confusion with IPv4 addresses. 765 766If you need to get the IP address of the current reference source, use the `-n` 767option to disable resolving of IP addresses and read the second field (printed 768in parentheses) on the `Reference ID` line. 769 770=== Is the `chronyc` / `chronyd` protocol documented anywhere? 771 772Only by the source code. See _cmdmon.c_ (`chronyd` side) and _client.c_ 773(`chronyc` side). 774 775== Real-time clock issues 776 777=== What is the real-time clock (RTC)? 778 779This is the clock which keeps the time even when your computer is turned off. 780It is used to initialise the system clock on boot. It normally does not drift 781more than few seconds per day. 782 783There are two approaches how `chronyd` can work with it. One is to use the 784`rtcsync` directive, which tells `chronyd` to enable a kernel mode which sets 785the RTC from the system clock every 11 minutes. `chronyd` itself will not touch 786the RTC. If the computer is not turned off for a long time, the RTC should 787still be close to the true time when the system clock will be initialised from 788it on the next boot. 789 790The other option is to use the `rtcfile` directive, which tells `chronyd` to 791monitor the rate at which the RTC gains or loses time. When `chronyd` is 792started with the `-s` option on the next boot, it will set the system time from 793the RTC and also compensate for the drift it has measured previously. The 794`rtcautotrim` directive can be used to keep the RTC close to the true time, but 795it is not strictly necessary if its only purpose is to set the system clock when 796`chronyd` is started on boot. See the documentation for details. 797 798=== Does `hwclock` have to be disabled? 799 800The `hwclock` program is run by default in the boot and/or shutdown 801scripts in some Linux installations. With the kernel RTC synchronisation 802(`rtcsync` directive), the RTC will be set also every 11 minutes as long as the 803system clock is synchronised. If you want to use ``chronyd``'s RTC monitoring 804(`rtcfile` directive), it is important to disable `hwclock` in the shutdown 805procedure. If you do not do that, it will overwrite the RTC with a new value, unknown 806to `chronyd`. At the next reboot, `chronyd` started with the `-s` option will 807compensate this (wrong) time with its estimate of how far the RTC has drifted 808whilst the power was off, giving a meaningless initial system time. 809 810There is no need to remove `hwclock` from the boot process, as long as `chronyd` 811is started after it has run. 812 813=== I just keep getting the `513 RTC driver not running` message 814 815For the real-time clock support to work, you need the following three 816things 817 818* an RTC in your computer 819* a Linux kernel with enabled RTC support 820* an `rtcfile` directive in your _chrony.conf_ file 821 822=== I get `Could not open /dev/rtc, Device or resource busy` in my syslog file 823 824Some other program running on the system might be using the device. 825 826=== When I start `chronyd`, the log says `Could not enable RTC interrupt : Invalid argument` (or it may say `disable`) 827 828Your real-time clock hardware might not support the required ioctl requests: 829 830* `RTC_UIE_ON` 831* `RTC_UIE_OFF` 832 833A possible solution could be to build the Linux kernel with support for software 834emulation instead; try enabling the following configuration option when building 835the Linux kernel: 836 837* `CONFIG_RTC_INTF_DEV_UIE_EMUL` 838 839=== What if my computer does not have an RTC or backup battery? 840 841In this case you can still use the `-s` option to set the system clock to the 842last modification time of the drift file, which should correspond to the system 843time when `chronyd` was previously stopped. The initial system time will be 844increasing across reboots and applications started after `chronyd` will not 845observe backward steps. 846 847== NTP-specific issues 848 849=== Can `chronyd` be driven from broadcast/multicast NTP servers? 850 851No, the broadcast/multicast client mode is not supported and there is currently 852no plan to implement it. While this mode can simplify configuration 853of clients in large networks, it is inherently less accurate and less secure 854(even with authentication) than the ordinary client/server mode. 855 856When configuring a large number of clients in a network, it is recommended to 857use the `pool` directive with a DNS name which resolves to addresses of 858multiple NTP servers. The clients will automatically replace the servers when 859they become unreachable, or otherwise unsuitable for synchronisation, with new 860servers from the pool. 861 862Even with very modest hardware, an NTP server can serve time to hundreds of 863thousands of clients using the ordinary client/server mode. 864 865=== Can `chronyd` transmit broadcast NTP packets? 866 867Yes, the `broadcast` directive can be used to enable the broadcast server mode 868to serve time to clients in the network which support the broadcast client mode 869(it is not supported in `chronyd`). Note that this mode should generally be 870avoided. See the previous question. 871 872=== Can `chronyd` keep the system clock a fixed offset away from real time? 873 874Yes. Starting from version 3.0, an offset can be specified by the `offset` 875option for all time sources in the _chrony.conf_ file. 876 877=== What happens if the network connection is dropped without using ``chronyc``'s `offline` command first? 878 879`chronyd` will keep trying to access the sources that it thinks are online, and 880it will take longer before new measurements are actually made and the clock is 881corrected when the network is connected again. If the sources were set to 882offline, `chronyd` would make new measurements immediately after issuing the 883`online` command. 884 885Unless the network connection lasts only few minutes (less than the maximum 886polling interval), the delay is usually not a problem, and it might be acceptable 887to keep all sources online all the time. 888 889=== Why is an offset measured between two computers synchronised to each another? 890 891When two computers are synchronised to each other using the client/server or 892symmetric NTP mode, there is an expectation that NTP measurements between the 893two computers made on both ends show an average offset close to zero. 894 895With `chronyd` that can be expected only when the interleaved mode is enabled 896by the `xleave` option. Otherwise, `chronyd` will use different transmit 897timestamps (e.g. daemon timestamp vs kernel timestamp) for serving time and 898synchronisation of its own clock, which will cause the other computer to 899measure a significant offset. 900 901== Operating systems 902 903=== Does `chrony` support Windows? 904 905No. The `chronyc` program (the command-line client used for configuring 906`chronyd` while it is running) has been successfully built and run under 907Cygwin in the past. `chronyd` is not portable, because part of it is 908very system-dependent. It needs adapting to work with Windows' 909equivalent of the adjtimex() call, and it needs to be made to work as a 910service. 911 912=== Are there any plans to support Windows? 913 914We have no plans to do this. Anyone is welcome to pick this work up and 915contribute it back to the project. 916