CHRONY.CONF(5)

📦

version 4.9 · 14 versions

4.9 · centos-stream 10, centos-stream 9, fedora 44 (latest)
4.8 · nixos 26.05
4.9 · nixpkgs unstable
4.6.1 · alpine 3.22
4.8 · alpine 3.23
4.8 · alpine 3.24
4.9 · arch rolling
4.2 · ubuntu jammy
4.8 · fedora 43, fedora 44, opensuse-leap 16.0
4.3 · debian bookworm
4.5 · ubuntu noble
4.8 · ubuntu resolute, ubuntu stonking
4.6.1 · debian trixie
4.7 · ubuntu questing

, in centos-stream 10, centos-stream 9, fedora 44

✨ NAME ✨

chrony.conf — literally the configuration file for the chronyd daemon. that's the whole name bestie, short and iconic 💖

🦋 SYNOPSIS 🦋

chrony.conf

💅 DESCRIPTION 💅

okay so. this file? this file is where you configure the chronyd daemon. the compiled-in location is /etc/chrony.conf, but you can point it somewhere else on the chronyd command line with the -f option. flex, honestly ✨

every directive in the config file lives on its own separate line. the sections below walk through each directive one at a time. and here's the tea: the directives are not case-sensitive. generally they can show up in any order in the file, and if you specify the same directive multiple times, only the last one will be effective — the earlier ones get ghosted 👻. any exceptions to that get called out in the descriptions, so keep reading, no skipping.

you can also drop configuration directives directly on the chronyd command line. when you do that, each argument gets parsed as a new line, and the configuration file is ignored entirely. like, completely. don't come for me when your file does nothing, you told it to sit this one out 💀

now, the number of supported directives is large, but lowkey only a few of them are typically needed. check the EXAMPLES section for configs in typical operating scenarios 🫶

oh and also — the config file might contain comment lines. a comment line is any line that starts with zero or more spaces followed by any one of these characters: !, ;, #, %. any line in that format will be ignored. so go ahead and annotate your life, she won't read it 🌸

👑 DIRECTIVES 👑

🌸 Time sources 🌸

server hostname [option]... — this directive says "here's an NTP server, she's a time source bestie" ⏰

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. it's giving one-way street, no cap 🚫

you can specify the server by its hostname or IP address. if the hostname can't 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 the last 8 requests), unsynchronised, a falseticker (i.e. does not agree with a majority of other sources), the root distance is too large (the limit can be configured by the maxdistance directive), or the stratum is too small or too large (the limits can be configured by the minstratum and maxstratum directives). the automatic replacement happens at most once per 30 minutes and only one server can be replaced at a time. the address is also refreshed periodically when the server is working normally (the interval can be configured by the refresh directive).

this directive can be used multiple times to specify multiple servers. each server must have a different IP address to be usable by chronyd. if a server is specified by a hostname that resolves only to addresses already used by other servers, the server will be treated as having an unknown address (e.g. reported by the chronyc activity command). awkward 💀

this directive supports the following options:

minpoll poll — sets the minimum interval between requests sent to the server, as a power of 2 in seconds. for example, minpoll 5 would mean 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. don't be that girl. 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 — sets the maximum interval between requests sent to the server, as a power of 2 in seconds. for example, maxpoll 9 indicates 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 so the first update of the clock happens sooner. she's impatient, we respect it. 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. math is mathing 📐
key ID — the NTP protocol supports a message authentication code (MAC) to prevent computers from having their system time upset by rogue packets being sent to them. rude. 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) chronyd should 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. it's giving situationship that never launches 💔

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. she's secure AND low-maintenance, we love 🎀

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 — 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 🛡️
maxntsretry interval — when the NTS-KE server used with the nts option is not responding, or providing acceptable cookies, chronyd will increase the interval between the attempts exponentially to avoid overloading the NTS-KE server. this option specifies the maximum interval as a power of 2 in seconds. the default is 19 (6 days), the minimum is 6 (64 seconds), and maximum 24 (6 months) ⏳
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. beyond a certain level of delay, however, 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. we've all been there, bestie 📶)

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 — okay so this one pins down a fixed minimum round-trip delay instead of letting chronyd use the smallest value it's seen in the previous measurements. Why would you want that? Bestie, in networks with static configuration it's lowkey a glow-up for stability — it helps with corrections for asymmetric jitter, the weighting of measurements, and the maxdelayratio and maxdelaydevratio tests. But you have to set the value accurately for it to actually have a positive effect on the synchronisation. No cap. 💅
asymmetry ratio — this sets the asymmetry of the network jitter on the path to the source, and it's used to correct the measured offset according to the delay. The ratio can be anywhere 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 just estimates the asymmetry automatically, main character energy, it handles it. ✨
offset offset — a correction (in seconds) applied to offsets measured with this source. Super useful for compensating 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 — sets the minimum number of samples kept for this source, and it overrides the minsamples directive. 💖
maxsamples samples — same vibe, opposite direction: sets the maximum number of samples kept for this source, and it overrides the maxsamples directive. 💖
maxunreach polls — the maximum number of polls this source can stay selected for synchronisation while it's unreachable (i.e. no valid response was received to the last 8 requests). Important bit: only sources with at least one sample more recent than the oldest sample of all reachable sources can be selected. The default is 100000. 😭
filter polls — turns on a median filter to reduce noise in NTP measurements. The filter takes the samples collected over the specified number of polls and smooshes them into a single sample. It's intended for very short polling intervals in local networks, where generating a lot of NTP traffic is just fine. 🔥
offline — if the server won't be reachable when chronyd starts, use this. chronyd will not try to poll the server until it's enabled to do so, by using the online command in chronyc. 🦋
auto_offline — with this one, the server is assumed to have gone offline when sending a request fails, e.g. because there's no route to the network. This saves you from having to run the offline command from chronyc when you unplug the network link. (You'll still need the online command once the link is established, so measurements can actually start.) 🙈
prefer — prefer this source over other selectable sources that don't have the prefer option. 💅
noselect — never select this source. Especially handy for monitoring. 👑
trust — assume time from this source is always true. It can only be rejected as a falseticker in the source selection if another source with this option doesn't agree with it. ✨
require — require that at least one of the sources specified with this option is selectable (i.e. recently reachable and not a falseticker) before updating the clock. Combined with the trust option, this can be useful to safely combine a trusted authenticated source with unauthenticated sources to improve the accuracy of the clock. Those sources can be selected and used for synchronisation only if they agree with the trusted and required source. 🫶
xleave — enables the interleaved mode of NTP (RFC 9769). It lets the server respond with more accurate transmit timestamps (e.g. kernel or hardware timestamps), which literally cannot fit inside the transmitted packet itself and have to refer to a previous packet instead. This can significantly improve the accuracy and stability of the measurements. 🌈

Interleaved mode is compatible with servers that only support the basic mode. Note that even servers that do support interleaved mode might respond in basic mode, because interleaved mode requires the servers to keep some state for each client — and that state might get 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). 💀

You can combine xleave with the presend option to shorten the interval in which the server has to keep the state to be able to respond in interleaved mode. ✨

polltarget target — the 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 — lets you specify the UDP port on which the server understands NTP requests. For normal servers you shouldn't need this (the default is 123, the standard NTP port). 🧚
ntsport port — 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 — okay so picture this: if the timing measurements chronyd is making are the only network data passing between two computers, some measurements might come out badly skewed because either the client or the server had to do an ARP lookup on the other party before 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. 😭

To dodge that whole situation, use the presend option. It takes a single integer argument: the smallest polling interval for which an extra pair of NTP packets will be exchanged between client and server prior to the actual measurement. For example, with this option in a server directive:

    presend 9

When the polling interval is 512 seconds or more, an extra NTP client packet gets sent to the server a short time (2 seconds) before the actual measurement is made. 🦋

