man/timedatectl.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="timedatectl" conditional='ENABLE_TIMEDATECTL'
   7   xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>timedatectl</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>timedatectl</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>timedatectl</refname>
  21     <refpurpose>Control the system time and date</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>timedatectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command>
  27     </cmdsynopsis>
  28   </refsynopsisdiv>
  29
  30   <refsect1>
  31     <title>Description</title>
  32
  33     <para><command>timedatectl</command> may be used to query and
  34     change the system clock and its settings.</para>
  35
  36     <para>Use
  37     <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  38     to initialize the system time zone for mounted (but not booted)
  39     system images.</para>
  40
  41     <para><command>timedatectl</command> may be used to show the current status of
  42     <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  43     </para>
  44
  45   </refsect1>
  46
  47   <refsect1>
  48     <title>Options</title>
  49
  50     <para>The following options are understood:</para>
  51
  52     <variablelist>
  53       <varlistentry>
  54         <term><option>--no-ask-password</option></term>
  55
  56         <listitem><para>Do not query the user for authentication for
  57         privileged operations.</para></listitem>
  58       </varlistentry>
  59
  60       <varlistentry>
  61         <term><option>--adjust-system-clock</option></term>
  62
  63         <listitem><para>If <command>set-local-rtc</command> is invoked
  64         and this option is passed, the system clock is synchronized
  65         from the RTC again, taking the new setting into account.
  66         Otherwise, the RTC is synchronized from the system
  67         clock.</para></listitem>
  68       </varlistentry>
  69
  70       <varlistentry>
  71         <term><option>--monitor</option></term>
  72
  73         <listitem><para>If <command>timesync-status</command> is invoked and this option is passed, then
  74         <command>timedatectl</command> monitors the status of
  75         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  76         and updates the outputs. Use <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> to terminate the
  77         monitoring.</para></listitem>
  78       </varlistentry>
  79
  80       <varlistentry>
  81         <term><option>-a</option></term>
  82         <term><option>--all</option></term>
  83
  84         <listitem><para>When showing properties of
  85         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  86         show all properties regardless of whether they are set or not.</para></listitem>
  87       </varlistentry>
  88
  89       <varlistentry>
  90         <term><option>-p</option></term>
  91         <term><option>--property=</option></term>
  92
  93         <listitem><para>When showing properties of
  94         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  95         limit display to certain properties as specified as argument. If not specified, all set properties are shown.
  96         The argument should be a property name, such as <literal>ServerName</literal>. If specified more than once,
  97         all properties with the specified names are shown.</para></listitem>
  98       </varlistentry>
  99
 100       <varlistentry>
 101         <term><option>--value</option></term>
 102
 103         <listitem>
 104           <para>When printing properties with <command>show-timesync</command>, only print the value, and skip the
 105           property name and <literal>=</literal>.</para></listitem>
 106       </varlistentry>
 107
 108       <xi:include href="user-system-options.xml" xpointer="host" />
 109       <xi:include href="user-system-options.xml" xpointer="machine" />
 110
 111       <xi:include href="standard-options.xml" xpointer="help" />
 112       <xi:include href="standard-options.xml" xpointer="version" />
 113       <xi:include href="standard-options.xml" xpointer="no-pager" />
 114     </variablelist>
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>Commands</title>
 119
 120     <para>The following commands are understood:</para>
 121
 122     <variablelist>
 123       <varlistentry>
 124         <term><command>status</command></term>
 125
 126         <listitem><para>Show current settings of the system clock and RTC,
 127         including whether network time synchronization through
 128         <filename>systemd-timesyncd.service</filename> is active. Even if it is
 129         inactive, a different service might still synchronize the clock.
 130         If no command is specified, this is the implied default.
 131         </para></listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135         <term><command>show</command></term>
 136
 137         <listitem><para>Show the same information as <option>status</option>, but in machine readable form.
 138         This command is intended to be used whenever computer-parsable output is required.
 139         Use <option>status</option> if you are looking for formatted human-readable output.</para>
 140         <para>By default, empty properties are suppressed. Use <option>--all</option> to show those too.
 141         To select specific properties to show, use <option>--property=</option>.</para></listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term><command>set-time [TIME]</command></term>
 146
 147         <listitem><para>Set the system clock to the specified time.
 148         This will also update the RTC time accordingly. The time may
 149         be specified in the format "2012-10-30
 150         18:17:16".</para></listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term><command>set-timezone [TIMEZONE]</command></term>
 155
 156         <listitem><para>Set the system time zone to the specified
 157         value. Available timezones can be listed with
 158         <command>list-timezones</command>. If the RTC is configured to
 159         be in the local time, this will also update the RTC time. This
 160         call will alter the <filename>/etc/localtime</filename>
 161         symlink. See
 162         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 163         for more information.</para></listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><command>list-timezones</command></term>
 168
 169         <listitem><para>List available time zones, one per line.
 170         Entries from the list can be set as the system timezone with
 171         <command>set-timezone</command>.</para></listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175         <term><command>set-local-rtc [BOOL]</command></term>
 176
 177         <listitem><para>Takes a boolean argument. If
 178         <literal>0</literal>, the system is configured to maintain the
 179         RTC in universal time. If <literal>1</literal>, it will
 180         maintain the RTC in local time instead. Note that maintaining
 181         the RTC in the local timezone is not fully supported and will
 182         create various problems with time zone changes and daylight
 183         saving adjustments. If at all possible, keep the RTC in UTC
 184         mode. Note that invoking this will also synchronize the RTC
 185         from the system clock, unless
 186         <option>--adjust-system-clock</option> is passed (see above).
 187         This command will change the 3rd line of
 188         <filename>/etc/adjtime</filename>, as documented in
 189         <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 190         </para></listitem>
 191       </varlistentry>
 192
 193       <varlistentry>
 194         <term><command>set-ntp [BOOL]</command></term>
 195
 196         <listitem><para>Takes a boolean argument. Controls whether network time synchronization is active
 197         and enabled (if available). If the argument is true, this enables and starts the first existed
 198         service listed in the environment variable <varname>$SYSTEMD_TIMEDATED_NTP_SERVICES</varname>
 199         of <filename>systemd-timedated.service</filename>. If the argument is false, then this disables and
 200         stops the all services listed in <varname>$SYSTEMD_TIMEDATED_NTP_SERVICES</varname>.</para></listitem>
 201       </varlistentry>
 202
 203     </variablelist>
 204
 205     <refsect2>
 206       <title>systemd-timesyncd Commands</title>
 207
 208       <para>The following commands are specific to
 209       <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 210       </para>
 211
 212       <variablelist>
 213         <varlistentry>
 214           <term><command>timesync-status</command></term>
 215
 216           <listitem><para>Show current status of
 217           <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 218           If <option>--monitor</option> is specified, then this will monitor the status updates.</para></listitem>
 219         </varlistentry>
 220
 221         <varlistentry>
 222           <term><command>show-timesync</command></term>
 223
 224           <listitem><para>Show the same information as <option>timesync-status</option>, but in machine readable form.
 225           This command is intended to be used whenever computer-parsable output is required.
 226           Use <option>timesync-status</option> if you are looking for formatted human-readable output.</para>
 227           <para>By default, empty properties are suppressed. Use <option>--all</option> to show those too.
 228           To select specific properties to show, use <option>--property=</option>.</para></listitem>
 229         </varlistentry>
 230       </variablelist>
 231
 232     </refsect2>
 233
 234   </refsect1>
 235
 236   <refsect1>
 237     <title>Exit status</title>
 238
 239     <para>On success, 0 is returned, a non-zero failure
 240     code otherwise.</para>
 241   </refsect1>
 242
 243   <xi:include href="less-variables.xml" />
 244
 245   <refsect1>
 246     <title>Examples</title>
 247     <para>Show current settings:
 248     <programlisting>$ timedatectl
 249                Local time: Thu 2017-09-21 16:08:56 CEST
 250            Universal time: Thu 2017-09-21 14:08:56 UTC
 251                  RTC time: Thu 2017-09-21 14:08:56
 252                 Time zone: Europe/Warsaw (CEST, +0200)
 253 System clock synchronized: yes
 254               NTP service: active
 255           RTC in local TZ: no</programlisting>
 256     </para>
 257
 258     <para>Enable network time synchronization:
 259     <programlisting>$ timedatectl set-ntp true
 260 ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp ===
 261 Authentication is required to control whether network time synchronization shall be enabled.
 262 Authenticating as: user
 263 Password: ********
 264 ==== AUTHENTICATION COMPLETE ===</programlisting>
 265
 266     <programlisting>$ systemctl status systemd-timesyncd.service
 267 ● systemd-timesyncd.service - Network Time Synchronization
 268    Loaded: loaded (/usr/lib/systemd/system/systemd-timesyncd.service; enabled)
 269    Active: active (running) since Mo 2015-03-30 14:20:38 CEST; 5s ago
 270      Docs: man:systemd-timesyncd.service(8)
 271  Main PID: 595 (systemd-timesyn)
 272    Status: "Using Time Server 216.239.38.15:123 (time4.google.com)."
 273    CGroup: /system.slice/systemd-timesyncd.service
 274            └─595 /usr/lib/systemd/systemd-timesyncd
 275 …</programlisting>
 276     </para>
 277
 278     <para>Show current status of
 279     <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>:
 280     <programlisting>$ timedatectl timesync-status
 281        Server: 216.239.38.15 (time4.google.com)
 282 Poll interval: 1min 4s (min: 32s; max 34min 8s)
 283          Leap: normal
 284       Version: 4
 285       Stratum: 1
 286     Reference: GPS
 287     Precision: 1us (-20)
 288 Root distance: 335us (max: 5s)
 289        Offset: +316us
 290         Delay: 349us
 291        Jitter: 0
 292  Packet count: 1
 293     Frequency: -8.802ppm</programlisting>
 294     </para>
 295
 296   </refsect1>
 297
 298   <refsect1>
 299     <title>See Also</title>
 300     <para>
 301       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 302       <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 303       <citerefentry project='man-pages'><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 304       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 305       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 306       <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 307       <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 308       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 309     </para>
 310   </refsect1>
 311
 312 </refentry>