system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-09-30 05:15:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse source 
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.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2024-06-05 14:15:21 +02:00
parent e0c7c9a00d
commit 863098fdc9
3 changed files with 64 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
man/systemd-timesyncd.service.xml
View file

@ -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>

44
man/systemd.xml
View file

@ -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>

6
tools/command_ignorelist
View file

@ -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"]