1 Administrative issues
=======================

1.1 Where can I get chrony source code?
---------------------------------------

Tarballs are available via the 'Download' link on the chrony web site.
For the current development from the developers' version control system
see the 'Git' link on the web site.

1.2 Are there any packaged versions of chrony?
----------------------------------------------

We are aware of packages for Arch, Debian, Fedora, Gentoo, Mandriva,
Slackware, Ubuntu, FreeBSD and NetBSD. We are not involved with how
these are built or distributed.

1.3 Where is the home page?
---------------------------

It is currently at http://chrony.tuxfamily.org
(http://chrony.tuxfamily.org).

1.4 Is there a mailing list?
----------------------------

Yes, it's currently at <chrony-users@chrony.tuxfamily.org>.  There is a
low-volume list called chrony-announce which is just for announcements
of new releases or similar matters of high importance.  You can join the
lists by sending a message with the subject subscribe to
<chrony-users-request@chrony.tuxfamily.org> or
<chrony-announce-request@chrony.tuxfamily.org> respectively.

   For those who want to contribute to the development of chrony, there
is a developers' mailing list.  You can subscribe by sending mail with
the subject subscribe to <chrony-dev-request@chrony.tuxfamily.org>.

1.5 What licence is applied to chrony?
--------------------------------------

Starting from version 1.15, chrony is licensed under the GNU General
Public License, Version 2.  Versions prior to 1.15 were licensed under a
custom BSD-like license.

2 Chrony compared to other programs
===================================

2.1 How does chrony compare to ntpd?
------------------------------------

Chrony can usually synchronise the system clock faster and with better
time accuracy, but it doesn't implement all NTP features, e.g.
broadcast/multicast mode, or authentication based on public-key
cryptography.  For a more detailed comparison, see section 'Comparison
with ntpd' in the manual.

   If your computer connects to the 'net only for few minutes at a time,
you turn your Linux computer off or suspend it frequently, the clock is
not very stable (e.g.  it is a virtual machine), or you want to use NTP
on an isolated network with no hardware clocks in sight, chrony will
probably work much better for you.

   The original reason chrony was written was that ntpd (called xntpd at
the time) could not to do anything sensible on a PC which was connected
to the 'net only for about 5 minutes once or twice a day, mainly to
upload/download email and news.  The requirements were

   * slew the time to correct it when going online and NTP servers
     become visible
   * determine the rate at which the computer gains or loses time and
     use this information to keep it reasonably correct between connects
     to the 'net.  This has to be done using a method that does not care
     about the intermittent availability of the references or the fact
     the computer is turned off between groups of measurements.
   * maintain the time across reboots, by working out the error and
     drift rate of the computer's real-time clock and using this
     information to set the system clock correctly at boot up.

   Also, when working with isolated networks with no true time
references at all ntpd was found to give no help with managing the local
clock's gain/loss rate on the NTP master node (which was set from
watch).  Some automated support was added to chrony to deal with this.

3 Configuration issues
======================

3.1 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 master, with
the others as clients of it.  Add a 'local' directive to the master'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.

3.2 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 hostnames specified in the 'server' and 'peer' directives in
increasing intervals until it succeeds.  The 'online' command can be
issued from 'chronyc' to try to resolve them immediately.

3.3 How can I make chronyd more secure?
---------------------------------------

If you don't need to serve time to NTP clients, you can add 'port 0' to
the 'chrony.conf' file to disable the NTP server/peer sockets and
prevent NTP requests from reaching 'chronyd'.

   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

     bindcmdaddress 127.0.0.1
     bindcmdaddress ::1

   If you don't need to use 'chronyc' at all, you can disable the
command sockets by adding 'cmdport 0' to the configuration file.

   On Linux, if 'chronyd' is compiled with support for Linux
capabilities (available in the libcap library), you can specify an
unprivileged user with the '-u' option or 'user' directive in the
'chrony.conf' file to drop root privileges after start.  The configure
option '--with-user' can be used to drop the privileges by default.

3.4 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 falsetickers
and combine measurements from multiple sources.

   There are also useful options which can be set in the 'server'
directive, they are 'minpoll', 'maxpoll', 'polltarget', 'maxdelay',
'maxdelayratio' and 'maxdelaydevratio'.

   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 suitable for public NTP
servers, which normally don't allow too frequent polling, but if you run
your own NTP servers or have permission to poll the servers frequently,
setting the options for shorter polling intervals may significantly
improve the accuracy of the system clock.

   The optimal polling interval depends on many factors, this includes
