From 8facb23dd458d619cb3a72ea23cf07aac61a1206 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Mon, 12 Jun 2023 14:06:10 +0200
Subject: [PATCH] man: explain timesyncd epoch mtime touch files in a bit more
 detail

Let's mention what /usr/lib/clock-epoch precisely does, and underline we
only *advance* the time based on it.

Inspired by Darkdragon-001's #23214.

Replaces #23214

(cherry picked from commit 2efddcb24551521b75542043d033e39338207de8)
(cherry picked from commit 1c07e6206cbe15ec2f963a65711c06933b2cb5a1)
(cherry picked from commit 38011797cfad69ea7ccb5577a8625b408281337f)
---
 man/systemd-timesyncd.service.xml | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml
index 34e0a67472..45fb6b716f 100644
--- a/man/systemd-timesyncd.service.xml
+++ b/man/systemd-timesyncd.service.xml
@@ -75,14 +75,27 @@
         <term><filename>/var/lib/systemd/timesync/clock</filename></term>
 
         <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>.
-          At the minimum, it will be set to the systemd build date. It is used to ensure that the system clock
-          remains roughly monotonic across reboots, in case no local RTC is available.</para>
+          <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>
+
+          <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>
         </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></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><filename>/run/systemd/timesync/synchronized</filename></term>