diff --git a/man/systemd-time-wait-sync.service.xml b/man/systemd-time-wait-sync.service.xml
index 28f55a184e..cd26ae4f0b 100644
--- a/man/systemd-time-wait-sync.service.xml
+++ b/man/systemd-time-wait-sync.service.xml
@@ -29,15 +29,17 @@
Description
- systemd-time-wait-sync is a system service that delays the start of units that depend on
- time-sync.target until the system time has been synchronized with an accurate time source by
+ systemd-time-wait-sync is a system service that delays the start of units that
+ are ordered after time-sync.target (see
+ systemd.special7 for
+ details) until the system time has been synchronized with an accurate remote reference time source by
systemd-timesyncd.service.
- systemd-timesyncd.service notifies on successful synchronization.
- systemd-time-wait-sync also tries to detect when the kernel marks the time as synchronized,
- but this detection is not reliable and is intended only as a fallback for other services that can be used to
- synchronize time (e.g., ntpd, chronyd).
-
+ systemd-timesyncd.service notifies systemd-time-wait-sync
+ about successful synchronization. systemd-time-wait-sync also tries to detect when
+ the kernel marks the system clock as synchronized, but this detection is not reliable and is intended
+ only as a fallback for compatibility with alternative NTP services that can be used to synchronize time
+ (e.g., ntpd, chronyd).
diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml
index ff14c40665..9ab4af9763 100644
--- a/man/systemd-timesyncd.service.xml
+++ b/man/systemd-timesyncd.service.xml
@@ -29,35 +29,42 @@
Description
- systemd-timesyncd is a system service
- that may be used to synchronize the local system clock with a
- remote Network Time Protocol server. It also saves the local time
- to disk every time the clock has been synchronized and uses this
- to possibly advance the system realtime clock on subsequent
- reboots to ensure it monotonically advances even if the system
- lacks a battery-buffered RTC chip.
+ systemd-timesyncd is a system service that may be used to synchronize the
+ local system clock with a remote Network Time Protocol (NTP) server. It also saves the local time to disk
+ every time the clock has been synchronized and uses this to possibly advance the system realtime clock on
+ subsequent reboots to ensure it (roughly) monotonically advances even if the system lacks a
+ battery-buffered RTC chip.
- The systemd-timesyncd service
- specifically implements only SNTP. This minimalistic
- service will set the system clock for large offsets or
- slowly adjust it for smaller deltas. More complex use
- cases are not covered by systemd-timesyncd.
+ The systemd-timesyncd service implements SNTP only. This minimalistic service
+ will step the system clock for large offsets or slowly adjust it for smaller deltas. Complex use cases
+ that require full NTP support (and where SNTP is not sufficient) are not covered by
+ systemd-timesyncd.
- The NTP servers contacted are determined from the global
- settings in
- timesyncd.conf5,
- the per-link static settings in .network
- files, and the per-link dynamic settings received over DHCP. See
- systemd.network5
- for more details.
+ The NTP servers contacted are determined from the global settings in
+ timesyncd.conf5, the
+ per-link static settings in .network files, and the per-link dynamic settings
+ received over DHCP. See
+ systemd.network5 for
+ further details.
timedatectl1's
- set-ntp command may be used to enable and
- start, or disable and stop this service.
+ set-ntp command may be used to enable and start, or disable and stop this
+ service.
timedatectl1's
timesync-status or show-timesync command can be used to show the
current status of this service.
+
+ systemd-timesyncd initialization delays the start of units that are ordered
+ after time-set.target (see
+ systemd.special7 for
+ details) until the local time has been updated from /var/lib/systemd/timesync/clock
+ (see below) in order to make it roughly monotonic. It does not delay other units until synchronization
+ with an accurate reference time sources has been reached. Use
+ systemd-time-wait-sync.service8
+ to achieve that, which will delay start of units that are ordered after
+ time-sync.target until synchronization to an accurate reference clock is
+ reached.
@@ -68,9 +75,10 @@
/var/lib/systemd/timesync/clock
- The modification time of this file indicates the timestamp of the last successful
- synchronization (or at least the systemd build date, in case synchronization was not
- possible).
+ The modification time ("mtime") of this file indicates the timestamp of the last successful
+ synchronization (or at least the systemd build date, in case synchronization was not possible). It
+ is used to ensure that the system clock remains roughly monotonic across reboots, in case no local
+ RTC is available.
@@ -80,7 +88,7 @@
A file that is touched on each successful synchronization, to assist
systemd-time-wait-sync and other applications to detecting synchronization
- events.
+ with accurate reference clocks.
@@ -95,6 +103,7 @@
systemd.network5,
systemd-networkd.service8,
systemd-time-wait-sync.service8,
+ systemd.special7,
timedatectl1,
localtime5,
hwclock8
diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 1977157f9e..e731c9ced2 100644
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -998,36 +998,103 @@
time-set.target
- Services responsible for setting the system clock from
- a local source (such as a maintained timestamp file or
- imprecise real-time clock) should pull in this target and
- order themselves before it. Services where approximate time
- is desired should be ordered after this unit, but not pull
- it in. This target does not provide the accuracy guarantees
- of time-sync.target.
+ Services responsible for setting the system clock (CLOCK_REALTIME)
+ from a local source (such as a maintained timestamp file or imprecise real-time clock) should
+ pull in this target and order themselves before it. Services where approximate, roughly monotonic
+ time is desired should be ordered after this unit, but not pull it in.
+
+ This target does not provide the accuracy guarantees of
+ time-sync.target (see below), however does not depend on remote clock
+ sources to be reachable, i.e. the target is typically not delayed by network problems and
+ similar. Use of this target is recommended for services where approximate clock accuracy and
+ rough monotonicity is desired but activation shall not be delayed for possibly unreliable network
+ communication.
+
+ The service manager automatically adds dependencies of type After= for
+ this target unit to all timer units with at least one OnCalendar=
+ directive.
+
+ The
+ systemd-timesyncd.service8
+ service is a simple daemon that pulls in this target and orders itself before it. Besides
+ implementing the SNTP network protocol it maintains a timestamp file on disk whose modification
+ time is regularlary updated. At service start-up the local system clock is set from that modification time,
+ ensuring it increases roughly monotonically.
+
+ Note that ordering a unit after time-set.target only has effect if
+ there's actually a service ordered before it that delays it until the clock is adjusted for rough
+ monotonicity. Otherwise, this target might get reached before the clock is adjusted to be roughly
+ monotonic. Enable
+ systemd-timesyncd.service8,
+ or an alternative NTP implementation to delay the target.
time-sync.target
- Services responsible for synchronizing the system
- clock from a remote source (such as NTP client
- implementations) should pull in this target and order
- themselves before it. All services where correct time is
- essential should be ordered after this unit, but not pull it
- in. systemd automatically adds dependencies of type
- After= for this target unit to all SysV
- init script service units with an LSB header referring to
- the $time facility, and also to all timer
- units with at least one OnCalendar=
- directive.
+ Services indicating completed synchronization of the system clock
+ (CLOCK_REALTIME) to a remote source should pull in this target and order
+ themselves before it. Services where accurate time is essential should be ordered after this
+ unit, but not pull it in.
- This target might get reached before the clock is actually synchronized to an accurate reference
- clock. To prevent that, enable
- systemd-time-wait-sync.service8
- if you're using
+ The service manager automatically adds dependencies of type After= for
+ this target unit to all SysV init script service units with an LSB header referring to the
+ $time facility, as well to all timer units with at least one
+ OnCalendar= directive.
+
+ This target provides stricter clock accuracy guarantees than
+ time-set.target (see above), but likely requires
+ network communication and thus introduces unpredictable delays.
+ Services that require clock accuracy and where network
+ communication delays are acceptable should use this target. Services that require a less accurate
+ clock, and only approximate and roughly monotonic clock behaviour should use
+ time-set.target instead.
+
+ Note that ordering a unit after time-sync.target only has effect if
+ there's actually a service ordered before it that delays it until clock synchronization is
+ reached. Otherwise, this target might get reached before the clock is synchronized to any remote
+ accurate reference clock. When using
systemd-timesyncd.service8,
- or an equivalent service for other NTP implementations.
+ enable
+ systemd-time-wait-sync.service8
+ to delay the target; or use an equivalent service for other NTP implementations.
+
+
+ Comparison
+
+
+
+
+
+ time-set.target
+ time-sync.target
+
+
+
+
+ "quick" to reach
+ "slow" to reach
+
+
+ typically uses local clock sources, boot process not affected by availability of external resources
+ typically uses remote clock sources, inserts dependencies on remote resources into boot process
+
+
+ reliable, because local
+ unreliable, because typically network involved
+
+
+ typically guarantees an approximate and roughly monotonic clock only
+ typically guarantees an accurate clock
+
+
+ implemented by systemd-timesyncd.service
+ implemented by systemd-time-wait-sync.service
+
+
+
+
+