Merge pull request #18048 from poettering/timesync-man-more

man: extend time-{set,sync}.target + systemd-timesyncd/wait-sync docs

man/systemd-time-wait-sync.service.xml

@@ -29,15 +29,17 @@
   <refsect1>
     <title>Description</title>
 
-    <para><filename>systemd-time-wait-sync</filename> is a system service that delays the start of units that depend on
-    <filename>time-sync.target</filename> until the system time has been synchronized with an accurate time source by
+    <para><filename>systemd-time-wait-sync</filename> is a system service that delays the start of units that
+    are ordered after <filename>time-sync.target</filename> (see
+    <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+    details) until the system time has been synchronized with an accurate remote reference time source by
     <filename>systemd-timesyncd.service</filename>.</para>
 
-    <para><filename>systemd-timesyncd.service</filename> notifies on successful synchronization.
-    <filename>systemd-time-wait-sync</filename> 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).</para>
-
+    <para><filename>systemd-timesyncd.service</filename> notifies <filename>systemd-time-wait-sync</filename>
+    about successful synchronization.  <filename>systemd-time-wait-sync</filename> 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).</para>
   </refsect1>
 
   <refsect1>

man/systemd-timesyncd.service.xml

@@ -29,35 +29,42 @@
   <refsect1>
     <title>Description</title>
 
-    <para><filename>systemd-timesyncd</filename> 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.</para>
+    <para><filename>systemd-timesyncd</filename> 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.</para>
 
-    <para>The <filename>systemd-timesyncd</filename> 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 <filename>systemd-timesyncd</filename>.</para>
+    <para>The <filename>systemd-timesyncd</filename> 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
+    <filename>systemd-timesyncd</filename>.</para>
 
-    <para>The NTP servers contacted are determined from the global
-    settings in
-    <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-    the per-link static settings in <filename>.network</filename>
-    files, and the per-link dynamic settings received over DHCP. See
-    <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-    for more details.</para>
+    <para>The NTP servers contacted are determined from the global settings in
+    <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, the
+    per-link static settings in <filename>.network</filename> files, and the per-link dynamic settings
+    received over DHCP. See
+    <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+    further details.</para>
 
     <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
-    <command>set-ntp</command> command may be used to enable and
-    start, or disable and stop this service.</para>
+    <command>set-ntp</command> command may be used to enable and start, or disable and stop this
+    service.</para>
 
     <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
     <command>timesync-status</command> or <command>show-timesync</command> command can be used to show the
     current status of this service.</para>
+
+    <para><filename>systemd-timesyncd</filename> initialization delays the start of units that are ordered
+    after <filename>time-set.target</filename> (see
+    <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+    details) until the local time has been updated from <filename>/var/lib/systemd/timesync/clock</filename>
+    (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
+    <citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    to achieve that, which will delay start of units that are ordered after
+    <filename>time-sync.target</filename> until synchronization to an accurate reference clock is
+    reached.</para>
   </refsect1>
 
   <refsect1>
@@ -68,9 +75,10 @@
         <term><filename>/var/lib/systemd/timesync/clock</filename></term>
 
         <listitem>
-          <para>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).</para>
+          <para>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.</para>
         </listitem>
       </varlistentry>
 
@@ -80,7 +88,7 @@
         <listitem>
           <para>A file that is touched on each successful synchronization, to assist
           <filename>systemd-time-wait-sync</filename> and other applications to detecting synchronization
-          events.</para>
+          with accurate reference clocks.</para>
         </listitem>
 
       </varlistentry>
@@ -95,6 +103,7 @@
       <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>

man/systemd.special.xml

@@ -998,36 +998,103 @@
         <varlistentry>
           <term><filename>time-set.target</filename></term>
           <listitem>
-            <para>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 <filename>time-sync.target</filename>.</para>
+            <para>Services responsible for setting the system clock (<constant>CLOCK_REALTIME</constant>)
+            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.</para>
+
+            <para>This target does not provide the accuracy guarantees of
+            <filename>time-sync.target</filename> (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.</para>
+
+            <para>The service manager automatically adds dependencies of type <varname>After=</varname> for
+            this target unit to all timer units with at least one <varname>OnCalendar=</varname>
+            directive.</para>
+
+            <para>The
+            <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+            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.</para>
+
+            <para>Note that ordering a unit after <filename>time-set.target</filename> 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
+            <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+            or an alternative NTP implementation to delay the target.</para>
           </listitem>
         </varlistentry>
         <varlistentry>
           <term><filename>time-sync.target</filename></term>
           <listitem>
-            <para>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
-            <varname>After=</varname> for this target unit to all SysV
-            init script service units with an LSB header referring to
-            the <literal>$time</literal> facility, and also to all timer
-            units with at least one <varname>OnCalendar=</varname>
-            directive. </para>
+            <para>Services indicating completed synchronization of the system clock
+            (<constant>CLOCK_REALTIME</constant>) 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.</para>
 
-            <para>This target might get reached before the clock is actually synchronized to an accurate reference
-            clock. To prevent that, enable
-            <citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-            if you're using
+            <para>The service manager automatically adds dependencies of type <varname>After=</varname> for
+            this target unit to all SysV init script service units with an LSB header referring to the
+            <literal>$time</literal> facility, as well to all timer units with at least one
+            <varname>OnCalendar=</varname> directive.</para>
+
+            <para>This target provides stricter clock accuracy guarantees than
+            <filename>time-set.target</filename> (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
+            <filename>time-set.target</filename> instead.</para>
+
+            <para>Note that ordering a unit after <filename>time-sync.target</filename> 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
             <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-            or an equivalent service for other NTP implementations.</para>
+            enable
+            <citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+            to delay the target; or use an equivalent service for other NTP implementations.</para>
+
+            <table>
+              <title>Comparison</title>
+              <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+                <colspec colname="time-set" />
+                <colspec colname="time-sync" />
+                <thead>
+                  <row>
+                    <entry><filename>time-set.target</filename></entry>
+                    <entry><filename>time-sync.target</filename></entry>
+                  </row>
+                </thead>
+                <tbody>
+                  <row>
+                    <entry>"quick" to reach</entry>
+                    <entry>"slow" to reach</entry>
+                  </row>
+                  <row>
+                    <entry>typically uses local clock sources, boot process not affected by availability of external resources</entry>
+                    <entry>typically uses remote clock sources, inserts dependencies on remote resources into boot process</entry>
+                  </row>
+                  <row>
+                    <entry>reliable, because local</entry>
+                    <entry>unreliable, because typically network involved</entry>
+                  </row>
+                  <row>
+                    <entry>typically guarantees an approximate and roughly monotonic clock only</entry>
+                    <entry>typically guarantees an accurate clock</entry>
+                  </row>
+                  <row>
+                    <entry>implemented by <filename>systemd-timesyncd.service</filename></entry>
+                    <entry>implemented by <filename>systemd-time-wait-sync.service</filename></entry>
+                  </row>
+                </tbody>
+              </tgroup>
+            </table>
+
           </listitem>
         </varlistentry>
       </variablelist>