15.2. Understanding chrony and Its Configuration

15.2.1. Understanding chronyd

The chrony daemon, chronyd, running in user space, makes adjustments to the system clock which is running in the kernel. It does this by consulting external time sources, using the NTP protocol, when ever network access allows it to do so. When external references are not available, chronyd will use the last calculated drift stored in the drift file. It can also be commanded manually to make corrections, by chronyc.

15.2.2. Understanding chronyc

The chrony daemon, chronyd, can be controlled by the command line utility chronyc. This utility provides a command prompt which allows entering of a number of commands to make changes to chronyd. The default configuration is for chronyd to only accept commands from a local instance of chronyc, but chronyc can be used to alter the configuration so that chronyd will allow external control. chronyc can be run remotely after first configuring chronyd to accept remote connections. The IP addresses allowed to connect to chronyd should be tightly controlled.

15.2.3. Understanding the chrony Configuration Commands

The default configuration file for chronyd is /etc/chrony.conf. The -f option can be used to specify an alternate configuration file path. See the chronyd man page for further options. For a complete list of the directives that can be used see http://chrony.tuxfamily.org/manual.html#Configuration-file. Below is a selection of configuration options:
Comments
Comments should be preceded by #, %, ; or !
allow
Optionally specify a host, subnet, or network from which to allow NTP connections to a machine acting as NTP server. The default is not to allow connections.

Examples:

  1. allow server1.example.com
    Use this form to specify a particular host, by its host name, to be allowed access.
  2. allow 192.0.2.0/24
    Use this form to specify a particular network to be allowed access.
  3. allow 2001:db8::/32
    Use this form to specify an IPv6 address to be allowed access.
cmdallow
This is similar to the allow directive (see section allow), except that it allows control access (rather than NTP client access) to a particular subnet or host. (By control access is meant that chronyc can be run on those hosts and successfully connect to chronyd on this computer.) The syntax is identical. There is also a cmddeny all directive with similar behavior to the cmdallow all directive.
dumpdir
Path to the directory to save the measurement history across restarts of chronyd (assuming no changes are made to the system clock behavior 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.
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).
local
The local keyword is used to allow chronyd to appear synchronized to real time from the viewpoint of clients polling it, even if it has no current synchronization source. This option is normally used on the master computer in an isolated network, where several computers are required to synchronize to one another, and the master is kept in line with real time by manual input.
An example of the command is:
local stratum 10
A large value of 10 indicates that the clock is so many hops away from a reference clock that its time is unreliable. If the computer ever has access to another computer which is ultimately synchronized 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.
log
The log command indicates that certain information is to be logged. It accepts the following options:
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 log files are written to the directory specified by the logdir command. An example of the command is:
log measurements statistics tracking
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
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 only works with NTP sources.
An example of the use of this directive is:
makestep 1000 10
This would step the system clock if the adjustment is larger than 1000 seconds, but only in the first ten clock updates.
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.
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 indicates that the measurements have not settled down yet, and that the estimated gain or loss rate is not very reliable. The maxupdateskew parameter is the threshold for determining whether an estimate is too unreliable to be used. By default, the threshold is 1000 ppm. The format of 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 telephone 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.
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.
reselectdist
When chronyd selects synchronization source from available sources, it will prefer the one with minimum synchronization 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 format of the syntax is:
reselectdist dist-in-seconds
stratumweight
The stratumweight directive sets how much distance should be added per stratum to the synchronization distance when chronyd selects the synchronization source from available sources.
The format of the syntax is:
stratumweight dist-in-seconds
By default, dist-in-seconds is 1 second. This means that sources with lower stratum are usually preferred to sources with higher stratum even when their distance is significantly worse. Setting stratumweight to 0 makes chronyd ignore stratum when selecting the source.
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 format of the syntax is:
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. Not all real-time clocks are supported as their code is system-specific. Note that if this directive is used then the real-time clock should not be manually adjusted as this would interfere with chrony's need to measure the rate at which the real-time clock drifts if it was adjusted at random intervals.
rtcsync
The rtcsync directive is present in the /etc/chrony.conf file by default. This will inform the kernel the system clock is kept synchronized and the kernel will update the real-time clock every 11 minutes.

15.2.4. Security with chronyc

As access to chronyc allows changing chronyd just as editing the configuration files would, access to chronyc should be limited. Passwords can be specified in the key file, written in ASCII or HEX, to restrict the use of chronyc. One of the entries is used to restrict the use of operational commands and is referred to as the command key. In the default configuration, a random command key is generated automatically on start. It should not be necessary to specify or alter it manually.
Other entries in the key file can be used as NTP keys to authenticate packets received from remote NTP servers or peers. The two sides need to share a key with identical ID, hash type and password in their key file. This requires manually creating the keys and copying them over a secure medium, such as SSH. If the key ID was, for example, 10 then the systems that act as clients must have a line in their configuration files in the following format:
server w.x.y.z key 10
peer w.x.y.z key 10
The location of the key file is specified in the /etc/chrony.conf file. The default entry in the configuration file is:
keyfile /etc/chrony.keys
The command key number is specified in /etc/chrony.conf using the commandkey directive, it is the key chronyd will use for authentication of user commands. The directive in the configuration file takes the following form:
commandkey 1
An example of the format of the default entry in the key file, /etc/chrony.keys, for the command key is:
1 SHA1 HEX:A6CFC50C9C93AB6E5A19754C246242FC5471BCDF
Where 1 is the key ID, SHA1 is the hash function to use, HEX is the format of the key, and A6CFC50C9C93AB6E5A19754C246242FC5471BCDF is the key randomly generated when chronyd was started for the first time. The key can be given in hexidecimal or ASCII format (the default).
A manual entry in the key file, used to authenticate packets from certain NTP servers or peers, can be as simple as the following:
20 foobar
Where 20 is the key ID and foobar is the secret authentication key. The default hash is MD5, and ASCII is the default format for the key.
By default, chronyd is configured to listen for commands only from localhost (127.0.0.1 and ::1) on port 323. To access chronyd remotely with chronyc, any bindcmdaddress directives in the /etc/chrony.conf file should be removed to enable listening on all interfaces and the cmdallow directive should be used to allow commands from the remote IP address, network, or subnet. In addition, port 323 has to be opened in the firewall in order to connect from a remote system. Note that the allow directive is for NTP access whereas the cmdallow directive is to enable the receiving of remote commands. It is possible to make these changes temporarily using chronyc running locally. Edit the configuration file to make persistent changes.
The communication between chronyc and chronyd is done over UDP, so it needs to be authorized before issuing operational commands. To authorize, use the authhash and password commands as follows:
chronyc> authhash SHA1
chronyc> password HEX:A6CFC50C9C93AB6E5A19754C246242FC5471BCDF
200 OK
If chronyc is used to configure the local chronyd, the -a option will run the authhash and password commands automatically.
Only the following commands can be used without providing a password: activity , authhash , dns , exit , help , password , quit , rtcdata , sources , sourcestats , tracking , waitsync .