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