<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>
<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>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 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><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 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
+ 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>
<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>
<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>
<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>
<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>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>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>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>
projects / thirdparty / systemd.git / commitdiff
