Chapter 6. Using the Chrony suite to configure NTP

6.1. Introduction to configuring NTP with chrony

Accurate timekeeping is important for a number of reasons in IT. In networking for example, accurate time stamps in packets and logs are required. In Linux systems, the NTP protocol is implemented by a daemon running in user space.

The user space daemon updates the system clock running in the kernel. The system clock can keep time by using various clock sources. Usually, the Time Stamp Counter (TSC) is used. The TSC is a CPU register which counts the number of cycles since it was last reset. It is very fast, has a high resolution, and there are no interruptions.

In Red Hat Enterprise Linux 8, the NTP protocol is implemented by the chronyd daemon, available from the repositories in the chrony package.

These sections describe the use of the chrony suite.

6.2. Introduction to chrony suite

chrony is an implementation of the Network Time Protocol (NTP). You can use chrony:

To synchronize the system clock with NTP servers
To synchronize the system clock with a reference clock, for example a GPS receiver
To synchronize the system clock with a manual time input
As an NTPv4(RFC 5905) server or peer to provide a time service to other computers in the network

chrony performs 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 continuously, or run on a virtual machine.

Typical accuracy between two machines synchronized over the Internet is within a few milliseconds, and for machines on a LAN within tens of microseconds. Hardware timestamping or a hardware reference clock may improve accuracy between two machines synchronized to a sub-microsecond level.

chrony consists of chronyd, a daemon that runs in user space, and chronyc, a command line program which can be used to monitor the performance of chronyd and to change various operating parameters when it is running.

The chrony daemon, chronyd, can be monitored and controlled by the command line utility chronyc. This utility provides a command prompt which allows entering a number of commands to query the current state of chronyd and make changes to its configuration. By default, chronyd accepts only commands from a local instance of chronyc, but it can be configured to accept monitoring commands also from remote hosts. The remote access should be restricted.

6.2.1. Using chronyc to control chronyd

To make changes to the local instance of chronyd using the command line utility chronyc in interactive mode, enter the following command as root:

# chronyc

chronyc must run as root if some of the restricted commands are to be used.

The chronyc command prompt will be displayed as follows:

chronyc>

You can type help to list all of the commands.

The utility can also be invoked in non-interactive command mode if called together with a command as follows:

chronyc command

Note

Changes made using chronyc are not permanent, they will be lost after a chronyd restart. For permanent changes, modify /etc/chrony.conf.

6.3. Differences between chrony and ntp

Network Time Protocol (NTP) has two different implementations with similar basic functionality - ntp and chrony.

Both ntp and chrony can operate as an NTP client in order to synchronize the system clock with NTP servers and they can operate as an NTP server for other computers in the network. Each implementation has some unique features. For comparison of ntp and chrony, see Comparison of NTP implementations.

Configuration specific to an NTP client is identical in most cases. NTP servers are specified with the server directive. A pool of servers can be specified with the pool directive.

Configuration specific to an NTP server differs in how the client access is controlled. By default, ntpd responds to client requests from any address. The access can be restricted with the restrict directive, but it is not possible to disable the access completely if ntpd uses any servers as a client. chronyd allows no access by default and operates as an NTP client only. To make chrony operate as an NTP server, you need to specify some addresses within the allow directive.

ntpd and chronyd differ also in the default behavior with respect to corrections of the system clock. ntpd corrects the clock by step when the offset is larger than 128 milliseconds. If the offset is larger than 1000 seconds, ntpd exits unless it is the first correction of the clock and ntpd is started with the -g option. chronyd does not step the clock by default, but the default chrony.conf file provided in the chrony package allows steps in the first three updates of the clock. After that, all corrections are made slowly by speeding up or slowing down the clock. The chronyc makestep command can be issued to force chronyd to step the clock at any time.

6.4. Migrating to chrony

In Red Hat Enterprise Linux 7, users could choose between ntp and chrony to ensure accurate timekeeping. For differences between ntp and chrony, ntpd and chronyd, see Differences between ntpd and chronyd.

In Red Hat Enterprise Linux 8, ntp is no longer supported. chrony is enabled by default. For this reason, you might need to migrate from ntp to chrony.

Migrating from ntp to chrony is straightforward in most cases. The corresponding names of the programs, configuration files and services are:

Table 6.1. Corresponding names of the programs, configuration files and services when migrating from ntp to chrony

