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