Reference	Topics
core-configuration.md	Upgrade requirements, daemon and client behavior, source options, packet controls, logging, service integration
reference-clocks.md	RTC, PHC, PPS, GPS, gpsd, reachability, locking, startup, and time scales
hardware-timestamping-and-ptp.md	Hardware timestamping, interleaved NTP, NTP-over-PTP, transparent clocks, PHCs, and virtualization
network-time-security.md	NTS client state, authentication diagnostics, server setup, policy compatibility, and verification
monitoring-and-troubleshooting.md	`chronyc`, exporter metrics, source selection, transport errors, client records, and network recovery

Using this patch

Check the upgrade notes before carrying an older configuration or build setup forward.
Use the quick references below for common decisions, then load the indexed topic file for constraints and edge cases.
Treat examples as fragments: retain the access controls, source diversity, measured offsets, and platform-specific paths required by the deployment.

Breaking changes and upgrade checks

Configuration and build compatibility

Since 4.7, integer configuration values receive sanity checks. Values that were accepted despite being nonsensical can now fail validation.
NTS builds require Nettle 3.6 or newer and GnuTLS 3.6.14 or newer.
Building without POSIX threads is no longer supported.
On RHEL, the FIPS and OSPP profiles are incompatible with NTS and can make an NTS-configured daemon exit fatally. A service-only exception can be set in /etc/sysconfig/chronyd:

GNUTLS_FORCE_FIPS_MODE=0

Security and compatibility behavior

In 4.8, root-run chronyc -u drops privileges to the configured client user.
The chronyc socket is hidden to prevent unsafe permission changes against it.
Keep both endpoints of an NTP-over-PTP connection on the same chrony version.
Do not discipline the physical PHC used for hardware-timestamped NTP-over-PTP; use a virtual clock if PTP must share the interface.

Core 4.7–4.8 configuration

Source retention and identity

The maxunreach source option, added in batch 4.8-configuration, limits the number of polls for which an unreachable NTP source or refclock can remain selected. It defaults to 100000, and retention also requires a sample newer than the oldest sample from any reachable source.

server ntp.example.net maxunreach 8
refclock PPS /dev/pps0 maxunreach 4

The copy option lets a closely related client assume an upstream server's reference ID and stratum. It is useful when one daemon disciplines the system clock and a second chronyd -x serves it. Prevent synchronization loops; peer does not support copy.

server 127.0.0.1 copy

Traffic and remote-command controls

opencommands selects which monitoring commands are remotely available. Expose only the required command surface.
dscp marks transmitted NTP packets with a DSCP value from 0 through 63; the default is 0. For example, dscp 46 selects Expedited Forwarding.
ptpdomain filters NTP-over-PTP traffic by PTP domain. Its range is 0 through 255 and its default is 123.

dscp 46
ptpdomain 42

Persistence and lifecycle

driftfile accepts an interval option to control drift-data write frequency.
local accepts waitsynced and waitunsynced for explicit synchronized and unsynchronized wait behavior.
chronyd supports systemd Type=notify readiness signaling.
cyclelogs attempts to reopen the message log selected by -l.

Selection and reachability

chronyc sources prints Reach as an eight-bit poll history in octal. A set bit records a valid response or refclock sample; it does not prove the measurement passed every synchronization test.

In chronyc selectdata, uppercase S means that the source has only measurements older than reachable sources or has exceeded its maxunreach limit.

chronyc sources -v
chronyc selectdata -v

For a persistent network-delay increase, NTP test C can reject measurements for hours while older low-delay samples define its expectation. Inspect with ntpdata; if the change is permanent, clear retained samples.

chronyc ntpdata
chronyc reset sources

Repeated cases can be mitigated with a larger maxclockerror, or a very large maxdelaydevratio that effectively disables the test at the cost of weaker delay filtering.

Reference clocks and PPS/GPS

New and changed drivers

Batch 4.7 adds an RTC refclock driver.
A PHC refclock can use a network-interface name instead of a /dev/ptpN path.
Refclocks no longer need multiple samples per poll and remain reachable when excessive-delay samples are discarded.
In batch 4.8, extpps works on Linux 6.15 and newer.
Refclock samples are validated before updating reachability, so invalid samples no longer make a source appear reachable.

Lock a precise PPS to coarse time of day

For one GPS receiver providing NMEA through gpsd SHM and PPS through /dev/pps0, lock PPS to the NMEA refid and mark PPS trusted. This allows PPS selection even when the much less accurate correlated NMEA source is a falseticker.

refclock SHM 0 refid NMEA offset 0.000 precision 1e-3 poll 0 filter 3
refclock PPS /dev/pps0 refid PPS lock NMEA poll 3 trust

