1
0
mirror of https://github.com/systemd/systemd.git synced 2024-12-22 17:35:35 +03:00

man: extend time-{set,sync}.target + systemd-timesyncd/wait-sync docs

Let's link the three man pages together more tightly and explain what
the two targets are about, emphasizing local/quick/reliable/approximate
vs remote/slow/unreliable/accurate synchronization.

Follow-up for: 1431b2f701 fe934b42e4
This commit is contained in:
Lennart Poettering 2020-12-20 21:03:53 +01:00
parent 5def1f11f8
commit b149d230ea
3 changed files with 134 additions and 55 deletions

View File

@ -29,15 +29,17 @@
<refsect1>
<title>Description</title>
<para><filename>systemd-time-wait-sync</filename> is a system service that delays the start of units that depend on
<filename>time-sync.target</filename> until the system time has been synchronized with an accurate time source by
<para><filename>systemd-time-wait-sync</filename> is a system service that delays the start of units that
are ordered after <filename>time-sync.target</filename> (see
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
details) until the system time has been synchronized with an accurate remote reference time source by
<filename>systemd-timesyncd.service</filename>.</para>
<para><filename>systemd-timesyncd.service</filename> notifies on successful synchronization.
<filename>systemd-time-wait-sync</filename> also tries to detect when the kernel marks the time as synchronized,
but this detection is not reliable and is intended only as a fallback for other services that can be used to
synchronize time (e.g., ntpd, chronyd).</para>
<para><filename>systemd-timesyncd.service</filename> notifies <filename>systemd-time-wait-sync</filename>
about successful synchronization. <filename>systemd-time-wait-sync</filename> also tries to detect when
the kernel marks the system clock as synchronized, but this detection is not reliable and is intended
only as a fallback for compatibility with alternative NTP services that can be used to synchronize time
(e.g., ntpd, chronyd).</para>
</refsect1>
<refsect1>

View File

@ -29,35 +29,43 @@
<refsect1>
<title>Description</title>
<para><filename>systemd-timesyncd</filename> is a system service
that may be used to synchronize the local system clock with a
remote Network Time Protocol server. It also saves the local time
to disk every time the clock has been synchronized and uses this
to possibly advance the system realtime clock on subsequent
reboots to ensure it monotonically advances even if the system
lacks a battery-buffered RTC chip.</para>
<para><filename>systemd-timesyncd</filename> is a system service that may be used to synchronize the
local system clock with a remote Network Time Protocol (NTP) server. It also saves the local time to disk
every time the clock has been synchronized and uses this to possibly advance the system realtime clock on
subsequent reboots to ensure it (roughly) monotonically advances even if the system lacks a
battery-buffered RTC chip.</para>
<para>The <filename>systemd-timesyncd</filename> service
specifically implements only SNTP. This minimalistic
service will set the system clock for large offsets or
slowly adjust it for smaller deltas. More complex use
cases are not covered by <filename>systemd-timesyncd</filename>.</para>
<para>The <filename>systemd-timesyncd</filename> service implements SNTP only. This minimalistic service
will step the system clock for large offsets or slowly adjust it for smaller deltas. Complex use cases
that require full NTP support (and where SNTP is not sufficient) are not covered by
<filename>systemd-timesyncd</filename>.</para>
<para>The NTP servers contacted are determined from the global
settings in
<citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
the per-link static settings in <filename>.network</filename>
files, and the per-link dynamic settings received over DHCP. See
<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for more details.</para>
<para>The NTP servers contacted are determined from the global settings in
<citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, the
per-link static settings in <filename>.network</filename> files, and the per-link dynamic settings
received over DHCP. See
<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
further details.</para>
<para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
<command>set-ntp</command> command may be used to enable and
start, or disable and stop this service.</para>
<command>set-ntp</command> command may be used to enable and start, or disable and stop this
service.</para>
<para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
<command>timesync-status</command> or <command>show-timesync</command> command can be used to show the
current status of this service.</para>
<para><filename>systemd-timesyncd</filename> initialization delays the start of units that are ordered
after <filename>time-set.target</filename> (see
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
details) until the local time has been updated from <filename>/var/lib/systemd/timesync/clock</filename>
(see below) in order to make it roughly monotonic (see above), should this be necessary — for example
because no RTC device is available. It does not delay other units until synchronization with an accurate
reference time sources has been reached. Use
<citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
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>
</refsect1>
<refsect1>
@ -68,9 +76,10 @@
<term><filename>/var/lib/systemd/timesync/clock</filename></term>
<listitem>
<para>The modification time of this file indicates the timestamp of the last successful
synchronization (or at least the systemd build date, in case synchronization was not
possible).</para>
<para>The modification time ("mtime") of this file indicates the timestamp of the last successful
synchronization (or at least the systemd build date, in case synchronization was not possible). It
is used to ensure that the system clock remains roughly monotonic across reboots, in case no local
RTC is available.</para>
</listitem>
</varlistentry>
@ -80,7 +89,7 @@
<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
events.</para>
with accurate reference clocks.</para>
</listitem>
</varlistentry>
@ -95,6 +104,7 @@
<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>

