Chrony Knowledge Patch

---
name: chrony-knowledge-patch
description: chrony
version: "4.8"
license: MIT
metadata:
  author: Nevaberry
---


# chrony 4.7–4.8 Knowledge Patch

## Reference index

| Reference | Topics |
| --- | --- |
| [core-configuration.md](references/core-configuration.md) | Upgrade requirements, daemon and client behavior, source options, packet controls, logging, service integration |
| [reference-clocks.md](references/reference-clocks.md) | RTC, PHC, PPS, GPS, gpsd, reachability, locking, startup, and time scales |
| [hardware-timestamping-and-ptp.md](references/hardware-timestamping-and-ptp.md) | Hardware timestamping, interleaved NTP, NTP-over-PTP, transparent clocks, PHCs, and virtualization |
| [network-time-security.md](references/network-time-security.md) | NTS client state, authentication diagnostics, server setup, policy compatibility, and verification |
| [monitoring-and-troubleshooting.md](references/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`:

```sh
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.

```conf
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`.

```conf
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.

```conf
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.

```sh
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.

```sh
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.

```conf
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.

```sh
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.

```conf
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.

```conf
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.

```conf
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.

```conf
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:

```sh
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.

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

An absolute clock-error bound is:

```promql
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.