man: describe setting of the clock by systemd and systemd-timesyncd

The setting of systemd clock is important and deserves an accurate description,
see for example:
https://discussion.fedoraproject.org/t/f38-to-f39-40-dnf-system-upgrade-can-fail-on-raspberry-pi/92403
https://bugzilla.redhat.com/show_bug.cgi?id=2242759

The meat of the description was in systemd-timesyncd.service(8), but
actually it's systemd that sets the clock. In particular, systemd-timesyncd
doesn't know anything about /usr/lib/clock-epoch, and since systemd sets
the clock to the epoch when initializing, systemd-timesyncd would only
get to advance the clock to the epoch under special circumstances.
Also, systemd-timesyncd is an optional component, so we can't even rely
on its man page being installed in all circumstances. The description needs
to be moved to systemd(1).

The description is updated to describe the changes that were made in
previous commits.

diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml
index 25b236df5fabfe942834f0079bb082682b28b577..1f504deac14afd7d5dd1c273c096e512561d25b2 100644 (file)
--- a/man/systemd-timesyncd.service.xml
+++ b/man/systemd-timesyncd.service.xml
@@ -66,6 +66,16 @@
     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>
+
+    <para><filename>systemd</filename> and <filename>systemd-timesyncd</filename> advance the system clock to
+    the "epoch" (the lowest date above which the system clock time is assumed to be set correctly). See
+    "System clock epoch" section in
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details.
+    <filename>systemd</filename> will set the clock when initializing, but
+    <filename>/var/lib/systemd/timesync/clock</filename> might not yet be available at that point.
+    <filename>systemd-timesyncd</filename> will advance the clock when it is started and notices that the
+    system clock is before the modification time of <filename>/var/lib/systemd/timesync/clock</filename>.
+    </para>
   </refsect1>
 
   <refsect1>
@@ -78,36 +88,24 @@
         <listitem>
           <para>The modification time ("mtime") of this file is updated on each successful NTP
           synchronization or after each <varname>SaveIntervalSec=</varname> time interval, as specified in
-          <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+          <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+          </para>
 
-          <para>When initializing, the local clock is advanced to the modification time of this file (if the
-          file timestamp is in the past this adjustment is not made). If the file does not exist yet, the
-          clock is instead advanced to the modification time of <filename>/usr/lib/clock-epoch</filename> –
-          if it exists – or to a time derived from the source tree at build time. This mechanism is used to
-          ensure that the system clock remains somewhat reasonably initialized and roughly monotonic across
-          reboots, in case no battery-buffered local RTC is available.</para>
+          <para>If present, the modification time of this file is used for the epoch by
+          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
+          <filename>systemd-timesyncd.service</filename>.</para>
 
           <xi:include href="version-info.xml" xpointer="v219"/>
         </listitem>
       </varlistentry>
 
-      <varlistentry>
-        <term><filename>/usr/lib/clock-epoch</filename></term>
-
-        <listitem><para>The modification time ("mtime") of this file is used for advancing the system clock
-        in case <filename>/var/lib/systemd/timesync/clock</filename> does not exist yet, see
-        above.</para>
-
-        <xi:include href="version-info.xml" xpointer="v254"/></listitem>
-      </varlistentry>
-
       <varlistentry>
         <term><filename>/run/systemd/timesync/synchronized</filename></term>
 
         <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>
+          <para>A file that is touched on each successful synchronization to assist
+          <filename>systemd-time-wait-sync</filename> and other applications in detecting synchronization to
+          an accurate reference clock.</para>
 
           <xi:include href="version-info.xml" xpointer="v239"/>
         </listitem>

diff --git a/man/systemd.xml b/man/systemd.xml
index f4aa7e06cac821ca1c8e6da7d6186f12407a4d0b..af3d57b65787c781a77c7b5957ed46cc5433f935 100644 (file)
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -68,6 +68,9 @@
     network device. It also sets up and mounts various API file systems, such as <filename>/sys/</filename>,
     <filename>/proc/</filename>, and <filename>/dev/</filename>.</para>
 
