diff options
| -rw-r--r-- | man/systemd-timesyncd.service.xml | 38 | ||||
| -rw-r--r-- | man/systemd.xml | 44 | ||||
| -rw-r--r-- | tools/command_ignorelist | 6 |
3 files changed, 64 insertions, 24 deletions
diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml index 25b236df5f..1f504deac1 100644 --- 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 f4aa7e06ca..af3d57b657 100644 --- 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 af694c16db..d88ebbb3ff 100644 --- 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"] |