Manual for version 2.3

1 Introduction

1.1 Overview

chrony is a versatile implementation of the Network Time Protocol (NTP). It can synchronize the system clock with NTP servers, reference clocks (e.g. GPS receiver), and manual input using wristwatch and keyboard. It can also operate as an NTPv4 (RFC 5905) server and peer to provide a time service to other computers in the network.

It is designed to perform well in a wide range of conditions, including intermittent network connections, heavily congested networks, changing temperatures (ordinary computer clocks are sensitive to temperature), and systems that do not run continuosly, or run on a virtual machine.

Typical accuracy between two machines on a LAN is in tens, or a few hundreds, of microseconds; over the Internet, accuracy is typically within a few milliseconds. With a good hardware reference clock sub-microsecond accuracy is possible.

Two programs are included in chrony, chronyd is a daemon that can be started at boot time and chronyc is a command-line interface program which can be used to monitor chronyd ’s performance and to change various operating parameters whilst it is running.

The IP addresses from which chronyc clients may connect can be tightly controlled. The default is just the computer that chronyd itself is running on.

1.2 Acknowledgements

The chrony suite makes use of the algorithm known as RSA Data Security, Inc. MD5 Message-Digest Algorithm for authenticating messages between different machines on the network.

In writing the chronyd program, extensive use has been made of RFC 1305 and RFC 5905, written by David Mills. The source code of the NTP reference implementation has been used to check details of the protocol.

1.3 Availability

1.3.1 Getting the software Where can I get the software from? 1.3.2 Platforms Which platforms will it run on?

1.3.1 Getting the software

Links on the chrony home page describe how to obtain the software.

1.3.2 Platforms

Although most of the program is portable between Unix-like systems, there are parts that have to be tailored to each specific vendor’s system. These are the parts that interface with the operating system’s facilities for adjusting the system clock; different operating systems may provide different function calls to achieve this, and even where the same function is used it may have different quirks in its behaviour.

The software is known to work on Linux, FreeBSD, NetBSD, Mac OS X and Solaris. Closely related systems may work too. Porting the software to other systems (particularly to those supporting an adjtime or ntp_adjtime system call) should not be difficult, however it requires access to such systems to test out the driver.

1.4 Relationship to other software packages

1.4.1 ntpd

The ‘reference’ implementation of the Network Time Protocol is the program ntpd , available via The NTP home page.

One of the main differences between ntpd and chronyd is in how they control the computer’s clock. Things chronyd can do better than ntpd :

chronyd can perform usefully in an environment where access to the time reference is intermittent. ntpd needs regular polling of the reference to work well.

can perform usefully in an environment where access to the time reference is intermittent. needs regular polling of the reference to work well. chronyd can usually synchronise the clock faster and with better time accuracy.

can usually synchronise the clock faster and with better time accuracy. chronyd quickly adapts to sudden changes in the rate of the clock (e.g. due to changes in the temperature of the crystal oscillator). ntpd may need a long time to settle down again.

quickly adapts to sudden changes in the rate of the clock (e.g. due to changes in the temperature of the crystal oscillator). may need a long time to settle down again. chronyd can perform well even when the network is congested for longer periods of time.

can perform well even when the network is congested for longer periods of time. chronyd in the default configuration never steps the time to not upset other running programs. ntpd can be configured to never step the time too, but in that case it has to use a different means of adjusting the clock (daemon loop instead of kernel discipline), which may have a negative effect on accuracy of the clock.

in the default configuration never steps the time to not upset other running programs. can be configured to never step the time too, but in that case it has to use a different means of adjusting the clock (daemon loop instead of kernel discipline), which may have a negative effect on accuracy of the clock. chronyd can adjust the rate of the clock in a larger range, which allows it to operate even on machines with broken or unstable clock (e.g. in some virtual machines).

can adjust the rate of the clock in a larger range, which allows it to operate even on machines with broken or unstable clock (e.g. in some virtual machines). chronyd is smaller, it uses less memory and it wakes up the CPU only when necessary, which is better for power saving.

Things chronyd can do that ntpd can’t:

chronyd provides support for isolated networks whether the only method of time correction is manual entry (e.g. by the administrator looking at a clock). chronyd can look at the errors corrected at different updates to work out the rate at which the computer gains or loses time, and use this estimate to trim the computer clock subsequently.

provides support for isolated networks whether the only method of time correction is manual entry (e.g. by the administrator looking at a clock). can look at the errors corrected at different updates to work out the rate at which the computer gains or loses time, and use this estimate to trim the computer clock subsequently. chronyd provides support to work out the gain or loss rate of the ‘real-time clock’, i.e. the clock that maintains the time when the computer is turned off. It can use this data when the system boots to set the system time from a corrected version of the real-time clock. These real-time clock facilities are only available on Linux, so far.

Things ntpd can do that chronyd can’t:

ntpd supports all operating modes from RFC 5905, including broadcast, multicast, and manycast server/client. However, the broadcast and multicast modes are inherently less accurate and less secure (even with authentication) than the ordinary server/client mode and should generally be avoided.

supports all operating modes from RFC 5905, including broadcast, multicast, and manycast server/client. However, the broadcast and multicast modes are inherently less accurate and less secure (even with authentication) than the ordinary server/client mode and should generally be avoided. ntpd supports the Autokey protocol (RFC 5906) to authenticate servers with public-key cryptography. Note that the protocol has been shown to be insecure and it will be probably replaced with an implementation of the Network Time Security (NTS) specification.

supports the Autokey protocol (RFC 5906) to authenticate servers with public-key cryptography. Note that the protocol has been shown to be insecure and it will be probably replaced with an implementation of the Network Time Security (NTS) specification. ntpd supports the orphan mode, which allows synchronisation to a common timescale in isolated networks with multiple servers. With chronyd there can be only one master and all other computers have to be directly or indirectly synchronised to it.

supports the orphan mode, which allows synchronisation to a common timescale in isolated networks with multiple servers. With there can be only one master and all other computers have to be directly or indirectly synchronised to it. ntpd has been ported to more operating systems.

has been ported to more operating systems. ntpd includes a large number of reference clock drivers. chronyd relies on other programs (e.g. gpsd ) to access the timing data via the SHM or SOCK driver.

A comparison of NTP implementations that includes more features and also their performance is on the chrony comparison page.

1.4.2 timed

timed is a program that is part of the BSD networking suite. It uses broadcast packets to find all machines running the daemon within a subnet. The machines elect a master which periodically measures the system clock offsets of the other computers using ICMP timestamps. Corrections are sent to each member as a result of this process.

Problems that may arise with timed are :

Because it uses broadcasts, it is not possible to isolate its functionality to a particular group of computers; there is a risk of upsetting other computers on the same network (e.g. where a whole company is on the same subnet but different departments are independent from the point of view of administering their computers.)

The update period appears to be 10 minutes. Computers can build up significant offsets relative to each other in that time. If a computer can estimate its rate of drift it can keep itself closer to the other computers between updates by adjusting its clock every few seconds. timed does not seem to do this.

does not seem to do this. timed does not have any integrated capability for feeding real-time into its estimates, or for estimating the average rate of time loss/gain of the machines relative to real-time (unless one of the computers in the group has access to an external reference and is always appointed as the ‘master’).

timed does have the benefit over chronyd that for isolated networks of computers, they will track the ‘majority vote’ time. For such isolated networks, chronyd requires one computer to be the ‘master’ with the others slaved to it. If the master has a particular defective clock, the whole set of computers will tend to slip relative to real time (but they will stay accurate relative to one another).

1.5 Distribution rights and (lack of) warranty

Chrony may be distributed in accordance with the GNU General Public License version 2, reproduced in See section GNU General Public License.

1.6 Bug reporting and suggestions

If you think you’ve found a bug in chrony, or have a suggestion, please let us know. You can join chrony users mailing list by sending a message with the subject subscribe to chrony-users-request@chrony.tuxfamily.org. Only subscribers can post to the list.

When you are reporting a bug, please send us all the information you can. Unfortunately, chrony has proven to be one of those programs where it is very difficult to reproduce bugs in a different environment. So we may have to interact with you quite a lot to obtain enough extra logging and tracing to pin-point the problem in some cases. Please be patient and plan for this!

Of course, if you can debug the problem yourself and send us a source code patch to fix it, we will be very grateful!

2 Installation

The software is distributed as source code which has to be compiled. The source code is supplied in the form of a gzipped tar file, which unpacks to a subdirectory identifying the name and version of the program.

After unpacking the source code, change directory into it, and type

./configure

This is a shell script that automatically determines the system type. There is a single optional parameter, --prefix which indicates the directory tree where the software should be installed. For example,

./configure --prefix=/opt/free

will install the chronyd daemon into /opt/free/sbin and the chronyc control program into /opt/free/bin. The default value for the prefix is /usr/local.

The configure script assumes you want to use gcc as your compiler. If you want to use a different compiler, you can configure this way:

CC=cc CFLAGS=-O ./configure --prefix=/opt/free

for Bourne-family shells, or

setenv CC cc setenv CFLAGS -O ./configure --prefix=/opt/free

for C-family shells.

If the software cannot (yet) be built on your system, an error message will be shown. Otherwise, ‘ Makefile ’ will be generated.

On Linux, if development files for the libcap library are available, chronyd will be built with support for dropping root privileges. On other systems no extra library is needed. The default user which chronyd should run as can be specified with the --with-user option of the configure script.

If development files for the editline or readline library are available, chronyc will be built with line editing support. If you don’t want this, specify the –disable-readline flag to configure. Please refer to see section Support for line editing libraries for more information.

If a ‘ timepps.h ’ header is available (e.g. from the LinuxPPS project), chronyd will be built with PPS API reference clock driver. If the header is installed in a location that isn’t normally searched by the compiler, you can add it to the searched locations by setting CPPFLAGS variable to -I/path/to/timepps .

Now type

make

to build the programs.

If you want to build the manual in plain text, HTML and info versions, type

make docs

