mirror of
https://github.com/systemd/systemd.git
synced 2024-11-23 10:13:34 +08: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:1431b2f701fe934b42e4
This commit is contained in:
Lennart Poettering
parent
5def1f11f8
commit
b149d230ea
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user