And if presend is used together with the xleave option, chronyd will send two extra packets instead of one. 💅

minstratum stratum — when the synchronisation source is picked from the available sources, sources with lower stratum are normally slightly preferred. This option bumps the stratum of the source up to the specified minimum, so chronyd will avoid selecting that source. Useful with low-stratum sources that are known to be unreliable or inaccurate and that should only be used when other sources are unreachable. Note that the minstratum directive is distinct from this option. ⭐
version version — sets the NTP version of packets sent to the server. Handy when the server runs an old NTP implementation that doesn't 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 aren't used and the key option specifies a key using a hash function with an 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 — specifies that the server and client are closely related, their configuration doesn't allow a synchronisation loop to form between them, and the client is allowed to assume the reference ID and stratum of the server. 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 — enables an NTPv4 extension field specified by its type as a hexadecimal number. It'll 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:

10A — the Network Correction extension field, enabling the use of the Precision Time Protocol (PTP) corrections in NTP-over-PTP messages updated by one-step end-to-end transparent clocks (e.g. network switches). It can significantly improve the accuracy and stability of the synchronisation. NTP over PTP needs to be enabled by the ptpport directive and by setting the port option to the PTP port. The corrections are applied only to NTP measurements with HW timestamps (enabled by the hwtimestamp directive). 🌸

F323 — an experimental extension field that turns on a bunch of upgrades that were floated for the next version of NTP (aka NTPv5). What's inside? Root delay and dispersion at way higher resolution, plus a monotonic receive timestamp — and that timestamp is the moment bestie, because it lets a frequency transfer happen between server and client and that significantly levels up how stable the synchronisation is. 💅 Only turn this one on for servers you know are running chronyd version 4.2 or later, okay? No guessing.
ipv4, ipv6 — these two force chronyd to use only IPv4 or only IPv6 addresses respectively for this source. And heads up: they do not override the -4 or -6 option on the chronyd command line. Those win. 🫶

🌊 `pool` 🌊

pool name [option]...

Okay so the syntax here is basically server's twin, except instead of one single NTP server you're naming a whole pool of them. The pool name is expected to resolve to multiple addresses — and those addresses can literally change over time. It's giving ✨dynamic✨.

You can use this directive as many times as you want to specify multiple pools. Stack 'em.

Every option that works in server works here too. But there's exactly one option that's pool-exclusive:

maxsources sources — sets the number of sources you actually want to be using out of the pool. chronyd will keep trying to resolve that name over and over until it gets this many sources responding to requests. Default is 4, and the maximum is 16. 🔥

Wanna see it in the wild? Here's an example of the pool directive:

pool pool.ntp.org iburst maxsources 3

🤝 `peer` 🤝

peer hostname [option]...

Syntax is identical to server, but the vibe is different: this one specifies a symmetric association with an NTP peer instead of a client/server association with an NTP server. One symmetric association means both peers get to be servers and clients to each other at the same time. Mutual. Reciprocal. It's giving healthy relationship. 💖

It's mainly useful when the peer's NTP implementation (think ntpd) supports ephemeral symmetric associations and doesn't need to be configured with this host's address. And no — chronyd itself does not support ephemeral associations. Not a thing.

You can use this directive multiple times to specify multiple peers.

Now, the part where some options just don't show up to the party. These options of the server directive do not work in peer: iburst, burst, nts, presend, copy.

When you're using the xleave option, both peers must support and have enabled the interleaved mode — otherwise the synchronisation will only work in one direction. One-way street energy, not the move. And when a key is specified by the key option to enable authentication, both peers must use the same key and the same key number. 🗝️

⚠️ Big serious moment: symmetric mode is less secure than client/server mode. A denial-of-service attack is possible on unauthenticated symmetric associations — that means when the peer was specified without the key option. An attacker who doesn't see the network traffic between two hosts but knows they're peering with each other can periodically send them unauthenticated packets with spoofed source addresses to disrupt their NTP state and stop them from synchronising to each other. And when the association is authenticated, an attacker who does see the network traffic but can't stop the packets from reaching the other host can still wreck the state by replaying old packets. That attacker effectively has the same power as a man-in-the-middle attacker. 😭 chronyd has a partial protection against this implemented in it, which can protect the peers if they're using the same polling interval and never sent an authenticated packet with a timestamp from the future — but do not rely on it, because it's difficult to make sure those conditions are actually met. If two hosts should be able to sync to each other in both directions, the recommendation is to use two separate client/server associations instead (specified by the server directive on both hosts). Periodt.

🚀 `initstepslew` 🚀

initstepslew step-threshold [hostname]...

📢 This directive is deprecated in favour of the makestep directive. Still here, still working, but bestie… it's legacy.

So what's the whole point of initstepslew? It lets chronyd make a rapid measurement of the system clock error at boot time and correct the system clock by stepping before normal operation begins. And because this would normally happen only at an appropriate point in the system boot sequence, no other software should get messed up by the step. 🎀

If the correction needed is less than a specified threshold, a slew is used instead. That makes it way safer to restart chronyd while the system is in normal operation.

initstepslew takes a threshold and a list of NTP servers as arguments. Each of those servers gets rapidly polled several times, and then a majority voting mechanism is used to find the most likely range of system clock error that's present. A step or a slew gets applied to the system clock to correct that error, and then chronyd enters its normal operating mode. Iconic behaviour honestly. 👑

Example of using the directive:

initstepslew 30 ntp1.example.net ntp2.example.net ntp3.example.net

Here 3 NTP servers are used to make the measurement. The 30 means: if the system's error is found to be 30 seconds or less, a slew gets used to correct it; if the error is above 30 seconds, a step gets used. Slay.

initstepslew can also be used in an isolated LAN environment where the clocks are set by hand. The most stable computer gets 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 that 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 finishes its reboot. 🦋

Functionally, initstepslew is similar to a combo of the makestep and server directives with the iburst option. The main difference? The initstepslew servers are used only before normal operation begins, and the foreground chronyd process waits for initstepslew to finish before exiting. That prevents programs started in the boot sequence after chronyd from reading the clock before it's been stepped. With the makestep directive, you'd use the waitsync command of chronyc instead.

⏰ `refclock` ⏰

refclock driver parameter[:option]... [option]...

This one specifies a hardware reference clock to be used as a time source. Two mandatory parameters, bestie: a driver name and a driver-specific parameter. After those two you can have zero or more refclock options. Some drivers have special options that get appended to the driver-specific parameter using the : character. 💅

You can use this directive multiple times to specify multiple reference clocks.

There are six 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?). Since PPS refclocks don't supply full time, you need another time source (like an NTP server or a non-PPS refclock) to complete the samples from the PPS refclock. Alternative move: enable the local directive to allow synchronisation with some unknown but constant offset. The driver supports this option:

clear — by default, the PPS refclock uses assert events (rising edge) for synchronisation. With this option, it uses 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 one 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 that 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 doesn't provide a PPS signal, or it can't 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. Implements the protocol of the ntpd driver type 28. Functionally it's similar to the SOCK driver, but it 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 — and from that the key of the memory segment is derived as 0x4e545030 + unit.

The driver supports this option:

perm=mode — specifies the permissions of the shared memory segment created by chronyd. They're specified as a numeric mode. The default value is 0600 (read-write access for owner only). 🙈

okay so unlike the SOCK driver, there is no prescribed order for starting chronyd and the program that gives you the measurements — they can show up in whatever order, no drama. Both are expected to create the memory segment if it doesn't exist yet. And chronyd will happily attach to an existing segment even if it's owned by someone who isn't root, or if the permissions are different from whatever the perm option says. 👀

