checkId: check.timestamp.timesync.system plugin: stellaops.doctor.timestamping severity: fail tags: [timestamping, timesync, ntp, system, air-gap]

System Time Synchronization

This Stella Ops Doctor check confirms that the host clock is closely synchronized with a trusted NTP source. It is most relevant to operators of any deployment that signs or verifies timestamped release evidence, because an inaccurate system clock silently corrupts timestamp tokens and breaks downstream certificate and audit validation. This is a fail-severity check.

What It Checks

Checks that the system clock is synchronized with NTP servers. The check:

Air-Gap Behavior

When the deployment is sealed by AirGap policy, or STELLAOPS_DOCTOR_OFFLINE_PROFILE=true forces Doctor offline mode, the check only probes configured local/private NTP servers. If all configured servers are external, Doctor returns a sealed-mode Healthy result with airGapSealed=true and a message explaining that the external probe was disabled. This plugin uses Healthy for sealed skips because the timestamping health model does not expose a Skip status.

Use a local NTP source, hypervisor time sync, or an offline-kit-approved time source for sealed deployments. When sealed and no internal (loopback / RFC1918) NTP server is configured, the check falls back to the offline-kit NTP stratum proof shipped at var/lib/stellaops/airgap/timestamping/ntp/<sha256>.json via IAirGapArtefactStore; the proof’s recorded serverTime − queriedAt skew is compared to the warning/critical thresholds and the check emits the canonical evidence rows airGapSealed=true, source=offline-kit, artefactSha256=…, artefactIssuedAt=…, plus ntpServer, ntpStratum, and observedSkewMs. When no proof is shipped, the check fails closed (source=offline-kit-missing). The last successful NTP query is cached for 5 minutes to avoid repeated hot fetches during frequent Doctor runs.

Why It Matters

Accurate system time is fundamental to timestamping. Clock skew causes timestamp tokens to have incorrect genTime values, which can invalidate evidence during verification. Large skew can also cause TLS certificate validation failures, authentication token rejection, and incorrect audit log ordering.

Common Causes

How to Fix

Docker Compose

Docker containers inherit the host’s clock. Fix time sync on the Docker host:

# Check host time sync
timedatectl status

# Enable NTP sync
sudo timedatectl set-ntp true

# Or configure chrony
sudo systemctl restart chronyd

Bare Metal / systemd

# Check time sync status
timedatectl status
chronyc tracking

# Force sync
sudo chronyc makestep

# Enable NTP
sudo timedatectl set-ntp true
sudo systemctl enable chronyd

Kubernetes / Helm

Kubernetes nodes must have NTP configured. Verify on each node:

# On each node
timedatectl status
chronyc tracking

Ensure NTP is part of your node provisioning configuration.

Verification

stella doctor run --check check.timestamp.timesync.system