Once the programs have been successfully compiled, they need to be installed in their target locations. This step normally needs to be performed by the superuser, and requires the following command to be entered.

make install

This will install the binaries and manpages.

To install the plain text, HTML and info versions of the manual, enter the command

make install-docs

If you want chrony to appear in the top level info directory listing, you need to run the install-info command manually after this step. install-info takes 2 arguments. The first is the path to the ‘ chrony.info ’ file you have just installed. This will be the argument you gave to –prefix when you configured (‘ /usr/local ’ by default), with ‘ /share/info/chrony.info ’ on the end. The second argument is the location of the file called ‘ dir ’. This will typically be ‘ /usr/share/info/dir ’. So the typical command line would be

install-info /usr/local/share/info/chrony.info /usr/share/info/dir

Now that the software is successfully installed, the next step is to set up a configuration file. The default location of the file is ‘ /etc/chrony.conf ’. Several examples of configuration with comments are included in the examples directory. Suppose you want to use public NTP servers from the pool.ntp.org project as your time reference. A minimal useful configuration file could be

pool pool.ntp.org iburst makestep 1.0 3 rtcsync

Then, chronyd can be run. For security reasons, it’s recommended to create an unprivileged user for chronyd and specify it with the -u command-line option or the user directive in the configuration file, or set the default user with the --with-user configure option before building.

2.1 Support for line editing libraries

Chronyc can be built with support for line editing, this allows you to use the cursor keys to replay and edit old commands. Two libraries are supported which provide such functionality, editline and GNU readline.

Please note that readline since version 6.0 is licensed under GPLv3+ which is incompatible with chrony’s license GPLv2. You should use editline instead if you don’t want to use older readline versions.

The configure script will automatically enable the line editing support if one of the supported libraries is available. If they are both available, the editline library will be used.

If you don’t want to use it (in which case chronyc will use a minimal command line interface), invoke configure like this:

./configure --disable-readline other-options...

If you have editline, readline or ncurses installed in locations that aren’t normally searched by the compiler and linker, you need to use extra options:

‘ --with-readline-includes=directory_name ’ This defines the name of the directory above the one where ‘ readline.h ’ is. ‘ readline.h ’ is assumed to be in ‘ editline ’ or ‘ readline ’ subdirectory of the named directory. ‘ --with-readline-library=directory_name ’ This defines the directory containing the ‘ libedit.a ’ or ‘ libedit.so ’ file, or ‘ libreadline.a ’ or ‘ libreadline.so ’ file. ‘ --with-ncurses-library=directory_name ’ This defines the directory containing the ‘ libncurses.a ’ or ‘ libncurses.so ’ file.

2.2 Extra options for package builders

The configure and make procedures have some extra options that may be useful if you are building a distribution package for chrony.

The –infodir=DIR option to configure specifies an install directory for the info files. This overrides the ‘ info ’ subdirectory of the argument to the –prefix option. For example, you might use

./configure --prefix=/usr --infodir=/usr/share/info

The –mandir=DIR option to configure specifies an install directory for the man pages. This overrides the ‘ man ’ subdirectory of the argument to the –prefix option.

./configure --prefix=/usr --infodir=/usr/share/info --mandir=/usr/share/man

to set both options together.

The final option is the DESTDIR option to the make command. For example, you could use the commands

./configure --prefix=/usr --infodir=/usr/share/info --mandir=/usr/share/man make all docs make install DESTDIR=./tmp cd tmp tar cvf - . | gzip -9 > chrony.tar.gz

to build a package. When untarred within the root directory, this will install the files to the intended final locations.

3 Typical operating scenarios

3.1 Computers connected to the internet

In this section we discuss how to configure chrony for computers that are connected to the Internet (or to any network containing true NTP servers which ultimately derive their time from a reference clock) permanently or most of the time.

To operate in this mode, you will need to know the names of the NTP server machines you wish to use. You may be able to find names of suitable servers by one of the following methods:

Your institution may already operate servers on its network. Contact your system administrator to find out.

Your ISP probably has one or more NTP servers available for its customers.

Somewhere under the NTP homepage there is a list of public stratum 1 and stratum 2 servers. You should find one or more servers that are near to you — check that their access policy allows you to use their facilities.

Use public servers from the pool.ntp.org project.

Assuming that you have found some servers, you need to set up a configuration file to run chrony. The (compiled-in) default location for this file is ‘ /etc/chrony.conf ’. Assuming that your NTP servers are called foo.example.net , bar.example.net and baz.example.net , your ‘ chrony.conf ’ file could contain as a minimum

server foo.example.net server bar.example.net server baz.example.net

However, you will probably want to include some of the other directives described later. The following directives may be particularly useful : driftfile , makestep , rtcsync . Also, the iburst server option is useful to speed up the initial synchronization. The smallest useful configuration file would look something like

server foo.example.net iburst server bar.example.net iburst server baz.example.net iburst driftfile /var/lib/chrony/drift makestep 1.0 3 rtcsync

When using a pool of NTP servers (one name is used for multiple servers which may change over time), it’s better to specify them with the pool directive instead of multiple server directives. The configuration file could in this case look like

pool pool.ntp.org iburst driftfile /var/lib/chrony/drift makestep 1.0 3 rtcsync

3.2 Infrequent connection to true NTP servers

In this section we discuss how to configure chrony for computers that have occasional connections to the internet.

3.2.1 Setting up the configuration file for infrequent connections

As in the previous section, you will need access to NTP servers on the internet. The same remarks apply for how to find them.

In this case, you will need some additional configuration to tell chronyd when the connection to the internet goes up and down. This saves the program from continuously trying to poll the servers when they are inaccessible.

Again, assuming that your NTP servers are called foo.example.net , bar.example.net and baz.example.net , your ‘ chrony.conf ’ file would need to contain something like

server foo.example.net server bar.example.net server baz.example.net

However, your computer will keep trying to contact the servers to obtain timestamps, even whilst offline. If you operate a dial-on-demand system, things are even worse, because the link to the internet will keep getting established.

For this reason, it would be better to specify this part of your configuration file in the following way:

server foo.example.net offline server bar.example.net offline server baz.example.net offline

The offline keyword indicates that the servers start in an offline state, and that they should not be contacted until chronyd receives notification from chronyc that the link to the internet is present.

The smallest useful configuration file would look something like

server foo.example.net offline server bar.example.net offline server baz.example.net offline driftfile /var/lib/chrony/drift makestep 1.0 3 rtcsync

The next section describes how to tell chronyd when the internet link goes up and down.

3.2.2 How to tell chronyd when the internet link is available.

To tell chronyd when to start and finish sampling the servers, the online and offline commands of chronyc need to be used. To give an example of their use, we assume that pppd is the program being used to connect to the internet, and that chronyc has been installed at its default location ‘ /usr/local/bin/chronyc ’.

In the file ‘ /etc/ppp/ip-up ’ we add the command sequence

/usr/local/bin/chronyc online

and in the file ‘ /etc/ppp/ip-down ’ we add the sequence

/usr/local/bin/chronyc offline

chronyd's polling of the servers will now only occur whilst the machine is actually connected to the Internet.

3.3 Isolated networks

In this section we discuss how to configure chrony for computers that never have network conectivity to any computer which ultimately derives its time from a reference clock.

In this situation, one computer is selected to be the master timeserver. The other computers are either direct clients of the master, or clients of clients.

The rate value in the master’s drift file needs to be set to the average rate at which the master gains or loses time. chronyd includes support for this, in the form of the manual directive in the configuration file and the settime command in the chronyc program.

The smoothtime directive (see section smoothtime) is useful when the clocks of the clients need to stay close together when the local time is adjusted by the settime command. The smoothing process needs to be activated by the smoothtime activate command when the local time is ready to be served. After that point, any adjustments will be smoothed out.

A typical configuration file for the master (called master ) might be (assuming the clients are in the 192.168.165.x subnet)

driftfile /var/lib/chrony/drift local stratum 8 manual allow 192.168.165 smoothtime 400 0.01

For the clients the configuration file might be

server master iburst driftfile /var/lib/chrony/drift logdir /var/log/chrony log measurements statistics tracking

3.4 The home PC with a dial-up connection

3.4.1 Assumptions/how the software works

This section considers the home computer which has a dial-up connection. It assumes that Linux is run exclusively on the computer. Dual-boot systems may work; it depends what (if anything) the other system does to the system’s real-time clock.

Much of the configuration for this case is discussed earlier (see section Infrequent connection to true NTP servers). This section addresses specifically the case of a computer which is turned off between ’sessions’.

In this case, chronyd relies on the computer’s real-time clock (RTC) to maintain the time between the periods when it is powered up. The arrangement is shown in the figure below.

trim if required PSTN +---------------------------+ +----------+ | | | | v | | | +---------+ +-------+ +-----+ +---+ | System's| measure error/ |chronyd| |modem| |ISP| |real-time|------------------->| |-------| | | | | clock | drift rate +-------+ +-----+ +---+ +---------+ ^ | | | | +---------------------------+ --o-----o--- set time at boot up | +----------+ |NTP server| +----------+

When the computer is connected to the Internet (via the modem), chronyd has access to external NTP servers which it makes measurements from. These measurements are saved, and straight-line fits are performed on them to provide an estimate of the computer’s time error and rate of gaining/losing time.

When the computer is taken offline from the Internet, the best estimate of the gain/loss rate is used to free-run the computer until it next goes online.

Whilst the computer is running, chronyd makes measurements of the real-time clock (RTC) (via the ‘ /dev/rtc ’ interface, which must be compiled into the kernel). An estimate is made of the RTC error at a particular RTC second, and the rate at which the RTC gains or loses time relative to true time.

On 2.6 and later kernels, if your motherboard has a HPET, you need to enable the ‘ HPET_EMULATE_RTC ’ option in your kernel configuration. Otherwise, chrony will not be able to interact with the RTC device and will give up using it.

