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</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="req">COMMAND</arg>
  29     </cmdsynopsis>
  30   </refsynopsisdiv>
  31
  32   <refsect1>
  33     <title>Description</title>
  34
  35     <para><command>timedatectl</command> may be used to query and change the system clock and its settings,
  36     and enable or disable time synchronization services.</para>
  37
  38     <para>Use
  39     <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  40     to initialize the system time zone for mounted (but not booted)
  41     system images.</para>
  42
  43     <para><command>timedatectl</command> may be used to show the current status of time synchronization
  44     services, for example
  45     <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  46     </para>
  47
  48   </refsect1>
  49
  50   <refsect1>
  51     <title>Commands</title>
  52
  53     <para>The following commands are understood:</para>
  54
  55     <variablelist>
  56       <varlistentry>
  57         <term><command>status</command></term>
  58
  59         <listitem><para>Show current settings of the system clock and RTC, including whether network time
  60         synchronization is active. If no command is specified, this is the implied default.
  61         </para></listitem>
  62       </varlistentry>
  63
  64       <varlistentry>
  65         <term><command>show</command></term>
  66
  67         <listitem><para>Show the same information as <option>status</option>, but in machine readable form.
  68         This command is intended to be used whenever computer-parsable output is required.
  69         Use <option>status</option> if you are looking for formatted human-readable output.</para>
  70         <para>By default, empty properties are suppressed. Use <option>--all</option> to show those too.
  71         To select specific properties to show, use <option>--property=</option>.</para></listitem>
  72       </varlistentry>
  73
  74       <varlistentry>
  75         <term><command>set-time [TIME]</command></term>
  76
  77         <listitem><para>Set the system clock to the specified time.
  78         This will also update the RTC time accordingly. The time may
  79         be specified in the format "2012-10-30
  80         18:17:16".</para></listitem>
  81       </varlistentry>
  82
  83       <varlistentry>
  84         <term><command>set-timezone [TIMEZONE]</command></term>
  85
  86         <listitem><para>Set the system time zone to the specified
  87         value. Available timezones can be listed with
  88         <command>list-timezones</command>. If the RTC is configured to
  89         be in the local time, this will also update the RTC time. This
  90         call will alter the <filename>/etc/localtime</filename>
  91         symlink. See
  92         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  93         for more information.</para></listitem>
  94       </varlistentry>
  95
  96       <varlistentry>
  97         <term><command>list-timezones</command></term>
  98
  99         <listitem><para>List available time zones, one per line.
 100         Entries from the list can be set as the system timezone with
 101         <command>set-timezone</command>.</para></listitem>
 102       </varlistentry>
 103
 104       <varlistentry>
 105         <term><command>set-local-rtc [BOOL]</command></term>
 106
 107         <listitem><para>Takes a boolean argument. If
 108         <literal>0</literal>, the system is configured to maintain the
 109         RTC in universal time. If <literal>1</literal>, it will
 110         maintain the RTC in local time instead. Note that maintaining
 111         the RTC in the local timezone is not fully supported and will
 112         create various problems with time zone changes and daylight
 113         saving adjustments. If at all possible, keep the RTC in UTC
 114         mode. Note that invoking this will also synchronize the RTC
 115         from the system clock, unless
 116         <option>--adjust-system-clock</option> is passed (see above).
 117         This command will change the 3rd line of
 118         <filename>/etc/adjtime</filename>, as documented in
 119         <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 120         </para></listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><command>set-ntp [BOOL]</command></term>
 125
 126         <listitem><para>Takes a boolean argument. Controls whether network time synchronization is active and
 127         enabled (if available). If the argument is true, this enables and starts the first existing network
 128         synchronization service. If the argument is false, then this disables and stops the known network
 129         synchronization services. The way that the list of services is built is described below.</para>
 130         </listitem>
 131       </varlistentry>
 132
 133     </variablelist>
 134
 135     <refsect2>
 136       <title>systemd-timesyncd Commands</title>
 137
 138       <para>The following commands are specific to
 139       <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 140       </para>
 141
 142       <variablelist>
 143         <varlistentry>
 144           <term><command>timesync-status</command></term>
 145
 146           <listitem><para>Show current status of
 147           <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 148           If <option>--monitor</option> is specified, then this will monitor the status updates.</para></listitem>
 149         </varlistentry>
 150
 151         <varlistentry>
 152           <term><command>show-timesync</command></term>
 153
 154           <listitem><para>Show the same information as <option>timesync-status</option>, but in machine readable form.
 155           This command is intended to be used whenever computer-parsable output is required.
 156           Use <option>timesync-status</option> if you are looking for formatted human-readable output.</para>
 157           <para>By default, empty properties are suppressed. Use <option>--all</option> to show those too.
 158           To select specific properties to show, use <option>--property=</option>.</para></listitem>
 159         </varlistentry>
 160
 161         <varlistentry>
 162           <term><command>ntp-servers <replaceable>INTERFACE</replaceable> <replaceable>SERVER</replaceable>…</command></term>
 163
 164           <listitem><para>Set the interface specific NTP servers. This command can be used only when the
 165           interface is managed by <command>systemd-networkd</command>.</para></listitem>
 166         </varlistentry>
 167
 168         <varlistentry>
 169           <term><command>revert <replaceable>INTERFACE</replaceable></command></term>
 170
 171           <listitem><para>Revert the interface specific NTP servers. This command can be used only when
 172           the interface is managed by <command>systemd-networkd</command>.</para></listitem>
 173         </varlistentry>
 174       </variablelist>
 175
 176     </refsect2>
 177
 178   </refsect1>
 179
 180   <refsect1>
 181     <title>Options</title>
 182
 183     <para>The following options are understood:</para>
 184
 185     <variablelist>
 186       <varlistentry>
 187         <term><option>--no-ask-password</option></term>
 188
 189         <listitem><para>Do not query the user for authentication for
 190         privileged operations.</para></listitem>
 191       </varlistentry>
 192
 193       <varlistentry>
 194         <term><option>--adjust-system-clock</option></term>
 195
 196         <listitem><para>If <command>set-local-rtc</command> is invoked
 197         and this option is passed, the system clock is synchronized
 198         from the RTC again, taking the new setting into account.
 199         Otherwise, the RTC is synchronized from the system
 200         clock.</para></listitem>
 201       </varlistentry>
 202
 203       <varlistentry>
 204         <term><option>--monitor</option></term>
 205
 206         <listitem><para>If <command>timesync-status</command> is invoked and this option is passed, then
 207         <command>timedatectl</command> monitors the status of
 208         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 209         and updates the outputs. Use <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> to terminate the
 210         monitoring.</para></listitem>
 211       </varlistentry>
 212
 213       <varlistentry>
 214         <term><option>-a</option></term>
 215         <term><option>--all</option></term>
 216
 217         <listitem><para>When showing properties of
 218         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 219         show all properties regardless of whether they are set or not.</para></listitem>
 220       </varlistentry>
 221
 222       <varlistentry>
 223         <term><option>-p</option></term>
 224         <term><option>--property=</option></term>
 225
 226         <listitem><para>When showing properties of
 227         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 228         limit display to certain properties as specified as argument. If not specified, all set properties are shown.
 229         The argument should be a property name, such as <literal>ServerName</literal>. If specified more than once,
 230         all properties with the specified names are shown.</para></listitem>
 231       </varlistentry>
 232
 233       <varlistentry>
 234         <term><option>--value</option></term>
 235
 236         <listitem>
 237           <para>When printing properties with <command>show-timesync</command>, only print the value, and skip the
 238           property name and <literal>=</literal>.</para></listitem>
 239       </varlistentry>
 240
 241       <xi:include href="user-system-options.xml" xpointer="host" />
 242       <xi:include href="user-system-options.xml" xpointer="machine" />
 243
 244       <xi:include href="standard-options.xml" xpointer="help" />
 245       <xi:include href="standard-options.xml" xpointer="version" />
 246       <xi:include href="standard-options.xml" xpointer="no-pager" />
 247     </variablelist>
 248   </refsect1>
 249
 250   <refsect1>
 251     <title>Exit status</title>
 252
 253     <para>On success, 0 is returned, a non-zero failure 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>