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 time-sync.target until synchronization to an accurate reference clock is reached. + + systemd and systemd-timesyncd 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 + systemd1 for details. + systemd will set the clock when initializing, but + /var/lib/systemd/timesync/clock might not yet be available at that point. + systemd-timesyncd will advance the clock when it is started and notices that the + system clock is before the modification time of /var/lib/systemd/timesync/clock. + @@ -78,36 +88,24 @@ The modification time ("mtime") of this file is updated on each successful NTP synchronization or after each SaveIntervalSec= time interval, as specified in - timesyncd.conf5. + timesyncd.conf5. + - 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 /usr/lib/clock-epoch – - 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. + If present, the modification time of this file is used for the epoch by + systemd1 and + systemd-timesyncd.service. - - /usr/lib/clock-epoch - - The modification time ("mtime") of this file is used for advancing the system clock - in case /var/lib/systemd/timesync/clock does not exist yet, see - above. - - - - /run/systemd/timesync/synchronized - A file that is touched on each successful synchronization, to assist - systemd-time-wait-sync and other applications to detecting synchronization - with accurate reference clocks. + A file that is touched on each successful synchronization to assist + systemd-time-wait-sync and other applications in detecting synchronization to + an accurate reference clock. 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 /sys/, /proc/, and /dev/. + systemd will also reset the system clock during early boot if it appears to be + set incorrectly. See "System clock epoch" section below. + Note that some but not all interfaces provided by systemd are covered by the Interface Portability and Stability Promise. @@ -1482,7 +1485,26 @@ - Sockets and FIFOs + System clock epoch + + When systemd 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. + + The epoch is the lowest date above which the system clock time is assumed to be set correctly. When + initializing, the local clock is advanced 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 rewound to the epoch. + + The epoch is set to the highest of: the build time of systemd, the + modification time ("mtime") of /usr/lib/clock-epoch, and the modification time of + /var/lib/systemd/timesync/clock. + + + + Files @@ -1516,6 +1538,26 @@ named pipe in the file system. This interface is obsolete and should not be used in new applications. + + + /usr/lib/clock-epoch + + The modification time ("mtime") of this file is used for the time epoch, see previous + section. + + + + + + /var/lib/systemd/timesync/clock + + The modification time ("mtime") of this file is updated by + systemd-timesyncd.service8. + If present, the modification time of file is used for the epoch, see previous section. + + + + 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"]