When the computer is powered down, the measurement histories for all the NTP servers are saved to files (if the dumponexit directive is specified in the configuration file), and the RTC tracking information is also saved to a file (if the rtcfile directive has been specified). These pieces of information are also saved if the dump and writertc commands respectively are issued through chronyc .

When the computer is rebooted, chronyd reads the current RTC time and the RTC information saved at the last shutdown. This information is used to set the system clock to the best estimate of what its time would have been now, had it been left running continuously. The measurement histories for the servers are then reloaded.

The next time the computer goes online, the previous sessions’ measurements can contribute to the line-fitting process, which gives a much better estimate of the computer’s gain/loss rate.

One problem with saving the measurements and RTC data when the machine is shut down is what happens if there is a power failure; the most recent data will not be saved. Although chronyd is robust enough to cope with this, some performance may be lost. (The main danger arises if the RTC has been changed during the session, with the trimrtc command in chronyc . Because of this, trimrtc will make sure that a meaningful RTC file is saved out after the change is completed).

The easiest protection against power failure is to put the dump and writertc commands in the same place as the offline command is issued to take chronyd offline; because chronyd free-runs between online sessions, no parameters will change significantly between going offline from the Internet and any power failure.

A final point regards home computers which are left running for extended periods and where it is desired to spin down the hard disc when it is not in use (e.g. when not accessed for 15 minutes). chronyd has been planned so it supports such operation; this is the reason why the RTC tracking parameters are not saved to disc after every update, but only when the user requests such a write, or during the shutdown sequence. The only other facility that will generate periodic writes to the disc is the log rtc facility in the configuration file; this option should not be used if you want your disc to spin down.

3.4.2 Typical configuration files.

To illustrate how a dial-up home computer might be configured, example configuration files are shown in this section.

For the ‘ /etc/chrony.conf ’ file, the following can be used as an example.

server foo.example.net maxdelay 0.4 offline server bar.example.net maxdelay 0.4 offline server baz.example.net maxdelay 0.4 offline logdir /var/log/chrony log statistics measurements tracking driftfile /var/lib/chrony/drift makestep 1.0 3 maxupdateskew 100.0 dumponexit dumpdir /var/lib/chrony rtcfile /var/lib/chrony/rtc

pppd is used for connecting to the internet. This runs two scripts ‘ /etc/ppp/ip-up ’ and ‘ /etc/ppp/ip-down ’ when the link goes online and offline respectively.

The relevant part of the ‘ /etc/ppp/ip-up ’ file is

/usr/local/bin/chronyc online

and the relevant part of the ‘ /etc/ppp/ip-down ’ script is

/usr/local/bin/chronyc -m offline dump writertc

To start chronyd during the boot sequence, the following is in ‘ /etc/rc.d/rc.local ’ (this is a Slackware system)

if [ -f /usr/local/sbin/chronyd -a -f /etc/chrony.conf ]; then /usr/local/sbin/chronyd -r -s echo "Start chronyd" fi

The placement of this command may be important on some systems. In particular, chronyd may need to be started before any software that depends on the system clock not jumping or moving backwards, depending on the directives in chronyd's configuration file.

For the system shutdown, chronyd should receive a SIGTERM several seconds before the final SIGKILL; the SIGTERM causes the measurement histories and RTC information to be saved out.

3.5 Other important configuration options

The most common option to include in the configuration file is the driftfile option. One of the major tasks of chronyd is to work out how fast or how slow the system clock runs relative to real time - e.g. in terms of seconds gained or lost per day. Measurements over a long period are usually required to refine this estimate to an acceptable degree of accuracy. Therefore, it would be bad if chronyd had to work the value out each time it is restarted, because the system clock would not run so accurately whilst the determination is taking place.

To avoid this problem, chronyd allows the gain or loss rate to be stored in a file, which can be read back in when the program is restarted. This file is called the drift file, and might typically be stored in ‘ /var/lib/chrony/drift ’. By specifying an option like the following

driftfile /var/lib/chrony/drift

in the configuration file (‘ /etc/chrony.conf ’), the drift file facility will be activated.

4 Usage reference

4.1 Starting chronyd

If chronyd has been installed to its default location ‘ /usr/local/sbin/chronyd ’, starting it is simply a matter of entering the command

/usr/local/sbin/chronyd

Information messages and warnings will be logged to syslog.

If no configuration commands are specified on the command line, chronyd will read the commands from the configuration file (default ‘ /etc/chrony.conf ’).

The command line options supported are as follows:

-n When run in this mode, the program will not detach itself from the terminal. -d When run in this mode, the program will not detach itself from the terminal, and all messages will be sent to the terminal instead of to syslog. When chronyd was compiled with debugging support, this option can be used twice to print also debugging messages. -f <conf-file> This option can be used to specify an alternate location for the configuration file (default ‘ /etc/chrony.conf ’). -r This option will reload sample histories for each of the servers and refclocks being used. These histories are created by using the dump command in chronyc , or by setting the dumponexit directive in the configuration file. This option is useful if you want to stop and restart chronyd briefly for any reason, e.g. to install a new version. However, it should be used only on systems where the kernel can maintain clock compensation whilst not under chronyd's control (i.e. Linux, FreeBSD, NetBSD and Solaris). -R When this option is used, the initstepslew directive and the makestep directive used with a positive limit will be ignored. This option is useful when restarting chronyd and can be used in conjunction with the ‘-r’ option. -s This option will set the system clock from the computer’s real-time clock or to the last modification time of the file specified by the driftfile directive. Real-time clocks are supported only on Linux. If used in conjunction with the ‘-r’ flag, chronyd will attempt to preserve the old samples after setting the system clock from the real time clock (RTC). This can be used to allow chronyd to perform long term averaging of the gain or loss rate across system reboots, and is useful for dial-up systems that are shut down when not in use. For this to work well, it relies on chronyd having been able to determine accurate statistics for the difference between the RTC and system clock last time the computer was on. If the last modification time of the drift file is later than the current time and the RTC time, the system time will be set to it to restore the time when chronyd was previously stopped. This is useful on computers that have no RTC or the RTC is broken (e.g. it has no battery). -u <user> This option sets the name of the system user to which chronyd will switch after start in order to drop root privileges. It overrides the user directive (default chrony ). On Linux, chronyd needs to be compiled with support for the libcap library. On Mac OS X, FreeBSD, NetBSD and Solaris 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. -F <level> This option configures a system call filter when chronyd is compiled with support for the Linux secure computing (seccomp) facility. In level 1 the process is killed when a forbidden system call is made, in level -1 the SYSSIG signal is thrown instead and in level 0 the filter is disabled (default 0). 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. -q When run in this mode, chronyd will set the system clock once and exit. It will not detach from the terminal. -Q This option is similar to ‘-q’, but it will only print the offset and not correct the clock. -v This option displays chronyd's version number to the terminal and exits. -P <priority> On Linux, this option will select the SCHED_FIFO real-time scheduler at the specified priority (which must be between 0 and 100). On Mac OS X, this option must have either a value of 0 (the default) to disable the thread time constraint policy or 1 for the policy to be enabled. Other systems do not support this option. -m This option will lock chronyd into RAM so that it will never be paged out. This mode is only supported on Linux. -4 With this option hostnames will be resolved only to IPv4 addresses and only IPv4 sockets will be created. -6 With this option hostnames will be resolved only to IPv6 addresses and only IPv6 sockets will be created.

On systems that support an ‘ /etc/rc.local ’ file for starting programs at boot time, chronyd can be started from there.

On systems with a System V style initialisation, a suitable start/stop script might be as shown below. This might be placed in the file ‘ /etc/rc2.d/S83chrony ’.

#!/bin/sh # This file should have uid root, gid sys and chmod 744 # killproc() { # kill the named process(es) pid=`/usr/bin/ps -e | /usr/bin/grep -w $1 | /usr/bin/sed -e 's/^ *//' -e 's/ .*//'` [ "$pid" != "" ] && kill $pid } case "$1" in 'start') if [ -f /opt/free/sbin/chronyd -a -f /etc/chrony.conf ]; then /opt/free/sbin/chronyd fi ;; 'stop') killproc chronyd ;; *) echo "Usage: /etc/rc2.d/S83chrony { start | stop }" ;; esac

(In both cases, you may want to bear in mind that chronyd can step the time when it starts. There may be other programs started at boot time that could be upset by this, so you may need to consider the ordering carefully. However, chronyd will need to start after daemons providing services that it may require, e.g. the domain name service.)

4.2 The chronyd configuration file

The configuration file is normally called ‘ /etc/chrony.conf ’; in fact, this is the compiled-in default. However, other locations can be specified with a command line option.

Each command in the configuration file is placed on a separate line. The following sections describe each of the commands in turn. The directives can occur in any order in the file and they are not case-sensitive.

The configuration commands can also be specified directly on the chronyd command line, each argument is parsed as a line and the configuration file is ignored.

4.2.1 Comments in the configuration file

The configuration file may contain comment lines. A comment line is any line that starts with zero or more spaces followed by any one of the following characters:

!

;

#

%

Any line with this format will be ignored.

4.2.2 acquisitionport

By default, chronyd uses a separate client socket for each configured server and their source port is chosen arbitrarily by the operating system. However, you can use the acquisitionport directive to explicitly specify a port and use only one socket (per IPv4/IPv6 address family) for all configured servers. This may be useful for getting through firewalls. If set to 0, the source port of the socket will be chosen arbitrarily.

It may be set to the same port as used by the NTP server (see section port) to use only one socket for all NTP packets.

An example of the acquisitionport command is

acquisitionport 1123

This would change the source port used for client requests to udp/1123. You could then persuade the firewall administrator to let that port through.

4.2.3 allow

The allow command is used to designate a particular subnet from which NTP clients are allowed to access the computer as an NTP server.

The default is that no clients are allowed access, i.e. chronyd operates purely as an NTP client. If the allow directive is used, chronyd will be both a client of its servers, and a server to other clients.

Examples of use of the command are as follows:

allow foo.example.net allow 1.2 allow 3.4.5 allow 6.7.8/22 allow 6.7.8.9/22 allow 2001:db8::/32 allow 0/0 allow ::/0 allow