ntp name	chrony name
/etc/ntp.conf	/etc/chrony.conf
/etc/ntp/keys	/etc/chrony.keys
ntpd	chronyd
ntpq	chronyc
ntpd.service	chronyd.service
ntp-wait.service	chrony-wait.service

The ntpdate and sntp utilities, which are included in the ntp distribution, can be replaced with chronyd using the -q option or the -t option. The configuration can be specified on the command line to avoid reading /etc/chrony.conf. For example, instead of running ntpdate ntp.example.com, chronyd could be started as:

# chronyd -q 'server ntp.example.com iburst'
2018-05-18T12:37:43Z chronyd version 3.3 starting (+CMDMON +NTP +REFCLOCK +RTC +PRIVDROP +SCFILTER +SIGND +ASYNCDNS +SECHASH +IPV6 +DEBUG)
2018-05-18T12:37:43Z Initial frequency -2.630 ppm
2018-05-18T12:37:48Z System clock wrong by 0.003159 seconds (step)
2018-05-18T12:37:48Z chronyd exiting

The ntpstat utility, which was previously included in the ntp package and supported only ntpd, now supports both ntpd and chronyd. It is available in the ntpstat package.

6.4.1. Migration script

A Python script called ntp2chrony.py is included in the documentation of the chrony package (/usr/share/doc/chrony). The script automatically converts an existing ntp configuration to chrony. It supports the most common directives and options in the ntp.conf file. Any lines that are ignored in the conversion are included as comments in the generated chrony.conf file for review. Keys that are specified in the ntp key file, but are not marked as trusted keys in ntp.conf are included in the generated chrony.keys file as comments.

By default, the script does not overwrite any files. If /etc/chrony.conf or /etc/chrony.keys already exist, the -b option can be used to rename the file as a backup. The script supports other options. The --help option prints all supported options.

An example of an invocation of the script with the default ntp.conf provided in the ntp package is:

# python3 /usr/share/doc/chrony/ntp2chrony.py -b -v
Reading /etc/ntp.conf
Reading /etc/ntp/crypto/pw
Reading /etc/ntp/keys
Writing /etc/chrony.conf
Writing /etc/chrony.keys

The only directive ignored in this case is disable monitor, which has a chrony equivalent in the noclientlog directive, but it was included in the default ntp.conf only to mitigate an amplification attack.

The generated chrony.conf file typically includes a number of allow directives corresponding to the restrict lines in ntp.conf. If you do not want to run chronyd as an NTP server, remove all allow directives from chrony.conf.

6.4.2. Timesync role

Note that using the timesync role on your Red Hat Enterprise Linux 7 system facilitates the migration to chrony, because you can use the same playbook on all versions of RHEL starting with RHEL 6 regardless of whether the system uses ntp or chrony to implement the NTP protocol.

For more information on using the timesync role to manage time synchronization, see System roles documentation.

6.5. Configuring chrony

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 chrony.conf(5) man page for further options. For a complete list of the directives that can be used see The chronyd configuration file.

Below is a selection of chronyd 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:

allow 192.0.2.0/24

Use this command to grant access to a specific network.

allow 2001:0db8:85a3::8a2e:0370:7334

Use this this command to grant access to an IPv6.

The UDP port number 123 needs to be open in the firewall in order to allow the client access:

#  firewall-cmd --zone=public --add-port=123/udp

If you want to open port 123 permanently, use the --permanent option:

#  firewall-cmd --permanent --zone=public --add-port=123/udp

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

hwtimestamp

The hwtimestamp directive enables hardware timestamping for extremely accurate synchronization. For more details, see the chrony.conf(5) manual page.

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

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 format of the syntax is:

minsources number-of-sources

By default, number-of-sources is 1. Setting minsources to a larger number can be used to improve the reliability, because multiple sources will need to correspond with each other.

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 and enabling the clients to use interleaved mode with the xleave option in the server directive.

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

6.5.1. Configuring chrony for security

chronyc can access chronyd in two ways:

Internet Protocol, IPv4 or IPv6.
Unix domain socket, which is accessible locally by the root or chrony user.

By default, chronyc connects to the Unix domain socket. The default path is /var/run/chrony/chronyd.sock. If this connection fails, which can happen for example when chronyc is running under a non-root user, chronyc tries to connect to 127.0.0.1 and then ::1.

Only the following monitoring commands, which do not affect the behavior of chronyd, are allowed from the network:

