chiark / gitweb /
man: fix grammatical errors and other formatting issues
[elogind.git] / man / timedatectl.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2012 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="timedatectl" conditional='ENABLE_TIMEDATED'
25         xmlns:xi="http://www.w3.org/2001/XInclude">
26
27         <refentryinfo>
28                 <title>timedatectl</title>
29                 <productname>systemd</productname>
30
31                 <authorgroup>
32                         <author>
33                                 <contrib>Developer</contrib>
34                                 <firstname>Lennart</firstname>
35                                 <surname>Poettering</surname>
36                                 <email>lennart@poettering.net</email>
37                         </author>
38                 </authorgroup>
39         </refentryinfo>
40
41         <refmeta>
42                 <refentrytitle>timedatectl</refentrytitle>
43                 <manvolnum>1</manvolnum>
44         </refmeta>
45
46         <refnamediv>
47                 <refname>timedatectl</refname>
48                 <refpurpose>Control the system time and date</refpurpose>
49         </refnamediv>
50
51         <refsynopsisdiv>
52                 <cmdsynopsis>
53                         <command>timedatectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command>
54                 </cmdsynopsis>
55         </refsynopsisdiv>
56
57         <refsect1>
58                 <title>Description</title>
59
60                 <para><command>timedatectl</command> may be used to
61                 query and change the system clock and its
62                 settings.</para>
63         </refsect1>
64
65         <refsect1>
66                 <title>Options</title>
67
68                 <para>The following options are understood:</para>
69
70                 <variablelist>
71                         <varlistentry>
72                                 <term><option>-h</option></term>
73                                 <term><option>--help</option></term>
74
75                                 <listitem><para>Prints a short help
76                                 text and exits.</para></listitem>
77                         </varlistentry>
78
79                         <varlistentry>
80                                 <term><option>--version</option></term>
81
82                                 <listitem><para>Prints a short version
83                                 string and exits.</para></listitem>
84                         </varlistentry>
85
86                         <varlistentry>
87                                 <term><option>--no-pager</option></term>
88
89                                 <listitem><para>Do not pipe output into a
90                                 pager.</para></listitem>
91                         </varlistentry>
92
93                         <varlistentry>
94                                 <term><option>--no-ask-password</option></term>
95
96                                 <listitem><para>Do not query the user
97                                 for authentication for privileged
98                                 operations.</para></listitem>
99                         </varlistentry>
100
101                         <varlistentry>
102                                 <term><option>-H</option></term>
103                                 <term><option>--host=</option></term>
104
105                                 <listitem><para>Execute the operation
106                                 remotely. Specify a hostname, or
107                                 username and hostname separated by <literal>@</literal>,
108                                 to connect to. This will use SSH to
109                                 talk to the remote machine manager
110                                 instance.</para></listitem>
111                         </varlistentry>
112
113                         <varlistentry>
114                                 <term><option>-M</option></term>
115                                 <term><option>--machine=</option></term>
116
117                                 <listitem><para>Execute operation on a
118                                 local container. Specify a container
119                                 name to connect to.</para></listitem>
120                         </varlistentry>
121
122                         <varlistentry>
123                                 <term><option>--adjust-system-clock</option></term>
124
125                                 <listitem><para>If
126                                 <command>set-local-rtc</command> is
127                                 invoked and this option is passed, the
128                                 system clock is synchronized from the
129                                 RTC again, taking the new setting into
130                                 account. Otherwise, the RTC is
131                                 synchronized from the system
132                                 clock.</para></listitem>
133                         </varlistentry>
134                 </variablelist>
135
136                 <para>The following commands are understood:</para>
137
138                 <variablelist>
139                         <varlistentry>
140                                 <term><command>status</command></term>
141
142                                 <listitem><para>Show current settings
143                                 of the system clock and
144                                 RTC.</para></listitem>
145                         </varlistentry>
146
147                         <varlistentry>
148                                 <term><command>set-time [TIME]</command></term>
149
150                                 <listitem><para>Set the system clock
151                                 to the specified time. This will also
152                                 update the RTC time accordingly. The time
153                                 may be specified in the format
154                                 "2012-10-30
155                                 18:17:16".</para></listitem>
156                         </varlistentry>
157
158                         <varlistentry>
159                                 <term><command>set-timezone [TIMEZONE]</command></term>
160
161                                 <listitem><para>Set the system time
162                                 zone to the specified value. Available
163                                 timezones can be listed with
164                                 <command>list-timezones</command>. If
165                                 the RTC is configured to be in the
166                                 local time, this will also update the
167                                 RTC time. This call will alter the
168                                 <filename>/etc/localtime</filename>
169                                 symlink. See
170                                 <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
171                                 for more
172                                 information.</para></listitem>
173                         </varlistentry>
174
175                         <varlistentry>
176                                 <term><command>list-timezones</command></term>
177
178                                 <listitem><para>List available time
179                                 zones, one per line. Entries from the
180                                 list can be set as the system
181                                 timezone with
182                                 <command>set-timezone</command>.</para></listitem>
183                         </varlistentry>
184
185                         <varlistentry>
186                                 <term><command>set-local-rtc [BOOL]</command></term>
187
188                                 <listitem><para>Takes a boolean
189                                 argument. If <literal>0</literal>, the
190                                 system is configured to maintain the
191                                 RTC in universal time. If
192                                 <literal>1</literal>, it will maintain
193                                 the RTC in local time instead. Note
194                                 that maintaining the RTC in the local
195                                 timezone is not fully supported and
196                                 will create various problems with time
197                                 zone changes and daylight saving
198                                 adjustments. If at all possible, keep the
199                                 RTC in UTC mode. Note that invoking this
200                                 will also synchronize the RTC from the
201                                 system clock, unless
202                                 <option>--adjust-system-clock</option> is
203                                 passed (see above). This command will
204                                 change the 3rd line of
205                                 <filename>/etc/adjtime</filename>, as
206                                 documented in
207                                 <citerefentry><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
208                         </varlistentry>
209
210                         <varlistentry>
211                                 <term><command>set-ntp [BOOL]</command></term>
212
213                                 <listitem><para>Takes a boolean
214                                 argument. Controls whether NTP based
215                                 network time synchronization is
216                                 enabled (if
217                                 available).</para></listitem>
218                         </varlistentry>
219
220                 </variablelist>
221
222         </refsect1>
223
224         <refsect1>
225                 <title>Exit status</title>
226
227                 <para>On success, 0 is returned, a non-zero failure
228                 code otherwise.</para>
229         </refsect1>
230
231         <xi:include href="less-variables.xml" />
232
233         <refsect1>
234                 <title>Examples</title>
235                 <para>Show current settings:
236                 <programlisting>$ timedatectl
237       Local time: Fri, 2012-11-02 09:26:46 CET
238   Universal time: Fri, 2012-11-02 08:26:46 UTC
239         RTC time: Fri, 2012-11-02 08:26:45
240         Timezone: Europe/Warsaw
241       UTC offset: +0100
242      NTP enabled: no
243 NTP synchronized: no
244  RTC in local TZ: no
245       DST active: no
246  Last DST change: CEST → CET, DST became inactive
247                   Sun, 2012-10-28 02:59:59 CEST
248                   Sun, 2012-10-28 02:00:00 CET
249  Next DST change: CET → CEST, DST will become active
250                   the clock will jump one hour forward
251                   Sun, 2013-03-31 01:59:59 CET
252                   Sun, 2013-03-31 03:00:00 CEST</programlisting>
253                 </para>
254
255                 <para>Enable an NTP daemon (chronyd):
256                 <programlisting>$ timedatectl set-ntp true
257 ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp ===
258 Authentication is required to control whether network time synchronization shall be enabled.
259 Authenticating as: user
260 Password: ********
261 ==== AUTHENTICATION COMPLETE ===</programlisting>
262
263                 <programlisting>$ systemctl status chronyd.service
264 chronyd.service - NTP client/server
265           Loaded: loaded (/usr/lib/systemd/system/chronyd.service; enabled)
266           Active: active (running) since Fri, 2012-11-02 09:36:25 CET; 5s ago
267 ...</programlisting>
268                 </para>
269         </refsect1>
270
271         <refsect1>
272                 <title>See Also</title>
273                 <para>
274                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
275                         <citerefentry><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
276                         <citerefentry><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
277                         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
278                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
279                         <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
280                 </para>
281         </refsect1>
282
283 </refentry>