Ntp · XB Field Notes

Check timesyncd’s service state and clock evidence separately

Thu, 11 Mar 2027 00:00:00 +0000

systemd-timesyncd is a minimal SNTP client for synchronizing the local system clock against configured time sources. It can help keep certificate checks and wall-clock timestamps meaningful, but it does not provide an unconditional accuracy guarantee. Whether the daemon can run, whether it receives acceptable samples, and whether the system reports synchronization are separate facts to establish.

When it breaks

The daemon does not always smooth corrections. The documented behavior steps the clock for large offsets and adjusts it gradually for smaller differences. A machine starting far from correct time may therefore experience a discontinuity. Use monotonic clocks for elapsed-duration measurements, and design applications that interpret wall-clock timestamps to handle corrections rather than assuming time always moves smoothly.

FallbackNTP is not a general emergency list used whenever an explicitly configured server becomes unreachable. It applies when no other server information is known. Global NTP entries and per-link sources supplied through networkd take precedence over that fallback. Inspect the actual source selection and configuration drop-ins before concluding that a particular backup server must have been contacted.

An unsynchronized state also does not prove UDP traffic is blocked. A service can be absent, disabled, excluded by unit conditions, unable to adjust time, or rejecting unsuitable samples. Conversely, a global synchronization property does not identify which process supplied time. Distinguish the manager’s service state, the time client’s observations, and the kernel-level synchronization indication.

Check it quickly

This failure-mode exercise runs as root inside a disposable Debian 12 Docker container with systemd 252.39 as PID 1. Its init process was launched through /usr/bin/setpriv --bounding-set=-sys_time,-sys_module /sbin/init; the capability restriction prevents adjustment of the Docker VM’s shared clock. The script verifies that prerequisite before requesting any service start, and requires the packaged container-exclusion condition:

from pathlib import Path
import json,subprocess

def run(*args):
 result=subprocess.run(args,text=True,capture_output=True,timeout=10)
 assert result.returncode==0,(args,result.stderr)
 return result.stdout.strip()
def properties(unit):
 output=run('systemctl','show',unit,'-p','ActiveState','-p','SubState','-p','MainPID','-p','ConditionResult')
 return dict(line.split('=',1) for line in output.splitlines())
# This failure-mode exercise requires an isolated container that cannot set time.
status=dict(line.split(':',1) for line in Path('/proc/1/status').read_text().splitlines() if ':' in line)
assert int(status['CapBnd'].strip(),16)&(1<<25)==0,'PID 1 must lack CAP_SYS_TIME'
assert run('systemd-detect-virt','--container')=='docker'
unit='systemd-timesyncd.service';definition=run('systemctl','cat',unit)
assert 'ConditionCapability=CAP_SYS_TIME' in definition
assert 'ConditionVirtualization=!container' in definition
assert properties(unit)['ActiveState']=='inactive'
run('systemctl','start',unit)
state=properties(unit)
assert state=={'MainPID':'0','ActiveState':'inactive','SubState':'dead','ConditionResult':'no'},state
clock=dict(line.split('=',1) for line in run('timedatectl','show','-p','CanNTP','-p','NTP','-p','NTPSynchronized').splitlines())
assert all(value in ('yes','no') for value in clock.values())
print('start command returned zero; unit stayed inactive with PID 0 and failed conditions')
print('clock properties:',json.dumps(clock,sort_keys=True))
print('PID 1 lacks time-setting capability; Docker condition also excludes this packaged service')
print('no clock-setting command was issued and no NTP synchronization was claimed')

The start command returns zero, yet the unit remains inactive with main PID zero and ConditionResult=no. A skipped conditional activation is not the same as a successfully running daemon. The fixture’s packaged unit requires the time-setting capability and excludes containers; this environment satisfies neither prerequisite. The observed outcome is therefore explained before any theory about blocked NTP packets is needed.

The recorded clock properties are CanNTP=yes, NTP=no, and NTPSynchronized=no. They describe different aspects of the system’s time-service interface. In particular, knowing that NTP service support is available does not make that service active or establish that the clock has synchronized. The script reports the actual values rather than replacing them with an assumed healthy result.

No clock-setting command is issued, and no successful NTP exchange or clock adjustment is claimed. This verifies a real activation failure mode in a container that cannot set time. Testing successful clock discipline requires an appropriate machine or independently clocked virtual machine with the required authority and a reachable, suitable time source.