activity
manual list
rtcdata
smoothing
sources
sourcestats
tracking
waitsync

The set of hosts from which chronyd accepts these commands can be configured with the cmdallow directive in the configuration file of chronyd, or the cmdallow command in chronyc. By default, the commands are accepted only from localhost (127.0.0.1 or ::1).

All other commands are allowed only through the Unix domain socket. When sent over the network, chronyd responds with a Not authorised error, even if it is from localhost.

Accessing chronyd remotely with chronyc

Allow access from both IPv4 and IPv6 addresses by adding the following to the /etc/chrony.conf file:
```
bindcmdaddress 0.0.0.0
```
or
```
bindcmdaddress :
```
Allow commands from the remote IP address, network, or subnet by using the cmdallow directive.
Add the following content to the /etc/chrony.conf file:
```
cmdallow 192.168.1.0/24
```
Open port 323 in the firewall to connect from a remote system.
```
#  firewall-cmd --zone=public --add-port=323/udp
```
If you want to open port 323 permanently, use the --permanent.
```
#  firewall-cmd --permanent --zone=public --add-port=323/udp
```

Note that the allow directive is for NTP access whereas the cmdallow directive is to enable receiving of remote commands. It is possible to make these changes temporarily using chronyc running locally. Edit the configuration file to make permanent changes.

6.6. Using Chrony

6.6.1. Installing chrony

The chrony suite is installed by default on Red Hat Enterprise Linux. To ensure that it is, run the following command as root:

# yum install chrony

The default location for the chrony daemon is /usr/sbin/chronyd. The command line utility will be installed to /usr/bin/chronyc.

6.6.2. Checking the status of chronyd

To check the status of chronyd, issue the following command:

$ systemctl status chronyd
chronyd.service - NTP client/server
   Loaded: loaded (/usr/lib/systemd/system/chronyd.service; enabled)
   Active: active (running) since Wed 2013-06-12 22:23:16 CEST; 11h ago

6.6.3. Starting chronyd

To start chronyd, issue the following command as root:

# systemctl start chronyd

To ensure chronyd starts automatically at system start, issue the following command as root:

# systemctl enable chronyd

6.6.4. Stopping chronyd

To stop chronyd, issue the following command as root:

# systemctl stop chronyd

To prevent chronyd from starting automatically at system start, issue the following command as root:

# systemctl disable chronyd

6.6.5. Checking if chrony is synchronized

To check if chrony is synchronized, make use of the tracking, sources, and sourcestats commands.

6.6.5.1. Checking chrony tracking

To check chrony tracking, issue the following command:

$ chronyc tracking
Reference ID    : CB00710F (foo.example.net)
Stratum         : 3
Ref time (UTC)  : Fri Jan 27 09:49:17 2017
System time     :  0.000006523 seconds slow of NTP time
Last offset     : -0.000006747 seconds
RMS offset      : 0.000035822 seconds
Frequency       : 3.225 ppm slow
Residual freq   : 0.000 ppm
Skew            : 0.129 ppm
Root delay      : 0.013639022 seconds
Root dispersion : 0.001100737 seconds
Update interval : 64.2 seconds
Leap status     : Normal

The fields are as follows:

Reference ID

This is the reference ID and name (or IP address) if available, of the server to which the computer is currently synchronized. Reference ID is a hexadecimal number to avoid confusion with IPv4 addresses.

Stratum

The stratum indicates how many hops away from a computer with an attached reference clock we are. Such a computer is a stratum-1 computer, so the computer in the example is two hops away (that is to say, a.b.c is a stratum-2 and is synchronized from a stratum-1).

Ref time

This is the time (UTC) at which the last measurement from the reference source was processed.

System time

In normal operation, chronyd never steps the system clock, because any jump in the timescale can have adverse consequences for certain application programs. Instead, any error in the system clock is corrected by slightly speeding up or slowing down the system clock until the error has been removed, and then returning to the system clock’s normal speed. A consequence of this is that there will be a period when the system clock (as read by other programs using the gettimeofday() system call, or by the date command in the shell) will be different from chronyd's estimate of the current true time (which it reports to NTP clients when it is operating in server mode). The value reported on this line is the difference due to this effect.

Last offset

This is the estimated local offset on the last clock update.

RMS offset

This is a long-term average of the offset value.

Frequency

