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