When the daemon is actually running, its timedatectl timesync-status interface provides client-specific server and synchronization information. Check service state before relying on that interface; a request to an unavailable service can wait for D-Bus activation and time out. The container probe reached its five-second observation limit, which was treated as unavailable evidence, not a successful synchronization check.

Build a time requirement that can be verified

Choose sources appropriate to the network and inspect offset, delay, and accepted-source quality over time. Reachability alone does not make a server accurate or trustworthy. Polling and root-distance settings influence sample handling; they do not turn a minimal client into a complete time-distribution service or establish an accuracy service-level agreement by themselves.

The saved /var/lib/systemd/timesync/clock timestamp helps initialize time across boots without a reliable hardware clock. It can also be updated periodically without a recent synchronization, so its existence is not proof of a fresh accepted network sample. Rough initialization and synchronization to a reference clock are different milestones.

If dependent work requires synchronized time, configure and verify the appropriate wait service and ordering after time-sync.target. Starting timesyncd alone does not delay every application until an accurate reference is reached. Keep the startup requirement and runtime monitoring explicit, and use the evidence from the actual deployment rather than a generic “NTP enabled” label.

Sources

systemd 252 systemd-timesyncd.service, SNTP behavior, large clock steps, saved clock state, and synchronization signals, checked 2026-09-12.
systemd 252 timesyncd.conf, source selection, fallback precedence, polling, and root-distance limits, checked 2026-09-12.
systemd 252 org.freedesktop.timedate1, NTP availability, enablement, and the kernel synchronization property, checked 2026-09-12.
systemd 252 systemd-time-wait-sync.service, ordering dependent services after verified time synchronization, checked 2026-09-12.

Servers need observable time discipline

Wed, 02 Sep 2026 00:00:00 +0000

A time daemon is useful only when its operating state supports the application’s time requirements. A running process can have no usable source, and a selected source can still be wrong or insufficiently measured. Treat time service health as an observable chain: source configuration, successful observations, selection, uncertainty, and permitted clock control. A green process indicator covers only the beginning.

Read what the daemon actually reports

Chrony’s tracking report distinguishes the reference, stratum, last update, remaining system-time correction, estimated frequency, frequency skew, root delay, and root dispersion. These fields answer different questions. Offset concerns time difference; frequency concerns clock rate; skew expresses uncertainty in that frequency estimate. Root delay and dispersion contribute to the uncertainty inherited from the reference path. One small offset does not summarize them all.

The sources report identifies candidates and the selected source. In the usual display, ^* denotes the selected NTP server. Reach is an octal history register, with 377 representing successful responses in the last eight polling opportunities; it is not a percentage or a promise of future availability. LastRx helps reveal how old a received sample is. Read source state alongside tracking rather than interpreting a process uptime counter as synchronization evidence.

A daemon can continue estimating time after an upstream interruption, but uncertainty can grow. Monitor update age and error estimates against the application’s tolerances, and distinguish temporary holdover from indefinitely trustworthy time. Several server names are not necessarily independent references if they share infrastructure. Source selection reduces some failure risks without proving every upstream claim correct.

When it breaks

Containers commonly share the host’s kernel clock. Running a time daemon inside one does not give it an independent civil clock to adjust. Chronyd’s -x option deliberately disables system-clock control while retaining estimation and server operation. A client can therefore report synchronization while the system clock remains uncorrected. Verify the active mode and the layer responsible for host time.

The local directive is another source of misleading confidence. It lets chronyd appear synchronized without an external reference, which can support intentional isolated-network arrangements. Enabling it solely to silence a synchronization alarm hides the missing reference. Check the reference identity and the intended source policy before interpreting Normal as evidence of UTC accuracy.

Operational checks also need meaningful limits. Chronyc waitsync can wait for synchronization and optionally bound remaining correction and frequency skew. Zero limits disable those additional checks. A successful invocation with both limits disabled is weaker evidence than a gate enforcing application-specific tolerances. It still cannot authenticate the correctness of an arbitrary upstream clock.

Check it quickly

Use a fresh disposable Debian 12 Docker container with Python 3 and chrony installed. Prepare packages with apt-get update and apt-get install -y python3 chrony, save this as chrony-status.py, and run python3 chrony-status.py as root. Keep host networking disabled and drop SYS_TIME capability. The recorded run used chrony 4.3 and Python 3.11.2.

from pathlib import Path
from tempfile import TemporaryDirectory
import json
import os
import socket
import subprocess
import time

