chiark / gitweb /
update TODO
[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
64                 <para>Use
65                 <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
66                 to initialize the system time zone for mounted (but not
67                 booted) system images.</para>
68         </refsect1>
69
70         <refsect1>
71                 <title>Options</title>
72
73                 <para>The following options are understood:</para>
74
75                 <variablelist>
76                         <varlistentry>
77                                 <term><option>--no-ask-password</option></term>
78
79                                 <listitem><para>Do not query the user
80                                 for authentication for privileged
81                                 operations.</para></listitem>
82                         </varlistentry>
83
84                         <varlistentry>
85                                 <term><option>--adjust-system-clock</option></term>
86
87                                 <listitem><para>If
88                                 <command>set-local-rtc</command> is
89                                 invoked and this option is passed, the
90                                 system clock is synchronized from the
91                                 RTC again, taking the new setting into
92                                 account. Otherwise, the RTC is
93                                 synchronized from the system
94                                 clock.</para></listitem>
95                         </varlistentry>
96
97                         <xi:include href="user-system-options.xml" xpointer="host" />
98                         <xi:include href="user-system-options.xml" xpointer="machine" />
99
100                         <xi:include href="standard-options.xml" xpointer="help" />
101                         <xi:include href="standard-options.xml" xpointer="version" />
102                         <xi:include href="standard-options.xml" xpointer="no-pager" />
103                 </variablelist>
104
105                 <para>The following commands are understood:</para>
106
107                 <variablelist>
108                         <varlistentry>
109                                 <term><command>status</command></term>
110
111                                 <listitem><para>Show current settings
112                                 of the system clock and
113                                 RTC.</para></listitem>
114                         </varlistentry>
115
116                         <varlistentry>
117                                 <term><command>set-time [TIME]</command></term>
118
119                                 <listitem><para>Set the system clock
120                                 to the specified time. This will also
121                                 update the RTC time accordingly. The time
122                                 may be specified in the format
123                                 "2012-10-30
124                                 18:17:16".</para></listitem>
125                         </varlistentry>
126
127                         <varlistentry>
128                                 <term><command>set-timezone [TIMEZONE]</command></term>
129
130                                 <listitem><para>Set the system time
131                                 zone to the specified value. Available
132                                 timezones can be listed with
133                                 <command>list-timezones</command>. If
134                                 the RTC is configured to be in the
135                                 local time, this will also update the
136                                 RTC time. This call will alter the
137                                 <filename>/etc/localtime</filename>
138                                 symlink. See
139                                 <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
140                                 for more
141                                 information.</para></listitem>
142                         </varlistentry>
143
144                         <varlistentry>
145                                 <term><command>list-timezones</command></term>
146
147                                 <listitem><para>List available time
148                                 zones, one per line. Entries from the
149                                 list can be set as the system
150                                 timezone with
151                                 <command>set-timezone</command>.</para></listitem>
152                         </varlistentry>
153
154                         <varlistentry>
155                                 <term><command>set-local-rtc [BOOL]</command></term>
156
157                                 <listitem><para>Takes a boolean
158                                 argument. If <literal>0</literal>, the
159                                 system is configured to maintain the
160                                 RTC in universal time. If
161                                 <literal>1</literal>, it will maintain
162                                 the RTC in local time instead. Note
163                                 that maintaining the RTC in the local
164                                 timezone is not fully supported and
165                                 will create various problems with time
166                                 zone changes and daylight saving
167                                 adjustments. If at all possible, keep the
168                                 RTC in UTC mode. Note that invoking this
169                                 will also synchronize the RTC from the
170                                 system clock, unless
171                                 <option>--adjust-system-clock</option> is
172                                 passed (see above). This command will
173                                 change the 3rd line of
174                                 <filename>/etc/adjtime</filename>, as
175                                 documented in
176                                 <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
177                         </varlistentry>
178
179                         <varlistentry>
180                                 <term><command>set-ntp [BOOL]</command></term>
181
182                                 <listitem><para>Takes a boolean
183                                 argument. Controls whether NTP based
184                                 network time synchronization is
185                                 enabled (if
186                                 available).</para></listitem>
187                         </varlistentry>
188
189                 </variablelist>
190
191         </refsect1>
192
193         <refsect1>
194                 <title>Exit status</title>
195
196                 <para>On success, 0 is returned, a non-zero failure
197                 code otherwise.</para>
198         </refsect1>
199
200         <xi:include href="less-variables.xml" />
201
202         <refsect1>
203                 <title>Examples</title>
204                 <para>Show current settings:
205                 <programlisting>$ timedatectl
206       Local time: Fri, 2012-11-02 09:26:46 CET
207   Universal time: Fri, 2012-11-02 08:26:46 UTC
208         RTC time: Fri, 2012-11-02 08:26:45
209         Timezone: Europe/Warsaw
210       UTC offset: +0100
211      NTP enabled: no
212 NTP synchronized: no
213  RTC in local TZ: no
214       DST active: no
215  Last DST change: CEST → CET, DST became inactive
216                   Sun, 2012-10-28 02:59:59 CEST
217                   Sun, 2012-10-28 02:00:00 CET
218  Next DST change: CET → CEST, DST will become active
219                   the clock will jump one hour forward
220                   Sun, 2013-03-31 01:59:59 CET
221                   Sun, 2013-03-31 03:00:00 CEST</programlisting>
222                 </para>
223
224                 <para>Enable an NTP daemon (chronyd):
225                 <programlisting>$ timedatectl set-ntp true
226 ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp ===
227 Authentication is required to control whether network time synchronization shall be enabled.
228 Authenticating as: user
229 Password: ********
230 ==== AUTHENTICATION COMPLETE ===</programlisting>
231
232                 <programlisting>$ systemctl status chronyd.service
233 chronyd.service - NTP client/server
234           Loaded: loaded (/usr/lib/systemd/system/chronyd.service; enabled)
235           Active: active (running) since Fri, 2012-11-02 09:36:25 CET; 5s ago
236 ...</programlisting>
237                 </para>
238         </refsect1>
239
240         <refsect1>
241                 <title>See Also</title>
242                 <para>
243                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
244                         <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
245                         <citerefentry project='man-pages'><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
246                         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
247                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
248                         <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
249                         <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
250                 </para>
251         </refsect1>
252
253 </refentry>