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
8  <refentryinfo>
9    <title>systemd-timesyncd.service</title>
10    <productname>systemd</productname>
11  </refentryinfo>
12
13  <refmeta>
14    <refentrytitle>systemd-timesyncd.service</refentrytitle>
15    <manvolnum>8</manvolnum>
16  </refmeta>
17
18  <refnamediv>
19    <refname>systemd-timesyncd.service</refname>
20    <refname>systemd-timesyncd</refname>
21    <refpurpose>Network Time Synchronization</refpurpose>
22  </refnamediv>
23
24  <refsynopsisdiv>
25    <para><filename>systemd-timesyncd.service</filename></para>
26    <para><filename>/usr/lib/systemd/systemd-timesyncd</filename></para>
27  </refsynopsisdiv>
28
29  <refsect1>
30    <title>Description</title>
31
32    <para><filename>systemd-timesyncd</filename> is a system service that may be used to synchronize the
33    local system clock with a remote Network Time Protocol (NTP) server. It also saves the local time to disk
34    every time the clock has been synchronized and uses this to possibly advance the system realtime clock on
35    subsequent reboots to ensure it (roughly) monotonically advances even if the system lacks a
36    battery-buffered RTC chip.</para>
37
38    <para>The <filename>systemd-timesyncd</filename> service implements SNTP only. This minimalistic service
39    will step the system clock for large offsets or slowly adjust it for smaller deltas. Complex use cases
40    that require full NTP support (and where SNTP is not sufficient) are not covered by
41    <filename>systemd-timesyncd</filename>.</para>
42
43    <para>The NTP servers contacted are determined from the global settings in
44    <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, the
45    per-link static settings in <filename>.network</filename> files, and the per-link dynamic settings
46    received over DHCP. See
47    <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
48    further details.</para>
49
50    <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
51    <command>set-ntp</command> command may be used to enable and start, or disable and stop this
52    service.</para>
53
54    <para><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
55    <command>timesync-status</command> or <command>show-timesync</command> command can be used to show the
56    current status of this service.</para>
57
58    <para><filename>systemd-timesyncd</filename> initialization delays the start of units that are ordered
59    after <filename>time-set.target</filename> (see
60    <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
61    details) until the local time has been updated from <filename>/var/lib/systemd/timesync/clock</filename>
62    (see below) in order to make it roughly monotonic. It does not delay other units until synchronization
63    with an accurate reference time sources has been reached. Use
64    <citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
65    to achieve that, which will delay start of units that are ordered after
66    <filename>time-sync.target</filename> until synchronization to an accurate reference clock is
67    reached.</para>
68  </refsect1>
69
70  <refsect1>
71    <title>Files</title>
72
73    <variablelist>
74      <varlistentry>
75        <term><filename>/var/lib/systemd/timesync/clock</filename></term>
76
77        <listitem>
78          <para>The modification time ("mtime") of this file is updated on each successful NTP synchronization
79          or after each <varname>SaveIntervalSec=</varname> time interval, as specified in
80          <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
81          At the minimum, it will be set to the systemd build date. It is used to ensure that the system clock
82          remains roughly monotonic across reboots, in case no local RTC is available.</para>
83        </listitem>
84      </varlistentry>
85
86      <varlistentry>
87        <term><filename>/run/systemd/timesync/synchronized</filename></term>
88
89        <listitem>
90          <para>A file that is touched on each successful synchronization, to assist
91          <filename>systemd-time-wait-sync</filename> and other applications to detecting synchronization
92          with accurate reference clocks.</para>
93        </listitem>
94
95      </varlistentry>
96    </variablelist>
97  </refsect1>
98
99  <refsect1>
100    <title>See Also</title>
101    <para>
102      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
103      <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
104      <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
105      <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
106      <citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
107      <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
108      <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
109      <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
110      <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>
111    </para>
112  </refsect1>
113
114</refentry>
115