time-wait-sync: use watchfile to coordinate with timesyncd

[thirdparty/systemd.git] / man / systemd-timesyncd.service.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  SPDX-License-Identifier: LGPL-2.1+

  This file is part of systemd.

  Copyright 2014 Kay Sievers
-->

<refentry id="systemd-timesyncd.service" conditional='ENABLE_TIMESYNCD'>

  <refentryinfo>
    <title>systemd-timesyncd.service</title>
    <productname>systemd</productname>

    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>Kay</firstname>
        <surname>Sievers</surname>
        <email>kay@vrfy.org</email>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd-timesyncd.service</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd-timesyncd.service</refname>
    <refname>systemd-timesyncd</refname>
    <refpurpose>Network Time Synchronization</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para><filename>systemd-timesyncd.service</filename></para>
    <para><filename>/usr/lib/systemd/systemd-timesyncd</filename></para>
  </refsynopsisdiv>

  <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><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>
  </refsect1>

  <refsect1>
    <title>Files</title>

    <variablelist>
      <varlistentry>
        <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.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><filename>/run/systemd/timesync/synchronized</filename></term>

        <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>
        </listitem>

      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <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>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>
    </para>
  </refsect1>

</refentry>