The "frequency" is the rate by which the system’s clock would be wrong if chronyd was not correcting it. It is expressed in ppm (parts per million). For example, a value of 1 ppm would mean that when the system’s clock thinks it has advanced 1 second, it has actually advanced by 1.000001 seconds relative to true time.

Residual freq

This shows the "residual frequency" for the currently selected reference source. This reflects any difference between what the measurements from the reference source indicate the frequency should be and the frequency currently being used.

The reason this is not always zero is that a smoothing procedure is applied to the frequency. Each time a measurement from the reference source is obtained and a new residual frequency computed, the estimated accuracy of this residual is compared with the estimated accuracy (see skew) of the existing frequency value. A weighted average is computed for the new frequency, with weights depending on these accuracies. If the measurements from the reference source follow a consistent trend, the residual will be driven to zero over time.

Skew

This is the estimated error bound on the frequency.

Root delay

This is the total of the network path delays to the stratum-1 computer from which the computer is ultimately synchronized. Root delay values are printed in nanosecond resolution. In certain extreme situations, this value can be negative. (This can arise in a symmetric peer arrangement where the computers’ frequencies are not tracking each other and the network delay is very short relative to the turn-around time at each computer.)

Root dispersion

This is the total dispersion accumulated through all the computers back to the stratum-1 computer from which the computer is ultimately synchronized. Dispersion is due to system clock resolution, statistical measurement variations etc. Root dispersion values are printed in nanosecond resolution.

Leap status

This is the leap status, which can be Normal, Insert second, Delete second or Not synchronized.

6.6.5.2. Checking chrony sources

The sources command displays information about the current time sources that chronyd is accessing.

The optional argument -v can be specified, meaning verbose. In this case, extra caption lines are shown as a reminder of the meanings of the columns.

$ chronyc sources
	210 Number of sources = 3
MS Name/IP address         Stratum Poll Reach LastRx Last sample
===============================================================================
#* GPS0                          0   4   377    11   -479ns[ -621ns] /-  134ns
^? a.b.c                         2   6   377    23   -923us[ -924us] +/-   43ms
^ d.e.f                         1   6   377    21  -2629us[-2619us] +/-   86ms

The columns are as follows:

M

This indicates the mode of the source. ^ means a server, = means a peer and # indicates a locally connected reference clock.

S

This column indicates the state of the sources. "*" indicates the source to which chronyd is currently synchronized. "+" indicates acceptable sources which are combined with the selected source. "-" indicates acceptable sources which are excluded by the combining algorithm. "?" indicates sources to which connectivity has been lost or whose packets do not pass all tests. "x" indicates a clock which chronyd thinks is a falseticker (its time is inconsistent with a majority of other sources). "~" indicates a source whose time appears to have too much variability. The "?" condition is also shown at start-up, until at least 3 samples have been gathered from it.

Name/IP address

This shows the name or the IP address of the source, or reference ID for reference clock.

Stratum

This shows the stratum of the source, as reported in its most recently received sample. Stratum 1 indicates a computer with a locally attached reference clock. A computer that is synchronized to a stratum 1 computer is at stratum 2. A computer that is synchronized to a stratum 2 computer is at stratum 3, and so on.

Poll

This shows the rate at which the source is being polled, as a base-2 logarithm of the interval in seconds. Thus, a value of 6 would indicate that a measurement is being made every 64 seconds.

chronyd automatically varies the polling rate in response to prevailing conditions.

Reach

This shows the source’s reach register printed as an octal number. The register has 8 bits and is updated on every received or missed packet from the source. A value of 377 indicates that a valid reply was received for all of the last eight transmissions.

LastRx

This column shows how long ago the last sample was received from the source. This is normally in seconds. The letters m, h, d or y indicate minutes, hours, days or years. A value of 10 years indicates there were no samples received from this source yet.

Last sample

This column shows the offset between the local clock and the source at the last measurement. The number in the square brackets shows the actual measured offset. This may be suffixed by ns (indicating nanoseconds), us (indicating microseconds), ms (indicating milliseconds), or s (indicating seconds). The number to the left of the square brackets shows the original measurement, adjusted to allow for any slews applied to the local clock since. The number following the +/- indicator shows the margin of error in the measurement. Positive offsets indicate that the local clock is ahead of the source.

6.6.5.3. Checking chrony source statistics

The sourcestats command displays information about the drift rate and offset estimation process for each of the sources currently being examined by chronyd.

