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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2012 Lennart Poettering
  11 -->
  12
  13 <refentry id="timedatectl" conditional='ENABLE_TIMEDATED'
  14   xmlns:xi="http://www.w3.org/2001/XInclude">
  15
  16   <refentryinfo>
  17     <title>timedatectl</title>
  18     <productname>systemd</productname>
  19
  20     <authorgroup>
  21       <author>
  22         <contrib>Developer</contrib>
  23         <firstname>Lennart</firstname>
  24         <surname>Poettering</surname>
  25         <email>lennart@poettering.net</email>
  26       </author>
  27     </authorgroup>
  28   </refentryinfo>
  29
  30   <refmeta>
  31     <refentrytitle>timedatectl</refentrytitle>
  32     <manvolnum>1</manvolnum>
  33   </refmeta>
  34
  35   <refnamediv>
  36     <refname>timedatectl</refname>
  37     <refpurpose>Control the system time and date</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <cmdsynopsis>
  42       <command>timedatectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command>
  43     </cmdsynopsis>
  44   </refsynopsisdiv>
  45
  46   <refsect1>
  47     <title>Description</title>
  48
  49     <para><command>timedatectl</command> may be used to query and
  50     change the system clock and its settings.</para>
  51
  52     <para>Use
  53     <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  54     to initialize the system time zone for mounted (but not booted)
  55     system images.</para>
  56   </refsect1>
  57
  58   <refsect1>
  59     <title>Options</title>
  60
  61     <para>The following options are understood:</para>
  62
  63     <variablelist>
  64       <varlistentry>
  65         <term><option>--no-ask-password</option></term>
  66
  67         <listitem><para>Do not query the user for authentication for
  68         privileged operations.</para></listitem>
  69       </varlistentry>
  70
  71       <varlistentry>
  72         <term><option>--adjust-system-clock</option></term>
  73
  74         <listitem><para>If <command>set-local-rtc</command> is invoked
  75         and this option is passed, the system clock is synchronized
  76         from the RTC again, taking the new setting into account.
  77         Otherwise, the RTC is synchronized from the system
  78         clock.</para></listitem>
  79       </varlistentry>
  80
  81       <xi:include href="user-system-options.xml" xpointer="host" />
  82       <xi:include href="user-system-options.xml" xpointer="machine" />
  83
  84       <xi:include href="standard-options.xml" xpointer="help" />
  85       <xi:include href="standard-options.xml" xpointer="version" />
  86       <xi:include href="standard-options.xml" xpointer="no-pager" />
  87     </variablelist>
  88   </refsect1>
  89
  90   <refsect1>
  91     <title>Commands</title>
  92
  93     <para>The following commands are understood:</para>
  94
  95     <variablelist>
  96       <varlistentry>
  97         <term><command>status</command></term>
  98
  99         <listitem><para>Show current settings of the system clock and RTC,
 100         including whether network time synchronization through
 101         <filename>systemd-timesyncd.service</filename> is active. Even if it is
 102         inactive, a different service might still synchronize the clock.
 103         If no command is specified, this is the implied default.
 104         </para></listitem>
 105       </varlistentry>
 106
 107       <varlistentry>
 108         <term><command>set-time [TIME]</command></term>
 109
 110         <listitem><para>Set the system clock to the specified time.
 111         This will also update the RTC time accordingly. The time may
 112         be specified in the format "2012-10-30
 113         18:17:16".</para></listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term><command>set-timezone [TIMEZONE]</command></term>
 118
 119         <listitem><para>Set the system time zone to the specified
 120         value. Available timezones can be listed with
 121         <command>list-timezones</command>. If the RTC is configured to
 122         be in the local time, this will also update the RTC time. This
 123         call will alter the <filename>/etc/localtime</filename>
 124         symlink. See
 125         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 126         for more information.</para></listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><command>list-timezones</command></term>
 131
 132         <listitem><para>List available time zones, one per line.
 133         Entries from the list can be set as the system timezone with
 134         <command>set-timezone</command>.</para></listitem>
 135       </varlistentry>
 136
 137       <varlistentry>
 138         <term><command>set-local-rtc [BOOL]</command></term>
 139
 140         <listitem><para>Takes a boolean argument. If
 141         <literal>0</literal>, the system is configured to maintain the
 142         RTC in universal time. If <literal>1</literal>, it will
 143         maintain the RTC in local time instead. Note that maintaining
 144         the RTC in the local timezone is not fully supported and will
 145         create various problems with time zone changes and daylight
 146         saving adjustments. If at all possible, keep the RTC in UTC
 147         mode. Note that invoking this will also synchronize the RTC
 148         from the system clock, unless
 149         <option>--adjust-system-clock</option> is passed (see above).
 150         This command will change the 3rd line of
 151         <filename>/etc/adjtime</filename>, as documented in
 152         <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 153         </para></listitem>
 154       </varlistentry>
 155
 156       <varlistentry>
 157         <term><command>set-ntp [BOOL]</command></term>
 158
 159         <listitem><para>Takes a boolean argument. Controls whether
 160         network time synchronization is active and enabled (if
 161         available). This enables and starts, or disables and stops the
 162         <filename>systemd-timesyncd.service</filename> unit. It does
 163         not affect the state of any other, unrelated network time
 164         synchronization services that might be installed on the
 165         system. This command is hence mostly equivalent to:
 166         <command>systemctl enable --now
 167         systemd-timesyncd.service</command> and <command>systemctl
 168         disable --now systemd-timesyncd.service</command>, but is
 169         protected by a different access policy.</para>
 170
 171         <para>Note that even if time synchronization is turned off
 172         with this command, another unrelated system service might
 173         still synchronize the clock with the network. Also note that,
 174         strictly speaking,
 175         <filename>systemd-timesyncd.service</filename> does more than
 176         just network time synchronization, as it ensures a monotonic
 177         clock on systems without RTC even if no network is
 178         available. See
 179         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 180         for details about this.</para></listitem>
 181       </varlistentry>
 182
 183     </variablelist>
 184
 185   </refsect1>
 186
 187   <refsect1>
 188     <title>Exit status</title>
 189
 190     <para>On success, 0 is returned, a non-zero failure
 191     code otherwise.</para>
 192   </refsect1>
 193
 194   <xi:include href="less-variables.xml" />
 195
 196   <refsect1>
 197     <title>Examples</title>
 198     <para>Show current settings:
 199     <programlisting>$ timedatectl
 200                       Local time: Thu 2017-09-21 16:08:56 CEST
 201                   Universal time: Thu 2017-09-21 14:08:56 UTC
 202                         RTC time: Thu 2017-09-21 14:08:56
 203                        Time zone: Europe/Warsaw (CEST, +0200)
 204        System clock synchronized: yes
 205 systemd-timesyncd.service active: yes
 206                  RTC in local TZ: no</programlisting>
 207     </para>
 208
 209     <para>Enable network time synchronization:
 210     <programlisting>$ timedatectl set-ntp true
 211 ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp ===
 212 Authentication is required to control whether network time synchronization shall be enabled.
 213 Authenticating as: user
 214 Password: ********
 215 ==== AUTHENTICATION COMPLETE ===</programlisting>
 216
 217     <programlisting>$ systemctl status systemd-timesyncd.service
 218 ● systemd-timesyncd.service - Network Time Synchronization
 219    Loaded: loaded (/usr/lib/systemd/system/systemd-timesyncd.service; enabled)
 220    Active: active (running) since Mo 2015-03-30 14:20:38 CEST; 5s ago
 221      Docs: man:systemd-timesyncd.service(8)
 222  Main PID: 595 (systemd-timesyn)
 223    Status: "Using Time Server 216.239.38.15:123 (time4.google.com)."
 224    CGroup: /system.slice/systemd-timesyncd.service
 225            └─595 /usr/lib/systemd/systemd-timesyncd
 226 …</programlisting>
 227     </para>
 228   </refsect1>
 229
 230   <refsect1>
 231     <title>See Also</title>
 232     <para>
 233       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 234       <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 235       <citerefentry project='man-pages'><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 236       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 237       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 238       <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 239       <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 240       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 241     </para>
 242   </refsect1>
 243
 244 </refentry>