]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/timedatectl.xml
Merge pull request #8822 from fbuihuu/rfc-tmpfiles-safe-upstream
[thirdparty/systemd.git] / man / timedatectl.xml
CommitLineData
6d0274f1
LP
1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6d0274f1
LP
4
5<!--
572eb058 6 SPDX-License-Identifier: LGPL-2.1+
6d0274f1
LP
7-->
8
1e4acc77 9<refentry id="timedatectl" conditional='ENABLE_TIMEDATECTL'
798d3a52
ZJS
10 xmlns:xi="http://www.w3.org/2001/XInclude">
11
12 <refentryinfo>
13 <title>timedatectl</title>
14 <productname>systemd</productname>
798d3a52
ZJS
15 </refentryinfo>
16
17 <refmeta>
18 <refentrytitle>timedatectl</refentrytitle>
19 <manvolnum>1</manvolnum>
20 </refmeta>
21
22 <refnamediv>
23 <refname>timedatectl</refname>
24 <refpurpose>Control the system time and date</refpurpose>
25 </refnamediv>
26
27 <refsynopsisdiv>
28 <cmdsynopsis>
29 <command>timedatectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command>
30 </cmdsynopsis>
31 </refsynopsisdiv>
32
33 <refsect1>
34 <title>Description</title>
35
36 <para><command>timedatectl</command> may be used to query and
37 change the system clock and its settings.</para>
38
39 <para>Use
40 <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
41 to initialize the system time zone for mounted (but not booted)
42 system images.</para>
1e4acc77
YW
43
44 <para><command>timedatectl</command> may be used to show the current status of
45 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
46 </para>
47
798d3a52
ZJS
48 </refsect1>
49
50 <refsect1>
51 <title>Options</title>
52
53 <para>The following options are understood:</para>
54
55 <variablelist>
56 <varlistentry>
57 <term><option>--no-ask-password</option></term>
58
59 <listitem><para>Do not query the user for authentication for
60 privileged operations.</para></listitem>
61 </varlistentry>
62
63 <varlistentry>
64 <term><option>--adjust-system-clock</option></term>
65
66 <listitem><para>If <command>set-local-rtc</command> is invoked
67 and this option is passed, the system clock is synchronized
68 from the RTC again, taking the new setting into account.
69 Otherwise, the RTC is synchronized from the system
70 clock.</para></listitem>
71 </varlistentry>
72
1e4acc77
YW
73 <varlistentry>
74 <term><option>--monitor</option></term>
75
76 <listitem><para>If <command>timesync-status</command> is invoked and this option is passed,
77 then <command>timedatectl</command> monitors the status of
78 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
79 and updates the outputs. Use Ctrl-C to terminate the monitoring.</para></listitem>
80 </varlistentry>
81
82 <varlistentry>
83 <term><option>-a</option></term>
84 <term><option>-all</option></term>
85
86 <listitem><para>When showing properties of
87 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
88 show all properties regardless of whether they are set or not.</para></listitem>
89 </varlistentry>
90
91 <varlistentry>
92 <term><option>-p</option></term>
93 <term><option>--property=</option></term>
94
95 <listitem><para>When showing properties of
96 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
97 limit display to certain properties as specified as argument. If not specified, all set properties are shown.
98 The argument should be a property name, such as <literal>ServerName</literal>. If specified more than once,
99 all properties with the specified names are shown.</para></listitem>
100 </varlistentry>
101
102 <varlistentry>
103 <term><option>--value</option></term>
104
105 <listitem>
106 <para>When printing properties with <command>show-timesync</command>, only print the value, and skip the
107 property name and <literal>=</literal>.</para></listitem>
108 </varlistentry>
109
798d3a52
ZJS
110 <xi:include href="user-system-options.xml" xpointer="host" />
111 <xi:include href="user-system-options.xml" xpointer="machine" />
112
113 <xi:include href="standard-options.xml" xpointer="help" />
114 <xi:include href="standard-options.xml" xpointer="version" />
115 <xi:include href="standard-options.xml" xpointer="no-pager" />
116 </variablelist>
24fcd009
YW
117 </refsect1>
118
119 <refsect1>
120 <title>Commands</title>
798d3a52
ZJS
121
122 <para>The following commands are understood:</para>
123
124 <variablelist>
125 <varlistentry>
126 <term><command>status</command></term>
127
1b7ac91f
ZJS
128 <listitem><para>Show current settings of the system clock and RTC,
129 including whether network time synchronization through
130 <filename>systemd-timesyncd.service</filename> is active. Even if it is
131 inactive, a different service might still synchronize the clock.
24fcd009 132 If no command is specified, this is the implied default.
1b7ac91f 133 </para></listitem>
798d3a52
ZJS
134 </varlistentry>
135
ead0adb1
YW
136 <varlistentry>
137 <term><command>show</command></term>
138
139 <listitem><para>Show the same information as <option>status</option>, but in machine readable form.
140 This command is intended to be used whenever computer-parsable output is required.
141 Use <option>status</option> if you are looking for formatted human-readable output.</para>
142 <para>By default, empty properties are suppressed. Use <option>--all</option> to show those too.
143 To select specific properties to show, use <option>--property=</option>.</para></listitem>
144 </varlistentry>
145
798d3a52
ZJS
146 <varlistentry>
147 <term><command>set-time [TIME]</command></term>
148
149 <listitem><para>Set the system clock to the specified time.
150 This will also update the RTC time accordingly. The time may
151 be specified in the format "2012-10-30
152 18:17:16".</para></listitem>
153 </varlistentry>
154
155 <varlistentry>
156 <term><command>set-timezone [TIMEZONE]</command></term>
157
158 <listitem><para>Set the system time zone to the specified
159 value. Available timezones can be listed with
160 <command>list-timezones</command>. If the RTC is configured to
161 be in the local time, this will also update the RTC time. This
162 call will alter the <filename>/etc/localtime</filename>
163 symlink. See
164 <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
165 for more information.</para></listitem>
166 </varlistentry>
167
168 <varlistentry>
169 <term><command>list-timezones</command></term>
170
171 <listitem><para>List available time zones, one per line.
172 Entries from the list can be set as the system timezone with
173 <command>set-timezone</command>.</para></listitem>
174 </varlistentry>
175
176 <varlistentry>
177 <term><command>set-local-rtc [BOOL]</command></term>
178
179 <listitem><para>Takes a boolean argument. If
180 <literal>0</literal>, the system is configured to maintain the
181 RTC in universal time. If <literal>1</literal>, it will
182 maintain the RTC in local time instead. Note that maintaining
183 the RTC in the local timezone is not fully supported and will
184 create various problems with time zone changes and daylight
185 saving adjustments. If at all possible, keep the RTC in UTC
186 mode. Note that invoking this will also synchronize the RTC
187 from the system clock, unless
188 <option>--adjust-system-clock</option> is passed (see above).
189 This command will change the 3rd line of
190 <filename>/etc/adjtime</filename>, as documented in
191 <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
192 </para></listitem>
193 </varlistentry>
194
195 <varlistentry>
196 <term><command>set-ntp [BOOL]</command></term>
197
326208e0
YW
198 <listitem><para>Takes a boolean argument. Controls whether network time synchronization is active
199 and enabled (if available). If the argument is true, this enables and starts the first existed
200 service listed in the environment variable <varname>$SYSTEMD_TIMEDATED_NTP_SERVICES</varname>
201 of <filename>systemd-timedated.service</filename>. If the argument is false, then this disables and
202 stops the all services listed in <varname>$SYSTEMD_TIMEDATED_NTP_SERVICES</varname>.</para></listitem>
798d3a52
ZJS
203 </varlistentry>
204
205 </variablelist>
206
ead0adb1
YW
207 <refsect2>
208 <title>systemd-timesyncd Commands</title>
1e4acc77 209
ead0adb1
YW
210 <para>The following commands are specific to
211 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
212 </para>
1e4acc77
YW
213
214 <variablelist>
215 <varlistentry>
216 <term><command>timesync-status</command></term>
217
218 <listitem><para>Show current status of
219 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
220 If <option>--monitor</option> is specified, then this will monitor the status updates.</para></listitem>
221 </varlistentry>
222
223 <varlistentry>
224 <term><command>show-timesync</command></term>
225
ead0adb1
YW
226 <listitem><para>Show the same information as <option>timesync-status</option>, but in machine readable form.
227 This command is intended to be used whenever computer-parsable output is required.
228 Use <option>timesync-status</option> if you are looking for formatted human-readable output.</para>
229 <para>By default, empty properties are suppressed. Use <option>--all</option> to show those too.
230 To select specific properties to show, use <option>--property=</option>.</para></listitem>
1e4acc77
YW
231 </varlistentry>
232 </variablelist>
233
234 </refsect2>
235
798d3a52
ZJS
236 </refsect1>
237
238 <refsect1>
239 <title>Exit status</title>
240
241 <para>On success, 0 is returned, a non-zero failure
242 code otherwise.</para>
243 </refsect1>
244
245 <xi:include href="less-variables.xml" />
246
247 <refsect1>
248 <title>Examples</title>
249 <para>Show current settings:
250 <programlisting>$ timedatectl
326208e0
YW
251 Local time: Thu 2017-09-21 16:08:56 CEST
252 Universal time: Thu 2017-09-21 14:08:56 UTC
253 RTC time: Thu 2017-09-21 14:08:56
254 Time zone: Europe/Warsaw (CEST, +0200)
255System clock synchronized: yes
256 NTP service: active
257 RTC in local TZ: no</programlisting>
798d3a52 258 </para>
be1015dd 259
b90930c7 260 <para>Enable network time synchronization:
798d3a52 261 <programlisting>$ timedatectl set-ntp true
be1015dd
ZJS
262==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp ===
263Authentication is required to control whether network time synchronization shall be enabled.
264Authenticating as: user
265Password: ********
9fccdb0f 266==== AUTHENTICATION COMPLETE ===</programlisting>
be1015dd 267
57506e7d
LP
268 <programlisting>$ systemctl status systemd-timesyncd.service
269● systemd-timesyncd.service - Network Time Synchronization
12b42c76 270 Loaded: loaded (/usr/lib/systemd/system/systemd-timesyncd.service; enabled)
57506e7d
LP
271 Active: active (running) since Mo 2015-03-30 14:20:38 CEST; 5s ago
272 Docs: man:systemd-timesyncd.service(8)
273 Main PID: 595 (systemd-timesyn)
274 Status: "Using Time Server 216.239.38.15:123 (time4.google.com)."
275 CGroup: /system.slice/systemd-timesyncd.service
12b42c76 276 └─595 /usr/lib/systemd/systemd-timesyncd
1eecafb8 277…</programlisting>
798d3a52 278 </para>
1e4acc77
YW
279
280 <para>Show current status of
281 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>:
282 <programlisting>$ timedatectl timesync-status
283 Server: 216.239.38.15 (time4.google.com)
284Poll interval: 1min 4s (min: 32s; max 34min 8s)
285 Leap: normal
286 Version: 4
287 Stratum: 1
288 Reference: GPS
289 Precision: 1us (-20)
290Root distance: 335us (max: 5s)
291 Offset: +316us
292 Delay: 349us
293 Jitter: 0
294 Packet count: 1
295 Frequency: -8.802ppm</programlisting>
296 </para>
297
798d3a52
ZJS
298 </refsect1>
299
300 <refsect1>
301 <title>See Also</title>
302 <para>
303 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
304 <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
305 <citerefentry project='man-pages'><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
306 <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
307 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
308 <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
ff5921ba 309 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a52
ZJS
310 <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
311 </para>
312 </refsect1>
6d0274f1
LP
313
314</refentry>