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

@@ -29,17 +29,15 @@
   <refsect1>
     <title>Description</title>
 
-    <para><filename>systemd-time-wait-sync</filename> is a system service that delays the start of units that
+    <para><filename>systemd-time-wait-sync</filename> is a system service that delays the start of units that depend on
-    are ordered after <filename>time-sync.target</filename> (see
+    <filename>time-sync.target</filename> until the system time has been synchronized with an accurate time source by
-    <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 <filename>systemd-time-wait-sync</filename>
+    <para><filename>systemd-timesyncd.service</filename> notifies on successful synchronization.
-    about successful synchronization.  <filename>systemd-time-wait-sync</filename> also tries to detect when
+    <filename>systemd-time-wait-sync</filename> also tries to detect when the kernel marks the time as synchronized,
-    the kernel marks the system clock as synchronized, but this detection is not reliable and is intended
+    but this detection is not reliable and is intended only as a fallback for other services that can be used to
-    only as a fallback for compatibility with alternative NTP services that can be used to synchronize time
+    synchronize time (e.g., ntpd, chronyd).</para>
-    (e.g., ntpd, chronyd).</para>
+
   </refsect1>
 
   <refsect1>

man/systemd-timesyncd.service.xml

@@ -29,42 +29,35 @@
   <refsect1>
     <title>Description</title>
 
-    <para><filename>systemd-timesyncd</filename> is a system service that may be used to synchronize the
+    <para><filename>systemd-timesyncd</filename> is a system service
-    local system clock with a remote Network Time Protocol (NTP) server. It also saves the local time to disk
+    that may be used to synchronize the local system clock with a
-    every time the clock has been synchronized and uses this to possibly advance the system realtime clock on
+    remote Network Time Protocol server. It also saves the local time
-    subsequent reboots to ensure it (roughly) monotonically advances even if the system lacks a
+    to disk every time the clock has been synchronized and uses this
-    battery-buffered RTC chip.</para>
+    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>The <filename>systemd-timesyncd</filename> service implements SNTP only. This minimalistic service
+    <para>The <filename>systemd-timesyncd</filename> service
-    will step the system clock for large offsets or slowly adjust it for smaller deltas. Complex use cases
+    specifically implements only SNTP. This minimalistic
-    that require full NTP support (and where SNTP is not sufficient) are not covered by
+    service will set the system clock for large offsets or
-    <filename>systemd-timesyncd</filename>.</para>
+    slowly adjust it for smaller deltas. More complex use
+    cases are not covered by <filename>systemd-timesyncd</filename>.</para>
 
-    <para>The NTP servers contacted are determined from the global settings in
+    <para>The NTP servers contacted are determined from the global
-    <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, the
+    settings in
-    per-link static settings in <filename>.network</filename> files, and the per-link dynamic settings
+    <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-    received over DHCP. See
+    the per-link static settings in <filename>.network</filename>
-    <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+    files, and the per-link dynamic settings received over DHCP. See
-    further details.</para>
+    <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for more 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
+    <command>set-ntp</command> command may be used to enable and
-    service.</para>
+    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>
@@ -75,10 +68,9 @@
         <term><filename>/var/lib/systemd/timesync/clock</filename></term>
 
         <listitem>
-          <para>The modification time ("mtime") of this file indicates the timestamp of the last successful
+          <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). It
+          synchronization (or at least the systemd build date, in case synchronization was not
-          is used to ensure that the system clock remains roughly monotonic across reboots, in case no local
+          possible).</para>
-          RTC is available.</para>
         </listitem>
       </varlistentry>
 
@@ -88,7 +80,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
-          with accurate reference clocks.</para>
+          events.</para>
         </listitem>
 
       </varlistentry>
@@ -103,7 +95,6 @@
       <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,103 +998,36 @@
         <varlistentry>
           <term><filename>time-set.target</filename></term>
           <listitem>
-            <para>Services responsible for setting the system clock (<constant>CLOCK_REALTIME</constant>)
+            <para>Services responsible for setting the system clock from
-            from a local source (such as a maintained timestamp file or imprecise real-time clock) should
+            a local source (such as a maintained timestamp file or
-            pull in this target and order themselves before it. Services where approximate, roughly monotonic
+            imprecise real-time clock) should pull in this target and
-            time is desired should be ordered after this unit, but not pull it in.</para>
+            order themselves before it.  Services where approximate time
-
+            is desired should be ordered after this unit, but not pull
-            <para>This target does not provide the accuracy guarantees of
+            it in.  This target does not provide the accuracy guarantees
-            <filename>time-sync.target</filename> (see below), however does not depend on remote clock
+            of <filename>time-sync.target</filename>.</para>
-            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 indicating completed synchronization of the system clock
+            <para>Services responsible for synchronizing the system
-            (<constant>CLOCK_REALTIME</constant>) to a remote source should pull in this target and order
+            clock from a remote source (such as NTP client
-            themselves before it. Services where accurate time is essential should be ordered after this
+            implementations) should pull in this target and order
-            unit, but not pull it in.</para>
+            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>The service manager automatically adds dependencies of type <varname>After=</varname> for
+            <para>This target might get reached before the clock is actually synchronized to an accurate reference
-            this target unit to all SysV init script service units with an LSB header referring to the
+            clock. To prevent that, enable
-            <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>,
-            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>
+            if you're using
-
+            <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-            <table>
+            or an equivalent service for other NTP implementations.</para>
-              <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>