Measure late NMEA delivery using statistics logs. A message arriving 900–1000 ms after its pulse can lock PPS to the wrong whole second; apply the opposite of the measured NMEA estimated offset and improve or reduce serial output if needed.

gpsd socket choice

gpsd 3.25 adds /run/chrony.clk.ttyX.sock for serial date-time; the older /run/chrony.ttyX.sock carries PPS only.
Use the .clk. socket as a non-selected lock source, or use SHM 0 with older gpsd.
For a gpsd-backed SOCK refclock, start gpsd after chronyd creates the socket and pass -n so gpsd polls without waiting for a client.

Hardware timestamping and NTP-over-PTP

Check ethtool -T before enabling hardware timestamps. The interface needs hardware transmit and receive timestamping, a matching /dev/ptpN, and HWTSTAMP_FILTER_ALL for ordinary NTP packets.

ethtool -T eth2

A local hardware-timestamped client can poll both NTP and the hardware clock at 16 Hz. F323 is experimental and improves stability when both endpoints support it.

server 192.168.123.1 minpoll -4 maxpoll -4 xleave extfield F323 filter 5
hwtimestamp * minpoll -4

For one-step end-to-end transparent switches, put NTP in PTP event messages on port 319 and request F324 at the client. Two-step, peer-to-peer, and boundary PTP clocks do not provide useful corrections for this mode.

server 192.168.123.1 xleave extfield F324 port 319
ptpport 319

At nanosecond precision, set a smaller clockprecision, at least on the server. Cross timestamping is automatic when the kernel provides it; nocrossts disables it. Transparent-clock corrections do not remove asymmetric PCIe latency between the NIC and system clock.

Limit hwtimestamp to interfaces not used by another timestamping application. Large interleaved-mode servers also need enough clientloglimit space for per-client transmit timestamps.

Network Time Security

Require NTS on a source with nts, and persist established state with ntsdumpdir to avoid a fresh NTS-KE exchange after every reboot.

server time.example.com iburst nts
ntsdumpdir /var/lib/chrony

Check authentication with chronyc -N authdata. A working NTS source reports mode NTS, nonzero KeyID, Type, and KLen, no NAKs, and at least one stored cookie. Packet reachability alone does not establish authentication, and failed negotiation does not downgrade silently.

An NTS server needs a readable PEM key, a PEM certificate file containing required intermediates, TCP 4460 for NTS-KE, and UDP 123 for NTP.

ntsserverkey /etc/pki/tls/private/time.example.com.key
ntsservercert /etc/pki/tls/certs/time.example.com.crt
ntsdumpdir /var/lib/chrony

Verify from another host without changing its clock, then inspect server counters:

chronyd -Q -t 3 'server time.example.com iburst nts maxsamples 1'
chronyc serverstats

Monitoring and first-response diagnostics

With cmdport 0, the exporter can use unix:///run/chrony/chronyd.sock instead of [::1]:323. The extended ntpdata source collector requires the socket; run the exporter as root or the chrony user, and add --collector.chmod-socket when running as root.

chrony_exporter --chrony.address=unix:///run/chrony/chronyd.sock \
  --collector.sources.with-ntpdata --collector.chmod-socket

An absolute clock-error bound is:

abs(chrony_tracking_last_offset_seconds) + chrony_tracking_root_dispersion_seconds + (0.5 * chrony_tracking_root_delay_seconds)

506 Cannot talk to daemon: check daemon availability, UDP 323, firewall rules, and cmdallow/bindcmdaddress.
501 Not authorised: the command needs the privileged Unix socket, or the socket directory ownership or permissions prevented its creation.
activity reporting unknown addresses means DNS resolution is incomplete; chronyc -N sources -a still shows configured names.
Windows NTP sources can advertise several seconds of root dispersion. Confirm with ntpdata, then raise maxdistance only as far as required.
After an unannounced disconnection, chronyc online triggers immediate measurements when connectivity returns; pair it with offline handling.

Platform deployment checks

A KVM guest needs CONFIG_PTP_1588_CLOCK_KVM for a virtual PHC.
On RHEL, mask 20-chrony-onoffline if routes managed outside NetworkManager must not leave sources offline.
On Gentoo, direct Linux PPS is a separate non-default pps USE flag; verify the other required time, security, and refclock feature gates.
Gentoo OpenRC reads /etc/conf.d/chronyd; -u ntp -F 2 selects the account and level-two seccomp, while -s -r restores RTC-derived time and saved samples when configured.
VMware Tools immediately steps a resumed guest to repair the lifecycle-induced offset created while the guest clock and synchronizer were suspended.