The optional argument -v can be specified, meaning verbose. In this case, extra caption lines are shown as a reminder of the meanings of the columns.

$ chronyc sourcestats
210 Number of sources = 1
Name/IP Address            NP  NR  Span  Frequency  Freq Skew  Offset  Std Dev
===============================================================================
abc.def.ghi                11   5   46m     -0.001      0.045      1us    25us

The columns are as follows:

Name/IP address: This is the name or IP address of the NTP server (or peer) or reference ID of the reference clock to which the rest of the line relates.
NP: This is the number of sample points currently being retained for the server. The drift rate and current offset are estimated by performing a linear regression through these points.
NR: This is the number of runs of residuals having the same sign following the last regression. If this number starts to become too small relative to the number of samples, it indicates that a straight line is no longer a good fit to the data. If the number of runs is too low, chronyd discards older samples and re-runs the regression until the number of runs becomes acceptable.
Span: This is the interval between the oldest and newest samples. If no unit is shown the value is in seconds. In the example, the interval is 46 minutes.
Frequency: This is the estimated residual frequency for the server, in parts per million. In this case, the computer’s clock is estimated to be running 1 part in 10⁹ slow relative to the server.
Freq Skew: This is the estimated error bounds on Freq (again in parts per million).
Offset: This is the estimated offset of the source.
Std Dev: This is the estimated sample standard deviation.

6.6.6. Manually Adjusting the System Clock

To step the system clock immediately, bypassing any adjustments in progress by slewing, issue the following command as root:

# chronyc makestep

If the rtcfile directive is used, the real-time clock should not be manually adjusted. Random adjustments would interfere with chrony's need to measure the rate at which the real-time clock drifts.

6.7. Setting up chrony for different environments

6.7.1. Setting up chrony for a system in an isolated network

For a network that is never connected to the Internet, one computer is selected to be the master timeserver. The other computers are either direct clients of the master, or clients of clients. On the master, the drift file must be manually set with the average rate of drift of the system clock. If the master is rebooted, it will obtain the time from surrounding systems and calculate an average to set its system clock. Thereafter it resumes applying adjustments based on the drift file. The drift file will be updated automatically when the settime command is used.

On the system selected to be the master, using a text editor running as root, edit /etc/chrony.conf as follows:

driftfile /var/lib/chrony/drift
commandkey 1
keyfile /etc/chrony.keys
initstepslew 10 client1 client3 client6
local stratum 8
manual
allow 192.0.2.0

Where 192.0.2.0 is the network or subnet address from which the clients are allowed to connect.

On the systems selected to be direct clients of the master, using a text editor running as root, edit the /etc/chrony.conf as follows:

server master
driftfile /var/lib/chrony/drift
logdir /var/log/chrony
log measurements statistics tracking
keyfile /etc/chrony.keys
commandkey 24
local stratum 10
initstepslew 20 master
allow 192.0.2.123

Where 192.0.2.123 is the address of the master, and master is the host name of the master. Clients with this configuration will resynchronize the master if it restarts.

On the client systems which are not to be direct clients of the master, the /etc/chrony.conf file should be the same except that the local and allow directives should be omitted.

In an isolated network, you can also use the local directive that enables a local reference mode, which allows chronyd operating as an NTP server to appear synchronized to real time, even when it was never synchronized or the last update of the clock happened a long time ago.

To allow multiple servers in the network to use the same local configuration and to be synchronized to one another, without confusing clients that poll more than one server, use the orphan option of the local directive which enables the orphan mode. Each server needs to be configured to poll all other servers with local. This ensures that only the server with the smallest reference ID has the local reference active and other servers are synchronized to it. When the server fails, another one will take over.

6.8. Chrony with HW timestamping

6.8.1. Understanding hardware timestamping

Hardware timestamping is a feature supported in some Network Interface Controller (NICs) which provides accurate timestamping of incoming and outgoing packets. NTP timestamps are usually created by the kernel and chronyd with the use of the system clock. However, when HW timestamping is enabled, the NIC uses its own clock to generate the timestamps when packets are entering or leaving the link layer or the physical layer. When used with NTP, hardware timestamping can significantly improve the accuracy of synchronization. For best accuracy, both NTP servers and NTP clients need to use hardware timestamping. Under ideal conditions, a sub-microsecond accuracy may be possible.

Another protocol for time synchronization that uses hardware timestamping is PTP.

