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 + + + +
+