assert os.geteuid() == 0 and Path('/.dockerenv').exists(), 'use a disposable root Linux container'
with TemporaryDirectory(prefix='chrony-status-') as directory:
 root = Path(directory)
 processes = []
 with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as reservation:
 reservation.bind(('127.0.0.1', 0))
 port = reservation.getsockname()[1]

 def start(name, extra):
 config = root / (name + '.conf')
 config.write_text(f'pidfile {root}/{name}.pid\ncmdport 0\nbindcmdaddress {root}/{name}.sock\n' + extra)
 process = subprocess.Popen(['chronyd', '-x', '-n', '-u', 'root', '-f', str(config)],
 stdout=subprocess.PIPE, stderr=subprocess.PIPE)
 processes.append(process)
 deadline = time.monotonic() + 5
 while not (root/(name+'.sock')).exists():
 assert process.poll() is None, 'chronyd exited before command socket was ready'
 if time.monotonic() > deadline:
 raise AssertionError('command socket not ready')
 time.sleep(0.05)
 return process

 def command(name, *args):
 return subprocess.run(['chronyc', '-n', '-h', str(root/(name+'.sock')), *args],
 capture_output=True, text=True, timeout=10)

 def tracking(name):
 result = command(name, 'tracking')
 assert result.returncode == 0, result.stderr
 return {line.split(':', 1)[0].strip(): line.split(':', 1)[1].strip()
 for line in result.stdout.splitlines() if ':' in line}

 try:
 client = start('client', f'port 0\nserver 127.0.0.1 port {port} iburst minpoll 0 maxpoll 0\n')
 before = tracking('client')
 before_gate = command('client', 'waitsync', '1', '0', '0', '0.1')
 assert client.poll() is None and before['Leap status'] == 'Not synchronised'
 assert before_gate.returncode != 0
 start('source', f'port {port}\nbindaddress 127.0.0.1\nlocal stratum 8\nallow 127.0.0.1\n')
 assert command('client', 'burst', '4/4').returncode == 0
 deadline = time.monotonic() + 25
 while time.monotonic() < deadline:
 sources = command('client', 'sources').stdout
 after = tracking('client')
 if '^* 127.0.0.1' in sources and after['Leap status'] == 'Normal':
 break
 time.sleep(0.2)
 else:
 raise AssertionError('local source was not selected')
 assert after['Stratum'] == '9'
 after_gate = command('client', 'waitsync', '1', '0', '0', '0.1')
 assert after_gate.returncode == 0
 source_tracking = tracking('source')
 assert source_tracking['Reference ID'].startswith('7F7F0101')
 print(json.dumps({'daemon_alive_while_unsynchronised': True,
 'before': before, 'after': after, 'selected_sources': sources,
 'waitsync_returncodes': [before_gate.returncode, after_gate.returncode],
 'source_reference': source_tracking['Reference ID'],
 'system_clock_adjustment_disabled': True,
 'external_UTC_accuracy_tested': False}))
 finally:
 for process in reversed(processes):
 process.terminate()
 process.communicate(timeout=5)

The script first starts a client pointing to an unused loopback port. Its process stays alive, but tracking reports Not synchronised and a one-attempt waitsync gate fails. It then starts a separate local stratum-eight source, requests a burst, and waits for actual selection. The client reports ^* 127.0.0.1, stratum nine, and Normal; the same gate now returns success. Both daemons run with clock adjustment disabled and are terminated afterward.

In the recorded initial selection, frequency skew remained very large even though the synchronization gate passed. The source reference was 7F7F0101, identifying local-reference operation rather than external synchronization. The fixture prints the full observations so these limitations remain visible. All assertions passed, but no external UTC accuracy, long-term convergence, loss-of-source recovery, or actual clock correction was tested. Use this counterexample to separate process availability, synchronization status, quality bounds, and authoritative time in production monitoring.

Sources

chronyc 4.3 manual, tracking fields, source selection and waitsync thresholds, checked 2026-09-13.
chronyd 4.3 manual, clock adjustment and the -x mode, checked 2026-09-13.
chrony.conf 4.3 manual, local-reference mode and source configuration, checked 2026-09-13.
RFC 5905: Network Time Protocol Version 4, synchronization state and uncertainty, checked 2026-09-13.

Ntp · XB Field Notes

Check timesyncd’s service state and clock evidence separately

When it breaks

Check it quickly

Build a time requirement that can be verified

Further reading

Sources

Servers need observable time discipline

Read what the daemon actually reports

When it breaks

Check it quickly

Further reading

Sources