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 query and
  61     change the system clock and its settings.</para>
  62
  63     <para>Use
  64     <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  65     to initialize the system time zone for mounted (but not booted)
  66     system images.</para>
  67   </refsect1>
  68
  69   <refsect1>
  70     <title>Options</title>
  71
  72     <para>The following options are understood:</para>
  73
  74     <variablelist>
  75       <varlistentry>
  76         <term><option>--no-ask-password</option></term>
  77
  78         <listitem><para>Do not query the user for authentication for
  79         privileged operations.</para></listitem>
  80       </varlistentry>
  81
  82       <varlistentry>
  83         <term><option>--adjust-system-clock</option></term>
  84
  85         <listitem><para>If <command>set-local-rtc</command> is invoked
  86         and this option is passed, the system clock is synchronized
  87         from the RTC again, taking the new setting into account.
  88         Otherwise, the RTC is synchronized from the system
  89         clock.</para></listitem>
  90       </varlistentry>
  91
  92       <xi:include href="user-system-options.xml" xpointer="host" />
  93       <xi:include href="user-system-options.xml" xpointer="machine" />
  94
  95       <xi:include href="standard-options.xml" xpointer="help" />
  96       <xi:include href="standard-options.xml" xpointer="version" />
  97       <xi:include href="standard-options.xml" xpointer="no-pager" />
  98     </variablelist>
  99
 100     <para>The following commands are understood:</para>
 101
 102     <variablelist>
 103       <varlistentry>
 104         <term><command>status</command></term>
 105
 106         <listitem><para>Show current settings of the system clock and RTC,
 107         including whether network time synchronization through
 108         <filename>systemd-timesyncd.service</filename> is active. Even if it is
 109         inactive, a different service might still synchronize the clock.
 110         </para></listitem>
 111       </varlistentry>
 112
 113       <varlistentry>
 114         <term><command>set-time [TIME]</command></term>
 115
 116         <listitem><para>Set the system clock to the specified time.
 117         This will also update the RTC time accordingly. The time may
 118         be specified in the format "2012-10-30
 119         18:17:16".</para></listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term><command>set-timezone [TIMEZONE]</command></term>
 124
 125         <listitem><para>Set the system time zone to the specified
 126         value. Available timezones can be listed with
 127         <command>list-timezones</command>. If the RTC is configured to
 128         be in the local time, this will also update the RTC time. This
 129         call will alter the <filename>/etc/localtime</filename>
 130         symlink. See
 131         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 132         for more information.</para></listitem>
 133       </varlistentry>
 134
 135       <varlistentry>
 136         <term><command>list-timezones</command></term>
 137
 138         <listitem><para>List available time zones, one per line.
 139         Entries from the list can be set as the system timezone with
 140         <command>set-timezone</command>.</para></listitem>
 141       </varlistentry>
 142
 143       <varlistentry>
 144         <term><command>set-local-rtc [BOOL]</command></term>
 145
 146         <listitem><para>Takes a boolean argument. If
 147         <literal>0</literal>, the system is configured to maintain the
 148         RTC in universal time. If <literal>1</literal>, it will
 149         maintain the RTC in local time instead. Note that maintaining
 150         the RTC in the local timezone is not fully supported and will
 151         create various problems with time zone changes and daylight
 152         saving adjustments. If at all possible, keep the RTC in UTC
 153         mode. Note that invoking this will also synchronize the RTC
 154         from the system clock, unless
 155         <option>--adjust-system-clock</option> is passed (see above).
 156         This command will change the 3rd line of
 157         <filename>/etc/adjtime</filename>, as documented in
 158         <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 159         </para></listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term><command>set-ntp [BOOL]</command></term>
 164
 165         <listitem><para>Takes a boolean argument. Controls whether
 166         network time synchronization is active and enabled (if
 167         available). This enables and starts, or disables and stops the
 168         <filename>systemd-timesyncd.service</filename> unit. It does
 169         not affect the state of any other, unrelated network time
 170         synchronization services that might be installed on the
 171         system. This command is hence mostly equivalent to:
 172         <command>systemctl enable --now
 173         systemd-timesyncd.service</command> and <command>systemctl
 174         disable --now systemd-timesyncd.service</command>, but is
 175         protected by a different access policy.</para>
 176
 177         <para>Note that even if time synchronization is turned off
 178         with this command, another unrelated system service might
 179         still synchronize the clock with the network. Also note that,
 180         strictly speaking,
 181         <filename>systemd-timesyncd.service</filename> does more than
 182         just network time synchronization, as it ensures a monotonic
 183         clock on systems without RTC even if no network is
 184         available. See
 185         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 186         for details about this.</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: Thu 2017-09-21 16:08:56 CEST
 207                   Universal time: Thu 2017-09-21 14:08:56 UTC
 208                         RTC time: Thu 2017-09-21 14:08:56
 209                        Time zone: Europe/Warsaw (CEST, +0200)
 210        System clock synchronized: yes
 211 systemd-timesyncd.service active: yes
 212                  RTC in local TZ: no</programlisting>
 213     </para>
 214
 215     <para>Enable network time synchronization:
 216     <programlisting>$ timedatectl set-ntp true
 217 ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp ===
 218 Authentication is required to control whether network time synchronization shall be enabled.
 219 Authenticating as: user
 220 Password: ********
 221 ==== AUTHENTICATION COMPLETE ===</programlisting>
 222
 223     <programlisting>$ systemctl status systemd-timesyncd.service
 224 ● systemd-timesyncd.service - Network Time Synchronization
 225    Loaded: loaded (/usr/lib/systemd/system/systemd-timesyncd.service; enabled)
 226    Active: active (running) since Mo 2015-03-30 14:20:38 CEST; 5s ago
 227      Docs: man:systemd-timesyncd.service(8)
 228  Main PID: 595 (systemd-timesyn)
 229    Status: "Using Time Server 216.239.38.15:123 (time4.google.com)."
 230    CGroup: /system.slice/systemd-timesyncd.service
 231            └─595 /usr/lib/systemd/systemd-timesyncd
 232 …</programlisting>
 233     </para>
 234   </refsect1>
 235
 236   <refsect1>
 237     <title>See Also</title>
 238     <para>
 239       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 240       <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 241       <citerefentry project='man-pages'><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 242       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 243       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 244       <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 245       <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 246       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 247     </para>
 248   </refsect1>
 249
 250 </refentry>