⚠️ bestie, listen: the segment needs to be created before untrusted apps or users can execute code, otherwise an attacker can feed chronyd fake measurements and that is not the vibe. You can check the owner and permissions of the segment 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 driver, aka the fancy hardware clock one. The parameter is either the absolute path to the device of the PTP clock you want to use as a time source, or the name of the network interface that's associated with that PTP clock. If the PTP clock is keeping time in TAI instead of UTC, you gotta add the tai option to the directive, or specify the current UTC-TAI offset with the offset option. 🕰️

The driver supports these options:

nocrossts — turns off the use of precise cross timestamping. just vibes only
extpps — enables a PPS mode where the PTP clock timestamps pulses of an external PPS signal hooked up to the clock. The clock itself doesn't need to be synchronised, but you do need another time source to complete the PPS samples. Heads up: some PTP clocks can't be configured to timestamp only assert or clear events, so you'll need the width option to filter out the wrong PPS samples. 🙈
pin=index — says which pin index should be enabled for the PPS timestamping. If the PHC doesn't have configurable pins (i.e. the channel function is fixed), you need to set the index to -1 to disable the pin configuration. Default is 0.
channel=index — the index of the channel for the PPS mode. Default is 0.
clear — timestamps clear events (falling edge) instead of assert events (rising edge) in PPS mode. Lowkey might 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

⏰ RTC ⏰

The driver for using the Real Time Clock as a reference clock. The parameter is the path to the RTC character device you want to use as a time source. This driver cannot be used together with the rtcfile or rtcsync directive — pick one, bestie. 🙅

The driver supports this one option:

utc — assume the RTC keeps Universal Coordinated Time (UTC) instead of local time.

Examples:

refclock RTC /dev/rtc0:utc

🦋 SENSOR 🦋

Driver for timedelta sensors from the OpenBSD hw.sensors framework. The parameter is the name of the sensor device (like nmea0) whose first timedelta sensor should be used as a time source. Timedelta sensors come from serial line time sources attached with ldattach(8), such as nmea(4), and from dedicated radio clock devices. When the line discipline is configured to timestamp a PPS signal (e.g. ldattach -t dcd nmea), the kernel timestamps the pulse at interrupt time and the sensor provides a PPS-corrected offset of the system clock. ✨

