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
  26         <refentryinfo>
  27                 <title>timedatectl</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>timedatectl</refentrytitle>
  42                 <manvolnum>1</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>timedatectl</refname>
  47                 <refpurpose>Control the system time and date</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <cmdsynopsis>
  52                         <command>timedatectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command>
  53                 </cmdsynopsis>
  54         </refsynopsisdiv>
  55
  56         <refsect1>
  57                 <title>Description</title>
  58
  59                 <para><command>timedatectl</command> may be used to
  60                 query and change the system clock and its
  61                 settings.</para>
  62         </refsect1>
  63
  64         <refsect1>
  65                 <title>Options</title>
  66
  67                 <para>The following options are understood:</para>
  68
  69                 <variablelist>
  70                         <varlistentry>
  71                                 <term><option>-h</option></term>
  72                                 <term><option>--help</option></term>
  73
  74                                 <listitem><para>Prints a short help
  75                                 text and exits.</para></listitem>
  76                         </varlistentry>
  77
  78                         <varlistentry>
  79                                 <term><option>--version</option></term>
  80
  81                                 <listitem><para>Prints a short version
  82                                 string and exits.</para></listitem>
  83                         </varlistentry>
  84
  85                         <varlistentry>
  86                                 <term><option>--no-pager</option></term>
  87
  88                                 <listitem><para>Do not pipe output into a
  89                                 pager.</para></listitem>
  90                         </varlistentry>
  91
  92                         <varlistentry>
  93                                 <term><option>--no-ask-password</option></term>
  94
  95                                 <listitem><para>Do not query the user
  96                                 for authentication for privileged
  97                                 operations.</para></listitem>
  98                         </varlistentry>
  99
 100                         <varlistentry>
 101                                 <term><option>-H</option></term>
 102                                 <term><option>--host=</option></term>
 103
 104                                 <listitem><para>Execute the operation
 105                                 remotely. Specify a hostname, or
 106                                 username and hostname separated by <literal>@</literal>,
 107                                 to connect to. This will use SSH to
 108                                 talk to the remote machine manager
 109                                 instance.</para></listitem>
 110                         </varlistentry>
 111
 112                         <varlistentry>
 113                                 <term><option>-M</option></term>
 114                                 <term><option>--machine=</option></term>
 115
 116                                 <listitem><para>Execute operation on a
 117                                 local container. Specify a container
 118                                 name to connect to.</para></listitem>
 119                         </varlistentry>
 120
 121                         <varlistentry>
 122                                 <term><option>--adjust-system-clock</option></term>
 123
 124                                 <listitem><para>If
 125                                 <command>set-local-rtc</command> is
 126                                 invoked and this option is passed, the
 127                                 system clock is synchronized from the
 128                                 RTC again, taking the new setting into
 129                                 account. Otherwise, the RTC is
 130                                 synchronized from the system
 131                                 clock.</para></listitem>
 132                         </varlistentry>
 133                 </variablelist>
 134
 135                 <para>The following commands are understood:</para>
 136
 137                 <variablelist>
 138                         <varlistentry>
 139                                 <term><command>status</command></term>
 140
 141                                 <listitem><para>Show current settings
 142                                 of the system clock and
 143                                 RTC.</para></listitem>
 144                         </varlistentry>
 145
 146                         <varlistentry>
 147                                 <term><command>set-time [TIME]</command></term>
 148
 149                                 <listitem><para>Set the system clock
 150                                 to the specified time. This will also
 151                                 update the RTC time accordingly. The time
 152                                 may be specified in the format
 153                                 "2012-10-30
 154                                 18:17:16".</para></listitem>
 155                         </varlistentry>
 156
 157                         <varlistentry>
 158                                 <term><command>set-timezone [TIMEZONE]</command></term>
 159
 160                                 <listitem><para>Set the system time
 161                                 zone to the specified value. Available
 162                                 timezones can be listed with
 163                                 <command>list-timezones</command>. If
 164                                 the RTC is configured to be in the
 165                                 local time, this will also update the
 166                                 RTC time. This call will alter the
 167                                 <filename>/etc/localtime</filename>
 168                                 symlink. See
 169                                 <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 170                                 for more
 171                                 information.</para></listitem>
 172                         </varlistentry>
 173
 174                         <varlistentry>
 175                                 <term><command>list-timezones</command></term>
 176
 177                                 <listitem><para>List available time
 178                                 zones, one per line. Entries from the
 179                                 list can be set as the system
 180                                 timezone with
 181                                 <command>set-timezone</command>.</para></listitem>
 182                         </varlistentry>
 183
 184                         <varlistentry>
 185                                 <term><command>set-local-rtc [BOOL]</command></term>
 186
 187                                 <listitem><para>Takes a boolean
 188                                 argument. If <literal>0</literal>, the
 189                                 system is configured to maintain the
 190                                 RTC in universal time. If
 191                                 <literal>1</literal>, it will maintain
 192                                 the RTC in local time instead. Note
 193                                 that maintaining the RTC in the local
 194                                 timezone is not fully supported and
 195                                 will create various problems with time
 196                                 zone changes and daylight saving
 197                                 adjustments. If at all possible, keep the
 198                                 RTC in UTC mode. Note that invoking this
 199                                 will also synchronize the RTC from the
 200                                 system clock, unless
 201                                 <option>--adjust-system-clock</option> is
 202                                 passed (see above). This command will
 203                                 change the 3rd line of
 204                                 <filename>/etc/adjtime</filename>, as
 205                                 documented in
 206                                 <citerefentry><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
 207                         </varlistentry>
 208
 209                         <varlistentry>
 210                                 <term><command>set-ntp [BOOL]</command></term>
 211
 212                                 <listitem><para>Takes a boolean
 213                                 argument. Controls whether NTP based
 214                                 network time synchronization is
 215                                 enabled (if
 216                                 available).</para></listitem>
 217                         </varlistentry>
 218
 219                 </variablelist>
 220
 221         </refsect1>
 222
 223         <refsect1>
 224                 <title>Exit status</title>
 225
 226                 <para>On success, 0 is returned, a non-zero failure
 227                 code otherwise.</para>
 228         </refsect1>
 229
 230         <refsect1>
 231                 <title>Environment</title>
 232
 233                 <variablelist class='environment-variables'>
 234                         <varlistentry>
 235                                 <term><varname>$SYSTEMD_PAGER</varname></term>
 236                                 <listitem><para>Pager to use when
 237                                 <option>--no-pager</option> is not given;
 238                                 overrides <varname>$PAGER</varname>.  Setting
 239                                 this to an empty string or the value
 240                                 <literal>cat</literal> is equivalent to passing
 241                                 <option>--no-pager</option>.</para></listitem>
 242                                 <term><varname>$SYSTEMD_LESS</varname></term>
 243                                 <listitem><para><varname>$SYSTEMD_LESS</varname> overrides the
 244                                 default options passed to <literal>less</literal>
 245                                 (<literal>FRSXMK</literal>).</para></listitem>
 246                         </varlistentry>
 247                 </variablelist>
 248         </refsect1>
 249
 250         <refsect1>
 251                 <title>Examples</title>
 252                 <para>Show current settings:
 253                 <programlisting>
 254 $ timedatectl
 255       Local time: Fri, 2012-11-02 09:26:46 CET
 256   Universal time: Fri, 2012-11-02 08:26:46 UTC
 257         RTC time: Fri, 2012-11-02 08:26:45
 258         Timezone: Europe/Warsaw
 259       UTC offset: +0100
 260      NTP enabled: no
 261 NTP synchronized: no
 262  RTC in local TZ: no
 263       DST active: no
 264  Last DST change: CEST → CET, DST became inactive
 265                   Sun, 2012-10-28 02:59:59 CEST
 266                   Sun, 2012-10-28 02:00:00 CET
 267  Next DST change: CET → CEST, DST will become active
 268                   the clock will jump one hour forward
 269                   Sun, 2013-03-31 01:59:59 CET
 270                   Sun, 2013-03-31 03:00:00 CEST
 271                 </programlisting>
 272                 </para>
 273
 274                 <para>Enable an NTP daemon (chronyd):
 275                 <programlisting>
 276 $ timedatectl set-ntp true
 277 ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp ===
 278 Authentication is required to control whether network time synchronization shall be enabled.
 279 Authenticating as: user
 280 Password: ********
 281 ==== AUTHENTICATION COMPLETE ===
 282                 </programlisting>
 283
 284                 <programlisting>
 285 $ systemctl status chronyd.service
 286 chronyd.service - NTP client/server
 287           Loaded: loaded (/usr/lib/systemd/system/chronyd.service; enabled)
 288           Active: active (running) since Fri, 2012-11-02 09:36:25 CET; 5s ago
 289 ...
 290                 </programlisting>
 291                 </para>
 292         </refsect1>
 293
 294         <refsect1>
 295                 <title>See Also</title>
 296                 <para>
 297                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 298                         <citerefentry><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 299                         <citerefentry><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 300                         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 301                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 302                         <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 303                 </para>
 304         </refsect1>
 305
 306 </refentry>