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>Options</title>
  52
  53     <para>The following options are understood:</para>
  54
  55     <variablelist>
  56       <varlistentry>
  57         <term><option>--no-ask-password</option></term>
  58
  59         <listitem><para>Do not query the user for authentication for
  60         privileged operations.</para></listitem>
  61       </varlistentry>
  62
  63       <varlistentry>
  64         <term><option>--adjust-system-clock</option></term>
  65
  66         <listitem><para>If <command>set-local-rtc</command> is invoked
  67         and this option is passed, the system clock is synchronized
  68         from the RTC again, taking the new setting into account.
  69         Otherwise, the RTC is synchronized from the system
  70         clock.</para></listitem>
  71       </varlistentry>
  72
  73       <varlistentry>
  74         <term><option>--monitor</option></term>
  75
  76         <listitem><para>If <command>timesync-status</command> is invoked and this option is passed, then
  77         <command>timedatectl</command> monitors the status of
  78         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  79         and updates the outputs. Use <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> to terminate the
  80         monitoring.</para></listitem>
  81       </varlistentry>
  82
  83       <varlistentry>
  84         <term><option>-a</option></term>
  85         <term><option>--all</option></term>
  86
  87         <listitem><para>When showing properties of
  88         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  89         show all properties regardless of whether they are set or not.</para></listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term><option>-p</option></term>
  94         <term><option>--property=</option></term>
  95
  96         <listitem><para>When showing properties of
  97         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  98         limit display to certain properties as specified as argument. If not specified, all set properties are shown.
  99         The argument should be a property name, such as <literal>ServerName</literal>. If specified more than once,
 100         all properties with the specified names are shown.</para></listitem>
 101       </varlistentry>
 102
 103       <varlistentry>
 104         <term><option>--value</option></term>
 105
 106         <listitem>
 107           <para>When printing properties with <command>show-timesync</command>, only print the value, and skip the
 108           property name and <literal>=</literal>.</para></listitem>
 109       </varlistentry>
 110
 111       <xi:include href="user-system-options.xml" xpointer="host" />
 112       <xi:include href="user-system-options.xml" xpointer="machine" />
 113
 114       <xi:include href="standard-options.xml" xpointer="help" />
 115       <xi:include href="standard-options.xml" xpointer="version" />
 116       <xi:include href="standard-options.xml" xpointer="no-pager" />
 117     </variablelist>
 118   </refsect1>
 119
 120   <refsect1>
 121     <title>Commands</title>
 122
 123     <para>The following commands are understood:</para>
 124
 125     <variablelist>
 126       <varlistentry>
 127         <term><command>status</command></term>
 128
 129         <listitem><para>Show current settings of the system clock and RTC, including whether network time
 130         synchronization is active. 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 and
 197         enabled (if available). If the argument is true, this enables and starts the first existing network
 198         synchronization service. If the argument is false, then this disables and stops the known network
 199         synchronization services. The way that the list of services is built is described below.</para>
 200         </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
 231         <varlistentry>
 232           <term><command>ntp-servers <replaceable>INTERFACE</replaceable> <replaceable>SERVER</replaceable>…</command></term>
 233
 234           <listitem><para>Set the interface specific NTP servers. This command can be used only when the
 235           interface is managed by <command>systemd-networkd</command>.</para></listitem>
 236         </varlistentry>
 237
 238         <varlistentry>
 239           <term><command>revert <replaceable>INTERFACE</replaceable></command></term>
 240
 241           <listitem><para>Revert the interface specific NTP servers. This command can be used only when
 242           the interface is managed by <command>systemd-networkd</command>.</para></listitem>
 243         </varlistentry>
 244       </variablelist>
 245
 246     </refsect2>
 247
 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>