Unlike NTP, PTP relies on assistance in network switches and routers. If you want to reach the best accuracy of synchronization, use PTP on networks that have switches and routers with PTP support, and prefer NTP on networks that do not have such switches and routers.

6.8.2. Verifying support for hardware timestamping

To verify that hardware timestamping with NTP is supported by an interface, use the ethtool -T command. An interface can be used for hardware timestamping with NTP if ethtool lists the SOF_TIMESTAMPING_TX_HARDWARE and SOF_TIMESTAMPING_TX_SOFTWARE capabilities and also the HWTSTAMP_FILTER_ALL filter mode.

Example 6.1. Verifying support for hardware timestamping on a specific interface

# ethtool -T eth0

Output:

Timestamping parameters for eth0:
Capabilities:
        hardware-transmit     (SOF_TIMESTAMPING_TX_HARDWARE)
        software-transmit     (SOF_TIMESTAMPING_TX_SOFTWARE)
        hardware-receive      (SOF_TIMESTAMPING_RX_HARDWARE)
        software-receive      (SOF_TIMESTAMPING_RX_SOFTWARE)
        software-system-clock (SOF_TIMESTAMPING_SOFTWARE)
        hardware-raw-clock    (SOF_TIMESTAMPING_RAW_HARDWARE)
PTP Hardware Clock: 0
Hardware Transmit Timestamp Modes:
        off                   (HWTSTAMP_TX_OFF)
        on                    (HWTSTAMP_TX_ON)
Hardware Receive Filter Modes:
        none                  (HWTSTAMP_FILTER_NONE)
        all                   (HWTSTAMP_FILTER_ALL)
        ptpv1-l4-sync         (HWTSTAMP_FILTER_PTP_V1_L4_SYNC)
        ptpv1-l4-delay-req    (HWTSTAMP_FILTER_PTP_V1_L4_DELAY_REQ)
        ptpv2-l4-sync         (HWTSTAMP_FILTER_PTP_V2_L4_SYNC)
        ptpv2-l4-delay-req    (HWTSTAMP_FILTER_PTP_V2_L4_DELAY_REQ)
        ptpv2-l2-sync         (HWTSTAMP_FILTER_PTP_V2_L2_SYNC)
        ptpv2-l2-delay-req    (HWTSTAMP_FILTER_PTP_V2_L2_DELAY_REQ)
        ptpv2-event           (HWTSTAMP_FILTER_PTP_V2_EVENT)
        ptpv2-sync            (HWTSTAMP_FILTER_PTP_V2_SYNC)
        ptpv2-delay-req       (HWTSTAMP_FILTER_PTP_V2_DELAY_REQ)

6.8.3. Enabling hardware timestamping

To enable hardware timestamping, use the hwtimestamp directive in the /etc/chrony.conf file. The directive can either specify a single interface, or a wildcard character can be used to enable hardware timestamping on all interfaces that support it. Use the wildcard specification in case that no other application, like ptp4l from the linuxptp package, is using hardware timestamping on an interface. Multiple hwtimestamp directives are allowed in the chrony configuration file.

Example 6.2. Enabling hardware timestamping by using the hwtimestamp directive

hwtimestamp eth0
hwtimestamp eth1
hwtimestamp *

6.8.4. Configuring client polling interval

The default range of a polling interval (64-1024 seconds) is recommended for servers on the Internet. For local servers and hardware timestamping, a shorter polling interval needs to be configured in order to minimize offset of the system clock.

The following directive in /etc/chrony.conf specifies a local NTP server using one second polling interval:

server ntp.local minpoll 0 maxpoll 0

6.8.5. Enabling interleaved mode

NTP servers that are not hardware NTP appliances, but rather general purpose computers running a software NTP implementation, like chrony, will get a hardware transmit timestamp only after sending a packet. This behavior prevents the server from saving the timestamp in the packet to which it corresponds. In order to enable NTP clients receiving transmit timestamps that were generated after the transmission, configure the clients to use the NTP interleaved mode by adding the xleave option to the server directive in /etc/chrony.conf:

server ntp.local minpoll 0 maxpoll 0 xleave

6.8.6. Configuring server for large number of clients

The default server configuration allows a few thousands of clients at most to use the interleaved mode concurrently. To configure the server for a larger number of clients, increase the clientloglimit directive in /etc/chrony.conf. This directive specifies the maximum size of memory allocated for logging of clients' access on the server:

