From b149d230ea23c14bac2dfe79c47e58782623200f Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Sun, 20 Dec 2020 21:03:53 +0100 Subject: [PATCH 1/2] man: extend time-{set,sync}.target + systemd-timesyncd/wait-sync docs Let's link the three man pages together more tightly and explain what the two targets are about, emphasizing local/quick/reliable/approximate vs remote/slow/unreliable/accurate synchronization. Follow-up for: 1431b2f701f7ba71e5d8664e709b1fad26797918 fe934b42e480473afba8a29a4a0d3d0e789543ac --- man/systemd-time-wait-sync.service.xml | 16 ++-- man/systemd-timesyncd.service.xml | 60 +++++++------ man/systemd.special.xml | 113 ++++++++++++++++++++----- 3 files changed, 134 insertions(+), 55 deletions(-) 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..fcd731fd6f 100644 --- a/man/systemd-timesyncd.service.xml +++ b/man/systemd-timesyncd.service.xml @@ -29,35 +29,43 @@ 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 (see above), should this be necessary — for example + because no RTC device is available. 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 +76,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 +89,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 +104,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..8a98fa4c0f 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 updated accordingly, + 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, + to achieve that — or an alternative NTP implementation. 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 relies on possibly unreliable + network communication and thus might introduce possibly substantial activation delays for + services ordered after this target. 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 achieve that; 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 + + + +
+ From 57b3b8f48c00109238ef5a1d569c0e6fee3e3efa Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 28 Dec 2020 10:43:10 +0100 Subject: [PATCH 2/2] man: apply @Minoru's suggestions from code review Co-authored-by: Alexander Batischev --- man/systemd-timesyncd.service.xml | 5 ++--- man/systemd.special.xml | 12 ++++++------ 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml index fcd731fd6f..9ab4af9763 100644 --- a/man/systemd-timesyncd.service.xml +++ b/man/systemd-timesyncd.service.xml @@ -59,9 +59,8 @@ 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 (see above), should this be necessary — for example - because no RTC device is available. It does not delay other units until synchronization with an accurate - reference time sources has been reached. Use + (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 diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 8a98fa4c0f..e731c9ced2 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -1018,7 +1018,7 @@ 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 updated accordingly, + 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 @@ -1026,7 +1026,7 @@ monotonicity. Otherwise, this target might get reached before the clock is adjusted to be roughly monotonic. Enable systemd-timesyncd.service8, - to achieve that — or an alternative NTP implementation. + or an alternative NTP implementation to delay the target. @@ -1043,9 +1043,9 @@ OnCalendar= directive. This target provides stricter clock accuracy guarantees than - time-set.target (see above), but likely relies on possibly unreliable - network communication and thus might introduce possibly substantial activation delays for - services ordered after this target. Services that require clock accuracy and where network + 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. @@ -1057,7 +1057,7 @@ systemd-timesyncd.service8, enable systemd-time-wait-sync.service8 - to achieve that; or use an equivalent service for other NTP implementations. + to delay the target; or use an equivalent service for other NTP implementations. Comparison