Samples get ignored while the kernel marks the sensor as invalid or its status isn't OK (e.g. the receiver lost its fix, or the PPS signal is missing). If the device doesn't exist yet when chronyd starts (e.g. it hasn't been attached with ldattach(8) yet), the driver just waits for it to appear. 🫶

📌 This driver is available only on OpenBSD.

Examples:

refclock SENSOR nmea0 refid GPS precision 1e-7 prefer

🎀 `refclock` options 🎀

The refclock directive supports all of these, so buckle up:

poll poll — timestamps from refclock drivers aren't used immediately; they get stored and processed by a median filter in the polling interval you set here. It's defined as a power of 2, and it can be negative to specify a sub-second interval. Default is 4 (16 seconds). A shorter interval lets chronyd react faster to frequency changes in the system clock, but it might mess with accuracy if the samples have a lot of jitter. 😬
dpoll dpoll — some drivers don't listen for external events and instead try to produce samples in their own polling interval. Also defined as a power of 2, also can be negative for a sub-second interval. Default is 0 (1 second).
refid refid — sets the reference ID of the refclock, up to four ASCII characters. The default reference ID is built from the first three characters of the driver name plus the number of the refclock. Every refclock needs a unique reference ID.
lock refid — locks a PPS refclock to another refclock, specified by its reference ID. In this mode, received PPS samples get paired directly with raw samples from that specified refclock. 🔗
rate rate — sets the rate of the pulses in the PPS signal, in Hz. This controls how the pulses get completed with real time. To receive more than one pulse per second, you have to specify a negative dpoll (-3 for a 5Hz signal). Default is 1.
maxlockage pulses — says, in number of pulses, how old samples from the refclock specified by the lock option can be to still get paired with the pulses. Raising this is useful when samples are produced at a lower rate than the pulses. Default is 2.
width width — sets the width of the pulses, in seconds. Used to filter PPS samples when the driver provides samples for both rising and falling edges. Heads up: it reduces the maximum allowed error of the time source that completes the PPS samples. If the duty cycle is configurable, 50% should be preferred to maximise the allowed error. 💅
pps — forces chronyd to treat any refclock (e.g. SHM or PHC) as a PPS refclock. Handy 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 — compensates for a constant error. The offset you give (in seconds) gets applied to all samples produced by the reference clock. Default is 0.0.
delay delay — sets the NTP delay of the source, in seconds. Half of this value gets 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. Default is 1e-9 (1 nanosecond).
stratum stratum — sets the NTP stratum of the refclock. Useful when the refclock provides time with a stratum other than 0. Default is 0.
precision precision — 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 a larger estimated dispersion get ignored. By default this limit is disabled.
filter samples — sets the max number of samples that can be stored in the median filter between polls of the source. The filter combines about 60 percent of the samples closest to the median offset into one sample. If the driver hands over more samples between polls, the oldest ones get dropped. One sample per poll is enough for the source to be selectable. Default is 64. 📌 Note: the PHC driver does additional filtering based on the reading delay.
prefer — prefer this source over other selectable sources that don't have the prefer option. 👑
noselect — never select this source. Useful for monitoring, or for sources that aren't very accurate but are locked with a PPS refclock.
trust — assume time from this source is always true. It can only be rejected as a falseticker in the source selection if another source with this option doesn't agree with it.
require — require that at least one of the sources specified with this option is selectable (i.e. recently reachable and not a falseticker) before updating the clock. Together with the trust option, this can be useful to let a trusted-but-not-very-precise reference clock be safely combined with unauthenticated NTP sources to improve clock accuracy. They can only be selected and used for synchronisation if they agree with the trusted and required source. 🤝
tai — says 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 has to be kept up to date for this correction to work as expected. This option does not make sense with PPS refclocks.
local — okay so bestie, this option says your reference clock is an unsynchronised clock that's more stable than the system clock (think 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 — sets the minimum number of samples kept for this source. This overrides the minsamples directive. (Yes, there's a global one too, we'll get to it.)
maxsamples samples — sets the maximum number of samples kept for this source. This overrides the maxsamples directive.
maxunreach polls — this option specifies the maximum number of polls that this source can stay selected for synchronisation when it is unreachable (i.e. no valid sample was received in the last 8 polls). Only sources with at least one sample more recent than the oldest sample of all reachable sources can be selected. The default is 100000. 😭
optional — this option indicates that the refclock device might be missing and chronyd is allowed to start even if the driver fails to initialise, causing the source to be ignored as if it was not specified in the configuration file. 🫶

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

`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 preferred 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) that 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 — okay so this one turns OFF the checking of certificate activation and expiration times for a set number of clock updates, bestie. Why would you want that? So the NTS authentication mechanism can actually be used on computers that boot up with the wrong time (think: no RTC, no backup battery, clock just vibing in the wrong decade 🙈). But listen — turning off these time checks has important security implications and should be used only as a last resort, and preferably with a minimal number of trusted certificates. The default is 0, which means the time checks are always on, periodt.

Example, slay:

nocerttimecheck 1

That disables the time checks until the clock gets updated for the first time — assuming that first update fixes the clock and the later checks can then work with the correct time. ✨

refresh interval — this sets the minimum interval, in seconds, between refreshing the IP addresses of NTP sources that were specified by hostname. If the hostname stops resolving to the address currently in use, it gets swapped for one of the new addresses, so you don't keep using a server that's no longer meant to be in service — even if it's still answering perfectly and wouldn't get dropped as unreachable. Only one source is refreshed at a time, and only when a valid response is received (unreachable sources get replaced independently, no cap 💅). Default value is 1209600 (that's 2 weeks, iykyk), and the max is 2^31-1 (68 years, literally). A value of 0 disables the periodic refreshment entirely.

Oh and — the refresh command can refresh all the sources immediately, so you don't gotta wait.

🌸 Source selection 🌸

authselectmode mode — so NTP sources can be specified with the key or nts option to enable authentication, and that's how you 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 inside those packets. So the worst they can do is cause a limited slew or step, plus make the clock run faster or slower than real time (up to double the maxdrift limit).

When authentication is on for an NTP source, it's important to disable unauthenticated NTP sources that could get exploited in the attack — like if they're not reachable only over a trusted network. Alternatively you can configure source selection with the require and trust options to synchronise to unauthenticated sources only if they agree with the authenticated ones, which might have a positive impact on the accuracy of the clock. But heads up: in that case the impact of the attack is higher. Attackers still can't cause an arbitrarily large step or slew, but they get more control over the frequency of the clock and can make chronyd report false info — like a significantly smaller root delay and dispersion. 😭

This directive determines the default selection options for authenticated and unauthenticated sources, so your configuration with the config file and chronyc commands stays simple. Basically 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 automatically get the noselect option so they can't be picked for synchronisation. No exceptions. 💅
prefer — here authentication is optional and preferred. If it's enabled for at least one NTP source, all unauthenticated NTP sources get the noselect option.
mix — 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 get the require and trust options, which prevents synchronisation to unauthenticated NTP sources if they don't agree with a majority of the authenticated sources and reference clocks. This is the default mode, bestie.
ignore — authentication is straight up ignored in the source selection. All sources have only the selection options specified in the configuration file, or the chronyc command. This was how chronyd behaved in versions before 4.0.

As an example, this 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 this 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 pick one as the synchronisation source. But the measured offsets and frequencies of the system clock relative to the other sources can be combined with the selected source to improve the accuracy of the system clock. Cute, right? 🎀

The combinelimit directive limits which sources get 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 that same option.

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

maxdistance distance — sets the maximum root distance of a source that's acceptable for synchronisation of the clock. Sources with a distance larger than the specified distance get 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 — sets the maximum allowed jitter of the sources, so they don't get rejected by the source selection algorithm. This stops synchronisation with sources that have a small root distance but whose time is just too variable, ngl.

By default, the maximum jitter is 1 second.

maxstratum stratum — sets the maximum allowed stratum of the sources to be selected for synchronisation. Default is 15. The useful range is 0 to 15.
minstratum stratum — sets the minimum allowed stratum of the sources to be selected for synchronisation. Default is 0. The useful range is 0 to 15.
minsources sources — sets the minimum number of sources that need to be considered selectable in the source selection algorithm before the local clock gets updated. Default is 1.

Setting this to a bigger number can improve reliability — more sources have to agree with each other, and the clock won't update when only one source (which could be serving straight-up incorrect time 💀) is reachable.

reselectdist distance — when chronyd selects a synchronisation source from the available sources, it prefers the one with the shortest synchronisation distance. But to avoid frequent reselecting when there are sources with similar distance, a fixed distance gets added to the distance of sources that aren't currently selected. You set that with reselectdist. By default, the distance is 100 microseconds.
stratumweight distance — sets how much distance should be added per stratum to the synchronisation distance when chronyd selects the synchronisation source from the available sources.

By default, the weight is 0.001 seconds. This means the stratum of the sources in the selection process matters only when the differences between the distances are in milliseconds. Tiny numbers, big vibes. ✨

👑 System clock 👑

clockprecision precision — specifies the precision of the system clock, in seconds. chronyd uses this value as the minimum expected error and amount of noise in NTP and refclock measurements, and to randomise the low-order bits of timestamps in NTP responses so they're less predictable. The minimum value is 1 nanosecond and the maximum value is 1 second.

By default, chronyd tries to determine the precision on start-up as the resolution of the clock. On Linux it tries to measure the resolution by observing the minimum change in differences between consecutive readings of the clock. On other systems it relies on the clock_getres(2) system function.

If the measurement fails, or the value the system provides is too large, the minimum measured time needed to read the clock gets used instead. That value is typically larger than the resolution, and it's sensitive to CPU speed — which can change over time to save power, annoyingly.

The server's precision is reported on clients by the ntpdata command.

An example setting the precision to 1 nanosecond (e.g. when the system clock is using a Time Stamp Counter (TSC) updated at a rate of at least 1 GHz) is:

clockprecision 1e-9

corrtimeratio ratio — when chronyd is slewing the system clock to correct an offset, the rate at which it's 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.

So the corrtimeratio directive sets the ratio between how long the clock gets slewed for an average correction (based on the source history, bestie, it's giving data 💅) and the interval in which the corrections actually happen — which is usually just the NTP polling interval. Corrections that are bigger than average take less time, and smaller corrections take more time. The amount of the correction and the correction time are inversely proportional. Math is math. ✨

Cranking up corrtimeratio makes your overall frequency error better 🎀 but it makes the overall time error worse, because the corrections are taking longer. Trade-offs, always.

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

The maximum allowed slew rate can be set by the maxslewrate directive. And the current remaining correction? That shows up in the tracking report as the System time value. Slay.

driftfile file [interval interval] — okay so one of the main activities of the chronyd program is figuring out the rate at which the system clock gains or loses time relative to real time.

Whenever chronyd computes a new value of that gain-or-loss rate, it really wants to record it somewhere 📝. Why? Because that lets chronyd start compensating the system clock at that rate whenever it's restarted — even before it's had a chance to get an equally good estimate of the rate during the new run. (And getting that estimate can take many minutes, at least. Not a quick vibe.)

The driftfile directive lets you specify a file into which chronyd can store the rate information. Two parameters get recorded in that file:

The rate at which the system clock gains or loses time, expressed in parts per million, with gains positive. So a value of 100.0 means that when the system clock has advanced by a second, it has gained 100 microseconds in reality — meaning the true time has only advanced by 999900 microseconds. 🤯
An estimate of the error bound around that first value, i.e. where the true rate actually lies.

The interval option specifies the minimum interval between updates of the file, in seconds. The file is written only on an update of the local clock. The default interval is 3600 seconds.

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 exist to stop you from quickly drifting away from true time when the clock wasn't 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're 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 the 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 changes 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. Simple life.

leapsecmode mode — a leap second is an adjustment that's occasionally applied to UTC to keep it close to the mean solar time. When a leap second gets inserted, the last day of June or December has an extra second: 23:59:60. Iconic of UTC honestly but a whole mess for computers 😭

For computer clocks, that's a problem. Unix time is defined as the 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. So the inserted leap second gets 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 — similar to the system mode, except the clock is stepped by chronyd instead of the kernel. Useful for avoiding bugs in the kernel code that would be executed in 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 system and step modes when applications running on the system are sensitive to jumps in the system time, and it's acceptable that the clock will be off for a longer time. On Linux with the default maxslewrate value, the correction takes 12 seconds.
ignore — no correction is applied to the clock for the leap second. The clock gets corrected later in normal operation when new measurements are made and the estimated offset includes that 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 you're serving time to NTP clients that can't be configured to correct their clocks for a leap second by slewing, or to clients that would correct at slightly different rates when it's 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 don't need any special configuration, because they don't know there's any leap second at all — they just follow the server time, which eventually brings them back to UTC. But careful: you gotta make sure they use only NTP servers that smear the leap second in exactly the same way for synchronisation. No mixing, bestie.

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'll start when the clock gets to 00:00:00 UTC, and it'll 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 the next leap second occurs and what the current offset between TAI and UTC is. It'll 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. And no, you do not need to restart chronyd. Chill.

This directive is useful with reference clocks and other time sources that don't announce leap seconds, or that 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's also useful when the system clock is required to have a 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'll be accepted even if it's 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's 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. But 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. 😭

okay so back to makestep — 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's lowkey 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.

Note that this directive does not work and should not be used when the system clock control is disabled by the -x option of chronyd. 💀

💥 `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 and OpenBSD, 500 ppm on FreeBSD, NetBSD, and macOS 10.13+, 32500 ppm on illumos). 🌍