clientloglimit 100000000

6.8.7. Verifying hardware timestamping

To verify that the interface has successfully enabled hardware timestamping, check the system log. The log should contain a message from chronyd for each interface with successfully enabled hardware timestamping.

Example 6.3. Log messages for interfaces with enabled hardware timestamping

chronyd[4081]: Enabled HW timestamping on eth0
chronyd[4081]: Enabled HW timestamping on eth1

When chronyd is configured as an NTP client or peer, you can have the transmit and receive timestamping modes and the interleaved mode reported for each NTP source by the chronyc ntpdata command:

Example 6.4. Reporting the transmit, receive timestamping and interleaved mode for each NTP source

# chronyc ntpdata

Output:

Remote address  : 203.0.113.15 (CB00710F)
Remote port     : 123
Local address   : 203.0.113.74 (CB00714A)
Leap status     : Normal
Version         : 4
Mode            : Server
Stratum         : 1
Poll interval   : 0 (1 seconds)
Precision       : -24 (0.000000060 seconds)
Root delay      : 0.000015 seconds
Root dispersion : 0.000015 seconds
Reference ID    : 47505300 (GPS)
Reference time  : Wed May 03 13:47:45 2017
Offset          : -0.000000134 seconds
Peer delay      : 0.000005396 seconds
Peer dispersion : 0.000002329 seconds
Response time   : 0.000152073 seconds
Jitter asymmetry: +0.00
NTP tests       : 111 111 1111
Interleaved     : Yes
Authenticated   : No
TX timestamping : Hardware
RX timestamping : Hardware
Total TX        : 27
Total RX        : 27
Total valid RX  : 27

Example 6.5. Reporting the stability of NTP measurements

# chronyc sourcestats

With hardware timestamping enabled, stability of NTP measurements should be in tens or hundreds of nanoseconds, under normal load. This stability is reported in the Std Dev column of the output of the chronyc sourcestats command:

Output:

210 Number of sources = 1
Name/IP Address            NP  NR  Span  Frequency  Freq Skew  Offset  Std Dev
ntp.local                  12   7    11     +0.000      0.019     +0ns    49ns

6.8.8. Configuring PTP-NTP bridge

If a highly accurate Precision Time Protocol (PTP) grandmaster is available in a network that does not have switches or routers with PTP support, a computer may be dedicated to operate as a PTP slave and a stratum-1 NTP server. Such a computer needs to have two or more network interfaces, and be close to the grandmaster or have a direct connection to it. This will ensure highly accurate synchronization in the network.

Configure the ptp4l and phc2sys programs from the linuxptp packages to use one interface to synchronize the system clock using PTP.

Configure chronyd to provide the system time using the other interface:

Example 6.6. Configuring chronyd to provide the system time using the other interface

bindaddress 203.0.113.74
hwtimestamp eth1
local stratum 1

6.9. Achieving some settings previously supported by ntp in chrony

Some settings that were in previous major version of Red Hat Enterprise Linux supported by ntp, are not supported by chrony. This section lists such settings, and describes ways to achieve them on a system with chrony.

6.9.1. Monitoring by ntpq and ntpdc

chronyd cannot be monitored by the ntpq and ntpdc utilities from the ntp distribution, because chrony does not support the NTP modes 6 and 7. It supports a different protocol and chronyc is the client implementation. For more information, see the chronyc(1) man page.

To monitor the status of the system clock sychronized by chronyd, you can:

Use the tracking command
Use the ntpstat utility, which supports chrony and provides a similar output as it used to with ntpd

Example 6.7. Using the tracking command

$ chronyc -n tracking
Reference ID    : 0A051B0A (10.5.27.10)
Stratum         : 2
Ref time (UTC)  : Thu Mar 08 15:46:20 2018
System time     : 0.000000338 seconds slow of NTP time
Last offset     : +0.000339408 seconds
RMS offset      : 0.000339408 seconds
Frequency       : 2.968 ppm slow
Residual freq   : +0.001 ppm
Skew            : 3.336 ppm
Root delay      : 0.157559142 seconds
Root dispersion : 0.001339232 seconds
Update interval : 64.5 seconds
Leap status     : Normal

Example 6.8. Using the ntpstat utility

$ ntpstat
synchronised to NTP server (10.5.27.10) at stratum 2
   time correct to within 80 ms
   polling server every 64 s

