Wait for Synchronised Time with systemd-time-wait-sync

A service that races the clock can log garbage timestamps or fail a certificate check, and systemd-time-wait-sync.service exists to stop that. It is a boot gate that lets units ordered after time-sync.target wait until the kernel clock is marked synchronised. The installed machine here uses systemd 255.4-1ubuntu8.17 from Ubuntu, and the examples target that behaviour.

Allow about fifteen minutes. You need a shell and administrator access for the enablement step. This service does not set the clock and is not an NTP client. It waits for systemd-timesyncd.service to report success, or falls back to the kernel synchronisation indication for other NTP clients such as ntpd or chronyd.

1. Check the installed unit before enabling it

Inspect the unit and package version first. These are read-only commands and do not need sudo:

$ systemctl --version
systemd 255 (255.4-1ubuntu8.17)
$ systemctl cat systemd-time-wait-sync.service
[Unit]
Description=Wait Until Kernel Time Synchronized
ConditionCapability=CAP_SYS_TIME
ConditionVirtualization=!container
Before=time-sync.target shutdown.target
Wants=time-sync.target

[Service]
Type=oneshot
ExecStart=/usr/lib/systemd/systemd-time-wait-sync
TimeoutStartSec=infinity
RemainAfterExit=yes

The real unit has more in it. Comments and packaging details are trimmed above; the useful boundaries are the conditions and ordering.
It gets skipped in two cases: when the manager lacks CAP_SYS_TIME, or when it is running inside a container.
It can wait forever. The installed unit sets TimeoutStartSec=infinity, so its start may hang indefinitely.

Checkpoint: confirm the helper exists and that the synchronisation marker is a runtime file:

$ command -v systemctl
/usr/bin/systemctl
$ ls -l /usr/lib/systemd/systemd-time-wait-sync /run/systemd/timesync/synchronized

2. Check the time synchronisation provider

The wait service needs another component to actually move the clock towards an accurate reference. Inspect the usual provider without changing state:

$ systemctl status systemd-timesyncd.service --no-pager
$ timedatectl show -p NTPSynchronized -p NTPService --value

Your output will vary. A running systemd-timesyncd.service is one valid provider. A different NTP daemon works too, but the manpage describes the kernel-clock check as a fallback and says detection is not reliable. Do not enable this gate assuming it will repair an NTP configuration problem for you.

If the provider is missing, stopped or unable to reach its servers, the wait service can sit pending. Diagnose that provider separately. Do not delete /run/systemd/timesync/synchronized to force a test: it is runtime state, and removing it can make the next boot or service start wait again.

3. Enable the boot gate

Enabling is a persistent change, and starting the service can hold the transaction until time is synchronised. Schedule a maintenance window if other boot jobs depend on this target. The following command needs elevated privileges:

$ sudo systemctl enable --now systemd-time-wait-sync.service
Created symlink /etc/systemd/system/sysinit.target.wants/systemd-time-wait-sync.service -> /usr/lib/systemd/system/systemd-time-wait-sync.service

The symlink message appears only when the unit was not already enabled. --now also starts it immediately, so the command may take time or sit waiting while the provider obtains a valid reference. A successful command does not mean the NTP daemon itself was configured correctly.

Checkpoint: ask systemd for the enablement and runtime state:

$ systemctl is-enabled systemd-time-wait-sync.service
enabled
$ systemctl status systemd-time-wait-sync.service --no-pager
● systemd-time-wait-sync.service - Wait Until Kernel Time Synchronized
     Loaded: loaded (/usr/lib/systemd/system/systemd-time-wait-sync.service; enabled)
     Active: active (exited)

The description may use slightly different spacing, and the boot timestamps are host-specific. active (exited) is expected for this oneshot service, because RemainAfterExit=yes records that the wait completed.

4. Order your own service after the target

The gate only affects units that are ordered after time-sync.target. Add both a dependency and an ordering relationship to a service that genuinely needs correct wall-clock time at start:

# /etc/systemd/system/example-worker.service.d/time.conf
[Unit]
Wants=time-sync.target
After=time-sync.target

Create the drop-in as root, then reload the manager. The directory and file are persistent configuration, so keep a copy in your normal configuration management:

$ sudo install -d /etc/systemd/system/example-worker.service.d
$ sudoedit /etc/systemd/system/example-worker.service.d/time.conf
$ sudo systemctl daemon-reload
$ systemctl cat example-worker.service

Wants= asks systemd to include the target in the transaction. After= controls order; it does not, by itself, pull the target in. Conversely, a dependency without ordering does not make the worker wait. Replace example-worker.service with the real unit name; do not paste the placeholder literally.

Do not add this ordering to every service. One that only needs monotonic time, or one that is part of the time provider itself, may deadlock or pick up an unnecessary boot delay. Read its startup requirements first.

5. Verify the target and the wait condition

Inspect the dependency graph and current properties without restarting the worker:

$ systemctl list-dependencies time-sync.target --all --no-pager
time-sync.target
● └─systemd-time-wait-sync.service
$ systemctl show systemd-time-wait-sync.service \
    -p ActiveState -p SubState -p ConditionResult -p ExecMainStatus
ActiveState=active
SubState=exited
ConditionResult=yes
ExecMainStatus=0

The dependency listing depends on which units are enabled on the host. A condition result of no means systemd skipped the unit, commonly because the process is in a container or lacks the required capability; it is not evidence that the clock is synchronised.

Check the clock state separately:

$ timedatectl show -p NTPSynchronized --value
yes

If this prints no, inspect the chosen NTP provider and its journal:

$ systemctl --failed
$ journalctl -u systemd-timesyncd.service -b --no-pager

Use the journal unit that actually provides time on your host. Running journalctl for an inactive or nonexistent provider can produce an empty result without explaining the real failure.

6. Recover from a wait that never finishes

First establish whether the service is waiting or was skipped:

$ systemctl show systemd-time-wait-sync.service \
    -p ActiveState -p SubState -p ConditionResult -p JobTimeoutUSec
$ systemctl status systemd-time-wait-sync.service --no-pager

If the unit is activating, do not repeatedly start it. Fix the NTP provider or its network path, then let the existing job complete.

Recovery: if this gate is causing an operational incident and you need the previous boot behaviour back, disable and stop it explicitly:

$ sudo systemctl disable --now systemd-time-wait-sync.service
Removed "/etc/systemd/system/sysinit.target.wants/systemd-time-wait-sync.service"

That removes this unit from future boots and stops its current wait. It does not disable systemd-timesyncd.service or another NTP daemon. If you also added a drop-in for your worker, remove that file only after confirming the service no longer needs the ordering, then run sudo systemctl daemon-reload. Deleting configuration without checking its owner is irreversible, so keep a copy first.

Done means

Version and conditions checked. The installed systemd version and unit conditions were reviewed.
Provider present. An NTP provider exists and its synchronisation state is understood.
Gate enabled deliberately. systemd-time-wait-sync.service is enabled only where its boot delay is acceptable.
Ordering set correctly. Dependent services use both Wants=time-sync.target and After=time-sync.target where required.
Wait completes. The wait service reaches active (exited) with a successful main status.
Rollback known. You know how to disable this gate without disabling the time provider.