By default, the maximum assumed drift is 100000 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 and OpenBSD it is 100000 ppm, on FreeBSD, NetBSD and macOS 10.13+ it is 5000 ppm, 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

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, while 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; yet, 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 dropped into the directives instead of the IP address, but the name has to actually resolve when chronyd starts up, like the network is already up and DNS is doing its thing. And if that hostname resolves to multiple addresses, only the first address — like, in the order the system resolver hands them back — gets allowed or denied. That's it, that's the one. 💅

Heads up bestie: if the initstepslew directive is in the config file, every single computer listed in that directive has to allow client access by this computer or the whole thing just doesn't work. no cap. 😭

🚫 deny

deny [all] [subnet]

Okay so this is the allow directive's evil twin 😈 — same deal, except it denies NTP and NTS-KE client access to a particular subnet or host instead of allowing it.

The syntax is identical, and you can use it multiple times too, just like allow. 🫶

And yeah, there's also a deny all directive with behaviour matching the allow all directive. twins fr fr 💖

🎀 bindaddress

bindaddress address

The bindaddress directive binds the sockets that chronyd listens on for NTP and NTS-KE requests to a local address of the computer. On systems that aren't Linux, the address of the computer needs to already be configured when chronyd is started. like, get it together first bestie ✨

Here's an example of the directive in the wild:

bindaddress 192.168.1.1

Right now, for each of the IPv4 and IPv6 protocols, you can only specify one bindaddress directive. So it's genuinely not useful on computers that should be serving NTP on multiple network interfaces. it's giving limited. 💀

🌸 binddevice

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 only specify one interface, and it's supported on Linux only — sorry to my BSD girlies, not today. 😭

An example:

binddevice eth0

📡 broadcast

broadcast interval address [port]

The broadcast directive is how you declare a broadcast address that chronyd should send packets to in NTP broadcast mode — i.e. making chronyd act as a broadcast server. Broadcast clients on that subnet will then be able to synchronise. slay 🔥

You can use this directive multiple times to specify multiple addresses. iconic.

The syntax goes like this:

broadcast 32 192.168.1.255
broadcast 64 192.168.2.255 12123
broadcast 64 ff02::101

Let's break it down bestie 🧚 In the first example, the destination port defaults to UDP port 123 (the normal NTP port, the classic). 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. That 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. more is more ✨

Now, 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. not for us, for them. 💅

And 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. So that broadcast subnet should also be the subject of an allow directive. don't forget or it's giving nothing. 🙈

🍓 clientloglimit

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, so ymmv girlie 🌸).

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. big numbers, big vibes. 👑

An example of the use of this directive is:

clientloglimit 1048576

🙈 noclientlog

This directive, which takes no arguments (she's low maintenance 💅), 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. so like, know what you're doing bestie ✨

⭐ local

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. main character energy fr fr 👑

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. vague is fine, we're not doing precision here 🫶

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 that 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 a configured time 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). When the clock is not synchronised, it is considered to have an infinite root distance, i.e. the local reference activates as soon as allowed by the waitunsynced option. The default threshold 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

math girlie moment 🧚✨

`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. no gatekeeping 💅

`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 way that it just hands off the crown 👑✨

The orphan mode is compatible with the ntpd's orphan mode (enabled by the tos orphan command). bestie crossover event 🫶

`waitsynced` interval

This option specifies the minimum interval (in seconds) between the last update of the clock and activation of the local reference as configured by the distance and activate options. The distance option can be set to 0 to ignore the root distance and control the activation only by the interval. In such case it should be at least as long as the maximum expected polling interval to prevent frequent activation in normal polling of the source. The default minimum interval is 0. ⏳

`waitunsynced` interval

This option specifies how long (in seconds) chronyd needs to wait before activating the local reference when the clock is not considered to be synchronised (e.g. after start or the source selection failing due to no majority). This delay prevents chronyd from serving incorrect time to clients before the configured time sources are given a chance to synchronise the local clock. The default interval is 300 seconds if the orphan option is set, otherwise it is 0 (i.e. local reference activates immediately). patience is a virtue girlie 🌸

Examples of the directive are:

local stratum 5
local stratum 10 orphan distance 0.1 activate 0.5
local stratum 10 orphan distance 0.0 waitsynced 7200 waitunsynced 300

🔐 ntpsigndsocket

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. fancy ✨

⚠️ Okay this part is important, bestie, listen up. 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. like, lock it down fr fr. 🔒😭

An example of the directive is:

ntpsigndsocket /var/lib/samba/ntp_signd

💜 ntsport

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 <em>only</em> when a certificate and a key are both specified by the ntsservercert and ntsserverkey directives. Both. No cert, no key, no port. That's the vibe check. 💅

`ntsservercert` file

Okay so this one tells chronyd which file holds a certificate in PEM format, so it can girlboss as an NTS server. ✨ The file should also include any intermediate certificates that the clients are gonna need to validate the server's certificate — don't leave them hanging bestie. 🫶

The file needs to be readable by the user under which chronyd is running after dropping root privileges. Keep that in mind.

You can use this directive multiple times, which lets you specify multiple certificates for different names of the server. Iconic. Multiple names, multiple certs.

⚠️ The files are loaded only once. chronyd needs to be restarted in order to load a renewed certificate. To get a near-seamless server operation, the ntsdumpdir and dumpdir directives with the -r option of chronyd are the recommended combo. 💖

`ntsserverkey` file

Same energy, but for the private key. 🔐 This directive specifies a file containing a private key in the PEM format so chronyd can 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. Like, genuinely, lock that down. 🙈

You can use this directive multiple times to specify multiple keys. But here's the rule: the number of keys must be the same as the number of certificates, and the corresponding files must be specified in the same order. Match them up correctly or it's giving chaos. 💀

`ntsprocesses` processes

This one is all about the helpers. 💪 It specifies how many helper processes chronyd — when it's operating as an NTS server — will start for handling client NTS-KE requests, in order to improve performance with multi-core CPUs and multithreading. Main character CPU energy. 🔥

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.
The maximum value is 1000.

`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. 🔐✨

When chronyd is acting as a server, it uses the first enabled algorithm from the list provided by the client. Algorithms that aren't supported by the installed version of the crypto library (Nettle, GnuTLS) are just ignored. Not personal, just facts.

The following IDs are supported:

15: AES-SIV-CMAC-256
30: AES-128-GCM-SIV

An example of the directive is:

ntsaeads 15

This list is used also by the NTS client. 👑

📜 Note that the NTS specification (RFC 8915) requires servers to support AES-SIV-CMAC-256, i.e. 15 should always be 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 at 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 the NTS cookies it hands out to clients. 🍪 The keys are saved to a single file named ntskeys.

When chronyd is restarted, reloading the keys allows the clients to keep using their 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) that is provided in the NTS-KE response to the clients. 🌈 It lets the NTS-KE server be separated from the NTP server, which is very demure, very mindful of your architecture.

⚠️ But the servers need to share the keys, i.e. external key management needs to be enabled by setting ntsrotate to 0. Otherwise it's not gonna work, bestie.

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. Very considerate of it. 💖

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). Sixty-eight years. Imagine. 😭

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). Chill schedule, honestly. 😌

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. Three ways in. Pick your fighter. 🥊

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. Pure lurker energy. 🙈

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 whole purpose is to reduce network traffic with misconfigured or broken NTP clients that are polling the server too frequently. Like, calm down. 😭

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. Group project rules. 📚

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. Clever, lowkey.

The maximum number of IP addresses that 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). Ate. 💅

`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: bestie the server is intentionally not serving its best estimate of the true time. Like, on purpose. 😭 If a big offset has piled up, smoothing it out can take forever. Only use this directive when your clients aren't also configured to poll another NTP server, because otherwise they might straight-up reject this server as a falseticker or fail to select a source at all. 💀

