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 network time synchronization is active
 160         and enabled (if available). If the argument is true, this enables and starts the first existed
 161         service listed in the environment variable <varname>$SYSTEMD_TIMEDATED_NTP_SERVICES</varname>
 162         of <filename>systemd-timedated.service</filename>. If the argument is false, then this disables and
 163         stops the all services listed in <varname>$SYSTEMD_TIMEDATED_NTP_SERVICES</varname>.</para></listitem>
 164       </varlistentry>
 165
 166     </variablelist>
 167
 168   </refsect1>
 169
 170   <refsect1>
 171     <title>Exit status</title>
 172
 173     <para>On success, 0 is returned, a non-zero failure
 174     code otherwise.</para>
 175   </refsect1>
 176
 177   <xi:include href="less-variables.xml" />
 178
 179   <refsect1>
 180     <title>Examples</title>
 181     <para>Show current settings:
 182     <programlisting>$ timedatectl
 183                Local time: Thu 2017-09-21 16:08:56 CEST
 184            Universal time: Thu 2017-09-21 14:08:56 UTC
 185                  RTC time: Thu 2017-09-21 14:08:56
 186                 Time zone: Europe/Warsaw (CEST, +0200)
 187 System clock synchronized: yes
 188               NTP service: active
 189           RTC in local TZ: no</programlisting>
 190     </para>
 191
 192     <para>Enable network time synchronization:
 193     <programlisting>$ timedatectl set-ntp true
 194 ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp ===
 195 Authentication is required to control whether network time synchronization shall be enabled.
 196 Authenticating as: user
 197 Password: ********
 198 ==== AUTHENTICATION COMPLETE ===</programlisting>
 199
 200     <programlisting>$ systemctl status systemd-timesyncd.service
 201 ● systemd-timesyncd.service - Network Time Synchronization
 202    Loaded: loaded (/usr/lib/systemd/system/systemd-timesyncd.service; enabled)
 203    Active: active (running) since Mo 2015-03-30 14:20:38 CEST; 5s ago
 204      Docs: man:systemd-timesyncd.service(8)
 205  Main PID: 595 (systemd-timesyn)
 206    Status: "Using Time Server 216.239.38.15:123 (time4.google.com)."
 207    CGroup: /system.slice/systemd-timesyncd.service
 208            └─595 /usr/lib/systemd/systemd-timesyncd
 209 …</programlisting>
 210     </para>
 211   </refsect1>
 212
 213   <refsect1>
 214     <title>See Also</title>
 215     <para>
 216       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 217       <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 218       <citerefentry project='man-pages'><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 219       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 220       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 221       <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 222       <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 223       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 224     </para>
 225   </refsect1>
 226
 227 </refentry>