6.9.2. Using authentication mechanism based on public key cryptography

In Red Hat Enterprise Linux 7, ntp supported Autokey, which is an authentication mechanism based on public key cryptography. Autokey is not supported in chronyd.

On a Red Hat Enterprise Linux 8 system, it is recommended to use symmetric keys instead. Generate the keys with the chronyc keygen command. A client and server need to share a key specified in /etc/chrony.keys. The client can enable authentication using the key option in the server, pool, or peer directive.

6.9.3. Using ephemeral symmetric associations

In Red Hat Enterprise Linux 7, ntpd supported ephemeral symmetric associations, which can be mobilized by packets from peers which are not specified in the ntp.conf configuration file. In Red Hat Enterprise Linux 8, chronyd needs all peers to be specified in chrony.conf. Ephemeral symmetric associations are not supported.

Note that using the client/server mode enabled by the server or pool directive is more secure compared to the symmetric mode enabled by the peer directive.

6.9.4. multicast/broadcast client

Red Hat Enterprise Linux 7 supported the broadcast/multicast NTP mode, which simplifies configuration of clients. With this mode, clients can be configured to just listen for packets sent to a multicast/broadcast address instead of listening for specific names or addresses of individual servers, which may change over time.

In Red Hat Enterprise Linux 8, chronyd does not support the broadcast/multicast mode. The main reason is that it is less accurate and less secure than the ordinary client/server and symmetric modes.

There are several options of migration from an NTP broadcast/multicast setup:

Configure DNS to translate a single name, such as ntp.example.com, to multiple addresses of different servers
Clients can have a static configuration using only a single pool directive to synchronize with multiple servers. If a server from the pool becomes unreacheable, or otherwise unsuitable for synchronization, the clients automatically replace it with another server from the pool.
Distribute the list of NTP servers over DHCP
When NetworkManager gets a list of NTP servers from the DHCP server, chronyd is automatically configured to use them. This feature can be disabled by adding PEERNTP=no to the /etc/sysconfig/network file.
Use the Precision Time Protocol (PTP)
This option is suitable mainly for environments where servers change frequently, or if a larger group of clients needs to be able to synchronize to each other without having a designated server.
PTP was designed for multicast messaging and works similarly to the NTP broadcast mode. A PTP implementation is available in the linuxptp package.
PTP normally requires hardware timestamping and support in network switches to perform well. However, PTP is expected to work better than NTP in the broadcast mode even with software timestamping and no support in network switches.
In networks with very large number of PTP slaves in one communication path, it is recommended to configure the PTP slaves with the hybrid_e2e option in order to reduce the amount of network traffic generated by the slaves. You can configure a computer running chronyd as an NTP client, and possibly NTP server, to operate also as a PTP grandmaster to distribute synchronized time to a large number of computers using multicast messaging.

6.10. Additional resources

The following sources of information provide additional resources regarding chrony.

6.10.1. Installed Documentation

chronyc(1) man page — Describes the chronyc command-line interface tool including commands and command options.
chronyd(8) man page — Describes the chronyd daemon including commands and command options.
chrony.conf(5) man page — Describes the chrony configuration file.

6.10.2. Online Documentation

For answers to FAQs, see https://chrony.tuxfamily.org/faq.html

6.11. Managing time synchronization using RHEL System Roles

You can manage time synchronization on multiple target machines using the timesync role.

The timesync role installs and configures an NTP or PTP implementation to operate as an NTP client or PTP slave in order to synchronize the system clock with NTP servers or grandmasters in PTP domains.

Note that using the timesync role also facilitates migration to chrony, because you can use the same playbook on all versions of Red Hat Enterprise Linux starting with RHEL 6 regardless of whether the system uses ntp or chrony to implement the NTP protocol.

Warning

The timesync role replaces the configuration of the given or detected provider service on the managed host. Previous settings are lost, even if they are not specified in the role variables. The only preserved setting is the choice of provider if the timesync_ntp_provider variable is not defined.

The following example shows how to apply the timesync role in a situation with just one pool of servers.

Example 6.9. An example playbook applying the timesync role for a single pool of servers

---
- hosts: timesync-test
  vars:
    timesync_ntp_servers:
      - hostname: 2.rhel.pool.ntp.org
        pool: yes
        iburst: yes
  roles:
    - rhel-system-roles.timesync

For more information on using the timesync role, see System roles documentation.