The first command allows the named node to be an NTP client of this computer. The second command allows any node with an IPv4 address of the form 1.2.x.y (with x and y arbitrary) to be an NTP client of this computer. Likewise, the third command allows any node with an IPv4 address of the form 3.4.5.x to have client NTP access. The fourth and fifth forms allow access from any node with an IPv4 address of the form 6.7.8.x, 6.7.9.x, 6.7.10.x or 6.7.11.x (with x arbitrary), i.e. the value 22 is the number of bits defining the specified subnet. (In the fifth form, the final byte is ignored). The sixth form is used for IPv6 addresses. The seventh and eighth forms allow access by any IPv4 and IPv6 node respectively. The ninth forms allows access by any node (IPv4 or IPv6).

A second form of the directive, allow all , has a greater effect, depending on the ordering of directives in the configuration file. To illustrate the effect, consider the two examples

allow 1.2.3.4 deny 1.2.3 allow 1.2

and

allow 1.2.3.4 deny 1.2.3 allow all 1.2

In the first example, the effect is the same regardles of what order the three directives are given in. So the 1.2.x.y subnet is allowed access, except for the 1.2.3.x subnet, which is denied access, however the host 1.2.3.4 is allowed access.

In the second example, the allow all 1.2 directives overrides the effect of any previous directive relating to a subnet within the specified subnet. Within a configuration file this capability is probably rather moot; however, it is of greater use for reconfiguration at run-time via chronyc (see section allow all).

Note, if the initstepslew directive (see section initstepslew) is used in the configuration file, each of the computers listed in that directive must allow client access by this computer for it to work.

4.2.4 bindacqaddress

The bindacqaddress directive sets the network interface to which will chronyd bind its NTP client sockets. The syntax is similar to the bindaddress and bindcmdaddress directives.

For each of IPv4 and IPv6 protocols, only one bindacqaddress directive can be specified.

4.2.5 bindaddress

The bindaddress directive allows you to restrict the network interface to which chronyd will listen for NTP requests. This provides an additional level of access restriction above that available through the deny mechanism.

Suppose you have a local ethernet with addresses in the 192.168.1.0 subnet together with an internet connection. The ethernet interface’s IP address is 192.168.1.1. Suppose you want to block all access through the internet connection. You could add the line

bindaddress 192.168.1.1

to the configuration file.

For each of IPv4 and IPv6 protocols, only one bindaddress directive can be specified. Therefore, it’s not useful on computers which should serve NTP on multiple network interfaces.

4.2.6 bindcmdaddress

The bindcmdaddress directive allows you to specify the network interface to which chronyd will listen for monitoring command packets (issued by chronyc ). This provides an additional level of access restriction above that available through cmddeny mechanism.

This directive can also change the path of the Unix domain command socket, which is used by chronyc to send configuration commands. The socket must be in a directory that is accessible only by the root or chrony user. The directory will be created on start if it doesn’t exist. The default path of the socket is /var/run/chrony/chronyd.sock .

By default, chronyd binds to the loopback interface (with addresses 127.0.0.1 and ::1 ). This blocks all access except from localhost. To listen for command packets on all interfaces, you can add the lines

bindcmdaddress 0.0.0.0 bindcmdaddress ::

to the configuration file.

For each of IPv4 and IPv6 protocols, only one bindcmdaddress directive can be specified.

An example that sets the path of the Unix domain command socket is

bindcmdaddress /var/run/chrony/chronyd.sock

4.2.7 broadcast

The broadcast directive is used to declare a broadcast address to which chronyd should send packets in NTP broadcast mode (i.e. make chronyd act as a broadcast server). Broadcast clients on that subnet will be able to synchronise.

The syntax is as follows

broadcast 30 192.168.1.255 broadcast 60 192.168.2.255 12123 broadcast 60 ff02::101

In the first example, the destination port defaults to 123/udp (the normal NTP port). In the second example, the destionation port is specified as 12123. The first parameter in each case (30 or 60 respectively) is the interval in seconds between broadcast packets being sent. The second parameter in each case is the broadcast address to send the packet to. This should correspond to the broadcast address of one of the network interfaces on the computer where chronyd is running.

You can have more than 1 broadcast directive if you have more than 1 network interface onto which you wish to send NTP broadcast packets.

chronyd itself cannot currently act as a broadcast client; it must always be configured as a point-to-point client by defining specific NTP servers and peers. This broadcast server feature is intended for providing a time source to other NTP software (e.g. various MS Windows clients).

If ntpd is used as the broadcast client, it will try to use a point-to-point client/server NTP access to measure the round-trip delay. Thus, the broadcast subnet should also be the subject of an allow directive (see section allow).

4.2.8 clientloglimit

This directive specifies the maximum amount of memory that chronyd is allowed to allocate for logging of client accesses. The default limit is 524288 bytes, which allows monitoring of several thousands of addresses at the same time.

In older chrony versions if the limit was set to 0, the memory allocation was unlimited.

An example of the use of this directive is

clientloglimit 1048576

4.2.9 cmdallow

This is similar to the allow directive (see section allow), except that it allows monitoring access (rather than NTP client access) to a particular subnet or host. (By ’monitoring access’ is meant that chronyc can be run on those hosts and retrieve monitoring data from chronyd on this computer.)

The syntax is identical to the allow directive.

There is also a cmdallow all directive with similar behaviour to the allow all directive (but applying to monitoring access in this case, of course).

Note that chronyd has to be configured with the bindcmdaddress directive to not listen only on the loopback interface to actually allow remote access.

4.2.10 cmddeny

This is similar to the cmdallow directive (see section cmdallow), except that it denies monitoring access to a particular subnet or host, rather than allowing it.

The syntax is identical.

There is also a cmddeny all directive with similar behaviour to the cmdallow all directive.

4.2.11 cmdport

The cmdport directive allows the port that is used for run-time monitoring (via the chronyc program) to be altered from its default (323/udp). If set to 0, chronyd will not open the port, this is useful to disable the chronyc access from the internet. (It does not disable the Unix domain command socket.)

An example shows the syntax

cmdport 257

This would make chronyd use 257/udp as its command port. ( chronyc would need to be run with the -p 257 switch to inter-operate correctly).

4.2.12 cmdratelimit

This directive enables response rate limiting for command packets. It’s similar to the ratelimit directive (see section ratelimit), except responses to the localhost are never limited and the default interval is 1 (2 seconds), default burst is 16, and default leak rate is 2.

An example of use of the command is

cmdratelimit interval 2

4.2.13 combinelimit

When chronyd has multiple sources available for synchronization, it has to select one source as the synchronization source. The measured offsets and frequencies of the system clock relative to the other sources, however, can be combined with the selected source to improve the accuracy of the system clock.

The combinelimit directive limits which sources are included in the combining algorithm. Their synchronization distance has to be shorter than the distance of the selected source multiplied by the value of the limit. Also, their measured frequencies have to be close to the frequency of the selected source.

By default, the limit is 3. Setting the limit to 0 effectively disables the source combining algorithm and only the selected source will be used to control the system clock.

The syntax is

combinelimit <limit>

4.2.14 corrtimeratio

When chronyd is slewing the system clock to correct an offset, the rate at which it is slewing adds to the frequency error of the clock. On Linux, FreeBSD, NetBSD and Solaris this rate can be controlled.

The corrtimeratio directive sets the ratio between the duration in which the clock is slewed for an average correction according to the source history and the interval in which the corrections are done (usually the NTP polling interval). Corrections larger than the average take less time and smaller corrections take more time, the amount of the correction and the correction time are inversely proportional.

Increasing corrtimeratio improves the overall frequency error of the system clock, but increases the overall time error as the corrections take longer.

By default, the ratio is set to 3, the time accuracy of the clock is preferred over its frequency accuracy.

The syntax is

corrtimeratio 100