The smoothing process is done with a quadratic spline function with two or three pieces. It's independent from any slewing applied to the local system clock, but the accumulated offset and frequency get reset when the clock is corrected by stepping — e.g. by the makestep directive or the makestep command in chronyc. You can reset the process without stepping the clock using 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 that enables a mode where only leap seconds are smoothed out and normal offset and frequency changes are ignored. The leaponly option is useful in combination with the leapsecmode slew directive, so clients can safely use multiple time smoothing servers. ✨

The smoothing process activates automatically when 1/10000 of the estimated skew of the local clock falls below the maximum rate of frequency change. You can also activate it manually with the smoothtime activate command — which is especially handy when the clock is synchronised only with manual input and the skew is always bigger than the threshold. And the smoothing command can be used to monitor the process. 👑

An example suitable for clients using ntpd and 1024 second polling interval could be:

smoothtime 400 0.001

An example suitable for clients using chronyd on Linux could be:

smoothtime 50000 0.01

🎀 Command and monitoring access 🎀

bindcmdaddress address — this one specifies a local IP address that chronyd will bind the UDP socket to, the one listening for monitoring command packets (the ones chronyc sends out). On systems that aren't Linux, the address of the interface needs to be already configured when chronyd starts. 💅

This directive can also change the path of the Unix domain command socket, which is what chronyc uses to send configuration commands. The socket has to live in a directory that's accessible only by the root or chrony user. That directory gets created on start if it doesn't already exist. The compiled-in default path of the socket is /run/chrony/chronyd.sock. You can disable the socket entirely 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 these 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 — binds the UDP command sockets to a network device specified by the interface name. This directive can only specify one interface and it's supported on Linux only. 🐧

An example of the directive is:

bindcmddevice eth0

cmdallow [all] [subnet] — this is basically the allow directive's cousin, except it allows monitoring access (rather than NTP client access) to a particular subnet or host. (And by "monitoring access" we mean that chronyc can be run on those hosts and pull monitoring data from the chronyd on this computer. 🕵️)

The syntax is identical to the allow directive.

There's also a cmdallow all directive with similar behaviour to the allow all directive (but applying to monitoring access in this case, obviously 💁).

Addresses 127.0.0.1 and ::1 (i.e. the loopback interface) are always allowed.

Note that chronyd has to be configured with the bindcmdaddress directive to not listen only on the loopback interface, otherwise remote access is literally not happening. 😤

cmddeny [all] [subnet] — just like cmdallow, except it denies monitoring access to a particular subnet or host instead of allowing it. Rude but valid. 🙅

The syntax is identical.

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

cmdport port — lets you change the port used for run-time monitoring (via the chronyc program) from its default (323). If set to 0, chronyd will not open the port at all, 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 though. 🚫

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]... — enables response rate limiting for command packets. It's 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

opencommands [command]... — specifies a list of monitoring commands to be enabled for the hosts allowed by the cmdallow directive. The following commands can be specified (the naming follows chronyc): 👇

activity*, authdata, clients, manual*, ntpdata, rtcdata*, selectdata, serverstats, smoothing*, sourcename*, sources*, sourcestats*, tracking*.

The commands marked with * are enabled by default. The protocol of these commands is considered stable and can be expected to work between different versions of chronyc and chronyd. The protocol of the other commands is not considered stable, and different versions of chronyc and chronyd may not interoperate. When that happens, chronyc will print an 'Invalid command' or 'Bad reply from daemon' error. 😭

Note that some of the reported data can be potentially useful to attackers, enabling them to observe and predict better the internal state of chronyd. It is recommended to enable only commands that are actually needed for monitoring and limit the access to the hosts that need it. 🔒

🦋 Real-time clock (RTC) 🦋

hwclockfile file — 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 — 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 — sets the path to the device file for accessing the RTC. The default path is /dev/rtc. 💅
rtcfile file — 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 these three conditions apply: 😤

You are running Linux.
The kernel is compiled with extended real-time clock support (i.e. the /dev/rtc device is capable of doing useful things).
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 that 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's 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 or when the RTC is used as reference clock. 🙈

rtcsync — 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 ✨

Okay bestie, gather round. The log directive is basically saying “we’re logging stuff now, periodt.” The log files get written to whatever directory logdir tells them to. And a banner gets periodically written into the files so you can actually understand what the columns mean. 💅

log [option]... — the main character directive. Here are its options, and you’re gonna be obsessed:

rawmeasurements — logs the raw NTP measurements and related info 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):

Date [2015-10-13]
Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the local time zone. [05:40:50]
IP address of server or peer from which measurement came [203.0.113.15]
Leap status (N means normal, + means that the last minute of the current month has 61 seconds, - means that the last minute of the month has 59 seconds, ? means the remote computer is not currently synchronised.) [N]
Stratum of remote computer. [2]
RFC 5905 tests 1 through 3 (1=pass, 0=fail) [111]
RFC 5905 tests 5 through 7 (1=pass, 0=fail) [111]
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]
Local poll [10]
Remote poll [10]
‘Score’ (an internal score within each polling level used to decide when to increase or decrease the polling level. This is adjusted based on number of measurements currently being used for the regression algorithm). [1.0]
The estimated local clock error (theta in RFC 5905). Positive indicates that the local clock is slow of the remote source. [-4.966e-03]
The peer delay (delta in RFC 5905). [2.296e-01]
The peer dispersion (epsilon in RFC 5905). [1.577e-05]
The root delay (DELTA in RFC 5905). [1.615e-01]
The root dispersion (EPSILON in RFC 5905). [7.446e-03]
Reference ID of the server’s source as a hexadecimal number. [CB00717B]
NTP mode of the received packet (1=active peer, 2=passive peer, 4=server, B=basic, I=interleaved). [4B]
Source of the local transmit timestamp (D=daemon, K=kernel, H=hardware). [D]
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 that passed the RFC 5905 tests 1 through 7. This can be useful for producing graphs of the source’s performance. 📈
statistics — 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):

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

Date [2022-05-01]
Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the local time zone. [02:01:20]
IP address or reference ID of the source. [203.0.113.15]
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.
  - r - has a stratum outside of the allowed range (configured by the minstratum and maxstratum directives).
  - 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).
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.
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]

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] — periodt.
Interval since the last measurement of the source in seconds. [4.228e+01] — lowkey important.
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]
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 ✨

Bestie, 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) :

Date [2017-08-22]
Hour:Minute:Second. Note that the date-time pair is expressed in UTC, not the local time zone. [13:22:36]
The IP address of the server or peer to which the local system is synchronised. [203.0.113.15]
The stratum of the local system. [2]
The local system frequency (in ppm, positive means the local system runs fast of UTC). [-3.541]
The error bounds on the frequency (in ppm). [0.075]
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]
Leap status (N means normal, + means that the last minute of this month has 61 seconds, - means that the last minute of the month has 59 seconds, ? means the clock is not currently synchronised.) [N]
The number of combined sources. [2]
The estimated standard deviation of the combined offset (in seconds). [2.940e-03]
The remaining offset correction from the previous update (in seconds, positive means the system clock is slow of UTC). [-2.084e-04]
The total of the network path delays to the reference clock to which the local clock is ultimately synchronised (in seconds). [1.534e-02]
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]
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):

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

📡 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):

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

🌡️ 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):

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

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. It's giving helpful, honestly.