View File

@ -998,36 +998,103 @@
<varlistentry>
<term><filename>time-set.target</filename></term>
<listitem>
<para>Services responsible for setting the system clock from
a local source (such as a maintained timestamp file or
imprecise real-time clock) should pull in this target and
order themselves before it. Services where approximate time
is desired should be ordered after this unit, but not pull
it in. This target does not provide the accuracy guarantees
of <filename>time-sync.target</filename>.</para>
<para>Services responsible for setting the system clock (<constant>CLOCK_REALTIME</constant>)
from a local source (such as a maintained timestamp file or imprecise real-time clock) should
pull in this target and order themselves before it. Services where approximate, roughly monotonic
time is desired should be ordered after this unit, but not pull it in.</para>
<para>This target does not provide the accuracy guarantees of
<filename>time-sync.target</filename> (see below), however does not depend on remote clock
sources to be reachable, i.e. the target is typically not delayed by network problems and
similar. Use of this target is recommended for services where approximate clock accuracy and
rough monotonicity is desired but activation shall not be delayed for possibly unreliable network
communication.</para>
<para>The service manager automatically adds dependencies of type <varname>After=</varname> for
this target unit to all timer units with at least one <varname>OnCalendar=</varname>
directive.</para>
<para>The
<citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
service is a simple daemon that pulls in this target and orders itself before it. Besides
implementing the SNTP network protocol it maintains a timestamp file on disk whose modification
time is regularlary updated. At service start-up the local system clock is updated accordingly,
ensuring it increases roughly monotonically.</para>
<para>Note that ordering a unit after <filename>time-set.target</filename> only has effect if
there's actually a service ordered before it that delays it until the clock is adjusted for rough
monotonicity. Otherwise, this target might get reached before the clock is adjusted to be roughly
monotonic. Enable
<citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
to achieve that — or an alternative NTP implementation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>time-sync.target</filename></term>
<listitem>
<para>Services responsible for synchronizing the system
clock from a remote source (such as NTP client
implementations) should pull in this target and order
themselves before it. All services where correct time is
essential should be ordered after this unit, but not pull it
in. systemd automatically adds dependencies of type
<varname>After=</varname> for this target unit to all SysV
init script service units with an LSB header referring to
the <literal>$time</literal> facility, and also to all timer
units with at least one <varname>OnCalendar=</varname>
directive. </para>
<para>Services indicating completed synchronization of the system clock
(<constant>CLOCK_REALTIME</constant>) to a remote source should pull in this target and order
themselves before it. Services where accurate time is essential should be ordered after this
unit, but not pull it in.</para>
<para>This target might get reached before the clock is actually synchronized to an accurate reference
clock. To prevent that, enable
<citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
if you're using
<para>The service manager automatically adds dependencies of type <varname>After=</varname> for
this target unit to all SysV init script service units with an LSB header referring to the
<literal>$time</literal> facility, as well to all timer units with at least one
<varname>OnCalendar=</varname> directive.</para>
<para>This target provides stricter clock accuracy guarantees than
<filename>time-set.target</filename> (see above), but likely relies on possibly unreliable
network communication and thus might introduce possibly substantial activation delays for
services ordered after this target. Services that require clock accuracy and where network
communication delays are acceptable should use this target. Services that require a less accurate
clock, and only approximate and roughly monotonic clock behaviour should use
<filename>time-set.target</filename> instead.</para>
<para>Note that ordering a unit after <filename>time-sync.target</filename> only has effect if
there's actually a service ordered before it that delays it until clock synchronization is
reached. Otherwise, this target might get reached before the clock is synchronized to any remote
accurate reference clock. When using
<citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
or an equivalent service for other NTP implementations.</para>
enable
<citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
to achieve that; or use an equivalent service for other NTP implementations.</para>
<table>
<title>Comparison</title>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec colname="time-set" />
<colspec colname="time-sync" />
<thead>
<row>
<entry><filename>time-set.target</filename></entry>
<entry><filename>time-sync.target</filename></entry>
</row>
</thead>
<tbody>
<row>
<entry>"quick" to reach</entry>
<entry>"slow" to reach</entry>
</row>
<row>
<entry>typically uses local clock sources, boot process not affected by availability of external resources</entry>
<entry>typically uses remote clock sources, inserts dependencies on remote resources into boot process</entry>
</row>
<row>
<entry>reliable, because local</entry>
<entry>unreliable, because typically network involved</entry>
</row>
<row>
<entry>typically guarantees an approximate and roughly monotonic clock only</entry>
<entry>typically guarantees an accurate clock</entry>
</row>
<row>
<entry>implemented by <filename>systemd-timesyncd.service</filename></entry>
<entry>implemented by <filename>systemd-time-wait-sync.service</filename></entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
</variablelist>