the ratio between the wander of the clock and the network jitter
(sometimes expressed in NTP documents as the Allan intercept), the
temperature sensitivity of the crystal oscillator and the maximum rate
of change of the temperature.  An example of the directive for 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 larger
delay (e.g.  due to congestion in the network) and improve the stability
of the synchronisation.  The 'maxdelaydevratio' option could be added to
the previous example

     server ntp.local minpoll 2 maxpoll 4 polltarget 30 maxdelaydevratio 2

4 Computer is not synchronising
===============================

This is the most common problem.  There are a number of reasons, see the
following questions.

4.1 Behind a firewall?
----------------------

If there is a firewall between you and the NTP server you're trying to
use, the packets may be blocked.  Try using a tool like wireshark or
tcpdump to see if you're getting responses from the server.  If you have
an external modem, see if the receive light blinks straight after the
transmit light (when the link is quiet apart from the NTP traffic.)  Try
adding 'log measurements' to the 'chrony.conf' file and look in the
measurements.log file after chrony has been running for a short period.
See if any measurements appear.

4.2 Do you have a non-permanent (i.e. intermittent) Internet connection?
------------------------------------------------------------------------

Check that you're using chronyc's 'online' and 'offline' commands
appropriately.  Again, check in measurements.log to see if you're
getting any data back from the server.

4.3 In measurements.log, do the '7' and '8' flag columns always show zero?
--------------------------------------------------------------------------

Do you have a 'local stratum X' directive in the 'chrony.conf' file?  If
X is lower than the stratum of the server you're trying to use, this
situation will arise.  You should always make X quite high (e.g.  10) in
this directive.

5 Issues with chronyc
=====================

5.1 I keep getting the error '506 Cannot talk to daemon'
--------------------------------------------------------

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.  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.

5.2 Is the chronyc<->chronyd protocol documented anywhere?
----------------------------------------------------------

Only by the source code :-) See cmdmon.c ('chronyd' side) and client.c
('chronyc' side).

6 Real-time clock issues
========================

6.1 What is the real-time clock (RTC)?
--------------------------------------

This is the clock which keeps the time even when your computer is turned
off.  It works with 1 second resolution.  'chronyd' can monitor the rate
at which the real-time clock gains or loses time, and compensate for it
when you set the system time from it at the next reboot.  See the
documentation for details.

6.2 I want to use chronyd's real-time clock support. Must I disable hwclock?
----------------------------------------------------------------------------

The hwclock program is often set-up by default in the boot and shutdown
scripts with many Linux installations.  If you want to use chronyd's
real-time clock support, the important thing is 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' 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.

6.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
   * a kernel that is supported (e.g.  2.2 onwards)
   * enhanced RTC support compiled into the kernel
   * an 'rtcfile' directive in your chrony.conf file

7 Microsoft Windows
===================

7.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 an
NT service.

7.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.

8 NTP-specific issues
=====================

8.1 Can chrony be driven from broadcast NTP servers?
----------------------------------------------------

No, this NTP mode is not implemented yet.

8.2 Can chronyd transmit broadcast NTP packets (e.g. to synchronise other computers on a private LAN)?
------------------------------------------------------------------------------------------------------

Yes.  Starting from version 1.17, chrony has this capability.

8.3 Can chrony keep the system clock a fixed offset away from real time?
------------------------------------------------------------------------

This is not possible as the program currently stands.

8.4 What happens if the network connection is dropped without using chronyc's 'offline' command first?
------------------------------------------------------------------------------------------------------

In this case 'chronyd' will keep trying to access the server(s) that it
thinks are online.  Eventually it will decide that they are unreachable
and no longer consider itself synchronised to them.  If you have other
computers on your LAN accessing the computer that is affected this way,
they too will become 'unsynchronised', unless you have the 'local'
directive set up on the master computer.

   The 'auto_offline' option to the 'server' entry in the chrony.conf
file may be useful to avoid this situation.

9 Linux-specific issues
=======================

9.1 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.

10 Solaris-specific issues
==========================

10.1 On Solaris 2.8, I get an error message about not being able to open kvm to change dosynctodr
-------------------------------------------------------------------------------------------------

(The dosynctodr variable controls whether Solaris couples the equivalent
of its BIOS clock into its system clock at regular intervals).  The
Solaris port of chrony was developed in the Solaris 2.5 era.  Some
aspect of the Solaris kernel has changed which prevents the same
technique working.  We no longer have root access to any Solaris
machines to work on this, and we are reliant on somebody developing the
patch and testing it.