The logbanner directive specifies the cadence size of how many entries are written to the log file after which the banner is written anew. 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. So convenient.

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. Organized queen.

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

sourcedir directory... — okay so this is basically confdir's cooler twin ✨ same energy, three little plot twists:
- the config files rock a .sources suffix instead of .conf
- they can only specify NTP sources — so just server, pool, and peer, nothing else bestie
- every line is expected to be terminated by the newline character
- and they can be reloaded on the fly with the reload sources command in chronyc 🔥

It's particularly useful with dynamic sources like NTP servers you got handed from a DHCP server — a networking script can write those out to a file specific to the network interface. Very demure, very mindful.

This directive can be used multiple times 💅

Example of the directive:

sourcedir /var/run/chrony-dhcp

include pattern — this one pulls in a configuration file, or a whole bunch of them if you drop a wildcard pattern 🦋 Unlike confdir, you have to give the full name of the files, and at least one file is required to exist. No files, no vibes, no config.

This directive can be used multiple times 💅

Example of the directive:

include /etc/chrony.d/*.conf

hwtimestamp interface [option]... — the main character directive 👑 This turns on 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, dodging all the processing and queueing delays in the kernel, network driver, and hardware. That can significantly improve the accuracy of the timestamps and the measured offset, which is what gets used for synchronisation of the system clock. For 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 you can verify 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. Go off, * 🎀

The hwtimestamp directive has the following options:

minpoll poll — 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. Default is 0 (1 second), minimum is -6 (1/64th of a second), and maximum is 20 (about 12 days).
maxpoll poll — specifies the maximum interval between readings of the NIC clock, as a power of 2. Default is minpoll + 1, i.e. 1 (2 seconds) with the default minpoll of 0. Minimum and maximum values are the same as with the minpoll option.
minsamples samples — specifies the minimum number of readings kept for tracking of the NIC clock. Default is 2.
maxsamples samples — specifies the maximum number of readings kept for tracking of the NIC clock. Default is 16.
precision precision — specifies the assumed precision of reading of the NIC clock and maximum error in its tracking relative to the system clock. Larger offsets cause the tracking to reset and fall back to kernel or daemon timestamps. Default is 100e-9 (100 nanoseconds).
txcomp compensation — 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. Default is 0.
rxcomp compensation — 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. Default 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. Bye bestie 🙈
rxfilter filter — 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:

hwtimestamp eth0
hwtimestamp eth1 txcomp 300e-9 rxcomp 645e-9
hwtimestamp *

hwtstimeout timeout — okay so picture this: you're using hardware timestamping with a close NTP server, or the NIC or its driver is slow in providing the transmit timestamp of NTP requests. Now a response from the server can arrive 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 chronyd should 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.

maxtxbuffers messages — story time 🍓 When chronyd gets a kernel or hardware transmit timestamp after sending an NTP message to a server, peer, or client (using interleaved mode), it needs the address and content of the message to be able to correctly assign the timestamp to the server, peer, or client. The timestamps are processed asynchronously. The kernel provides with each timestamp the data-link frame that was timestamped, but chronyd can extract the necessary data only from plain IPv4 and IPv6 packets in Ethernet frames, possibly including VLAN tags. If the NTP packets are transmitted by a non-Ethernet device, or they are encapsulated in another layer (e.g. a WireGuard tunnel), chronyd is not able to extract the data and use the kernel or hardware transmit timestamps, having to fall back to less accurate daemon timestamps. Tragic 💀

On Linux 6.13 and newer, chronyd supports an alternative method of processing kernel and hardware transmit timestamps, which works with any device that can provide kernel and/or hardware transmit timestamps. chronyd can save its transmitted messages with their addresses and ports in a ring buffer, each assigned an ID that the kernel will provide back with the timestamp. This transmit ID enables chronyd to assign the timestamp to the correct server, peer, or client. Slay 🧚

The directive specifies the maximum number of messages that chronyd is allowed to save in the ring buffer. The minimum value is 0 and the maximum value is 1048576. It needs about 1.5 KB of allocated memory per message. chronyd will log a warning if the number of messages is insufficient for the actual rate of transmit timestamping. The default value is 0 (disabled).

Example:

maxtxbuffers 128

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

Security check bestie!! 🚨 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, OpenBSD, 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 that 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).

Support for NTP over PTP (RFC 10030) was added in chronyd version 4.9. It sends NTP-over-PTP messages as PTPv2 Delay_Req messages with the ORGANIZATION_EXTENSION TLV. It accepts PTPv2 and PTPv2.1 Delay_Req and Sync messages with the ORGANIZATION_EXTENSION or ORGANIZATION_EXTENSION_DO_NOT_PROPAGATE TLV. Versions 4.2-4.8 supported an experimental version of the transport, which is not compatible with the final specification.

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 that can timestamp PTP packets only, the rxfilter option of the hwtimestamp directive needs to be set to ptp. The extension field 10A 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 10A
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, OpenBSD, 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, OpenBSD, 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 that 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 project (https://www.pool.ntp.org/).

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

You will probably want to include some of the other directives, however. 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 is basically saying "bestie, we're not online yet" — the servers kick off in an offline state and literally will not be contacted until chronyd gets a heads-up from chronyc that the internet link is up. So to tell chronyd when to start and stop sampling those servers, you use the online and offline commands in chronyc. 💅

Real-world example, if pppd is the program dialing you into the internet and chronyc lives at /usr/bin/chronyc, then your /etc/ppp/ip-up script would have this in it:

/usr/bin/chronyc online

and your /etc/ppp/ip-down script would have this:

/usr/bin/chronyc offline

and boom 💥 — chronyd now only polls the servers while the machine is actually connected to the internet.

🌸 Isolated networks 🌸

This one's for the computers that never have network connectivity to any machine that ultimately traces its time back to a reference clock. It's giving lonely island energy, but make it timekeeping. 🏝️

In this situation, one computer gets picked to be the primary timeserver. Everyone else is either a direct client of that server, or a client of a client. Chain of slay.

The local directive switches on a local reference mode, which lets chronyd appear synchronised even when it very much is not. Yes, it's fake it till you make it, but for clocks. 🫶

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 has support for this — it comes in the form of the manual directive and the settime command in the chronyc program. ✨

Now, if the server gets rebooted, chronyd can re-read the drift rate from the drift file, but the server has no accurate estimate of the current time. Workaround? The system can be set up so the server initially sets itself to a 'majority-vote' of selected clients' times — which lets the clients 'flywheel' the server while it's busy rebooting. Teamwork, honestly. 👑

The smoothtime directive is your bestie when the clients' clocks need to stay close together while the local time gets adjusted by the settime command. The smoothing process has to be activated with the smoothtime activate command once the local time is ready to be served. After that point, all adjustments get smoothed out. So satisfying. 😌

A typical config file for the server (let's call it ntp.local) might look like this — assuming the clients and the server are all hanging out 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 config file might be:

server ntp.local iburst
driftfile /var/lib/chrony/drift
allow 192.168.165.0/24
makestep 1.0 3
rtcsync

And the rest of the clients? Same deal, except the allow directive isn't required. 🎀

Now — if there's no suitable computer to designate as the primary server, or if you're required to keep clients synchronised even when the primary server fails, the orphan option of the local directive enables a special mode where the server gets selected from multiple computers automatically. They all have to use the same local configuration and poll each other. The server with the smallest reference ID (which is based on its IP address) takes on the role of primary server, and the others synchronise to it. When it fails, the server with the second smallest reference ID takes over, and so on. It's giving succession planning. 💀

A config file for the first server might look like this (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 identical, except the hostnames in the initstepslew and server directives get swapped out to point at the other servers. And their clients might be configured to poll all three servers. Look at them, so resilient. 🌈

🦋 RTC tracking 🦋

Okay so this section is about a computer that only occasionally connects to the internet and gets turned off between 'sessions'. In this case, chronyd leans on the computer's RTC to hold the time together while the machine is powered down. It assumes 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'll need to enable the HPET_EMULATE_RTC option in your kernel configuration. Otherwise chronyd won't be able to interact with the RTC device and will just give up on it. And honestly? Fair.

When the computer is connected to the internet, chronyd has access to external NTP servers that it takes measurements from. Those measurements get saved, and straight-line fits are performed on them to give an estimate of the computer's time error and its rate of gaining or losing time. Math girlies rise up. 📈

Once the computer goes offline from the internet, the best estimate of the gain or loss rate gets used to free-run the computer until it next goes online. Autonomous era. 💅

While the computer is running, chronyd takes measurements of the RTC (through the /dev/rtc interface, which must be compiled into the kernel). It works out an estimate of the RTC error at a particular RTC second, plus 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 get saved to files, and the RTC tracking information also gets saved to a file (that is, if the rtcfile directive has been specified). These pieces of info also get saved if the dump and writertc commands are issued through chronyc, respectively.

When the computer reboots, chronyd reads the current RTC time plus the RTC information saved at the last shutdown. That info 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. Then the measurement histories for the servers get reloaded. ✨

And 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. Glow up achieved. 🎀

One problem with saving the measurements and RTC data when the machine shuts down: what happens if there's a power failure? The most recent data just won't get saved. chronyd is robust enough to cope with this, but some performance might be lost. (The main danger arises if the RTC has been changed during the session, using the trimrtc command in chronyc. Because of that, trimrtc makes sure 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 where the offline command gets 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. Big brain move, no cap. 🧠

A final point, about computers left running for extended periods where you want to spin down the hard disc when it's not in use (e.g. when it hasn't been accessed for 15 minutes). chronyd was planned so it supports that kind of operation — this is why the RTC tracking parameters aren't saved to disc after every update, but only when the user requests such a write, or during the shutdown sequence. The only other thing that will generate periodic writes to the disc is the log rtc facility in the configuration file; do not use that option if you want your disc to spin down. 💀

To show how a computer might be configured for this case, here are example configuration files.

For the chrony.conf file, this 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 what's used to connect to the internet here. It 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 gets 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 — depends on the directives in chronyd's configuration file. 👑

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

👑 Public NTP server 👑

chronyd can be configured to operate as a public NTP server — like, to join the pool.ntp.org <https://www.pool.ntp.org/en/join.html> project. Main character energy, honestly. ✨

The configuration is similar to the NTP client with permanent connection, except it needs to allow client access from all addresses. It's 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 with the refclock directive. 🛰️

The amount of memory used for logging client accesses can be increased, in order to let clients use the interleaved mode even when the server has a huge number of clients, and to better support rate limiting if it's enabled by the ratelimit directive. The system timezone database — if it's 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. And the -r option with the dumpdir directive shortens the time in which chronyd won't 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). So useful. 💖

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/. Please be nice to the maintainers, they're doing amazing sweetie. 🙏

🎀 AUTHORS 🎀

chrony was written by Richard Curnow, Miroslav Lichvar, and others. Legends only. 👑

And that's the whole page, bestie — that's chrony.conf(5) from the chrony 4.9 era, dated 2026-08-27. Go forth and sync your clocks, you absolute icon. 🦋💖

📦 where this page comes from

centos-stream 10: chrony 4.9-1.el10 · GPL-2.0-only
centos-stream 9: chrony 4.9-1.el9 · GPLv2
fedora 44: chrony 4.9-1.fc44 · GPL-2.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms

CHRONY.CONF(5)

✨ NAME ✨

🦋 SYNOPSIS 🦋

💅 DESCRIPTION 💅

👑 DIRECTIVES 👑

🌸 Time sources 🌸

🌊 pool 🌊

🤝 peer 🤝

🚀 initstepslew 🚀

⏰ refclock ⏰

📶 PPS 📶

🔌 SOCK 🔌

🧠 SHM 🧠

🌈 PHC 🌈

⏰ RTC ⏰

🦋 SENSOR 🦋

🎀 refclock options 🎀

manual

acquisitionport port

bindacqaddress address

bindacqdevice interface

dscp point

dumpdir directory

maxsamples samples

minsamples samples

ntsaeads ID...

ntsdumpdir directory

ntsrefresh interval

ntstrustedcerts [set-ID] file|directory

nosystemcert

🌸 Source selection 🌸

👑 System clock 👑

💥 maxchange offset start ignore

⏱️ maxclockerror error-in-ppm

🧭 maxdrift drift-in-ppm

📈 maxupdateskew skew-in-ppm

🛞 maxslewrate rate-in-ppm

🌡️ tempcomp file interval T0 k0 k1 k2, tempcomp file interval points-file

🌐 NTP server

🎟️ allow [all] [subnet]

🚫 deny

🎀 bindaddress

🌸 binddevice

📡 broadcast

🍓 clientloglimit

🙈 noclientlog

⭐ local

stratum stratum

distance distance

activate distance

orphan

waitsynced interval

waitunsynced interval

🔐 ntpsigndsocket

💜 ntsport

ntsservercert file

ntsserverkey file

ntsprocesses processes

maxntsconnections connections

ntsaeads ID...

ntsdumpdir directory

ntsntpserver hostname

ntsrotate interval

port port

ratelimit [option]...

ntsratelimit [option]...

smoothtime max-freq max-wander [leaponly]

🎀 Command and monitoring access 🎀

🦋 Real-time clock (RTC) 🦋

✨ Logging ✨

✨ tracking ✨

🕰️ rtc 🕰️

📡 refclocks 📡

🌡️ tempcomp 🌡️

🎀 logbanner entries 🎀

🦋 logchange threshold 🦋

💖 logdir directory 💖

📧 mailonchange email threshold 📧

🌈 Miscellaneous 🌈

🗂️ confdir directory... 🗂️

🌊 `pool` 🌊

🤝 `peer` 🤝

🚀 `initstepslew` 🚀

⏰ `refclock` ⏰

📶 `PPS` 📶

🔌 `SOCK` 🔌

🧠 `SHM` 🧠

🎀 `refclock` options 🎀

`manual`

`acquisitionport` `port`

`bindacqaddress` `address`

`bindacqdevice` `interface`

`dscp` `point`

`dumpdir` `directory`

`maxsamples` `samples`

`minsamples` `samples`

`ntsaeads` `ID...`

`ntsdumpdir` `directory`

`ntsrefresh` `interval`

`ntstrustedcerts` `[set-ID] file|directory`

`nosystemcert`

💥 `maxchange offset start ignore`

⏱️ `maxclockerror error-in-ppm`

🧭 `maxdrift drift-in-ppm`

📈 `maxupdateskew skew-in-ppm`

🛞 `maxslewrate rate-in-ppm`

🌡️ `tempcomp file interval T0 k0 k1 k2`, `tempcomp file interval points-file`

🎟️ `allow [all] [subnet]`

`stratum` stratum

`distance` distance

`activate` distance

`orphan`

`waitsynced` interval

`waitunsynced` interval

`ntsservercert` file

`ntsserverkey` file

`ntsprocesses` processes

`maxntsconnections` connections

`ntsaeads` ID...

`ntsdumpdir` directory

`ntsntpserver` hostname

`ntsrotate` interval

`port` port

`ratelimit` [option]...

`ntsratelimit` [option]...

`smoothtime` max-freq max-wander [leaponly]

`lock_all` 🔒

`pidfile` file 🪪

`ptpport` port 🕰️

`ptpdomain` domain 🌐

`sched_priority` priority ⚡

`user` user 🧑‍💻