man/systemd-timesyncd.service.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-timesyncd.service" conditional='ENABLE_TIMESYNCD'
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-timesyncd.service</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-timesyncd.service</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-timesyncd.service</refname>
  21     <refname>systemd-timesyncd</refname>
  22     <refpurpose>Network Time Synchronization</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <para><filename>systemd-timesyncd.service</filename></para>
  27     <para><filename>/usr/lib/systemd/systemd-timesyncd</filename></para>
  28   </refsynopsisdiv>
  29
  30   <refsect1>
  31     <title>Description</title>
  32
  33     <para><filename>systemd-timesyncd</filename> is a system service that may be used to synchronize the
  34     local system clock with a remote Network Time Protocol (NTP) server. It also saves the local time to disk
  35     every time the clock has been synchronized and uses this to possibly advance the system realtime clock on
  36     subsequent reboots to ensure it (roughly) monotonically advances even if the system lacks a
  37     battery-buffered RTC chip.</para>
  38
  39     <para>The <filename>systemd-timesyncd</filename> service implements SNTP only. This minimalistic service
  40     will step the system clock for large offsets or slowly adjust it for smaller deltas. Complex use cases
  41     that require full NTP support (and where SNTP is not sufficient) are not covered by
  42     <filename>systemd-timesyncd</filename>.</para>
  43
  44     <para>The NTP servers contacted are determined from the global settings in
  45     <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, the
  46     per-link static settings in <filename>.network</filename> files, and the per-link dynamic settings
  47     received over DHCP. See
  48     <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
  49     further details.</para>
  50
  51     <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
  52     <command>set-ntp</command> command may be used to enable and start, or disable and stop this
  53     service.</para>
  54
  55     <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
  56     <command>timesync-status</command> or <command>show-timesync</command> command can be used to show the
  57     current status of this service.</para>
  58
  59     <para><filename>systemd-timesyncd</filename> initialization delays the start of units that are ordered
  60     after <filename>time-set.target</filename> (see
  61     <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
  62     details) until the local time has been updated from <filename>/var/lib/systemd/timesync/clock</filename>
  63     (see below) in order to make it roughly monotonic. It does not delay other units until synchronization
  64     with an accurate reference time sources has been reached. Use
  65     <citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  66     to achieve that, which will delay start of units that are ordered after
  67     <filename>time-sync.target</filename> until synchronization to an accurate reference clock is
  68     reached.</para>
  69   </refsect1>
  70
  71   <refsect1>
  72     <title>Files</title>
  73
  74     <variablelist>
  75       <varlistentry>
  76         <term><filename>/var/lib/systemd/timesync/clock</filename></term>
  77
  78         <listitem>
  79           <para>The modification time ("mtime") of this file is updated on each successful NTP
  80           synchronization or after each <varname>SaveIntervalSec=</varname> time interval, as specified in
  81           <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  82
  83           <para>When initializing, the local clock is advanced to the modification time of this file (if the
  84           file timestamp is in the past this adjustment is not made). If the file does not exist yet, the
  85           clock is instead advanced to the modification time of <filename>/usr/lib/clock-epoch</filename> –
  86           if it exists – or to a time derived from the source tree at build time. This mechanism is used to
  87           ensure that the system clock remains somewhat reasonably initialized and roughly monotonic across
  88           reboots, in case no battery-buffered local RTC is available.</para>
  89         </listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term><filename>/usr/lib/clock-epoch</filename></term>
  94
  95         <listitem><para>The modification time ("mtime") of this file is used for advancing the system clock
  96         in case <filename>/var/lib/systemd/timesync/clock</filename> does not exist yet, see
  97         above.</para></listitem>
  98       </varlistentry>
  99
 100       <varlistentry>
 101         <term><filename>/run/systemd/timesync/synchronized</filename></term>
 102
 103         <listitem>
 104           <para>A file that is touched on each successful synchronization, to assist
 105           <filename>systemd-time-wait-sync</filename> and other applications to detecting synchronization
 106           with accurate reference clocks.</para>
 107         </listitem>
 108
 109       </varlistentry>
 110     </variablelist>
 111   </refsect1>
 112
 113   <refsect1>
 114     <title>See Also</title>
 115     <para>
 116       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 117       <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 118       <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 119       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 120       <citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 121       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 122       <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 123       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 124       <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 125     </para>
 126   </refsect1>
 127
 128 </refentry>