table of contents
CHRONY.CONF(5) | Configuration Files | CHRONY.CONF(5) |
NAME¶
chrony.conf - chronyd configuration file
SYNOPSIS¶
chrony.conf
DESCRIPTION¶
This file configures the chronyd daemon. The compiled-in location is /etc/chrony/chrony.conf. Other locations can be specified on the chronyd command line with the -f option.
Each directive in the configuration file is placed on a separate line. The following sections describe each of the directives in turn. The directives are not case-sensitive. Generally, the directives can occur in any order in the file and if a directive is specified multiple times, only the last one will be effective. Exceptions are noted in the descriptions.
The configuration directives can also be specified directly on the chronyd command line. In this case each argument is parsed as a new line and the configuration file is ignored.
While the number of supported directives is large, only a few of them are typically needed. See the EXAMPLES section for configuration in typical operating scenarios.
The configuration file might 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.
DIRECTIVES¶
Time sources¶
server hostname [option]...
The server can be specified by its hostname or IP address. If the hostname cannot be resolved on start, chronyd will try it again in increasing intervals, and also when the online command is issued in chronyc.
The DNS record can change over time. The used address will be replaced with a newly resolved address when the server becomes unreachable (i.e. no valid response to last 8 requests), unsynchronised, a falseticker (i.e. does not agree with a majority of other sources), or the root distance is too large (the limit can be configured by the maxdistance directive). The automatic replacement happens at most once per 30 minutes.
This directive can be used multiple times to specify multiple servers.
The directive supports the following options:
minpoll poll
maxpoll poll
iburst
burst
key ID
The key option specifies which key (with an ID in the range 1 through 2^32-1) should chronyd use to authenticate requests sent to the server and verify its responses. The server must have the same key for this number configured, otherwise no relationship between the computers will be possible.
If the server is running ntpd and the output size of the hash function used by the key is longer than 160 bits (e.g. SHA256), the version option needs to be set to 4 for compatibility.
nts
With this option, the hostname specified in the server or pool directive is the NTS-KE server or pool of NTS-KE servers respectively. The NTP server usually runs on the same host, but it can be separated from the NTS-KE server (the hostname or address of the NTP server is provided to the client by the NTS-KE server).
The NTS-KE server can be specified by IP address if it is included in the server’s certificate as a Subject Alternative Name (SAN).
certset ID
maxdelay delay
For small variations in the 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 wireless networks and 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 option. For example, maxdelay 0.3 would indicate that measurements with a round-trip delay greater than 0.3 seconds should be ignored. The default value is 3 seconds and the maximum value is 1000 seconds.
maxdelayratio ratio
maxdelaydevratio ratio
maxdelayquant p
The specified p value should be between 0.05 and 0.95. For example, maxdelayquant 0.2 would indicate that only measurements with the lowest 20 percent of round-trip delays should be accepted. Note that it can take many measurements for the estimated quantile to reach the expected value. This option is intended for synchronisation in mostly static local networks with very short polling intervals and possibly combined with the filter option. By default, this test is disabled in favour of the maxdelaydevratio test.
mindelay delay
asymmetry ratio
offset offset
minsamples samples
maxsamples samples
filter polls
offline
auto_offline
prefer
noselect
trust
require
xleave
The interleaved mode is compatible with servers that support only the basic mode. Note that even servers that support the interleaved mode might respond in the basic mode as the interleaved mode requires the servers to keep some state for each client and the state might be dropped when there are too many clients (e.g. clientloglimit is too small), or it might be overwritten by other clients that have the same IP address (e.g. computers behind NAT or someone sending requests with a spoofed source address).
The xleave option can be combined with the presend option in order to shorten the interval in which the server has to keep the state to be able to respond in the interleaved mode.
polltarget target
port port
ntsport port
presend poll
In order to avoid this problem, the presend option can be used. It takes a single integer argument, which is the smallest polling interval for which an extra pair of NTP packets will be exchanged between the client and the server prior to the actual measurement. For example, with the following option included in a server directive:
presend 9
when the polling interval is 512 seconds or more, an extra NTP client packet will be sent to the server a short time (2 seconds) before making the actual measurement.
If the presend option is used together with the xleave option, chronyd will send two extra packets instead of one.
minstratum stratum
version version
copy
extfield type
This option can be used multiple times to enable multiple extension fields.
The following extension fields are supported:
F323
F324
ipv4, ipv6
pool name [option]...
This directive can be used multiple times to specify multiple pools.
All options valid in the server directive can be used in this directive too. There is one option specific to the pool directive:
maxsources sources
An example of the pool directive is
pool pool.ntp.org iburst maxsources 3
peer hostname [option]...
This directive can be used multiple times to specify multiple peers.
The following options of the server directive do not work in the peer directive: iburst, burst, nts, presend, copy.
When using the xleave option, both peers must support and have enabled the interleaved mode, otherwise the synchronisation will work in one direction only. When a key is specified by the key option to enable authentication, both peers must use the same key and the same key number.
Note that the symmetric mode is less secure than the client/server mode. A denial-of-service attack is possible on unauthenticated symmetric associations, i.e. when the peer was specified without the key option. An attacker who does not see network traffic between two hosts, but knows that they are peering with each other, can periodically send them unauthenticated packets with spoofed source addresses in order to disrupt their NTP state and prevent them from synchronising to each other. When the association is authenticated, an attacker who does see the network traffic, but cannot prevent the packets from reaching the other host, can still disrupt the state by replaying old packets. The attacker has effectively the same power as a man-in-the-middle attacker. A partial protection against this attack is implemented in chronyd, which can protect the peers if they are using the same polling interval and they never sent an authenticated packet with a timestamp from future, but it should not be relied on as it is difficult to ensure the conditions are met. If two hosts should be able to synchronise to each other in both directions, it is recommended to use two separate client/server associations (specified by the server directive on both hosts) instead.
initstepslew step-threshold [hostname]...
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 safer 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 the use of the directive is:
initstepslew 30 ntp1.example.net ntp2.example.net ntp3.example.net
where 3 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 primary server and the other computers are its clients. If each of the clients is configured with the local directive, the server can be set up with an initstepslew directive which references some or all of the clients. Then, if the server machine has to be rebooted, the clients can be relied on to act analogously to a flywheel and preserve the time for a short period while the server completes its reboot.
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 prevent programs started in the boot sequence after chronyd from reading the clock before it has been stepped. With the makestep directive, the waitsync command of chronyc can be used instead.
refclock driver parameter[:option]... [option]...
This directive can be used multiple times to specify multiple reference clocks.
There are four drivers included in chronyd:
PPS
clear
refclock PPS /dev/pps0 lock NMEA refid GPS1 refclock SOCK /var/run/chrony.clk.ttyS0.sock offset 0.5 delay 0.2 refid NMEA noselect refclock PPS /dev/pps1:clear refid GPS2
SOCK
An application which supports the SOCK protocol is the gpsd daemon. It can provide accurate measurements using the receiver’s PPS signal, and since version 3.25 also (much less accurate) measurements based on the timing of serial data (e.g. NMEA), which can be useful when the receiver does not provide a PPS signal, or it cannot be connected to the computer. The paths where gpsd expects the sockets to be created by chronyd are described in the gpsd(8) man page. Note that gpsd needs to be started after chronyd in order to connect to the socket.
Examples:
refclock SOCK /var/run/chrony.ttyS0.sock refid GPS1 poll 2 filter 4 refclock SOCK /var/run/chrony.clk.ttyUSB0.sock refid GPS2 offset 0.2 delay 0.1
SHM
The driver supports the following option:
perm=mode
Unlike with the SOCK driver, there is no prescribed order of starting chronyd and the program providing measurements. Both are expected to create the memory segment if it does not exist. chronyd will attach to an existing segment even if it has a different owner than root or different permissions than the permissions specified by the perm option. The segment needs to be created before untrusted applications or users can execute code to prevent an attacker from feeding chronyd with false measurements. The owner and permissions of the segment can be verified with the ipcs -m command. For this reason, the SHM driver is deprecated in favor of SOCK.
Examples:
refclock SHM 0 poll 3 refid GPS1 refclock SHM 1:perm=0644 refid GPS2
PHC
nocrossts
extpps
pin=index
channel=index
clear
Examples:
refclock PHC /dev/ptp0 poll 0 dpoll -2 offset -37 refclock PHC /dev/ptp1:nocrossts poll 3 pps refclock PHC /dev/ptp2:extpps:pin=1 width 0.2 poll 2
poll poll
dpoll dpoll
refid refid
lock refid
rate rate
maxlockage pulses
width width
pps
offset offset
delay delay
stratum stratum
precision precision
maxdispersion dispersion
filter samples
prefer
noselect
trust
require
tai
local
minsamples samples
maxsamples samples
manual
Note that the settime command can be enabled at run-time using the manual command in chronyc. (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.)
acquisitionport port
It can be set to the same port as is used by the NTP server (which can be configured with the port directive) to use only one socket for all NTP packets.
An example of the acquisitionport directive is:
acquisitionport 1123
This would change the source port used for client requests to UDP port 1123. You could then persuade the firewall administrator to open that port.
bindacqaddress address
For each of the IPv4 and IPv6 protocols, only one bindacqaddress directive can be specified.
bindacqdevice interface
An example of the directive is:
bindacqdevice eth0
dscp point
An example of the directive (setting the Expedited Forwarding class) is:
dscp 46
dumpdir directory
All supported systems, with the exception of macOS 10.12 and earlier, have operating system support for setting the rate of gain or loss to compensate for known errors. (On macOS 10.12 and earlier, 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). The dumpdir directive defines the directory where the measurement histories are saved when chronyd exits, or the dump command in chronyc is issued.
If the directory does not exist, it will be created automatically.
The -r option of chronyd enables loading of the dump files on start. All dump files found in the directory will be removed after start, even if the -r option is not present.
An example of the directive is:
dumpdir /run/chrony
A source whose IP address is 1.2.3.4 would have its measurement history saved in the file /run/chrony/1.2.3.4.dat. History of reference clocks is saved to files named by their reference ID in form of refid:XXXXXXXX.dat.
maxsamples samples
As a special case, setting maxsamples to 1 disables frequency tracking in order to make the sources immediately selectable with only one sample. This can be useful when chronyd is started with the -q or -Q option.
minsamples samples
Forcing chronyd to keep more samples than it would normally keep reduces noise in the estimated frequency and offset, but slows down the response to changes in the frequency and offset of the clock. The offsets in the tracking and sourcestats reports (and the tracking.log and statistics.log files) may be smaller than the actual offsets.
ntsaeads ID...
The following IDs are supported:
The default list of IDs is 30 15. AES-128-GCM-SIV is prefered over AES-SIV-CMAC-256 for shorter keys, which makes NTS cookies shorter and improves reliability of NTS in networks that block or limit rate of longer NTP messages.
The ID of the used algorithm is reported for each server by the authdata command.
An example of the directive is:
ntsaeads 15
This list is used also by the NTS server.
ntsdumpdir directory
If the directory does not exist, it will be created automatically.
An example of the directive is:
ntsdumpdir /var/lib/chrony
This directory is used also by the NTS server to save keys.
ntsrefresh interval
The interval must be longer than polling intervals of all configured NTP sources using NTS, otherwise the source with a longer polling interval will refresh the keys on each poll and no NTP packets will be exchanged.
ntstrustedcerts [set-ID] file|directory
The optional set-ID argument is a number in the range 0 through 2^32-1, which selects the set of certificates where certificates from the specified file or directory are added. The default ID is 0, which is a set containing the system’s default trusted CAs (unless the nosystemcert directive is present). All other sets are empty by default. A set of certificates can be selected for verification of an NTS server by the certset option in the server or pool directive.
This directive can be used multiple times to specify one or more sets of trusted certificates, each containing certificates from one or more files and/or directories.
It is not necessary to restart chronyd in order to reload the certificates if they change (e.g. after a renewal).
An example is:
ntstrustedcerts /etc/pki/nts/ca1.example.net.crt ntstrustedcerts 1 /etc/pki/nts/ca2.example.net.crt ntstrustedcerts 1 /etc/pki/nts/ca3.example.net.crt ntstrustedcerts 2 /etc/pki/nts/ntp2.example.net.crt
nosystemcert
nocerttimecheck limit
An example of the directive is:
nocerttimecheck 1
This would disable the time checks until the clock is updated for the first time, assuming the first update corrects the clock and later checks can work with correct time.
refresh interval
The refresh command can be used to refresh all sources immediately.
Source selection¶
authselectmode mode
When authentication is enabled for an NTP source, it is important to disable unauthenticated NTP sources which could be exploited in the attack, e.g. if they are not reachable only over a trusted network. Alternatively, the source selection can be configured with the require and trust options to synchronise to the unauthenticated sources only if they agree with the authenticated sources and might have a positive impact on the accuracy of the clock. Note that in this case the impact of the attack is higher. The attackers cannot cause an arbitrarily large step or slew, but they have more control over the frequency of the clock and can cause chronyd to report false information, e.g. a significantly smaller root delay and dispersion.
This directive determines the default selection options for authenticated and unauthenticated sources in order to simplify the configuration with the configuration file and chronyc commands. It sets a policy for authentication.
Sources specified with the noselect option are ignored (not counted as either authenticated or unauthenticated), and they always have only the selection options specified in the configuration.
There are four modes:
require
prefer
mix
ignore
As an example, the following configuration using the default mix mode:
server ntp1.example.net nts server ntp2.example.net nts server ntp3.example.net refclock SOCK /var/run/chrony.ttyS0.sock
is equivalent to the following configuration using the ignore mode:
authselectmode ignore server ntp1.example.net nts require trust server ntp2.example.net nts require trust server ntp3.example.net refclock /var/run/chrony.ttyS0.sock require trust
combinelimit limit
The combinelimit directive limits which sources are included in the combining algorithm. Their synchronisation 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. If the selected source was specified with the prefer option, it can be combined only with other sources specified with this option.
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.
maxdistance distance
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.
maxjitter jitter
By default, the maximum jitter is 1 second.
minsources sources
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 incorrect time) is reachable.
reselectdist distance
stratumweight distance
By default, the weight is 0.001 seconds. This means that the stratum of the sources in the selection process matters only when the differences between the distances are in milliseconds.
System clock¶
clockprecision precision
The measured value works well in most cases. However, it generally overestimates the precision and it can be sensitive to the CPU speed, which can change over time to save power. In some cases with a high-precision clocksource (e.g. the Time Stamp Counter of the CPU) and hardware timestamping, setting the precision on the server to a smaller value can improve stability of clients' NTP measurements. The server’s precision is reported on clients by the ntpdata command.
An example setting the precision to 8 nanoseconds is:
clockprecision 8e-9
corrtimeratio ratio
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 maximum allowed slew rate can be set by the maxslewrate directive. The current remaining correction is shown in the tracking report as the System time value.
driftfile file
Whenever chronyd computes a new value of the gain or 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 can take many minutes, at least.)
The driftfile directive 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 in 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 directive is:
driftfile /var/lib/chrony/drift
fallbackdrift min-interval max-interval
The directive specifies the minimum and maximum interval since the 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 the 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, and so on. This might be a good setting to cover frequency changes due to daily and weekly temperature fluctuations. When the frequency is set to a fallback, the state of the clock will change to ‘Not synchronised’.
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 sources, reference clocks, or manual input.
leapsecmode mode
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
step
slew
ignore
When serving time to NTP clients that cannot be configured to correct their clocks for a leap second by slewing, or to clients that would correct at slightly different rates when it is necessary to keep them close together, the slew mode can be combined with the smoothtime directive 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 by slewing instead of stepping. The clients do not need any special configuration as they do not 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 only NTP servers which smear the leap second in exactly the same way for synchronisation.
This feature must 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.001024 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 62500 seconds (about 17.36 hours) to finish. The frequency offset will be changing by 0.001024 ppm per second and will reach a maximum of 32 ppm in 31250 seconds. 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.
The duration of the leap smear can be calculated from the specified wander as
duration = sqrt(4 / wander)
leapsectz timezone
When a leap second is announced, the timezone needs to be updated at least 12 hours before the leap second. It is not necessary to restart chronyd.
This directive is useful with reference clocks and other time sources which do not announce leap seconds, or announce them too late for an NTP server to forward them to its own clients. Clients of leap smearing servers must not use this directive.
It is also useful when the system clock is required to have correct TAI-UTC offset. Note that the offset is set only when leap seconds are handled by the kernel, i.e. leapsecmode is set to system.
The specified timezone is not used as an exclusive source of information about leap seconds. If a majority of time sources announce on the last day of June or December that a leap second should be inserted or deleted, it will be accepted even if it is not included in the timezone.
An example of the directive 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
leapseclist file
An example of this directive is:
leapseclist /usr/share/zoneinfo/leap-seconds.list
makestep threshold limit
This directive forces chronyd to step the 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 the specified limit. A negative value disables the limit.
On most systems it is desirable to step the system clock only on boot, before starting programs that rely on time advancing monotonically forwards.
An example of the use of this directive is:
makestep 0.1 3
This would step the system clock if the adjustment is larger than 0.1 seconds, but only in the first three clock updates.
maxchange offset start ignore
The check is enabled after the specified number of clock updates to allow a large initial offset to be corrected on start. Offsets larger than the specified maximum will be ignored for the specified number of times. Another large offset will cause chronyd to give up and exit. A negative value can be used to disable the limit to ignore all large offsets. A syslog message will be generated when an offset is ignored or it causes the exit.
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.
maxclockerror error-in-ppm
By default, the maximum error is 1 ppm.
Typical values for error-in-ppm might be 10 for a low quality clock and 0.1 for a high quality clock using a temperature compensated crystal oscillator.
maxdrift drift-in-ppm
By default, the maximum assumed drift is 500000 ppm, i.e. the adjustment is limited by the system driver rather than this directive.
maxupdateskew skew-in-ppm
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 directive sets the threshold for determining whether an estimate might be so unreliable that it should not be used. By default, the threshold is 1000 ppm.
Typical values for skew-in-ppm might be 100 for NTP sources polled over a wireless network, and 10 or smaller for sources on a local wired network.
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 existing estimate. If it has significantly smaller error bounds than the new estimate, the existing estimate will dominate in the new combined value.
maxslewrate rate-in-ppm
For each system there is a maximum frequency offset of the clock that can be set by the driver. On Linux it is 100000 ppm, on FreeBSD, NetBSD and macOS 10.13+ it is 5000 ppm, and on illumos it is 32500 ppm. Also, due to a kernel limitation, setting maxslewrate on FreeBSD, NetBSD, macOS 10.13+ 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).
tempcomp file interval T0 k0 k1 k2, tempcomp file interval points-file
If there are temperature measurements available from a sensor close to the oscillator, the tempcomp directive can be used to compensate for the changes in the temperature and improve the stability and accuracy of the clock.
The result depends on many factors, including the resolution of the sensor, the amount of noise in the measurements, the polling interval of the time source, the compensation update interval, how well the compensation is specified, and how close the sensor is to the oscillator. When it is working well, the frequency reported in the tracking.log file is more stable and the maximum reached offset is smaller.
There are two forms of the directive. The first one has six parameters: a path to the file containing the current temperature from the sensor (in text format), the compensation update interval (in seconds), and temperature coefficients T0, k0, k1, k2.
The frequency compensation is calculated (in ppm) as
comp = k0 + (T - T0) * k1 + (T - T0)^2 * k2
The result has to be between -10 ppm and 10 ppm, otherwise the measurement is considered invalid and will be ignored. The k0 coefficient can be adjusted to keep the compensation in that range.
An example of the use is:
tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 26000 0.0 0.000183 0.0
The measured temperature will be read from the file in the Linux sysfs filesystem every 30 seconds. When the temperature is 26000 (26 degrees Celsius), the frequency correction will be zero. When it is 27000 (27 degrees Celsius), the clock will be set to run faster by 0.183 ppm, etc.
The second form has three parameters: the path to the sensor file, the update interval, and a path to a file containing a list of (temperature, compensation) points, from which the compensation is linearly interpolated or extrapolated.
An example is:
tempcomp /sys/class/hwmon/hwmon0/temp2_input 30 /etc/chrony.tempcomp
where the /etc/chrony.tempcomp file could have
20000 1.0 21000 0.64 22000 0.36 23000 0.16 24000 0.04 25000 0.0 26000 0.04 27000 0.16 28000 0.36 29000 0.64 30000 1.0
Valid measurements with corresponding compensations are logged to the tempcomp.log file if enabled by the log tempcomp directive.
NTP server¶
allow [all] [subnet]
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.
This directive can be used multiple times.
Examples of the use of the directive are as follows:
allow 1.2.3.4 allow 3.4.5.0/24 allow 3.4.5 allow 2001:db8::/32 allow 0/0 allow ::/0 allow
The first directive allows access from an IPv4 address. The second directive allows access from all computers in an IPv4 subnet specified in the CIDR notation. The third directive specifies the same subnet using a simpler notation where the prefix length is determined by the number of dots. The fourth directive specifies an IPv6 subnet. The fifth and sixth directives allow access from all IPv4 and IPv6 addresses respectively. The seventh directive allows access from all addresses (both 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.0/24 allow 1.2.0.0/16
and
allow 1.2.3.4 deny 1.2.3.0/24 allow all 1.2.0.0/16
In the first example, the effect is the same regardless of what order the three directives are given in. So the 1.2.0.0/16 subnet is allowed access, except for the 1.2.3.0/24 subnet, which is denied access, however the host 1.2.3.4 is allowed access.
In the second example, the allow all 1.2.0.0/16 directive 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 with the allow all command.
The rules are internally represented as a tree of tables with one level per four bits of the IPv4 or IPv6 address. The order of the allow and deny directives matters if they modify the same records of one table, i.e. if one subnet is included in the other subnet and their prefix lengths are at the same level. For example, 1.2.3.0/28 and 1.2.3.0/29 are in different tables, but 1.2.3.0/25 and 1.2.3.0/28 are in the same table. The configuration can be verified for individual addresses with the accheck command in chronyc.
A hostname can be specified in the directives instead of the IP address, but the name must be resolvable when chronyd is started, i.e. the network is already up and DNS is working. If the hostname resolves to multiple addresses, only the first address (in the order returned by the system resolver) will be allowed or denied.
Note, if the initstepslew directive 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.
deny [all] [subnet]
The syntax is identical and the directive can be used multiple times too.
There is also a deny all directive with similar behaviour to the allow all directive.
bindaddress address
An example of the use of the directive is:
bindaddress 192.168.1.1
Currently, for each of the IPv4 and IPv6 protocols, only one bindaddress directive can be specified. Therefore, it is not useful on computers which should serve NTP on multiple network interfaces.
binddevice interface
An example of the directive is:
binddevice eth0
broadcast interval address [port]
This directive can be used multiple times to specify multiple addresses.
The syntax is as follows:
broadcast 32 192.168.1.255 broadcast 64 192.168.2.255 12123 broadcast 64 ff02::101
In the first example, the destination port defaults to UDP port 123 (the normal NTP port). In the second example, the destination port is specified as 12123. The first parameter in each case (32 or 64 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 want to send NTP broadcast packets.
chronyd itself cannot 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 implementations.
If ntpd is used as the broadcast client, it will try to measure the round-trip delay between the server and client with normal client mode packets. Thus, the broadcast subnet should also be the subject of an allow directive.
clientloglimit limit
An example of the use of this directive is:
clientloglimit 1048576
noclientlog
local [option]...
This directive is normally used in an isolated network, where computers are required to be synchronised to one another, but not necessarily to real time. The server can be kept vaguely in line with real time by manual input.
The local directive has the following options:
stratum stratum
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 value of 10 indicates that the clock is so many hops away from a reference clock that its time is fairly unreliable.
distance distance
The current root distance can be calculated from root delay and root dispersion (reported by the tracking command in chronyc) as:
distance = delay / 2 + dispersion
activate distance
orphan
This allows multiple servers in the network to use the same local configuration and to be synchronised to one another, without confusing clients that poll more than one server. Each server needs to be configured to poll all other servers with the local directive. This ensures only the server with the smallest reference ID has the local reference active and others are synchronised to it. If that server stops responding, the server with the second smallest reference ID will take over when its local reference mode activates (root distance reaches the threshold configured by the distance option).
The orphan mode is compatible with the ntpd's orphan mode (enabled by the tos orphan command).
An example of the directive is:
local stratum 10 orphan distance 0.1 activate 0.5
ntpsigndsocket directory
Note that MS-SNTP requests are not authenticated and any client that is allowed to access the server by the allow directive, or the allow command in chronyc, can get an MS-SNTP response signed with a trust account’s password and try to crack the password in a brute-force attack. Access to the server should be carefully controlled.
An example of the directive is:
ntpsigndsocket /var/lib/samba/ntp_signd
ntsport port
The port will be open only when a certificate and key is specified by the ntsservercert and ntsserverkey directives.
ntsservercert file
This directive can be used multiple times to specify multiple certificates for different names of the server.
The files are loaded only once. chronyd needs to be restarted in order to load a renewed certificate. The ntsdumpdir and dumpdir directives with the -r option of chronyd are recommended for a near-seamless server operation.
ntsserverkey file
This directive can be used multiple times to specify multiple keys. The number of keys must be the same as the number of certificates and the corresponding files must be specified in the same order.
ntsprocesses processes
maxntsconnections connections
ntsaeads ID...
The following IDs are supported:
The default list of IDs is 30 15. AES-128-GCM-SIV is prefered over AES-SIV-CMAC-256 for shorter keys, which makes NTS cookies shorter and improves reliability of NTS in networks that block or limit rate of longer NTP messages.
An example of the directive is:
ntsaeads 15
This list is used also by the NTS client.
Note the the NTS specification (RFC 8915) requires servers to support AES-SIV-CMAC-256, i.e. 15 should be always included in the specified list.
The AES-128-GCM-SIV keys used by chronyd do not comply to RFC 8915 for compatibility with older chrony clients unless the use of compliant keys is negotiated with an NTS-KE record <https://chrony-project.org/doc/spec/nts-compliant-128gcm.html>. Support for this record was added in version 4.6.1. As a client, chronyd can interoperate with a server that uses compliant keys, but does not support the negotiation, if it responds to incorrectly authenticated requests with an NTS NAK.
ntsdumpdir directory
An example of the directive is:
ntsdumpdir /var/lib/chrony
This directory is used also by the NTS client to save NTS cookies.
ntsntpserver hostname
ntsrotate interval
The automatic rotation of the keys can be disabled by setting ntsrotate to 0. In this case the keys are assumed to be managed externally. chronyd will not save the keys to the ntskeys file and will reload the keys from the file when the rekey command is issued in chronyc. The file can be periodically copied from another server running chronyd (which does not have ntsrotate set to 0) in order to have one or more servers dedicated to NTS-KE. The file includes the subsequent key to which the NTS-KE server will switch on the next rotation, i.e. the process copying and reloading the file does not need to be timed precisely (it can be delayed by up to one rotation interval). The NTS-KE servers need to be configured with the ntsntpserver directive to point the clients to the right NTP server.
An example of the directive is:
ntsrotate 2592000
port port
The default value is 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.
ratelimit [option]...
The ratelimit directive supports a number of options (which can be defined in any order):
interval interval
burst responses
leak rate
kod rate
An example use of the directive is:
ratelimit interval 1 burst 16
This would reduce the response rate for IP addresses sending packets on average more than once per 2 seconds, or sending packets in bursts of more than 16 packets, by up to 75% (with default leak of 2).
ntsratelimit [option]...
An example of the use of the directive is:
ntsratelimit interval 3 burst 1
smoothtime max-freq max-wander [leaponly]
BE WARNED: The server is intentionally not serving its best estimate of the true time. If a large offset has been accumulated, it can take a very long time to smooth it out. This directive should be used only when the clients are not configured to also poll another NTP server, because they could reject this server as a falseticker or fail to select a source completely.
The smoothing process is implemented with a quadratic spline function with two or three pieces. It is independent from any slewing applied to the local system clock, but the accumulated offset and frequency will be reset when the clock is corrected by stepping, e.g. by the makestep directive or the makestep command in chronyc. The process can be reset without stepping the clock by the smoothtime reset command.
The first two arguments of the directive are the maximum frequency offset of the smoothed time to the tracked NTP time (in ppm) and the maximum rate at which the frequency offset is allowed to change (in ppm per second). leaponly is an optional third argument which enables a mode where only leap seconds are smoothed out and normal offset and frequency changes are ignored. The leaponly option is useful in a combination with the leapsecmode slew directive to allow the clients to use multiple time smoothing servers safely.
The smoothing process is activated automatically when 1/10000 of the estimated skew of the local clock falls below the maximum rate of frequency change. It can be also activated manually by the smoothtime activate command, which is particularly useful when the clock is synchronised only with manual input and the skew is always larger than the threshold. The smoothing command can be used to monitor the process.
An example suitable for clients using ntpd and 1024 second polling interval could be:
smoothtime 400 0.001
An example suitable for clients using chronyd on Linux could be:
smoothtime 50000 0.01
Command and monitoring access¶
bindcmdaddress address
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 does not exist. The compiled-in default path of the socket is /run/chrony/chronyd.sock. The socket can be disabled by setting the path to /.
By default, chronyd binds the UDP sockets to the addresses 127.0.0.1 and ::1 (i.e. the loopback interface). 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 the IPv4, IPv6, and Unix domain 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
bindcmddevice interface
An example of the directive is:
bindcmddevice eth0
cmdallow [all] [subnet]
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.
cmddeny [all] [subnet]
The syntax is identical.
There is also a cmddeny all directive with similar behaviour to the cmdallow all directive.
cmdport port
An example shows the syntax:
cmdport 257
This would make chronyd use UDP 257 as its command port. (chronyc would need to be run with the -p 257 option to inter-operate correctly.)
cmdratelimit [option]...
An example of the use of the directive is:
cmdratelimit interval 2
Real-time clock (RTC)¶
hwclockfile file
The compiled-in default value is '/etc/adjtime'.
An example of the directive is:
hwclockfile /etc/adjtime
rtcautotrim threshold
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.
rtcdevice device
rtcfile file
An example of the directive 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.
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 RTC facilities (the rtcfile directive and the -s command-line option to chronyd) if the following three conditions apply:
rtconutc
If you keep the RTC 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 hwclock program.
Note that this setting is overridden by the hwclockfile file and is not relevant for the rtcsync directive.
rtcsync
On Linux, the RTC copy is performed by the kernel every 11 minutes.
On macOS, 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.
Logging¶
log [option]...
rawmeasurements
2016-11-09 05:40:50 203.0.113.15 N 2 111 111 1111 10 10 1.0 \
-4.966e-03 2.296e-01 1.577e-05 1.615e-01 7.446e-03 CB00717B 4B D K
The columns are as follows (the quantities in square brackets are the values from the example line above):
measurements
statistics
2016-08-10 05:40:50 203.0.113.15 6.261e-03 -3.247e-03 \
2.220e-03 1.874e-06 1.080e-06 7.8e-02 16 0 8 0.00
The columns are as follows (the quantities in square brackets are the values from the example line above):
selection
2022-05-01 02:01:20 203.0.113.15 * ----- 377 1.00 \
4.228e+01 -1.575e-04 1.239e-04
The columns are as follows (the quantities in square brackets are the values from the example line above):
tracking
2017-08-22 13:22:36 203.0.113.15 2 -3.541 0.075 -8.621e-06 N \
2 2.940e-03 -2.084e-04 1.534e-02 3.472e-04 8.304e-03
The columns are as follows (the quantities in square brackets are the values from the example line above) :
rtc
2015-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):
refclocks
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):
tempcomp
2015-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):
log measurements statistics tracking
logbanner entries
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.
logchange threshold
By default, the threshold is 1 second.
An example of the use is:
logchange 0.1
which would cause a syslog message to be generated if a system clock error of over 0.1 seconds starts to be compensated.
logdir directory
An example of the use of this directive is:
logdir /var/log/chrony
mailonchange email threshold
An example of the 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 cannot 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.
Miscellaneous¶
confdir directory...
Multiple directories (up to 10) can be specified with a single confdir directive. In this case, if multiple directories contain a file with the same name, only the first file in the order of the specified directories will be included. This enables a fragmented configuration where existing fragments can be replaced by adding files to a different directory.
This directive can be used multiple times.
An example of the directive is:
confdir /etc/chrony/chrony.d
sourcedir directory...
This directive can be used multiple times.
An example of the directive is:
sourcedir /var/run/chrony-dhcp
include pattern
This directive can be used multiple times.
An example of the directive is:
include /etc/chrony/chrony.d/*.conf
hwtimestamp interface [option]...
This directive is supported on Linux 3.19 and newer. The NIC must support HW timestamping, which can be verified with the ethtool -T command. The list of capabilities should include hardware-raw-clock, hardware-transmit, and hardware-receive. The receive filter all, or ntp, is necessary for timestamping of received NTP packets. Timestamping of packets received on bridged and bonded interfaces is supported on Linux 4.13 and newer. If HW timestamping does not work for received packets, chronyd will use kernel receive timestamps instead. Transmit-only HW timestamping can still be useful to improve stability of the synchronisation.
chronyd does not synchronise the NIC clock. It assumes the clock is running free. Multiple instances of chronyd can use the same interface with enabled HW timestamping. Applications which need HW timestamping with a synchronised clock (e.g. a PTP daemon) should use a virtual clock running on top of the physical clock created by writing to /sys/class/ptp/ptpX/n_vclocks. This feature is available on Linux 5.14 and newer.
If the kernel supports software timestamping, it will be enabled for all interfaces automatically.
The source of timestamps (i.e. hardware, kernel, or daemon) is indicated on the client side in the measurements.log file (if enabled by the log directive) and the ntpdata report. On the server side, the number of served timestamps from each source is provided in the serverstats report.
This directive can be used multiple times to enable HW timestamping on multiple interfaces. If the specified interface is *, chronyd will try to enable HW timestamping on all available interfaces.
The hwtimestamp directive has the following options:
minpoll poll
maxpoll poll
minsamples samples
maxsamples samples
precision precision
txcomp compensation
rxcomp compensation
nocrossts
rxfilter filter
all
ntp
ptp
none
Examples of the directive are:
hwtimestamp eth0 hwtimestamp eth1 txcomp 300e-9 rxcomp 645e-9 hwtimestamp *
hwtstimeout timeout
The default value is 0.001 seconds, which should be sufficient with most hardware. If you frequently see kernel transmit timestamps in the measurements.log file or ntpdata report, and it is not a server handling a high rate of requests in the interleaved mode on the same interface (which would compete with timestamping of the server’s own requests), increasing the timeout to 0.01 or possibly even longer might help. Note that the maximum timeout is limited by the NTP polling interval.
keyfile file
The format of the directive is shown in the example below:
keyfile /etc/chrony/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:933F62BE1D604E68A81B557F18CFA200483F5B70 30 AES128 HEX:7EA62AE64D190114D46D5A082F948EC1 31 AES256 HEX:37DDCBC67BB902BCB8E995977FAB4D2B5642F5B32EBCEEE421921D97E5CBFE39
...
Each line consists of an ID, optional type, and key.
The ID can be any positive integer in the range 1 through 2^32-1.
The type is a name of a cryptographic hash function or cipher which is used to generate and verify the MAC. The default type is MD5, which is always supported. If chronyd was built with enabled support for hashing using a crypto library (Nettle, GnuTLS, NSS, or LibTomCrypt), the following functions are available: MD5, SHA1, SHA256, SHA384, SHA512. Depending on which library and version is chronyd using, some of the following hash functions and ciphers may also be available: SHA3-224, SHA3-256, SHA3-384, SHA3-512, TIGER, WHIRLPOOL, AES128, AES256.
The key can be specified as a string of ASCII 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. If the type is a cipher, the length of the key must match the cipher (i.e. 128 bits for AES128 and 256 bits for AES256).
It is recommended to use randomly generated keys, specified in the hexadecimal format, which are at least 128 bits long (i.e. they have at least 32 characters after the HEX: prefix). chronyd will log a warning to syslog on start if a source is specified in the configuration file with a key shorter than 80 bits.
The recommended key types are AES ciphers and SHA3 hash functions. MD5 should be avoided unless no other type is supported on the server and client, or peers. A major weakness of MD5 for the NTP MAC is a length extension attack, where a man-in-the-middle attacker can add arbitrary extension fields to the NTP message and update the MAC to pass the verification of the extended message. The extfield option (enabling processing of the specified extension field) should not be used for NTP sources authenticated with an MD5 key.
The keygen command of chronyc can be used to generate random keys for the key file. By default, it generates 160-bit MD5 or SHA1 keys.
For security reasons, the file should be readable only by root and the user under which chronyd is normally running (to allow chronyd to re-read the file when the rekey command is issued by chronyc).
lock_all
pidfile file
pidfile /run/chronyd.pid
Setting this directive to / disables writing and checking of the PID file.
ptpport port
The NTP-over-PTP support is experimental. The protocol and configuration can change in future. It should be used only in local networks.
The PTP port will be open even if chronyd is not configured to operate as a server or client. The directive does not change the default protocol of specified NTP sources. Each NTP source that should use NTP-over-PTP needs to be specified with the port option set to the PTP port. To actually enable hardware timestamping on NICs which can timestamp PTP packets only, the rxfilter option of the hwtimestamp directive needs to be set to ptp. The extension field F324 needs to be enabled to use the corrections provided by the PTP transparent clocks.
An example of client configuration is:
server ntp1.example.net minpoll 0 maxpoll 0 xleave port 319 extfield F324 hwtimestamp * rxfilter ptp ptpport 319
ptpdomain domain
sched_priority priority
On systems other than macOS, this directive uses the pthread_setschedparam() 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 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 pthread_setschedparam(3) man page has more details.
On macOS, this directive uses the thread_policy_set() kernel call to specify real-time scheduling. As noted above, you should not use this directive unless you really need it.
user user
On Linux, chronyd needs to be compiled with support for the libcap library. On macOS, FreeBSD, NetBSD and illumos 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.
The compiled-in default value is _chrony.
EXAMPLES¶
NTP client with permanent connection to NTP servers¶
This section shows how to configure chronyd 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 servers you want to use. You might be able to find names of suitable servers by one of the following methods:
Assuming that your NTP servers are called ntp1.example.net, ntp2.example.net and ntp3.example.net, your chrony.conf file could contain as a minimum:
server ntp1.example.net server ntp2.example.net server ntp3.example.net
However, you will probably want to include some of the other directives. The driftfile, makestep and rtcsync might be particularly useful. Also, the iburst option of the server directive is useful to speed up the initial synchronisation. The smallest useful configuration file would look something like:
server ntp1.example.net iburst server ntp2.example.net iburst server ntp3.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 might change over time), it is 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
If the servers (or pool) support the Network Time Security (NTS) authentication mechanism and chronyd is compiled with NTS support, the nts option will enable a secure synchronisation to the servers. The configuration file could look like:
server ntp1.example.net iburst nts server ntp2.example.net iburst nts server ntp3.example.net iburst nts driftfile /var/lib/chrony/drift makestep 1.0 3 rtcsync
NTP client with infrequent connection to NTP servers¶
This section shows how to configure chronyd for computers that have occasional connections to NTP servers. In this case, you will need some additional configuration to tell chronyd when the connection 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 ntp1.example.net, ntp2.example.net and ntp3.example.net, your chrony.conf file would now contain:
server ntp1.example.net offline server ntp2.example.net offline server ntp3.example.net offline driftfile /var/lib/chrony/drift makestep 1.0 3 rtcsync
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. 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, assuming that pppd is the program being used to connect to the Internet and that chronyc has been installed at /usr/bin/chronyc, the script /etc/ppp/ip-up would include:
/usr/bin/chronyc online
and the script /etc/ppp/ip-down would include:
/usr/bin/chronyc offline
chronyd's polling of the servers would now only occur whilst the machine is actually connected to the Internet.
Isolated networks¶
This section shows how to configure chronyd for computers that never have network connectivity to any computer which ultimately derives its time from a reference clock.
In this situation, one computer is selected to be the primary timeserver. The other computers are either direct clients of the server, or clients of clients.
The local directive enables a local reference mode, which allows chronyd to appear synchronised even when it is not.
The rate value in the server’s drift file needs to be set to the average rate at which the server gains or loses time. chronyd includes support for this, in the form of the manual directive and the settime command in the chronyc program.
If the server is rebooted, chronyd can re-read the drift rate from the drift file. However, the server has no accurate estimate of the current time. To get around this, the system can be configured so that the server can initially set itself to a ‘majority-vote’ of selected clients' times; this allows the clients to ‘flywheel’ the server while it is rebooting.
The smoothtime directive 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 server (called ntp.local) might be (assuming the clients and the server are in the 192.168.165.x subnet):
initstepslew 1 client1 client3 client6 driftfile /var/lib/chrony/drift local stratum 8 manual allow 192.168.165.0/24 smoothtime 400 0.01 rtcsync
For the clients that have to resynchronise the server when it restarts, the configuration file might be:
server ntp.local iburst driftfile /var/lib/chrony/drift allow 192.168.165.0/24 makestep 1.0 3 rtcsync
The rest of the clients would be the same, except that the allow directive is not required.
If there is no suitable computer to be designated as the primary server, or there is a requirement to keep the clients synchronised even when it fails, the orphan option of the local directive enables a special mode where the server is selected from multiple computers automatically. They all need to use the same local configuration and poll one another. The server with the smallest reference ID (which is based on its IP address) will take the role of the primary server and others will be synchronised to it. When it fails, the server with the second smallest reference ID will take over and so on.
A configuration file for the first server might be (assuming there are three servers called ntp1.local, ntp2.local, and ntp3.local):
initstepslew 1 ntp2.local ntp3.local server ntp2.local server ntp3.local driftfile /var/lib/chrony/drift local stratum 8 orphan manual allow 192.168.165.0/24 rtcsync
The other servers would be the same, except the hostnames in the initstepslew and server directives would be modified to specify the other servers. Their clients might be configured to poll all three servers.
RTC tracking¶
This section considers a computer which has occasional connections to the Internet and is turned off between ‘sessions’. In this case, chronyd relies on the computer’s RTC to maintain the time between the periods when it is powered up. It assumes that Linux is run exclusively on the computer. Dual-boot systems might work; it depends what (if anything) the other system does to the RTC. On 2.6 and later kernels, if your motherboard has a HPET, you will need to enable the HPET_EMULATE_RTC option in your kernel configuration. Otherwise, chronyd will not be able to interact with the RTC device and will give up using it.
When the computer is connected to the Internet, 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 or losing time.
When the computer is taken offline from the Internet, the best estimate of the gain or loss rate is used to free-run the computer until it next goes online.
Whilst the computer is running, chronyd makes measurements of the 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.
When the computer is powered down, the measurement histories for all the NTP servers are saved to files, 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 or 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 might 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 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 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.
To illustrate how a computer might be configured for this case, example configuration files are shown.
For the chrony.conf file, the following can be used as an example.
server ntp1.example.net maxdelay 0.4 offline server ntp2.example.net maxdelay 0.4 offline server ntp3.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 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/bin/chronyc online
and the relevant part of the /etc/ppp/ip-down script is:
/usr/bin/chronyc -m offline dump writertc
chronyd is started during the boot sequence with the -r and -s options. It might 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.
Public NTP server¶
chronyd can be configured to operate as a public NTP server, e.g. to join the pool.ntp.org <https://www.pool.ntp.org/en/join.html> project. The configuration is similar to the NTP client with permanent connection, except it needs to allow client access from all addresses. It is recommended to find at least four good servers (e.g. from the pool, or on the NTP homepage). If the server has a hardware reference clock (e.g. a GPS receiver), it can be specified by the refclock directive.
The amount of memory used for logging client accesses can be increased in order to enable clients to use the interleaved mode even when the server has a large number of clients, and better support rate limiting if it is enabled by the ratelimit directive. The system timezone database, if it is kept up to date and includes the right/UTC timezone, can be used as a reliable source to determine when a leap second will be applied to UTC. The -r option with the dumpdir directive shortens the time in which chronyd will not be able to serve time to its clients when it needs to be restarted (e.g. after upgrading to a newer version, or a change in the configuration).
The configuration file could look like:
server ntp1.example.net iburst server ntp2.example.net iburst server ntp3.example.net iburst server ntp4.example.net iburst makestep 1.0 3 rtcsync allow clientloglimit 100000000 leapsectz right/UTC driftfile /var/lib/chrony/drift dumpdir /run/chrony
SEE ALSO¶
BUGS¶
For instructions on how to report bugs, please visit <https://chrony-project.org/>.
AUTHORS¶
chrony was written by Richard Curnow, Miroslav Lichvar, and others.
2024-10-08 | chrony 4.6.1 |