+    <para><command>systemd</command> will also reset the system clock during early boot if it appears to be
+    set incorrectly. See "System clock epoch" section below.</para>
+
     <para>Note that some but not all interfaces provided by systemd are covered by the
     <ulink url="https://systemd.io/PORTABILITY_AND_STABILITY/">Interface Portability and Stability Promise</ulink>.</para>
 
@@ -1482,7 +1485,26 @@
   </refsect1>
 
   <refsect1>
-    <title>Sockets and FIFOs</title>
+    <title>System clock epoch</title>
+
+    <para>When <command>systemd</command> is started or restarted, it may set the system clock to the
+    "epoch". This mechanism is used to ensure that the system clock remains somewhat reasonably initialized
+    and roughly monotonic across reboots, in case no battery-backed local RTC is available or it does not
+    work correctly.</para>
+
+    <para>The epoch is the lowest date above which the system clock time is assumed to be set correctly. When
+    initializing, the local clock is <emphasis>advanced</emphasis> to the epoch if it was set to a lower
+    value. As a special case, if the local clock is sufficiently far in the future (by default 15 years, but
+    this can be configured at build time), the hardware clock is assumed to be broken, and the system clock
+    is <emphasis>rewound</emphasis> to the epoch.</para>
+
+    <para>The epoch is set to the highest of: the build time of <filename>systemd</filename>, the
+    modification time ("mtime") of <filename>/usr/lib/clock-epoch</filename>, and the modification time of
+    <filename>/var/lib/systemd/timesync/clock</filename>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Files</title>
 
     <variablelist>
       <varlistentry>
@@ -1516,6 +1538,26 @@
         named pipe in the file system. This interface is obsolete and
         should not be used in new applications.</para></listitem>
       </varlistentry>
+
+      <varlistentry>
+        <term><filename>/usr/lib/clock-epoch</filename></term>
+
+        <listitem><para>The modification time ("mtime") of this file is used for the time epoch, see previous
+        section.</para>
+
+        <xi:include href="version-info.xml" xpointer="v247"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><filename>/var/lib/systemd/timesync/clock</filename></term>
+
+        <listitem><para>The modification time ("mtime") of this file is updated by
+        <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+        If present, the modification time of file is used for the epoch, see previous section.
+        </para>
+
+        <xi:include href="version-info.xml" xpointer="v257"/></listitem>
+      </varlistentry>
     </variablelist>
   </refsect1>
 

diff --git a/tools/command_ignorelist b/tools/command_ignorelist
index af694c16dbd7990ad91f6da87fd6d1e6325a7c00..d88ebbb3ff80c7da679d3fc0765b835f45b55ef9 100644 (file)
--- a/tools/command_ignorelist
+++ b/tools/command_ignorelist
@@ -394,9 +394,9 @@ systemd.xml /refsect1[title="Kernel Command Line"]/variablelist/varlistentry[ter
 systemd.xml /refsect1[title="Kernel Command Line"]/variablelist/varlistentry[term="systemd.log_color"]
 systemd.xml /refsect1[title="Kernel Command Line"]/variablelist/varlistentry[term="systemd.default_standard_output="]
 systemd.xml /refsect1[title="Kernel Command Line"]/variablelist/varlistentry[term="systemd.setenv="]
-systemd.xml /refsect1[title="Sockets and FIFOs"]/variablelist/varlistentry[term="/run/systemd/notify"]
-systemd.xml /refsect1[title="Sockets and FIFOs"]/variablelist/varlistentry[term="/run/systemd/private"]
-systemd.xml /refsect1[title="Sockets and FIFOs"]/variablelist/varlistentry[term="/dev/initctl"]
+systemd.xml /refsect1[title="Files"]/variablelist/varlistentry[term="/run/systemd/notify"]
+systemd.xml /refsect1[title="Files"]/variablelist/varlistentry[term="/run/systemd/private"]
+systemd.xml /refsect1[title="Files"]/variablelist/varlistentry[term="/dev/initctl"]
 telinit.xml /refsect1[title="Options"]/variablelist[1]/varlistentry[term="--help"]
 telinit.xml /refsect1[title="Options"]/variablelist[1]/varlistentry[term="--no-wall"]
 telinit.xml /refsect1[title="Options"]/variablelist[2]/varlistentry[term="0"]