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 directive specifies an NTP server which can be used as a
time source. The client-server relationship is strictly
hierarchical: a client might synchronise its system time to that of
the server, but the server’s system time will never be influenced by
that of a client.
The server 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
This option specifies the minimum interval between requests sent
to the server as a power of 2 in seconds. For example, minpoll 5
would mean that the polling interval should not drop below 32
seconds. The default is 6 (64 seconds), the minimum is -7
(1/128th of a second), and the maximum is 24 (6 months). Note
that intervals shorter than 6 (64 seconds) should generally not
be used with public servers on the Internet, because it might be
considered abuse. A sub-second interval will be enabled only
when the server is reachable and the round-trip delay is shorter
than 10 milliseconds, i.e. the server should be in a local
network.
maxpoll poll
This option specifies the maximum interval between requests sent
to the server as a power of 2 in seconds. For example, maxpoll 9
indicates that the polling interval should stay at or below 9
(512 seconds). The default is 10 (1024 seconds), the minimum is
-7 (1/128th of a second), and the maximum is 24 (6 months).
iburst
With this option, chronyd will start with a burst of 4-8
requests in order to make the first update of the clock sooner.
It will also repeat the burst every time the source is switched
from the offline state to online with the online command in
chronyc.
burst
With this option, chronyd will send a burst of up to 4 requests
when it cannot get a good measurement from the server. The
number of requests in the burst is limited by the current
polling interval to keep the average interval at or above the
minimum interval, i.e. the current interval needs to be at least
two times longer than the minimum interval in order to allow a
burst with two requests.
key ID
The NTP protocol supports a message authentication code (MAC) to
prevent computers having their system time upset by rogue
packets being sent to them. The MAC is generated as a function
of a key specified in the key file, which is specified by the
keyfile directive.
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
This option enables authentication using the Network Time
Security (NTS) mechanism. Unlike with the key option, the server
and client do not need to share a key in a key file. NTS has a
Key Establishment (NTS-KE) protocol using the Transport Layer
Security (TLS) protocol to get the keys and cookies required by
NTS for authentication of NTP packets.
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
This option specifies which set of trusted certificates should
be used to verify the server’s certificate when the nts option
is enabled. Sets of certificates can be specified with the
ntstrustedcerts directive. The default set is 0, which by
default contains certificates of the system’s default trusted
certificate authorities.
maxdelay delay
chronyd uses the network round-trip delay to the server to
determine how accurate a particular measurement is likely to be.
Long round-trip delays indicate that the request, or the
response, or both were delayed. If only one of the messages was
delayed the measurement error is likely to be substantial.
For small variations in 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
This option is similar to the maxdelay option above. chronyd
keeps a record of the minimum round-trip delay amongst the
previous measurements that it has buffered. If a measurement has
a round-trip delay that is greater than the specified ratio
times the minimum delay, it will be rejected. By default, this
test is disabled.
maxdelaydevratio ratio
If a measurement has a ratio of the increase in the round-trip
delay from the minimum delay amongst the previous measurements
to the standard deviation of the previous measurements that is
greater than the specified ratio, it will be rejected. The
default is 10.0.
maxdelayquant p
This option disables the maxdelaydevratio test and specifies the
maximum acceptable delay as a quantile of the round-trip delay
instead of a function of the minimum delay amongst the buffered
measurements. If a measurement has a round-trip delay that is
greater than a long-term estimate of the p-quantile, it will be
rejected.
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
This option specifies a fixed minimum round-trip delay to be
used instead of the minimum amongst the previous measurements.
This can be useful in networks with static configuration to
improve the stability of corrections for asymmetric jitter,
weighting of the measurements, and the maxdelayratio and
maxdelaydevratio tests. The value should be set accurately in
order to have a positive effect on the synchronisation.
asymmetry ratio
This option specifies the asymmetry of the network jitter on the
path to the source, which is used to correct the measured offset
according to the delay. The asymmetry can be between -0.5 and
+0.5. A negative value means the delay of packets sent to the
source is more variable than the delay of packets sent from the
source back. By default, chronyd estimates the asymmetry
automatically.
offset offset
This option specifies a correction (in seconds) which will be
applied to offsets measured with this source. It’s particularly
useful to compensate for a known asymmetry in network delay or
timestamping errors. For example, if packets sent to the source
were on average delayed by 100 microseconds more than packets
sent from the source back, the correction would be -0.00005 (-50
microseconds). The default is 0.0.
minsamples samples
Set the minimum number of samples kept for this source. This
overrides the minsamples directive.
maxsamples samples
Set the maximum number of samples kept for this source. This
overrides the maxsamples directive.
filter polls
This option enables a median filter to reduce noise in NTP
measurements. The filter will process samples collected in the
specified number of polls into a single sample. It is intended
to be used with very short polling intervals in local networks
where it is acceptable to generate a lot of NTP traffic.
offline
If the server will not be reachable when chronyd is started, the
offline option can be specified. chronyd will not try to poll
the server until it is enabled to do so (by using the online
command in chronyc).
auto_offline
With this option, the server will be assumed to have gone
offline when sending a request fails, e.g. due to a missing
route to the network. This option avoids the need to run the
offline command from chronyc when disconnecting the network
link. (It will still be necessary to use the online command when
the link has been established, to enable measurements to start.)
prefer
Prefer this source over other selectable sources without the
prefer option.
noselect
Never select this source. This is particularly useful for
monitoring.
trust
Assume time from this source is always true. It can be rejected
as a falseticker in the source selection only if another source
with this option does not agree with it.
require
Require that at least one of the sources specified with this
option is selectable (i.e. recently reachable and not a
falseticker) before updating the clock. Together with the trust
option this might be useful to allow a trusted authenticated
source to be safely combined with unauthenticated sources in
order to improve the accuracy of the clock. They can be selected
and used for synchronisation only if they agree with the trusted
and required source.
xleave
This option enables the interleaved mode of NTP. It enables the
server to respond with more accurate transmit timestamps (e.g.
kernel or hardware timestamps), which cannot be contained in the
transmitted packet itself and need to refer to a previous packet
instead. This can significantly improve the accuracy and
stability of the measurements.
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
Target number of measurements to use for the regression
algorithm which chronyd will try to maintain by adjusting the
polling interval between minpoll and maxpoll. A higher target
makes chronyd prefer shorter polling intervals. The default is 8
and a useful range is from 6 to 60.
port port
This option allows the UDP port on which the server understands
NTP requests to be specified. For normal servers this option
should not be required (the default is 123, the standard NTP
port).
ntsport port
This option specifies the TCP port on which the server is
listening for NTS-KE connections when the nts option is enabled.
The default is 4460.
presend poll
If the timing measurements being made by chronyd are the only
network data passing between two computers, you might find that
some measurements are badly skewed due to either the client or
the server having to do an ARP lookup on the other party prior
to transmitting a packet. This is more of a problem with long
sampling intervals, which might be similar in duration to the
lifetime of entries in the ARP caches of the machines.
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
When the synchronisation source is selected from available
sources, sources with lower stratum are normally slightly
preferred. This option can be used to increase stratum of the
source to the specified minimum, so chronyd will avoid selecting
that source. This is useful with low-stratum sources that are
known to be unreliable or inaccurate and which should be used
only when other sources are unreachable.
version version
This option sets the NTP version of packets sent to the server.
This can be useful when the server runs an old NTP
implementation that does not respond to requests using a newer
version. The default version depends on other options. If the
extfield or xleave option is used, the default version is 4. If
those options are not used and the key option specifies a key
using a hash function with output size longer than 160 bits
(e.g. SHA256), the default version is 3 for compatibility with
older chronyd servers. In other cases, the default version is 4.
copy
This option specifies that the server and client are closely
related, their configuration does not allow a synchronisation
loop to form between them, and the client is allowed to assume
the reference ID and stratum of the server. This is useful when
multiple instances of chronyd are running on one computer (e.g.
for security or performance reasons), one primarily operating as
a client to synchronise the system clock and other instances
started with the -x option to operate as NTP servers for other
computers with their NTP clocks synchronised to the first
instance.
extfield type
This option enables an NTPv4 extension field specified by its
type as a hexadecimal number. It will be included in requests
sent to the server and processed in received responses if the
server supports it. Note that some server implementations do not
respond to requests containing an unknown extension field
(chronyd as a server responded to such requests since version
2.0).
This option can be used multiple times to enable multiple
extension fields.
The following extension fields are supported:
F323
An experimental extension field to enable several
improvements that were proposed for the next version of the
NTP protocol (NTPv5). The field contains root delay and
dispersion in higher resolution and a monotonic receive
timestamp, which enables a frequency transfer between the
server and client to significantly improve stability of the
synchronisation. This field should be enabled only for
servers known to be running chronyd version 4.2 or later.
F324
An experimental extension field to enable the use of the
Precision Time Protocol (PTP) correction field in
NTP-over-PTP messages updated by one-step end-to-end
transparent clocks in network switches and routers to
significantly improve accuracy and stability of the
synchronisation. NTP-over-PTP can be enabled by the ptpport
directive and setting the port option to the PTP port. The
corrections are applied only to NTP measurements with HW
timestamps (enabled by the hwtimestamp directive). This
field should be enabled only for servers known to be running
chronyd version 4.5 or later.
ipv4, ipv6
These options force chronyd to use only IPv4 or IPv6 addresses
respectively for this source. They do not override the -4 or -6
option on the chronyd command line.
pool name [option]...
The syntax of this directive is similar to that for the server
directive, except that it is used to specify a pool of NTP servers
rather than a single NTP server. The pool name is expected to
resolve to multiple addresses which might change over time.
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
This option sets the desired number of sources to be used from
the pool. chronyd will repeatedly try to resolve the name until
it gets this number of sources responding to requests. The
default value is 4 and the maximum value is 16.
An example of the pool directive is
pool pool.ntp.org iburst maxsources 3
peer hostname [option]...
The syntax of this directive is identical to that for the server
directive, except that it specifies a symmetric association with an
NTP peer instead of a client/server association with an NTP server.
A single symmetric association allows the peers to be both servers
and clients to each other. This is mainly useful when the NTP
implementation of the peer (e.g. ntpd) supports ephemeral symmetric
associations and does not need to be configured with an address of
this host. chronyd does not support ephemeral associations.
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]...
(This directive is deprecated in favour of the makestep directive.)
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]...
The refclock directive specifies a hardware reference clock to be
used as a time source. It has two mandatory parameters, a driver
name and a driver-specific parameter. The two parameters are
followed by zero or more refclock options. Some drivers have special
options, which can be appended to the driver-specific parameter
using the : character.
This directive can be used multiple times to specify multiple
reference clocks.
There are four drivers included in chronyd:
PPS
Driver for the kernel PPS (pulse per second) API. The parameter
is the path to the PPS device (typically /dev/pps?). As PPS
refclocks do not supply full time, another time source (e.g. NTP
server or non-PPS refclock) is needed to complete samples from
the PPS refclock. An alternative is to enable the local
directive to allow synchronisation with some unknown but
constant offset. The driver supports the following option:
clear
By default, the PPS refclock uses assert events (rising
edge) for synchronisation. With this option, it will use
clear events (falling edge) instead.
Examples:
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
Unix domain socket driver. This driver uses a datagram socket to
receive samples from another application running on the system.
The parameter is the path to the socket, which chronyd will
create on start. The format of the messages is described in the
refclock_sock.c file in the chrony source code.
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
NTP shared memory driver. This driver implements the protocol of
the ntpd driver type 28. It is functionally similar to the SOCK
driver, but uses a shared memory segment instead of a socket.
The parameter is the unit number, typically a small number like
0, 1, 2, or 3, from which is derived the key of the memory
segment as 0x4e545030 + unit.
The driver supports the following option:
perm=mode
This option specifies the permissions of the shared memory
segment created by chronyd. They are specified as a numeric
mode. The default value is 0600 (read-write access for owner
only).
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
PTP hardware clock (PHC) driver. The parameter is the path to
the device of the PTP clock which should be used as a time
source. If the clock is kept in TAI instead of UTC (e.g. it is
synchronised by a PTP daemon), the current UTC-TAI offset needs
to be specified by the offset option. Alternatively, the pps
refclock option can be enabled to treat the PHC as a PPS
refclock, using only the sub-second offset for synchronisation.
The driver supports the following options:
nocrossts
This option disables use of precise cross timestamping.
extpps
This option enables a PPS mode in which the PTP clock is
timestamping pulses of an external PPS signal connected to
the clock. The clock does not need to be synchronised, but
another time source is needed to complete the PPS samples.
Note that some PTP clocks cannot be configured to timestamp
only assert or clear events, and it is necessary to use the
width option to filter wrong PPS samples.
pin=index
This option specifies the index of the pin which should be
enabled for the PPS timestamping. If the PHC does not have
configurable pins (i.e. the channel function is fixed), the
index needs to be set to -1 to disable the pin
configuration. The default value is 0.
channel=index
This option specifies the index of the channel for the PPS
mode. The default value is 0.
clear
This option enables timestamping of clear events (falling
edge) instead of assert events (rising edge) in the PPS
mode. This may not work with some clocks.
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
The refclock directive supports the following options:
poll poll
Timestamps produced by refclock drivers are not used
immediately, but they are stored and processed by a median
filter in the polling interval specified by this option. This is
defined as a power of 2 and can be negative to specify a
sub-second interval. The default is 4 (16 seconds). A shorter
interval allows chronyd to react faster to changes in the
frequency of the system clock, but it might have a negative
effect on its accuracy if the samples have a lot of jitter.
dpoll dpoll
Some drivers do not listen for external events and try to
produce samples in their own polling interval. This is defined
as a power of 2 and can be negative to specify a sub-second
interval. The default is 0 (1 second).
refid refid
This option is used to specify the reference ID of the refclock,
as up to four ASCII characters. The default reference ID is
composed from the first three characters of the driver name and
the number of the refclock. Each refclock must have a unique
reference ID.
lock refid
This option can be used to lock a PPS refclock to another
refclock, which is specified by its reference ID. In this mode
received PPS samples are paired directly with raw samples from
the specified refclock.
rate rate
This option sets the rate of the pulses in the PPS signal (in
Hz). This option controls how the pulses will be completed with
real time. To actually receive more than one pulse per second, a
negative dpoll has to be specified (-3 for a 5Hz signal). The
default is 1.
maxlockage pulses
This option specifies in number of pulses how old can be samples
from the refclock specified by the lock option to be paired with
the pulses. Increasing this value is useful when the samples are
produced at a lower rate than the pulses. The default is 2.
width width
This option specifies the width of the pulses (in seconds). It
is used to filter PPS samples when the driver provides samples
for both rising and falling edges. Note that it reduces the
maximum allowed error of the time source which completes the PPS
samples. If the duty cycle is configurable, 50% should be
preferred in order to maximise the allowed error.
pps
This options forces chronyd to treat any refclock (e.g. SHM or
PHC) as a PPS refclock. This can be useful when the refclock
provides time with a variable offset of a whole number of
seconds (e.g. it uses TAI instead of UTC). Another time source
is needed to complete samples from the refclock.
offset offset
This option can be used to compensate for a constant error. The
specified offset (in seconds) is applied to all samples produced
by the reference clock. The default is 0.0.
delay delay
This option sets the NTP delay of the source (in seconds). Half
of this value is included in the maximum assumed error which is
used in the source selection algorithm. Increasing the delay is
useful to avoid having no majority in the source selection or to
make it prefer other sources. The default is 1e-9 (1
nanosecond).
stratum stratum
This option sets the NTP stratum of the refclock. This can be
useful when the refclock provides time with a stratum other than
0. The default is 0.
precision precision
This option sets the precision of the reference clock (in
seconds). The default value is the estimated precision of the
system clock.
maxdispersion dispersion
Maximum allowed dispersion for filtered samples (in seconds).
Samples with larger estimated dispersion are ignored. By
default, this limit is disabled.
filter samples
This option sets the length of the median filter which is used
to reduce the noise in the measurements. With each poll about 40
percent of the stored samples are discarded and one final sample
is calculated as an average of the remaining samples. If the
length is 4 or more, at least 4 samples have to be collected
between polls. For lengths below 4, the filter has to be full.
The default is 64. With drivers that perform their own polling
(PPS, PHC, SHM), the maximum value is adjusted to the number of
driver polls per source poll, i.e. 2^(poll - dpoll).
prefer
Prefer this source over other selectable sources without the
prefer option.
noselect
Never select this source. This is useful for monitoring or with
sources which are not very accurate, but are locked with a PPS
refclock.
trust
Assume time from this source is always true. It can be rejected
as a falseticker in the source selection only if another source
with this option does not agree with it.
require
Require that at least one of the sources specified with this
option is selectable (i.e. recently reachable and not a
falseticker) before updating the clock. Together with the trust
option this can be useful to allow a trusted, but not very
precise, reference clock to be safely combined with
unauthenticated NTP sources in order to improve the accuracy of
the clock. They can be selected and used for synchronisation
only if they agree with the trusted and required source.
tai
This option indicates that the reference clock keeps time in TAI
instead of UTC and that chronyd should correct its offset by the
current TAI-UTC offset. The leapsectz or leapseclist directive
must be used with this option and the database must be kept up
to date in order for this correction to work as expected. This
option does not make sense with PPS refclocks.
local
This option specifies that the reference clock is an
unsynchronised clock which is more stable than the system clock
(e.g. TCXO, OCXO, or atomic clock) and it should be used as a
local standard to stabilise the system clock. The refclock will
bypass the source selection. There should be at most one
refclock specified with this option and it should have the
shortest polling interval among all configured sources.
minsamples samples
Set the minimum number of samples kept for this source. This
overrides the minsamples directive.
maxsamples samples
Set the maximum number of samples kept for this source. This
overrides the maxsamples directive.
manual
The manual directive enables support at run-time for the settime
command in chronyc. If no manual directive is included, any attempt
to use the settime command in chronyc will be met with an error
message.
Note that the settime command can be enabled at run-time using the
manual command in chronyc. (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
By default, chronyd as an NTP client opens a new socket for each
request with the source port chosen randomly by the operating
system. The acquisitionport directive can be used to specify the
source port and use only one socket (per IPv4 or IPv6 address
family) for all configured servers. This can be useful for getting
through some firewalls. It should not be used if not necessary as
there is a small impact on security of the client. If set to 0, the
source port of the permanent socket will be chosen randomly by the
operating system.
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
The bindacqaddress directive specifies a local IP address to which
chronyd will bind its NTP and NTS-KE client sockets. The syntax is
similar to the bindaddress and bindcmdaddress directives.
For each of the IPv4 and IPv6 protocols, only one bindacqaddress
directive can be specified.
bindacqdevice interface
The bindacqdevice directive binds the client sockets to a network
device specified by the interface name. This can be useful when the
local address is dynamic, or to enable an NTP source specified with
a link-local IPv6 address. This directive can specify only one
interface and it is supported on Linux only.
An example of the directive is:
bindacqdevice eth0
dscp point
The dscp directive sets the Differentiated Services Code Point
(DSCP) in transmitted NTP packets to the specified value. It can
improve stability of NTP measurements in local networks where
switches or routers are configured to prioritise forwarding of
packets with specific DSCP values. The default value is 0 and the
maximum value is 63.
An example of the directive (setting the Expedited Forwarding class)
is:
dscp 46
dumpdir directory
To compute the rate of gain or loss of time, chronyd has to store a
measurement history for each of the time sources it uses.
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
The maxsamples directive sets the default maximum number of samples
that chronyd should keep for each source. This setting can be
overridden for individual sources in the server and refclock
directives. The default value is 0, which disables the configurable
limit. The useful range is 4 to 64.
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
The minsamples directive sets the default minimum number of samples
that chronyd should keep for each source. This setting can be
overridden for individual sources in the server and refclock
directives. The default value is 6. The useful range is 4 to 64.
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...
This directive specifies a list of IDs of Authenticated Encryption
with Associated Data (AEAD) algorithms enabled for NTS
authentication of NTP messages. The algorithms are specified in
decreasing order of priority. Algorithms that are not supported by
the installed version of the crypto library (Nettle, GnuTLS) are
ignored.
The following IDs are supported:
• 15: AES-SIV-CMAC-256
• 30: AES-128-GCM-SIV
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
This directive specifies a directory for the client to save NTS
cookies it received from the server in order to avoid making an
NTS-KE request when chronyd is started again. The cookies are saved
separately for each NTP source in files named by the IP address of
the NTS-KE server (e.g. 1.2.3.4.nts). By default, the client does
not save the cookies.
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
This directive specifies the maximum interval between NTS-KE
handshakes (in seconds) in order to refresh the keys authenticating
NTP packets. The default value is 2419200 (4 weeks) and the maximum
value is 2^31-1 (68 years).
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
This directive specifies a file or directory containing trusted
certificates (in the PEM format) which are needed to verify
certificates of NTS-KE servers, e.g. certificates of trusted
certificate authorities (CA) or self-signed certificates of the
servers.
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
This directive disables the system’s default trusted CAs. Only
certificates specified by the ntstrustedcerts directive will be
trusted.
nocerttimecheck limit
This directive disables the checks of the activation and expiration
times of certificates for the specified number of clock updates. It
allows the NTS authentication mechanism to be used on computers
which start with wrong time (e.g. due to not having an RTC or backup
battery). Disabling the time checks has important security
implications and should be used only as a last resort, preferably
with a minimal number of trusted certificates. The default value is
0, which means the time checks are always enabled.
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
This directive specifies the interval (in seconds) between
refreshing IP addresses of NTP sources specified by hostname. If the
hostname no longer resolves to the currently used address, it will
be replaced with one of the new addresses to avoid using a server
which is no longer intended for service, even if it is still
responding correctly and would not be replaced as unreachable. Only
one source is refreshed at a time. The default value is 1209600 (2
weeks) and the maximum value is 2^31-1 (68 years). A value of 0
disables the periodic refreshment.
The refresh command can be used to refresh all sources immediately.
Source selection
authselectmode mode
NTP sources can be specified with the key or nts option to enable
authentication to limit the impact of man-in-the-middle attacks. The
attackers can drop or delay NTP packets (up to the maxdelay and
maxdistance limits), but they cannot modify the timestamps contained
in the packets. The attack can cause only a limited slew or step,
and also cause the clock to run faster or slower than real time (up
to double of the maxdrift limit).
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
Authentication is strictly required for NTP sources in this
mode. If any unauthenticated NTP sources are specified, they
will automatically get the noselect option to prevent them from
being selected for synchronisation.
prefer
In this mode, authentication is optional and preferred. If it is
enabled for at least one NTP source, all unauthenticated NTP
sources will get the noselect option.
mix
In this mode, authentication is optional and synchronisation to
a mix of authenticated and unauthenticated NTP sources is
allowed. If both authenticated and unauthenticated NTP sources
are specified, all authenticated NTP sources and reference
clocks will get the require and trust options to prevent
synchronisation to unauthenticated NTP sources if they do not
agree with a majority of the authenticated sources and reference
clocks. This is the default mode.
ignore
In this mode, authentication is ignored in the source selection.
All sources will have only the selection options that were
specified in the configuration file, or chronyc command. This
was the behaviour of chronyd in versions before 4.0.
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
When chronyd has multiple sources available for synchronisation, it
has to select one source as the synchronisation source. The measured
offsets and frequencies of the system clock relative to the other
sources, however, can be combined with the selected source to
improve the accuracy of the system clock.
The combinelimit directive limits which sources are included in the
combining algorithm. Their 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
The maxdistance directive sets the maximum root distance of a source
to be acceptable for synchronisation of the clock. Sources that have
a distance larger than the specified distance will be rejected. The
distance estimates the maximum error of the source. It includes the
root dispersion and half of the root delay (round-trip time)
accumulated on the path to the primary source.
By default, the maximum root distance is 3 seconds.
Setting maxdistance to a larger value can be useful to allow
synchronisation with a server that only has a very infrequent
connection to its sources and can accumulate a large dispersion
between updates of its clock.
maxjitter jitter
The maxjitter directive sets the maximum allowed jitter of the
sources to not be rejected by the source selection algorithm. This
prevents synchronisation with sources that have a small root
distance, but their time is too variable.
By default, the maximum jitter is 1 second.
minsources sources
The minsources directive sets the minimum number of sources that
need to be considered as selectable in the source selection
algorithm before the local clock is updated. The default value is 1.
Setting this option to a larger number can be used to improve the
reliability. More sources will have to agree with each other and the
clock will not be updated when only one source (which could be
serving incorrect time) is reachable.
reselectdist distance
When chronyd selects a synchronisation source from available
sources, it will prefer the one with the shortest synchronisation
distance. However, to avoid frequent reselecting when there are
sources with similar distance, a fixed distance is added to the
distance for sources that are currently not selected. This can be
set with the reselectdist directive. By default, the distance is 100
microseconds.
stratumweight distance
The stratumweight directive sets how much distance should be added
per stratum to the synchronisation distance when chronyd selects the
synchronisation source from available sources.
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 clockprecision directive specifies the precision of the system
clock (in seconds). It is used by chronyd to estimate the minimum
noise in NTP measurements and randomise low-order bits of timestamps
in NTP responses. By default, the precision is measured on start as
the minimum time to read the clock.
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
When chronyd is slewing the system clock to correct an offset, the
rate at which it is slewing adds to the frequency error of the
clock. On all supported systems, with the exception of macOS 12 and
earlier, this rate can be controlled.
The corrtimeratio directive sets the ratio between the duration in
which the clock is slewed for an average correction according to the
source history and the interval in which the corrections are done
(usually the NTP polling interval). Corrections larger than the
average take less time and smaller corrections take more time, the
amount of the correction and the correction time are inversely
proportional.
Increasing corrtimeratio improves the overall frequency error of the
system clock, but increases the overall time error as the
corrections take longer.
By default, the ratio is set to 3, the time accuracy of the clock is
preferred over its frequency accuracy.
The 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
One of the main activities of the chronyd program is to work out the
rate at which the system clock gains or loses time relative to real
time.
Whenever chronyd computes a new value of the gain 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
Fallback drifts are long-term averages of the system clock drift
calculated over exponentially increasing intervals. They are used to
avoid quickly drifting away from true time when the clock was not
updated for a longer period of time and there was a short-term
deviation in the drift before the updates stopped.
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
A leap second is an adjustment that is occasionally applied to UTC
to keep it close to the mean solar time. When a leap second is
inserted, the last day of June or December has an extra second
23:59:60.
For computer clocks that is a problem. The Unix time is defined as
number of seconds since 00:00:00 UTC on 1 January 1970 without leap
seconds. The system clock cannot have time 23:59:60, every minute
has 60 seconds and every day has 86400 seconds by definition. The
inserted leap second is skipped and the clock is suddenly ahead of
UTC by one second. The leapsecmode directive selects how that error
is corrected. There are four options:
system
When inserting a leap second, the kernel steps the system clock
backwards by one second when the clock gets to 00:00:00 UTC.
When deleting a leap second, it steps forward by one second when
the clock gets to 23:59:59 UTC. This is the default mode when
the system driver supports leap seconds (i.e. all supported
systems with the exception of macOS 12 and earlier).
step
This is similar to the system mode, except the clock is stepped
by chronyd instead of the kernel. It can be useful to avoid bugs
in the kernel code that would be executed in the system mode.
This is the default mode when the system driver does not support
leap seconds.
slew
The clock is corrected by slewing started at 00:00:00 UTC when a
leap second is inserted or 23:59:59 UTC when a leap second is
deleted. This might be preferred over the system and step modes
when applications running on the system are sensitive to jumps
in the system time and it is acceptable that the clock will be
off for a longer time. On Linux with the default maxslewrate
value the correction takes 12 seconds.
ignore
No correction is applied to the clock for the leap second. The
clock will be corrected later in normal operation when new
measurements are made and the estimated offset includes the one
second error. This option is particularly useful when multiple
chronyd instances are running on the system, one controlling the
system clock and others started with the -x option, which should
rely on the first instance to correct the system clock and
ignore it for the correction of their own NTP clock running on
top of the system clock.
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
This directive specifies a timezone in the system timezone database
which chronyd can use to determine when will the next leap second
occur and what is the current offset between TAI and UTC. It will
periodically check if 23:59:59 and 23:59:60 are valid times in the
timezone. This normally works with the right/UTC 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
This directive specifies the path to a file containing a list of
leap seconds and TAI-UTC offsets in NIST/IERS format. It is
recommended to use the file leap-seconds.list usually included with
the system timezone database. The behaviour of this directive is
otherwise equivalent to leapsectz.
An example of this directive is:
leapseclist /usr/share/zoneinfo/leap-seconds.list
makestep threshold limit
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, e.g. when chronyd is initially started, the
system clock might 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 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
This directive sets the maximum offset to be accepted on a clock
update. The offset is measured relative to the current estimate of
the true time, which is different from the system time if a previous
slew did not finish.
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
The maxclockerror directive sets the maximum assumed frequency error
that the system clock can gain on its own between clock updates. It
describes the stability of the clock.
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
This directive specifies the maximum assumed drift (frequency error)
of the system clock. It limits the frequency adjustment that chronyd
is allowed to use to correct the measured drift. It is an additional
limit to the maximum adjustment that can be set by the system driver
(100000 ppm on Linux, 500 ppm on FreeBSD, NetBSD, and macOS 10.13+,
32500 ppm on illumos).
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
One of chronyd's tasks is to work out how fast or slow the
computer’s clock runs relative to its reference sources. In
addition, it computes an estimate of the error bounds around the
estimated value.
If the range of error is too large, it probably indicates that the
measurements have not settled down yet, and that the estimated gain
or loss rate is not very reliable.
The maxupdateskew 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
The maxslewrate directive sets the maximum rate at which chronyd is
allowed to slew the time. It limits the slew rate controlled by the
correction time ratio (which can be set by the corrtimeratio
directive) and is effective only on systems where chronyd is able to
control the rate (i.e. all supported systems with the exception of
macOS 12 or earlier).
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
Normally, changes in the rate of drift of the system clock are
caused mainly by changes in the temperature of the crystal
oscillator on the motherboard.
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 allow directive is used to designate a particular subnet from
which NTP clients are allowed to access the computer as an NTP
server. It also controls access of NTS-KE clients when NTS is
enabled on the server.
The default is that no clients are allowed access, i.e. chronyd
operates purely as an NTP client. If the allow directive is used,
chronyd will be both a client of its servers, and a server to other
clients.
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]
This is similar to the allow directive, except that it denies NTP
and NTS-KE client access to a particular subnet or host, rather than
allowing it.
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
The bindaddress directive binds the sockets on which chronyd listens
for NTP and NTS-KE requests to a local address of the computer. On
systems other than Linux, the address of the computer needs to be
already configured when chronyd is started.
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
The binddevice directive binds the NTP and NTS-KE server sockets to
a network device specified by the interface name. This directive can
specify only one interface and it is supported on Linux only.
An example of the directive is:
binddevice eth0
broadcast interval address [port]
The broadcast directive is used to declare a broadcast address to
which chronyd should send packets in the NTP broadcast mode (i.e.
make chronyd act as a broadcast server). Broadcast clients on that
subnet will be able to synchronise.
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
This directive specifies the maximum amount of memory that chronyd
is allowed to allocate for logging of client accesses and the state
that chronyd as an NTP server needs to support the interleaved mode
for its clients. The default limit is 524288 bytes, which enables
monitoring of up to 4096 IP addresses at the same time and holding
NTP timestamps for up to 4096 clients using the interleaved mode
(depending on uniformity of their polling interval). The number of
addresses and timestamps is always a power of 2. The maximum
effective value is 2147483648 (2 GB), which corresponds to 16777216
addresses and timestamps.
An example of the use of this directive is:
clientloglimit 1048576
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. This
option also effectively disables server support for the NTP
interleaved mode.
local [option]...
The local directive enables a local reference mode, which allows
chronyd operating as an NTP server to appear synchronised to real
time (from the viewpoint of clients polling it), even when it was
never synchronised or the last update of the clock happened a long
time ago.
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
This option sets the stratum of the server which will be
reported to clients when the local reference is active. The
specified value is in the range 1 through 15, and the default
value is 10. It should be larger than the maximum expected
stratum in the network when external NTP servers are accessible.
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
This option sets the threshold for the root distance which will
activate the local reference. If chronyd was synchronised to
some source, the local reference will not be activated until its
root distance reaches the specified value (the rate at which the
distance is increasing depends on how well the clock was
tracking the source). The default value is 1 second.
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
This option sets an activating root distance for the local
reference. The local reference will not be used until the root
distance drops below the configured value for the first time.
This can be used to prevent the local reference from being
activated on a server which has never been synchronised with an
upstream server. The default value of 0.0 causes no activating
distance to be used, such that the local reference is always
eligible for activation.
orphan
This option enables a special ‘orphan’ mode, where sources with
stratum equal to the local stratum are assumed to not serve real
time. They are ignored unless no other source is selectable and
their reference IDs are smaller than the local reference ID.
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
This directive specifies the location of the Samba ntp_signd socket
when it is running as a Domain Controller (DC). If chronyd is
compiled with this feature, responses to MS-SNTP clients will be
signed by the smbd daemon.
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
This directive specifies the TCP port on which chronyd will provide
the NTS Key Establishment (NTS-KE) service. The default port is
4460.
The port will be open only when a certificate and key is specified
by the ntsservercert and ntsserverkey directives.
ntsservercert file
This directive specifies a file containing a certificate in the PEM
format for chronyd to operate as an NTS server. The file should also
include any intermediate certificates that the clients will need to
validate the server’s certificate. The file needs to be readable by
the user under which chronyd is running after dropping root
privileges.
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 specifies a file containing a private key in the PEM
format for chronyd to operate as an NTS server. The file needs to be
readable by the user under which chronyd is running after dropping
root privileges. For security reasons, it should not be readable by
other users.
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
This directive specifies how many helper processes will chronyd
operating as an NTS server start for handling client NTS-KE requests
in order to improve performance with multi-core CPUs and
multithreading. If set to 0, no helper process will be started and
all NTS-KE requests will be handled by the main chronyd process. The
default value is 1.
maxntsconnections connections
This directive specifies the maximum number of concurrent NTS-KE
connections per process that the NTS server will accept. The default
value is 100. The maximum practical value is half of the system
FD_SETSIZE constant (usually 1024).
ntsaeads ID...
This directive specifies a list of IDs of Authenticated Encryption
with Associated Data (AEAD) algorithms enabled for NTS
authentication of NTP messages. chronyd as a server uses the first
enabled algorithm from the list provided by the client. Algorithms
that are not supported by the installed version of the crypto
library (Nettle, GnuTLS) are ignored.
The following IDs are supported:
• 15: AES-SIV-CMAC-256
• 30: AES-128-GCM-SIV
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
This directive specifies a directory where chronyd operating as an
NTS server can save the keys which encrypt NTS cookies provided to
clients. The keys are saved to a single file named ntskeys. When
chronyd is restarted, reloading the keys allows the clients to
continue using old cookies and avoids a storm of NTS-KE requests. By
default, the server does not save the keys.
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
This directive specifies the hostname (as a fully qualified domain
name) or address of the NTP server(s) which is provided in the
NTS-KE response to the clients. It allows the NTS-KE server to be
separated from the NTP server. However, the servers need to share
the keys, i.e. external key management needs to be enabled by
setting ntsrotate to 0. By default, no hostname or address is
provided to the clients, which means they should use the same server
for NTS-KE and NTP.
ntsrotate interval
This directive specifies the rotation interval (in seconds) of the
server key which encrypts the NTS cookies. New keys are generated
automatically from the /dev/urandom device. The server keeps two
previous keys to give the clients time to get new cookies encrypted
by the latest key. The interval is measured as the server’s
operating time, i.e. the actual interval can be longer if chronyd is
not running continuously. The default interval is 604800 seconds (1
week). The maximum value is 2^31-1 (68 years).
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
This option allows you to configure the port on which chronyd will
listen for NTP requests. The port will be open only when an address
is allowed by the allow directive or the allow command in chronyc,
an NTP peer is configured, or the broadcast server mode is enabled.
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]...
This directive enables response rate limiting for NTP packets. Its
purpose is to reduce network traffic with misconfigured or broken
NTP clients that are polling the server too frequently. The limits
are applied to individual IP addresses. If multiple clients share
one IP address (e.g. multiple hosts behind NAT), the sum of their
traffic will be limited. If a client that increases its polling rate
when it does not receive a reply is detected, its rate limiting will
be temporarily suspended to avoid increasing the overall amount of
traffic. The maximum number of IP addresses which can be monitored
at the same time depends on the memory limit set by the
clientloglimit directive.
The ratelimit directive supports a number of options (which can be
defined in any order):
interval interval
This option sets the minimum interval between responses. It is
defined as a power of 2 in seconds. The default value is 3 (8
seconds). The minimum value is -19 (524288 packets per second)
and the maximum value is 12 (one packet per 4096 seconds). Note
that with values below -4 the rate limiting is coarse (responses
are allowed in bursts, even if the interval between them is
shorter than the specified interval).
burst responses
This option sets the maximum number of responses that can be
sent in a burst, temporarily exceeding the limit specified by
the interval option. This is useful for clients that make rapid
measurements on start (e.g. chronyd with the iburst option). The
default value is 8. The minimum value is 1 and the maximum value
is 255.
leak rate
This option sets the rate at which responses are randomly
allowed even if the limits specified by the interval and burst
options are exceeded. This is necessary to prevent an attacker
who is sending requests with a spoofed source address from
completely blocking responses to that address. The leak rate is
defined as a power of 1/2 and it is 2 by default, i.e. on
average at least every fourth request has a response. The
minimum value is 1 and the maximum value is 4.
kod rate
This option sets the rate at which Kiss-o'-Death (KoD) RATE
responses are randomly sent when the limits specified by the
interval and burst options are exceeded. It is an additional
stream of responses to the leak option. A KoD RATE response is a
request for the client to reduce its polling rate. Few
implementations actually support it. The rate is defined as a
power of 1/2. The default value is 0, which means disabled. The
minimum value is 0 and the maximum value is 4.
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]...
This directive enables rate limiting of NTS-KE requests. It is
similar to the ratelimit directive, except the default interval is 6
(1 connection per 64 seconds) and the kod option is not supported.
An example of the use of the directive is:
ntsratelimit interval 3 burst 1
smoothtime max-freq max-wander [leaponly]
The smoothtime directive can be used to enable smoothing of the time
that chronyd serves to its clients to make it easier for them to
track it and keep their clocks close together even when large offset
or frequency corrections are applied to the server’s clock, for
example after being offline for a longer time.
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
The bindcmdaddress directive specifies a local IP address to which
chronyd will bind the UDP socket listening for monitoring command
packets (issued by chronyc). On systems other than Linux, the
address of the interface needs to be already configured when chronyd
is started.
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
The bindcmddevice directive binds the UDP command sockets to a
network device specified by the interface name. This directive can
specify only one interface and it is supported on Linux only.
An example of the directive is:
bindcmddevice eth0
cmdallow [all] [subnet]
This is similar to the allow directive, except that it allows
monitoring access (rather than NTP client access) to a particular
subnet or host. (By ‘monitoring access’ is meant that chronyc can be
run on those hosts and retrieve monitoring data from chronyd on this
computer.)
The syntax is identical to the allow directive.
There is also a cmdallow all directive with similar behaviour to the
allow all directive (but applying to monitoring access in this case,
of course).
Note that chronyd has to be configured with the bindcmdaddress
directive to not listen only on the loopback interface to actually
allow remote access.
cmddeny [all] [subnet]
This is similar to the cmdallow directive, except that it denies
monitoring access to a particular subnet or host, rather than
allowing it.
The syntax is identical.
There is also a cmddeny all directive with similar behaviour to the
cmdallow all directive.
cmdport port
The cmdport directive allows the port that is used for run-time
monitoring (via the chronyc program) to be altered from its default
(323). If set to 0, chronyd will not open the port, which disables
remote chronyc access (with a non-default bindcmdaddress) and local
access for unprivileged users. It does not disable the Unix domain
command socket.
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]...
This directive enables response rate limiting for command packets.
It is similar to the ratelimit directive, except responses to
localhost are never limited, the default interval is -4 (16 packets
per second), and the kod option is not supported.
An example of the use of the directive is:
cmdratelimit interval 2
Real-time clock (RTC)
hwclockfile file
The hwclockfile directive sets the location of the adjtime file
which is used by the hwclock program on Linux. chronyd parses the
file to find out if the RTC keeps local time or UTC. It overrides
the rtconutc directive.
The compiled-in default value is '/etc/adjtime'.
An example of the directive is:
hwclockfile /etc/adjtime
rtcautotrim threshold
The rtcautotrim directive is used to keep the RTC close to the
system clock automatically. When the system clock is synchronised
and the estimated error between the two clocks is larger than the
specified threshold, chronyd will trim the RTC as if the trimrtc
command in chronyc was issued. The trimming operation is accurate to
only about 1 second, which is the minimum effective 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
The rtcdevice directive sets the path to the device file for
accessing the RTC. The default path is /dev/rtc.
rtcfile file
The rtcfile directive defines the name of the file in which chronyd
can save parameters associated with tracking the accuracy of the
RTC.
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:
1. You are running Linux.
2. The kernel is compiled with extended real-time clock support
(i.e. the /dev/rtc device is capable of doing useful things).
3. You do not have other applications that need to make use of
/dev/rtc at all.
rtconutc
chronyd assumes by default that the RTC keeps local time (including
any daylight saving changes). This is convenient on PCs running
Linux which are dual-booted with Windows.
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
The rtcsync directive enables a mode where the system time is
periodically copied to the RTC and chronyd does not try to track its
drift. This directive cannot be used with the rtcfile directive.
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]...
The log directive indicates that certain information is to be
logged. The log files are written to the directory specified by the
logdir directive. A banner is periodically written to the files to
indicate the meanings of the columns.
rawmeasurements
This option logs the raw NTP measurements and related
information to a file called measurements.log. An entry is made
for each packet received from the source. This can be useful
when debugging a problem. An example line (which actually
appears as a single line in the file) from the log file is shown
below.
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):
1. Date [2015-10-13]
2. Hour:Minute:Second. Note that the date-time pair is
expressed in UTC, not the local time zone. [05:40:50]
3. IP address of server or peer from which measurement came
[203.0.113.15]
4. Leap status (N means normal, + means that the last minute of
the current month has 61 seconds, - means that the last
minute of the month has 59 seconds, ? means the remote
computer is not currently synchronised.) [N]
5. Stratum of remote computer. [2]
6. RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111]
7. RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111]
8. Results of the maxdelay, maxdelayratio, and maxdelaydevratio
(or maxdelayquant) tests, and a test for synchronisation
loop (1=pass, 0=fail). The first test from these four also
checks the server precision, response time, validity of the
measured offset, and whether an interleaved response is
acceptable for synchronisation. [1111]
9. Local poll [10]
10. Remote poll [10]
11. ‘Score’ (an internal score within each polling level used
to decide when to increase or decrease the polling level.
This is adjusted based on number of measurements currently
being used for the regression algorithm). [1.0]
12. The estimated local clock error (theta in RFC 5905).
Positive indicates that the local clock is slow of the
remote source. [-4.966e-03]
13. The peer delay (delta in RFC 5905). [2.296e-01]
14. The peer dispersion (epsilon in RFC 5905). [1.577e-05]
15. The root delay (DELTA in RFC 5905). [1.615e-01]
16. The root dispersion (EPSILON in RFC 5905). [7.446e-03]
17. Reference ID of the server’s source as a hexadecimal
number. [CB00717B]
18. NTP mode of the received packet (1=active peer, 2=passive
peer, 4=server, B=basic, I=interleaved). [4B]
19. Source of the local transmit timestamp (D=daemon, K=kernel,
H=hardware). [D]
20. Source of the local receive timestamp (D=daemon, K=kernel,
H=hardware). [K]
measurements
This option is identical to the rawmeasurements option, except
it logs only valid measurements from synchronised sources, i.e.
measurements which passed the RFC 5905 tests 1 through 7. This
can be useful for producing graphs of the source’s performance.
statistics
This option logs information about the regression processing to
a file called statistics.log. An example line (which actually
appears as a single line in the file) from the log file is shown
below.
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):
1. Date [2015-07-22]
2. Hour:Minute:Second. Note that the date-time pair is
expressed in UTC, not the local time zone. [05:40:50]
3. IP address of server or peer from which measurement comes
[203.0.113.15]
4. The estimated standard deviation of the measurements from
the source (in seconds). [6.261e-03]
5. The estimated offset of the source (in seconds, positive
means the local clock is estimated to be fast, in this
case). [-3.247e-03]
6. The estimated standard deviation of the offset estimate (in
seconds). [2.220e-03]
7. The estimated rate at which the local clock is gaining or
losing time relative to the source (in seconds per second,
positive means the local clock is gaining). This is relative
to the compensation currently being applied to the local
clock, not to the local clock without any compensation.
[1.874e-06]
8. The estimated error in the rate value (in seconds per
second). [1.080e-06].
9. The ratio of |old_rate - new_rate| / old_rate_error. Large
values indicate the statistics are not modelling the source
very well. [7.8e-02]
10. The number of measurements currently being used for the
regression algorithm. [16]
11. The new starting index (the oldest sample has index 0; this
is the method used to prune old samples when it no longer
looks like the measurements fit a linear model). [0, i.e. no
samples discarded this time]
12. The number of runs. The number of runs of regression
residuals with the same sign is computed. If this is too
small it indicates that the measurements are no longer
represented well by a linear model and that some older
samples need to be discarded. The number of runs for the
data that is being retained is tabulated. Values of
approximately half the number of samples are expected. [8]
13. The estimated or configured asymmetry of network jitter on
the path to the source which was used to correct the
measured offsets. The asymmetry can be between -0.5 and
+0.5. A negative value means the delay of packets sent to
the source is more variable than the delay of packets sent
from the source back. [0.00, i.e. no correction for
asymmetry]
selection
This option logs information about selection of sources for
synchronisation to a file called selection.log. Note that the
rate of entries written to this file grows quadratically with
the number of specified sources (each measurement triggers the
selection for all sources). An example line (which actually
appears as a single line in the file) from the log file is shown
below.
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):
1. Date [2022-05-01]
2. Hour:Minute:Second. Note that the date-time pair is
expressed in UTC, not the local time zone. [02:01:20]
3. IP address or reference ID of the source. [203.0.113.15]
4. State of the source indicated with one of the following
symbols. [*]
Not considered selectable for synchronisation:
• N - has the noselect option.
• s - is not synchronised.
• M - does not have enough measurements.
• d - has a root distance larger than the maximum
distance (configured by the maxdistance directive).
• ~ - has a jitter larger than the maximum jitter
(configured by the maxjitter directive).
• w - waits for other sources to get out of the M
state.
• S - has older measurements than other sources.
• O - has a stratum equal or larger than the orphan
stratum (configured by the local directive).
• T - does not fully agree with sources that have the
trust option.
• x - does not agree with other sources (falseticker).
Considered selectable for synchronisation, but not
currently used:
• W - waits for other sources to be selectable
(required by the minsources directive, or the
require option of another source).
• P - another selectable source is preferred due to
the prefer option.
• U - waits for a new measurement (after selecting a
different best source).
• D - has, or recently had, a root distance which is
too large to be combined with other sources
(configured by the combinelimit directive).
Used for synchronisation of the local clock:
• + - combined with the best source.
• * - selected as the best source to update the
reference data (e.g. root delay, root dispersion).
5. Current effective selection options of the source. which can
be different from the configured options due to the
authentication selection mode (configured by the
authselectmode directive). [-----]
• N indicates the noselect option.
• P indicates the prefer option.
• T indicates the trust option.
• R indicates the require option.
6. Reachability 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 from the last eight
transmissions. [377]
7. Current score against the source in the * state. The scoring
system avoids frequent reselection when multiple sources
have a similar root distance. A value larger than 1
indicates this source was better than the * source in recent
selections. If the score reaches 10, the best source will be
reselected and the scores will be reset to 1. [1.00]
8. Interval since the last measurement of the source in
seconds. [4.228e+01]
9. Lower endpoint of the interval which was expected to contain
the true offset of the local clock determined by the root
distance of the source. [-1.575e-04]
10. Upper endpoint of the interval which was expected to
contain the true offset of the local clock determined by the
root distance of the source. [1.239e-04]
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. An
example line (which actually appears as a single line in the
file) from the log file is shown below.
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) :
1. Date [2017-08-22]
2. Hour:Minute:Second. Note that the date-time pair is
expressed in UTC, not the local time zone. [13:22:36]
3. The IP address of the server or peer to which the local
system is synchronised. [203.0.113.15]
4. The stratum of the local system. [2]
5. The local system frequency (in ppm, positive means the local
system runs fast of UTC). [-3.541]
6. The error bounds on the frequency (in ppm). [0.075]
7. The estimated local offset at the epoch, which is normally
corrected by slewing the local clock (in seconds, positive
indicates the clock is fast of UTC). [-8.621e-06]
8. Leap status (N means normal, + means that the last minute of
this month has 61 seconds, - means that the last minute of
the month has 59 seconds, ? means the clock is not currently
synchronised.) [N]
9. The number of combined sources. [2]
10. The estimated standard deviation of the combined offset (in
seconds). [2.940e-03]
11. The remaining offset correction from the previous update
(in seconds, positive means the system clock is slow of
UTC). [-2.084e-04]
12. The total of the network path delays to the reference clock
to which the local clock is ultimately synchronised (in
seconds). [1.534e-02]
13. The total dispersion accumulated through all the servers
back to the reference clock to which the local clock is
ultimately synchronised (in seconds). [3.472e-04]
14. The maximum estimated error of the system clock in the
interval since the previous update (in seconds). It includes
the offset, remaining offset correction, root delay, and
dispersion from the previous update with the dispersion
which accumulated in the interval. [8.304e-03]
rtc
This option logs information about the system’s real-time clock.
An example line (which actually appears as a single line in the
file) from the rtc.log file is shown below.
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):
1. Date [2015-07-22]
2. Hour:Minute:Second. Note that the date-time pair is
expressed in UTC, not the local time zone. [05:40:50]
3. The measured offset between the RTC and the system clock in
seconds. Positive indicates that the RTC is fast of the
system time [-0.037360].
4. Flag indicating whether the regression has produced valid
coefficients. (1 for yes, 0 for no). [1]
5. Offset at the current time predicted by the regression
process. A large difference between this value and the
measured offset tends to indicate that the measurement is an
outlier with a serious measurement error. [-0.037434]
6. The rate at which the RTC is losing or gaining time relative
to the system clock. In ppm, with positive indicating that
the RTC is gaining time. [-37.948]
7. The number of measurements used in the regression. [12]
8. The number of runs of regression residuals of the same sign.
Low values indicate that a straight line is no longer a good
model of the measured data and that older measurements
should be discarded. [5]
9. The measurement interval used prior to the measurement being
made (in seconds). [120]
refclocks
This option logs the raw and filtered reference clock
measurements to a file called refclocks.log. An example line
(which actually appears as a single line in the file) from the
log file is shown below.
2009-11-30 14:33:27.000000 PPS2 7 N 1 4.900000e-07 -6.741777e-07 1.000e-06
The columns are as follows (the quantities in square brackets
are the values from the example line above):
1. Date [2009-11-30]
2. Hour:Minute:Second.Microsecond. Note that the date-time pair
is expressed in UTC, not the local time zone.
[14:33:27.000000]
3. Reference ID of the reference clock from which the
measurement came. [PPS2]
4. Sequence number of driver poll within one polling interval
for raw samples, or - for filtered samples. [7]
5. Leap status (N means normal, + means that the last minute of
the current month has 61 seconds, - means that the last
minute of the month has 59 seconds). [N]
6. Flag indicating whether the sample comes from PPS source. (1
for yes, 0 for no, or - for filtered sample). [1]
7. Local clock error measured by reference clock driver, or -
for filtered sample. [4.900000e-07]
8. Local clock error with applied corrections. Positive
indicates that the local clock is slow. [-6.741777e-07]
9. Assumed dispersion of the sample. [1.000e-06]
tempcomp
This option logs the temperature measurements and system rate
compensations to a file called tempcomp.log. An example line
(which actually appears as a single line in the file) from the
log file is shown below.
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):
1. Date [2015-04-19]
2. Hour:Minute:Second. Note that the date-time pair is
expressed in UTC, not the local time zone. [10:39:48]
3. Temperature read from the sensor. [2.8000e+04]
4. Applied compensation in ppm, positive means the system clock
is running faster than it would be without the compensation.
[3.6600e-01]
An example of the directive is:
log measurements statistics tracking
logbanner entries
A banner is periodically written to the log files enabled by the log
directive to indicate the meanings of the columns.
The logbanner directive specifies after how many entries in the log
file should be the banner written. The default is 32, and 0 can be
used to disable it entirely.
logchange threshold
This directive sets the threshold for the adjustment of the system
clock that will generate a syslog message. Clock errors detected via
NTP packets, reference clocks, or timestamps entered via the settime
command of chronyc are logged.
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
This directive specifies the directory for writing log files enabled
by the log directive. If the directory does not exist, it will be
created automatically.
An example of the use of this directive is:
logdir /var/log/chrony
mailonchange email threshold
This directive defines an email address to which mail should be sent
if chronyd applies a correction exceeding a particular threshold to
the system clock.
An example of 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...
The confdir directive includes configuration files with the .conf
suffix from a directory. The files are included in the
lexicographical order of the file names.
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...
The sourcedir directive is identical to the confdir directive,
except the configuration files have the .sources suffix, they can
only specify NTP sources (i.e. the server, pool, and peer
directives), they are expected to have all lines terminated by the
newline character, and they can be reloaded by the reload sources
command in chronyc. It is particularly useful with dynamic sources
like NTP servers received from a DHCP server, which can be written
to a file specific to the network interface by a networking script.
This directive can be used multiple times.
An example of the directive is:
sourcedir /var/run/chrony-dhcp
include pattern
The include directive includes a configuration file, or multiple
configuration files if a wildcard pattern is specified. Unlike with
the confdir directive, the full name of the files needs to be
specified and at least one file is required to exist.
This directive can be used multiple times.
An example of the directive is:
include /etc/chrony/chrony.d/*.conf
hwtimestamp interface [option]...
This directive enables hardware timestamping of NTP packets sent to
and received from the specified network interface. The network
interface controller (NIC) uses its own clock to accurately
timestamp the actual transmissions and receptions, avoiding
processing and queueing delays in the kernel, network driver, and
hardware. This can significantly improve the accuracy of the
timestamps and the measured offset, which is used for
synchronisation of the system clock. In order to get the best
results, both sides receiving and sending NTP packets (i.e. server
and client, or two peers) need to use HW timestamping. If the server
or peer supports the interleaved mode, it needs to be enabled by the
xleave option in the server or the peer directive.
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
This option specifies the minimum interval between readings of
the NIC clock. It’s defined as a power of 2. It should
correspond to the minimum polling interval of all NTP sources
and the minimum expected polling interval of NTP clients. The
default value is 0 (1 second), the minimum value is -6 (1/64th
of a second), and the maximum value is 20 (about 12 days).
maxpoll poll
This option specifies the maximum interval between readings of
the NIC clock, as a power of 2. The default value is minpoll +
1, i.e. 1 (2 seconds) with the default minpoll of 0. The minimum
and maximum values are the same as with the minpoll option.
minsamples samples
This option specifies the minimum number of readings kept for
tracking of the NIC clock. The default value is 2.
maxsamples samples
This option specifies the maximum number of readings kept for
tracking of the NIC clock. The default value is 16.
precision precision
This option specifies the assumed precision of reading of the
NIC clock. The default value is 100e-9 (100 nanoseconds).
txcomp compensation
This option specifies the difference in seconds between the
actual transmission time at the physical layer and the reported
transmit timestamp. This value will be added to transmit
timestamps obtained from the NIC. The default value is 0.
rxcomp compensation
This option specifies the difference in seconds between the
reported receive timestamp and the actual reception time at the
physical layer. This value will be subtracted from receive
timestamps obtained from the NIC. The default value is 0.
nocrossts
Some hardware can precisely cross timestamp the NIC clock with
the system clock. This option disables the use of the cross
timestamping.
rxfilter filter
This option selects the receive timestamping filter. The filter
can be one of the following:
all
Enables timestamping of all received packets.
ntp
Enables timestamping of received NTP packets.
ptp
Enables timestamping of received PTP packets.
none
Disables timestamping of received packets.
The most specific filter for timestamping of NTP packets
supported by the NIC is selected by default. Some NICs can
timestamp PTP packets only. By default, they will be configured
with the none filter and expected to provide hardware timestamps
for transmitted packets only. Timestamping of PTP packets is
useful with NTP-over-PTP enabled by the ptpport directive, or
when another application is receiving PTP packets on the
interface. Forcing timestamping of all packets with the all
filter could be useful if the NIC supported both the all and ntp
filters, and it should timestamp both NTP and PTP packets, or
NTP packets on a different UDP port.
Examples of the directive are:
hwtimestamp eth0
hwtimestamp eth1 txcomp 300e-9 rxcomp 645e-9
hwtimestamp *
hwtstimeout timeout
If hardware timestamping is used with a close NTP server, or the NIC
or its driver is slow in providing the transmit timestamp of NTP
requests, a response from the server can be received before the
transmit timestamp of the request. To avoid calculating the offset
with a less accurate transmit timestamp, chronyd can save the
response for later processing and wait for the hardware transmit
timestamp. There is no guarantee that the timestamp will be provided
(NICs typically have a limited rate of transmit timestamping). This
directive configures how long should chronyd wait for the timestamp
after receiving a valid response from the server. If a second valid
response is received from the server while waiting for the
timestamp, they will be both processed immediately.
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
This directive is used to specify the location of the file
containing symmetric keys which are shared between NTP servers and
clients, or peers, in order to authenticate NTP packets with a
message authentication code (MAC) using a cryptographic hash
function or cipher.
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
The lock_all directive will lock the chronyd process into RAM so
that it will never be paged out. This can result in lower and more
consistent latency. The directive is supported on Linux, FreeBSD,
NetBSD, and illumos.
pidfile file
Unless chronyd is started with the -Q option, it writes its process
ID (PID) to a file, and checks this file on startup to see if
another chronyd might already be running on the system. By default,
the file used is /run/chrony/chronyd.pid. The pidfile directive
allows the name to be changed, e.g.:
pidfile /run/chronyd.pid
Setting this directive to / disables writing and checking of the PID
file.
ptpport port
The ptpport directive enables chronyd to send and receive NTP
messages contained in PTP event messages (NTP-over-PTP) to enable
hardware timestamping on NICs which cannot timestamp NTP packets,
but can timestamp unicast PTP packets, and also use corrections
provided by PTP one-step end-to-end transparent clocks in network
switches and routers. The port recognized by the NICs and PTP
transparent clocks is 319 (PTP event port). The default value is 0
(disabled).
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
The ptpdomain directive sets the PTP domain number of transmitted
and accepted NTP-over-PTP messages. Messages from other domains are
ignored. The default is 123, the minimum is 0, and the maximum is
255.
sched_priority priority
On Linux, FreeBSD, NetBSD, and illumos, the sched_priority directive
will select the SCHED_FIFO real-time scheduler at the specified
priority (which must be between 0 and 100). On macOS, this option
must have either a value of 0 (the default) to disable the thread
time constraint policy or 1 for the policy to be enabled.
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
The user directive sets the name of the system user to which chronyd
will switch after start in order to drop root privileges.
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:
• Your institution might already operate servers on its network.
Contact your system administrator to find out.
• Your ISP probably has one or more NTP servers available for its
customers.
• Somewhere under the NTP homepage there is a list of public stratum 1
and stratum 2 servers. You should find one or more servers that are
near to you. Check that their access policy allows you to use their
facilities.
• Use public servers from the pool.ntp.org <https://www.pool.ntp.org/>
project.
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
chronyc(1), chronyd(8)
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.
chrony 4.6.1 2024-10-08 CHRONY.CONF(5)
Generated by dwww version 1.16 on Tue Dec 16 07:18:41 CET 2025.