The maximum allowed slew rate can be set by the maxslewrate directive (see section maxslewrate. The current remaining correction is shown in the tracking report (see section tracking) as the System time value.

4.2.15 deny

This is similar to the allow directive (see section allow), except that it denies NTP client access to a particular subnet or host, rather than allowing it.

The syntax is identical.

There is also a deny all directive with similar behaviour to the allow all directive.

4.2.16 driftfile

One of the main activities of the chronyd program is to work out the rate at which the system clock gains or loses time relative to real time.

Whenever chronyd computes a new value of the gain/loss rate, it is desirable to record it somewhere. This allows chronyd to begin compensating the system clock at that rate whenever it is restarted, even before it has had a chance to obtain an equally good estimate of the rate during the new run. (This process may take many minutes, at least).

The driftfile command allows a file to be specified into which chronyd can store the rate information. Two parameters are recorded in the file. The first is the rate at which the system clock gains or loses time, expressed in parts per million, with gains positive. Therefore, a value of 100.0 indicates that when the system clock has advanced by a second, it has gained 100 microseconds on reality (so the true time has only advanced by 999900 microseconds). The second is an estimate of the error bound around the first value in which the true rate actually lies.

An example of the driftfile command is

driftfile /var/lib/chrony/drift

4.2.17 dumpdir

To compute the rate of gain or loss of time, chronyd has to store a measurement history for each of the time sources it uses.

Certain systems (Linux, FreeBSD, NetBSD, Solaris) have operating system support for setting the rate of gain or loss to compensate for known errors. (On Mac OS X, chronyd must simulate such a capability by periodically slewing the system clock forwards or backwards by a suitable amount to compensate for the error built up since the previous slew).

For such systems, it is possible to save the measurement history across restarts of chronyd (assuming no changes are made to the system clock behaviour whilst it is not running). If this capability is to be used (via the dumponexit command in the configuration file, or the dump command in chronyc), the dumpdir command should be used to define the directory where the measurement histories are saved.

An example of the command is

dumpdir /var/lib/chrony

A source whose reference id (the IP address for IPv4 sources) is 1.2.3.4 would have its measurement history saved in the file ‘ /var/lib/chrony/1.2.3.4.dat ’.

4.2.18 dumponexit

If this command is present, it indicates that chronyd should save the measurement history for each of its time sources recorded whenever the program exits. (See the dumpdir command above).

4.2.19 fallbackdrift

Fallback drifts are long-term averages of the system clock drift calculated over exponentially increasing intervals. They are used when the clock is no longer synchronised to avoid quickly drifting away from true time if there was a short-term deviation in the drift before the synchronisation was lost.

The directive specifies the minimum and maximum interval since last clock update to switch between fallback drifts. They are defined as a power of 2 (in seconds). The syntax is as follows

fallbackdrift 16 19

In this example, the minimum interval is 16 (18 hours) and maximum interval is 19 (6 days). The system clock frequency will be set to the first fallback 18 hours after last clock update, to the second after 36 hours, etc. This might be a good setting to cover daily and weekly temperature fluctuations.

By default (or if the specified maximum or minimum is 0), no fallbacks are used and the clock frequency changes only with new measurements from NTP, reference clocks or manual input.

4.2.20 hwclockfile

The hwclockfile directive sets the location of the adjtime file which is used by the ‘ /sbin/hwclock ’ program on Linux. chronyd parses the file to find out if the RTC keeps local time or UTC. It overrides the rtconutc directive (see section rtconutc).

The default value is ‘ ’.

An example of the command is

hwclockfile /etc/adjtime

4.2.21 include

The include directive includes a specified configuration file or multiple configuration files when a wildcard pattern is specified. This can be useful when maintaining configuration on multiple hosts to keep the differences in separate files.

An example of the command is

include /etc/chrony.d/*.conf

4.2.22 initstepslew

In normal operation, chronyd slews the time when it needs to adjust the system clock. For example, to correct a system clock which is 1 second slow, chronyd slightly increases the amount by which the system clock is advanced on each clock interrupt, until the error is removed. (Actually, this is done by calling the adjtime() or similar system function which does it for us.) Note that at no time does time run backwards with this method.

On most Unix systems it is not desirable to step the system clock, because many programs rely on time advancing monotonically forwards.

When the chronyd daemon is initially started, it is possible that the system clock is considerably in error. Attempting to correct such an error by slewing may not be sensible, since it may take several hours to correct the error by this means.

The purpose of the initstepslew directive is to allow chronyd to make a rapid measurement of the system clock error at boot time, and to correct the system clock by stepping before normal operation begins. Since this would normally be performed only at an appropriate point in the system boot sequence, no other software should be adversely affected by the step.

If the correction required is less than a specified threshold, a slew is used instead. This makes it easier to restart chronyd whilst the system is in normal operation.

The initstepslew directive takes a threshold and a list of NTP servers as arguments. Each of the servers is rapidly polled several times, and a majority voting mechanism used to find the most likely range of system clock error that is present. A step (or slew) is applied to the system clock to correct this error. chronyd then enters its normal operating mode.

An example of use of the command is

initstepslew 30 foo.example.net bar.example.net

where 2 NTP servers are used to make the measurement. The 30 indicates that if the system’s error is found to be 30 seconds or less, a slew will be used to correct it; if the error is above 30 seconds, a step will be used.

The initstepslew directive can also be used in an isolated LAN environment, where the clocks are set manually. The most stable computer is chosen as the master, and the other computers are slaved to it. If each of the slaves is configured with the local option (see below), the master can be set up with an initstepslew directive which references some or all of the slaves. Then, if the master machine has to be rebooted, the slaves can be relied on to ’flywheel’ the time for the master.

The initstepslew directive is functionally similar to a combination of the makestep and server directives with the iburst option. The main difference is that the initstepslew servers are used only before normal operation begins and that the foreground chronyd process waits for initstepslew to finish before exiting. This is useful to prevent programs started in the boot sequence after chronyd from reading the clock before it’s stepped.

4.2.23 keyfile

This command is used to specify the location of the file containing ID/key pairs for authentication of NTP packets.

The format of the command is shown in the example below

keyfile /etc/chrony.keys

The argument is simply the name of the file containing the ID/key pairs. The format of the file is shown below

10 tulip 11 hyacinth 20 MD5 ASCII:crocus 25 SHA1 HEX:1dc764e0791b11fa67efc7ecbc4b0d73f68a070c ...

Each line consists of an ID, name of an authentication hash function (optional) and a password. The ID can be any unsigned integer in the range 1 through 2**32-1. The default hash function is MD5. Depending on how chronyd was compiled, other supported functions may be SHA1, SHA256, SHA384, SHA512, RMD128, RMD160, RMD256, RMD320, TIGER and WHIRLPOOL. The password can be specified as a string of characters not containing white space with an optional ASCII: prefix, or as a hexadecimal number with the HEX: prefix. The maximum length of the line is 2047 characters.

The password is used with the hash function to generate and verify a message authentication code (MAC) in NTP packets. It’s recommended to use SHA1 or a stronger hash function with random passwords specified in the hexadecimal format that have at least 128 bits. chronyd will log a warning to syslog on start if a source is specified in the configuration file with a key that has password shorter than 80 bits.

The keygen command of chronyc (see section keygen) can be used to generate random keys for the key file. By default, it generates 160-bit MD5 or SHA1 keys.

4.2.24 leapsecmode

A leap second is an adjustment that is occasionally applied to UTC to keep it close to the mean solar time. When a leap second is inserted, the last day of June or December has an extra second 23:59:60.

For computer clocks that is a problem. The Unix time is defined as number of seconds since 00:00:00 UTC on 1 January 1970 without leap seconds. The system clock cannot have time 23:59:60, every minute has 60 seconds and every day has 86400 seconds by definition. The inserted leap second is skipped and the clock is suddenly ahead of UTC by one second. The leapsecmode directive selects how that error is corrected. There are four options:

system When inserting a leap second, the kernel steps the system clock backwards by one second when the clock gets to 00:00:00 UTC. When deleting a leap second, it steps forward by one second when the clock gets to 23:59:59 UTC. This is the default mode when the system driver supports leap seconds (i.e. on Linux, FreeBSD, NetBSD and Solaris). step This is similar to the system mode, except the clock is stepped by chronyd instead of the kernel. It can be useful to avoid bugs in the kernel code that would be executed in the system mode. This is the default mode when the system driver doesn’t support leap seconds. slew The clock is corrected by slewing started at 00:00:00 UTC when a leap second is inserted or 23:59:59 UTC when a leap second is deleted. This may be preferred over the system and step modes when applications running on the system are sensitive to jumps in the system time and it’s acceptable that the clock will be off for a longer time. On Linux with the default maxslewrate value (see section maxslewrate) the correction takes 12 seconds. ignore No correction is applied to the clock for the leap second. The clock will be corrected later in normal operation when new measurements are made and the estimated offset includes the one second error.

An example of the command is

leapsecmode slew

When serving time to NTP clients that can’t be configured to correct their clocks for a leap second by slewing or they would correct them at slightly different rates when it’s necessary to keep them close together, the slew mode can be combined with the smoothtime directive (see section smoothtime) to enable a server leap smear.

When smearing a leap second, the leap status is suppressed on the server and the served time is corrected slowly be slewing instead of stepping. The clients don’t need any special configuration as they don’t know there is any leap second and they follow the server time which eventually brings them back to UTC. Care must be taken to ensure they use for synchronization only NTP servers which smear the leap second in exactly the same way.

This feature needs to be used carefully, because the server is intentionally not serving its best estimate of the true time.

A recommended configuration to enable a server leap smear is:

leapsecmode slew maxslewrate 1000 smoothtime 400 0.001 leaponly

The first directive is necessary to disable the clock step which would reset the smoothing process. The second directive limits the slewing rate of the local clock to 1000 ppm, which improves the stability of the smoothing process when the local correction starts and ends. The third directive enables the server time smoothing process. It will start when the clock gets to 00:00:00 UTC and it will take 17 hours 34 minutes to finish. The frequency offset will be changing by 0.001 ppm per second and will reach maximum of 31.623 ppm. The leaponly option makes the duration of the leap smear constant and allows the clients to safely synchronise with multiple identically configured leap smearing servers.

4.2.25 leapsectz

This directive is used to set the name of the timezone in the system tz database which chronyd can use to find out when will the next leap second occur. It will periodically check if the times 23:59:59 and 23:59:60 are valid on Jun 30 and Dec 31 in the timezone. A useful timezone is right/UTC . This is mainly useful with reference clocks which don’t provide the leap second information. It is not necessary to restart chronyd if the tz database is updated with a new leap second at least 12 hours before the event.

An example of the command is

leapsectz right/UTC

The following shell command verifies that the timezone contains leap seconds and can be used with this directive

$ TZ=right/UTC date -d 'Dec 31 2008 23:59:60' Wed Dec 31 23:59:60 UTC 2008

4.2.26 local

The local keyword is used to allow chronyd to appear synchronised to real time (from the viewpoint of clients polling it), even if it has no current synchronisation source.

This option is normally used on computers in an isolated network, where several computers are required to synchronise to one other, this being the "master" which is kept vaguely in line with real time by manual input.

An example of the command is

local stratum 10

The value 10 may be substituted with other values in the range 1 through 15. Stratum 1 indicates a computer that has a true real-time reference directly connected to it (e.g. GPS, atomic clock etc) – such computers are expected to be very close to real time. Stratum 2 computers are those which have a stratum 1 server; stratum 3 computers have a stratum 2 server and so on.

A large value of 10 indicates that the clock is so many hops away from a reference clock that its time is fairly unreliable. Put another way, if the computer ever has access to another computer which is ultimately synchronised to a reference clock, it will almost certainly be at a stratum less than 10. Therefore, the choice of a high value like 10 for the local command prevents the machine’s own time from ever being confused with real time, were it ever to leak out to clients that have visibility of real servers.

4.2.27 lock_all

The lock_all directive will lock chronyd into RAM so that it will never be paged out. This mode is only supported on Linux. This directive uses the Linux mlockall() system call to prevent chronyd from ever being swapped out. This should result in lower and more consistent latency. It should not have significant impact on performance as chronyd's memory usage is modest. The mlockall man page has more details.

4.2.28 log

The log command indicates that certain information is to be logged.

measurements This option logs the raw NTP measurements and related information to a file called measurements.log. statistics This option logs information about the regression processing to a file called statistics.log. tracking This option logs changes to the estimate of the system’s gain or loss rate, and any slews made, to a file called tracking.log. rtc This option logs information about the system’s real-time clock. refclocks This option logs the raw and filtered reference clock measurements to a file called refclocks.log. tempcomp This option logs the temperature measurements and system rate compensations to a file called tempcomp.log.

The files are written to the directory specified by the logdir command.

An example of the command is

log measurements statistics tracking

4.2.28.1 Measurements log file format

An example line (which actually appears as a single line in the file) from the measurements log file is shown below.

2014-10-13 05:40:50 158.152.1.76 N 2 111 111 1111 10 10 1.0 \ -4.966e-03 2.296e-01 1.577e-05 1.615e-01 7.446e-03

The columns are as follows (the quantities in square brackets are the values from the example line above) :

Date [2014-10-13] Hour:Minute:Second [05:40:50]. Note that the date/time pair is expressed in UTC, not the local time zone. IP address of server/peer from which measurement comes [158.152.1.76] Leap status ( N means normal, + means that the last minute of the current month has 61 seconds, - means that the last minute of the month has 59 seconds, ? means the remote computer is not currently synchronised.) [N] Stratum of remote computer. [2] RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111] RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111] Tests for maximum delay, maximum delay ratio and maximum delay dev ratio, against defined parameters, and a test for synchronisation loop (1=pass, 0=fail) [1111] Local poll [10] Remote poll [10] ‘Score’ (an internal score within each polling level used to decide when to increase or decrease the polling level. This is adjusted based on number of measurements currently being used for the regression algorithm). [1.0] The estimated local clock error (‘theta’ in RFC 5905). Positive indicates that the local clock is slow of the remote source. [-4.966e-03]. The peer delay (‘delta’ in RFC 5905). [2.296e-01] The peer dispersion (‘epsilon’ in RFC 5905). [1.577e-05] The root delay (‘DELTA’ in RFC 5905). [1.615e-01] The root dispersion (‘EPSILON’ in RFC 5905). [7.446e-03]

A banner is periodically written to the log file to indicate the meanings of the columns.

4.2.28.2 Statistics log file format

An example line (which actually appears as a single line in the file) from the statistics log file is shown below.

1998-07-22 05:40:50 158.152.1.76 6.261e-03 -3.247e-03 \ 2.220e-03 1.874e-06 1.080e-06 7.8e-02 16 0 8

The columns are as follows (the quantities in square brackets are the values from the example line above) :

Date [1998-07-22] Hour:Minute:Second [05:40:50]. Note that the date/time pair is expressed in UTC, not the local time zone. IP address of server/peer from which measurement comes [158.152.1.76] The estimated standard deviation of the measurements from the source (in seconds). [6.261e-03] The estimated offset of the source (in seconds, positive means the local clock is estimated to be fast, in this case). [-3.247e-03] The estimated standard deviation of the offset estimate (in seconds). [2.220e-03] The estimated rate at which the local clock is gaining or losing time relative to the source (in seconds per second, positive means the local clock is gaining). This is relative to the compensation currently being applied to the local clock, not to the local clock without any compensation. [1.874e-06] The estimated error in the rate value (in seconds per second). [1.080e-06]. The ration of |old_rate - new_rate| / old_rate_error. Large values indicate the statistics are not modelling the source very well. [7.8e-02] The number of measurements currently being used for the regression algorithm. [16] The new starting index (the oldest sample has index 0; this is the method used to prune old samples when it no longer looks like the measurements fit a linear model). [0, i.e. no samples discarded this time] The number of runs. The number of runs of regression residuals with the same sign is computed. If this is too small it indicates that the measurements are no longer represented well by a linear model and that some older samples need to be discarded. The number of runs for the data that is being retained is tabulated. Values of approximately half the number of samples are expected. [8]

A banner is periodically written to the log file to indicate the meanings of the columns.

4.2.28.3 Tracking log file format

An example line (which actually appears as a single line in the file) from the tracking log file is shown below.

2012-02-23 05:40:50 158.152.1.76 3 340.529 1.606 1.046e-03 N \ 4 6.849e-03 -4.670e-04

The columns are as follows (the quantities in square brackets are the values from the example line above) :

Date [2012-02-03] Hour:Minute:Second [05:40:50]. Note that the date/time pair is expressed in UTC, not the local time zone. The IP address of the server/peer to which the local system is synchronised. [158.152.1.76] The stratum of the local system. [3] The local system frequency (in ppm, positive means the local system runs fast of UTC). [340.529] The error bounds on the frequency (in ppm) [1.606] The estimated local offset at the epoch (which is rapidly corrected by slewing the local clock. (In seconds, positive indicates the local system is fast of UTC). [1.046e-3] Leap status ( N means normal, + means that the last minute of this month has 61 seconds, - means that the last minute of the month has 59 seconds, ? means the clock is not currently synchronised.) [N] The number of combined sources. [4] The estimated standard deviation of the combined offset (in seconds). [6.849e-03] The remaining offset correction from the previous update (in seconds, positive means the system clock is slow of UTC). [-4.670e-04]

A banner is periodically written to the log file to indicate the meanings of the columns.

4.2.28.4 Real-time clock log file format

An example line (which actually appears as a single line in the file) from the measurements log file is shown below.

1998-07-22 05:40:50 -0.037360 1 -0.037434\ -37.948 12 5 120

The columns are as follows (the quantities in square brackets are the values from the example line above) :

Date [1998-07-22] Hour:Minute:Second [05:40:50]. Note that the date/time pair is expressed in UTC, not the local time zone. The measured offset between the system’s real time clock and the system ( gettimeofday() ) time. In seconds, positive indicates that the RTC is fast of the system time. [-0.037360]. Flag indicating whether the regression has produced valid coefficients. (1 for yes, 0 for no). [1] Offset at the current time predicted by the regression process. A large difference between this value and the measured offset tends to indicate that the measurement is an outlier with a serious measurement error. [-0.037434]. The rate at which the RTC is losing or gaining time relative to the system clock. In ppm, with positive indicating that the RTC is gaining time. [-37.948] The number of measurements used in the regression. [12] The number of runs of regression residuals of the same sign. Low values indicate that a straight line is no longer a good model of the measured data and that older measurements should be discarded. [5] The measurement interval used prior to the measurement being made (in seconds). [120]

A banner is periodically written to the log file to indicate the meanings of the columns.

4.2.28.5 Refclocks log file format

An example line (which actually appears as a single line in the file) from the refclocks log file is shown below.

2009-11-30 14:33:27.000000 PPS2 7 N 1 4.900000e-07 -6.741777e-07 1.000e-06

The columns are as follows (the quantities in square brackets are the values from the example line above) :

Date [2009-11-30] Hour:Minute:Second.Microsecond [14:33:27.000000]. Note that the date/time pair is expressed in UTC, not the local time zone. Reference ID of refclock from which measurement comes. [PPS2] Sequence number of driver poll within one polling interval for raw samples, or - for filtered samples. [7] Leap status ( N means normal, + means that the last minute of the current month has 61 seconds, - means that the last minute of the month has 59 seconds). [N] Flag indicating whether the sample comes from PPS source. (1 for yes, 0 for no, or - for filtered sample). [1] Local clock error measured by refclock driver, or - for filtered sample. [4.900000e-07] Local clock error with applied corrections. Positive indicates that the local clock is slow. [-6.741777e-07] Assumed dispersion of the sample. [1.000e-06]

A banner is periodically written to the log file to indicate the meanings of the columns.

4.2.28.6 Tempcomp log file format

An example line (which actually appears as a single line in the file) from the tempcomp log file is shown below.

2010-04-19 10:39:48 2.8000e+04 3.6600e-01

The columns are as follows (the quantities in square brackets are the values from the example line above) :

Date [2010-04-19] Hour:Minute:Second [10:39:48]. Note that the date/time pair is expressed in UTC, not the local time zone. Temperature read from tempcomp file. [2.8000e+04] Applied compensation in ppm, positive means the system clock is running faster than it would be without the compensation. [3.6600e-01]

A banner is periodically written to the log file to indicate the meanings of the columns.

4.2.29 logbanner

A banner is periodically written to the log files enabled by the log directive to indicate the meanings of the columns.

The logbanner directive specifies after how many entries in the log file should be the banner written. The default is 32, and 0 can be used to disable it entirely.

4.2.30 logchange

This directive sets the threshold for the adjustment of the system clock that will generate a syslog message.

By default, the threshold is 1 second.

An example of use is

logchange 0.1

which would cause a syslog message to be generated a system clock error of over 0.1 seconds starts to be compensated.

Clock errors detected via NTP packets, reference clocks, or timestamps entered via the settime command of chronyc are logged.

4.2.31 logdir

This directive allows the directory where log files are written to be specified.

An example of the use of this directive is

logdir /var/log/chrony

4.2.32 mailonchange

This directive defines an email address to which mail should be sent if chronyd applies a correction exceeding a particular threshold to the system clock.

An example of use of this directive is

mailonchange root@localhost 0.5

This would send a mail message to root if a change of more than 0.5 seconds were applied to the system clock.

This directive can’t be used when a system call filter is enabled by the -F option as the chronyd process will not be allowed to fork and execute the sendmail binary.

4.2.33 makestep

Normally chronyd will cause the system to gradually correct any time offset, by slowing down or speeding up the clock as required. In certain situations, the system clock may be so far adrift that this slewing process would take a very long time to correct the system clock.

This directive forces chronyd to step system clock if the adjustment is larger than a threshold value, but only if there were no more clock updates since chronyd was started than a specified limit (a negative value can be used to disable the limit).

This is particularly useful when using reference clocks, because the initstepslew directive (see section initstepslew) works only with NTP sources.

An example of the use of this directive is

makestep 0.1 10

This would step system clock if the adjustment is larger than 0.1 seconds, but only in the first ten clock updates.

4.2.34 manual

The manual directive enables support at run-time for the settime command in chronyc (see section settime). If no manual directive is included, any attempt to use the settime command in chronyc will be met with an error message.

Note that the settime command can be enabled at run-time using the manual command in chronyc (see section manual). (The idea of the two commands is that the manual command controls the manual clock driver’s behaviour, whereas the settime command allows samples of manually entered time to be provided).

4.2.35 maxchange

This directive sets the maximum allowed offset corrected on a clock update. The check is performed only after the specified number of updates to allow a large initial adjustment of the system clock. When an offset larger than the specified maximum occurs, it will be ignored for the specified number of times and then chronyd will give up and exit (a negative value can be used to never exit). In both cases a message is sent to syslog.

An example of the use of this directive is

maxchange 1000 1 2

After the first clock update, chronyd will check the offset on every clock update, it will ignore two adjustments larger than 1000 seconds and exit on another one.

4.2.36 maxclockerror

The maxclockerror directive sets the maximum assumed frequency error of the local clock. This is a frequency stability of the clock, not an absolute frequency error.

By default, the maximum assumed error is set to 1 ppm.

The syntax is

maxclockerror <error-in-ppm>

Typical values for <error-in-ppm> might be 10 for a low quality clock to 0.1 for a high quality clock using a temperature compensated crystal oscillator.

4.2.37 maxdistance

The maxdistance directive sets the maximum allowed root distance of the sources to not be rejected by the source selection algorithm. The distance includes the accumulated dispersion, which may be large when the source is no longer synchronised, and half of the total round-trip delay to the primary source.

By default, the maximum root distance is 3 seconds.

Setting maxdistance to a larger value can be useful to allow synchronisation with a server that only has a very infrequent connection to its sources and can accumulate a large dispersion between updates of its clock.

The syntax is

maxdistance <seconds>

4.2.38 maxsamples

The maxsamples directive sets the default maximum number of samples chronyd should keep for each source. This setting can be overriden for individual sources in the server and refclock directives (see section server, see section refclock). The default value is 0, which disables the configurable limit. The useful range is 4 to 64.

The syntax is

maxsamples <samples>

4.2.39 maxslewrate

The maxslewrate directive sets the maximum rate at which chronyd is allowed to slew the time. It limits the slew rate controlled by the correction time ratio (see section corrtimeratio) and is effective only on systems where chronyd is able to control the rate (i.e. Linux, FreeBSD, NetBSD, Solaris).

For each system there is a maximum frequency offset of the clock that can be set by the driver. On Linux it’s 100000 ppm, on FreeBSD and NetBSD it’s 5000 ppm and on Solaris it is 32500 ppm. Also, due to a kernel limitation, setting maxslewrate on FreeBSD and NetBSD to a value between 500 ppm and 5000 ppm will effectively set it to 500 ppm.

By default, the maximum slew rate is set to 83333.333 ppm (one twelfth).

The syntax is

maxslewrate <rate-in-ppm>

4.2.40 maxupdateskew

One of chronyd's tasks is to work out how fast or slow the computer’s clock runs relative to its reference sources. In addition, it computes an estimate of the error bounds around the estimated value.

If the range of error is too large, it probably indicates that the measurements have not settled down yet, and that the estimated gain or loss rate is not very reliable.

The maxupdateskew parameter allows the threshold for determining whether an estimate may be so unreliable that it should not be used. By default, the threshold is 1000 ppm.

The syntax is

maxupdateskew <skew-in-ppm>

Typical values for <skew-in-ppm> might be 100 for a dial-up connection to servers over a phone line, and 5 or 10 for a computer on a LAN.

It should be noted that this is not the only means of protection against using unreliable estimates. At all times, chronyd keeps track of both the estimated gain or loss rate, and the error bound on the estimate. When a new estimate is generated following another measurement from one of the sources, a weighted combination algorithm is used to update the master estimate. So if chronyd has an existing highly-reliable master estimate and a new estimate is generated which has large error bounds, the existing master estimate will dominate in the new master estimate.

4.2.41 minsamples

The minsamples directive sets the default minimum number of samples chronyd should keep for each source. This setting can be overriden for individual sources in the server and refclock directives (see section server, see section refclock). The default value is 0. The useful range is 4 to 64.

The syntax is

minsamples <samples>

4.2.42 minsources

The minsources directive sets the minimum number of sources that need to be considered as selectable in the source selection algorithm before the local clock is updated. The default value is 1.

Setting this option to a larger number can be used to improve the reliability. More sources will have to agree with each other and the clock will not be updated when only one source (which could be serving wrong time) is reachable.

The syntax is

minsources <sources>

4.2.43 noclientlog

This directive, which takes no arguments, specifies that client accesses are not to be logged. Normally they are logged, allowing statistics to be reported using the clients command in chronyc .

4.2.44 peer

The syntax of this directive is identical to that for the server directive (see section server), except that it is used to specify an NTP peer rather than an NTP server.

When a key is specified by the key option to enable authentication, both peers must be configured to use the same key and the same key number.

Please note that NTP peers that are not configured with a key to enable authentication are vulnerable to a denial-of-service attack. An attacker knowing that NTP hosts A and B are peering with each other can send a packet with random timestamps to host A with source address of B which will set the NTP state variables on A to the values sent by the attacker. Host A will then send on its next poll to B a packet with originate timestamp that doesn’t match the transmit timestamp of B and the packet will be dropped. If the attacker does this periodically for both hosts, they won’t be able to synchronize to each other.

This attack can be prevented by enabling authentication with the key option, or using the server directive on both sides to specify the other host as a server instead of peer, the only drawback is that it will double the network traffic between the two hosts.

4.2.45 pidfile

chronyd always writes its process ID (pid) to a file, and checks this file on startup to see if another chronyd may already be running on the system. By default, the file used is /var/run/chronyd.pid . The pidfile directive allows the name to be changed, e.g.

pidfile /var/tmp/chronyd.pid

4.2.46 pool

The syntax of this directive is similar to that for the server directive (see section server), except that it is used to specify a pool of NTP servers rather than a single NTP server. The pool name is expected to resolve to multiple addresses which may change over time.

All options valid in the server directive can be used in this directive too. There is one option specific to pool directive: maxsources sets the maximum number of sources that can be used from the pool, the default value is 4.

On start, when the pool name is resolved, chronyd will add up to 16 sources, one for each resolved address. When the number of sources from which at least one valid reply was received reaches maxsources , the other sources will be removed. When a pool source is unreachable or marked as falseticker, chronyd will try to replace the source with a newly resolved address of the pool.

An example of the pool directive is

pool pool.ntp.org iburst maxsources 3

4.2.47 port

This option allows you to configure the port on which chronyd will listen for NTP requests. The port will be open only when an address is allowed by the allow directive or command, an NTP peer is configured, or the broadcast server mode is enabled.

The compiled in default is udp/123, the standard NTP port. If set to 0, chronyd will never open the server port and will operate strictly in a client-only mode. The source port used in NTP client requests can be set by the acquisitionport directive.

An example of the port command is

port 11123

This would change the NTP port served by chronyd on the computer to udp/11123.

4.2.48 ratelimit

This directive enables response rate limiting for NTP packets. Its purpose is to reduce network traffic with misconfigured or broken NTP clients that are polling the server too frequently. The limits are applied to individual IP addresses. If multiple clients share one IP address (e.g. multiple hosts behind NAT), the sum of their traffic will be limited. If a client that increases its polling rate when it doesn’t receive a reply is detected, its rate limiting will be temporarily suspended to avoid increasing the overall amount of traffic. The maximum number of IP addresses which can be monitored at the same time depends on the memory limit set by the clientloglimit directive.

The ratelimit directive supports a number of subfields (which may be defined in any order):

interval This option sets the minimum interval between responses. It is defined as a power of 2 in seconds. The default value is 3 (8 seconds). The minimum value is -4 and the maximum value is 12. burst This option sets the maximum number of responses that can be send in a burst, temporarily exceeding the limit specified by the interval option. This is useful for clients that make rapid measurements on start (e.g. chronyd with the iburst option). The default value is 8. The minimum value is 1 and the maximum value is 255. leak This option sets the rate at which responses are randomly allowed even if the limits specified by the interval and burst options are exceeded. This is necessary to prevent an attacker who is sending requests with a spoofed source address from completely blocking responses to that address. The leak rate is defined as a power of 1/2 and it is 3 by default, i.e. on average at least every eighth request has a response. The minimum value is 1 and the maximum value is 4.

An example use of the command is

ratelimit interval 4 burst 4

This would reduce the response rate for IP addresses that send packets on average more frequently than once per 16 seconds and/or send packets in bursts with more than 4 packets.

4.2.49 refclock

Reference clocks allows very accurate synchronisation and chronyd can function as a stratum 1 server. They are specified by the refclock directive. It has two mandatory parameters, a refclock driver name and a driver specific parameter.

There are currently four drivers included:

PPS PPSAPI (pulse per second) driver. The parameter is the path to a PPS device. Assert events are used by default. Driver option :clear can be appended to the path if clear events should be used instead. As PPS refclock gets only sub-second time information, it needs another source (NTP or non-PPS refclock) or local directive (see section local) enabled to work. For example: refclock PPS /dev/pps0 lock NMEA refclock SHM 0 offset 0.5 delay 0.2 refid NMEA noselect SHM NTP shared memory driver. This driver uses a shared memory segment to receive data from another daemon which communicates with an actual reference clock. The parameter is the number of a shared memory segment, usually 0, 1, 2 or 3. For example: refclock SHM 1 poll 3 refid GPS1 A driver option in form :perm=NNN can be appended to the segment number to create the segment with permissions other than the default 0600 . Some examples of applications that can be used as SHM sources are gpsd , shmpps and radioclk . SOCK Unix domain socket driver. It is similar to the SHM driver, but uses a different format and uses a socket instead of shared memory. It does not require polling and it supports transmitting of PPS data. The parameter is a path to the socket which will be created by chronyd and used to receive the messages. The format of messages sent over the socket is described in the refclock_sock.c file. Recent versions of the gpsd daemon include support for the SOCK protocol. The path where the socket should be created is described in the gpsd(8) man page. For example: refclock SOCK /var/run/chrony.ttyS0.sock PHC PTP hardware clock (PHC) driver. The parameter is the path to the device of the PTP clock, which can be synchronised by a PTP daemon (e.g. ptp4l from the Linux PTP project. The PTP clocks are typically kept in TAI instead of UTC. The offset option can be used to compensate for the current UTC/TAI offset. For example: refclock PHC /dev/ptp0 poll 3 dpoll -2 offset -35

The refclock command also supports a number of subfields (which may be defined in any order):

poll Timestamps produced by refclock drivers are not used immediately, but they are stored and processed by a median filter in the polling interval specified by this option. This is defined as a power of 2 and may be negative to specify a sub-second interval. The default is 4 (16 seconds). A shorter interval allows chronyd to react faster to changes in clock frequency, but it may decrease the accuracy if the source is too noisy. dpoll Some drivers don’t listen for external events and try to produce samples in their own polling interval. This is defined as a power of 2 and may be negative to specify a sub-second interval. The default is 0 (1 second). refid This option is used to specify a reference id of the refclock, as up to four ASCII characters. By default, first three characters from driver name and the number of the refclock are used as refid. Each refclock must have an unique refid. filter This option sets the length of the median filter which is used to reduce noise. With each poll about 40 percent of the stored samples is discarded and one final sample is calculated as average of the remaining samples. If the length is 4 or above, at least 4 samples have to be collected between polls. For lengths below 4, the filter has to be full. The default is 64. rate PPS signal frequency (in Hz). This option only controls how the received pulses are aligned. To actually receive more than one pulse per second, a negative dpoll has to be specified (-3 for 5Hz signal). The default is 1. lock This option can be used to lock a PPS refclock to another refclock whose reference id is specified by this option. In this mode received pulses are aligned directly to unfiltered samples from the refclock. By default, pulses are aligned to local clock, but only when it is well synchronised. offset This option can be used to compensate a constant error. The specified offset (in seconds) is applied to all samples produced by the refclock. The default is 0.0. delay This option sets the NTP delay of the source (in seconds). Half of this value is included in the maximum assumed error which is used in the source selection algorithm. Increasing the delay is useful to avoid having no majority in the algorithm or to make it prefer other sources. The default is 1e-9 (1 nanosecond). precision Refclock precision (in seconds). The default is 1e-6 (1 microsecond) for SHM refclock, and 1e-9 (1 nanosecond) for SOCK, PPS and PHC refclocks. maxdispersion Maximum allowed dispersion for filtered samples (in seconds). Samples with larger estimated dispersion are ignored. By default, this limit is disabled. prefer Prefer this source over sources without prefer option. noselect Never select this source. This is useful for monitoring or with sources which are not very accurate, but are locked with a PPS refclock. trust Assume time from this source is always true. It can be rejected as a falseticker in the source selection only if another source with this option doesn’t agree with it. require Require that at least one of the sources specified with this option is selectable (i.e. recently reachable and not a falseticker) before updating the clock. Together with the trust option this may be useful to allow a trusted, but not very precise, reference clock to be safely combined with unauthenticated NTP sources in order to improve the accuracy of the clock. They can be selected and used for synchronisation only if they agree with the trusted and required source. minsamples Set the minimum number of samples kept for this source. This overrides the minsamples directive (see section minsamples). maxsamples Set the maximum number of samples kept for this source. This overrides the maxsamples directive (see section maxsamples).

4.2.50 reselectdist

When chronyd selects synchronisation source from available sources, it will prefer the one with minimum synchronisation distance. However, to avoid frequent reselecting when there are sources with similar distance, a fixed distance is added to the distance for sources that are currently not selected. This can be set with the reselectdist option. By default, the distance is 100 microseconds.

The syntax is

reselectdist <dist-in-seconds>

4.2.51 rtcautotrim

The rtcautotrim directive is used to keep the real time clock (RTC) close to the system clock automatically. When the system clock is synchronized and the estimated error between the two clocks is larger than the specified threshold, chronyd will trim the RTC as if the trimrtc (see section trimrtc) command was issued.

This directive is effective only with the rtcfile directive.

An example of the use of this directive is

rtcautotrim 30

This would set the threshold error to 30 seconds.

4.2.52 rtcdevice

The rtcdevice directive defines the name of the device file for accessing the real time clock. By default this is /dev/rtc , unless the directive is used to set a different value. This applies to Linux systems with devfs. An example of use is

rtcdevice /dev/misc/rtc

4.2.53 rtcfile

The rtcfile directive defines the name of the file in which chronyd can save parameters associated with tracking the accuracy of the system’s real-time clock (RTC).

The syntax is illustrated in the following example

rtcfile /var/lib/chrony/rtc

chronyd saves information in this file when it exits and when the writertc command is issued in chronyc . The information saved is the RTC’s error at some epoch, that epoch (in seconds since January 1 1970), and the rate at which the RTC gains or loses time.

So far, the support for real-time clocks is limited - their code is even more system-specific than the rest of the software. You can only use the real time clock facilities (the rtcfile directive and the -s command line option to chronyd ) if the following three conditions apply:

You are running Linux version 2.2.x or later. You have compiled the kernel with extended real-time clock support (i.e. the ‘ /dev/rtc ’ device is capable of doing useful things). You don’t have other applications that need to make use of ‘ /dev/rtc ’ at all.

4.2.54 rtconutc

chronyd assumes by default that the real time clock (RTC) keeps local time (including any daylight saving changes). This is convenient on PCs running Linux which are dual-booted with DOS or Windows.

NOTE : IF YOU KEEP THE REAL TIME CLOCK ON LOCAL TIME AND YOUR COMPUTER IS OFF WHEN DAYLIGHT SAVING (SUMMER TIME) STARTS OR ENDS, THE COMPUTER’S SYSTEM TIME WILL BE ONE HOUR IN ERROR WHEN YOU NEXT BOOT AND START CHRONYD.

An alternative is for the RTC to keep Universal Coordinated Time (UTC). This does not suffer from the 1 hour problem when daylight saving starts or ends.

If the rtconutc directive appears, it means the RTC is required to keep UTC. The directive takes no arguments. It is equivalent to specifying the -u switch to the Linux ‘ /sbin/hwclock ’ program.

Note that this setting is overriden when the hwclockfile directive (see section hwclockfile) is used.

4.2.55 rtcsync

The rtcsync directive enables a mode where the system time is periodically copied to the real time clock (RTC).

On Linux the RTC copy is performed by the kernel every 11 minutes. This directive cannot be used when the normal RTC tracking is enabled, i.e. when the rtcfile directive is used.

On Mac OS X, chronyd will perform the RTC copy every 60 minutes when the system clock is in a synchronised state.

On other systems this directive does nothing.

4.2.56 sched_priority

On Linux, the sched_priority directive will select the SCHED_FIFO real-time scheduler at the specified priority (which must be between 0 and 100). On Mac OS X, this option must have either a value of 0 (the default) to disable the thread time constraint policy or 1 for the policy to be enabled. Other systems do not support this option.

On Linux, this directive uses the sched_setscheduler() system call to instruct the kernel to use the SCHED_FIFO first-in, first-out real-time scheduling policy for chronyd with the specified priority. This means that whenever chronyd is ready to run it will run, interrupting whatever else is running unless it is a higher priority real-time process. This should not impact performance as chronyd's resource requirements are modest, but it should result in lower and more consistent latency since chronyd will not need to wait for the scheduler to get around to running it. You should not use this unless you really need it. The sched_setscheduler man page has more details.

On Mac OS X, this directive uses the thread_policy_set() kernel call to specify real-time scheduling. As noted for Linux, you should not use this directive unless you really need it.

4.2.57 server

The server directive allows NTP servers to be specified. The client/server relationship is strictly hierarchical : a client may synchronise its system time to that of the server, but the server’s system time will never be influenced by that of a client.

The server directive is immediately followed by either the name of the server, or its IP address. The server command also supports a number of subfields (which may be defined in any order):

port This option allows the UDP port on which the server understands NTP requests to be specified. For normal servers this option should not be required (the default is 123, the standard NTP port). minpoll Although chronyd will trim the rate at which it samples the server during normal operation, the user may wish to constrain the minimum polling interval. This is always defined as a power of 2, so minpoll 5 would mean that the polling interval cannot drop below 32 seconds. The default is 6 (64 seconds). maxpoll In a similar way, the user may wish to constrain the maximum polling interval. Again this is specified as a power of 2, maxpoll 9 indicates that the polling interval must stay at or below 512 seconds. The default is 10 (1024 seconds). maxdelay chronyd uses the network round-trip delay to the server to determine how accurate a particular measurement is likely to be. Long round-trip delays indicate that the request, or the response, or both were delayed. If only one of the messages was delayed the measurement error is likely to be substantial. For small variations in round trip delay, chronyd uses a weighting scheme when processing the measurements. However, beyond a certain level of delay the measurements are likely to be so corrupted as to be useless. (This is particularly so on dial-up or other slow links, where a long delay probably indicates a highly asymmetric delay caused by the response waiting behind a lot of packets related to a download of some sort). If the user knows that round trip delays above a certain level should cause the measurement to be ignored, this level can be defined with the maxdelay command. For example, maxdelay 0.3 would indicate that measurements with a round-trip delay of 0.3 seconds or more should be ignored. The default value is 3 seconds. maxdelayratio This option is similar to the maxdelay option above. chronyd keeps a record of the minimum round-trip delay amongst the previous measurements that it has buffered. If a measurement has a round trip delay that is greater than the maxdelayratio times the minimum delay, it w