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.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   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>
  62
  63         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
  64       </varlistentry>
  65
  66       <varlistentry>
  67         <term><command>show</command></term>
  68
  69         <listitem><para>Show the same information as <option>status</option>, but in machine readable form.
  70         This command is intended to be used whenever computer-parsable output is required.
  71         Use <option>status</option> if you are looking for formatted human-readable output.</para>
  72         <para>By default, empty properties are suppressed. Use <option>--all</option> to show those too.
  73         To select specific properties to show, use <option>--property=</option>.</para>
  74
  75         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
  76       </varlistentry>
  77
  78       <varlistentry>
  79         <term><command>set-time [TIME]</command></term>
  80
  81         <listitem><para>Set the system clock to the specified time.
  82         This will also update the RTC time accordingly. The time may
  83         be specified in the format "2012-10-30
  84         18:17:16".</para>
  85
  86         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
  87       </varlistentry>
  88
  89       <varlistentry>
  90         <term><command>set-timezone [TIMEZONE]</command></term>
  91
  92         <listitem><para>Set the system time zone to the specified
  93         value. Available timezones can be listed with
  94         <command>list-timezones</command>. If the RTC is configured to
  95         be in the local time, this will also update the RTC time. This
  96         call will alter the <filename>/etc/localtime</filename>
  97         symlink. See
  98         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  99         for more information.</para>
 100
 101         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 102       </varlistentry>
 103
 104       <varlistentry>
 105         <term><command>list-timezones</command></term>
 106
 107         <listitem><para>List available time zones, one per line.
 108         Entries from the list can be set as the system timezone with
 109         <command>set-timezone</command>.</para>
 110
 111         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><command>set-local-rtc [BOOL]</command></term>
 116
 117         <listitem><para>Takes a boolean argument. If
 118         <literal>0</literal>, the system is configured to maintain the
 119         RTC in universal time. If <literal>1</literal>, it will
 120         maintain the RTC in local time instead. Note that maintaining
 121         the RTC in the local timezone is not fully supported and will
 122         create various problems with time zone changes and daylight
 123         saving adjustments. If at all possible, keep the RTC in UTC
 124         mode. Note that invoking this will also synchronize the RTC
 125         from the system clock, unless
 126         <option>--adjust-system-clock</option> is passed (see above).
 127         This command will change the 3rd line of
 128         <filename>/etc/adjtime</filename>, as documented in
 129         <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 130         </para>
 131
 132         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 133       </varlistentry>
 134
 135       <varlistentry>
 136         <term><command>set-ntp [BOOL]</command></term>
 137
 138         <listitem><para>Takes a boolean argument. Controls whether network time synchronization is active and
 139         enabled (if available). If the argument is true, this enables and starts the first existing network
 140         synchronization service. If the argument is false, then this disables and stops the known network
 141         synchronization services. The way that the list of services is built is described in
 142         <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 143         </para>
 144
 145         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 146       </varlistentry>
 147
 148     </variablelist>
 149
 150     <refsect2>
 151       <title>systemd-timesyncd Commands</title>
 152
 153       <para>The following commands are specific to
 154       <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 155       </para>
 156
 157       <variablelist>
 158         <varlistentry>
 159           <term><command>timesync-status</command></term>
 160
 161           <listitem><para>Show current status of
 162           <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 163           If <option>--monitor</option> is specified, then this will monitor the status updates.</para>
 164
 165           <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 166         </varlistentry>
 167
 168         <varlistentry>
 169           <term><command>show-timesync</command></term>
 170
 171           <listitem><para>Show the same information as <option>timesync-status</option>, but in machine readable form.
 172           This command is intended to be used whenever computer-parsable output is required.
 173           Use <option>timesync-status</option> if you are looking for formatted human-readable output.</para>
 174           <para>By default, empty properties are suppressed. Use <option>--all</option> to show those too.
 175           To select specific properties to show, use <option>--property=</option>.</para>
 176
 177           <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 178         </varlistentry>
 179
 180         <varlistentry>
 181           <term><command>ntp-servers <replaceable>INTERFACE</replaceable> <replaceable>SERVER</replaceable>…</command></term>
 182
 183           <listitem><para>Set the interface specific NTP servers. This command can be used only when the
 184           interface is managed by <command>systemd-networkd</command>.</para>
 185
 186           <xi:include href="version-info.xml" xpointer="v243"/></listitem>
 187         </varlistentry>
 188
 189         <varlistentry>
 190           <term><command>revert <replaceable>INTERFACE</replaceable></command></term>
 191
 192           <listitem><para>Revert the interface specific NTP servers. This command can be used only when
 193           the interface is managed by <command>systemd-networkd</command>.</para>
 194
 195           <xi:include href="version-info.xml" xpointer="v243"/></listitem>
 196         </varlistentry>
 197       </variablelist>
 198
 199     </refsect2>
 200
 201   </refsect1>
 202
 203   <refsect1>
 204     <title>Options</title>
 205
 206     <para>The following options are understood:</para>
 207
 208     <variablelist>
 209       <varlistentry>
 210         <term><option>--no-ask-password</option></term>
 211
 212         <listitem><para>Do not query the user for authentication for
 213         privileged operations.</para>
 214
 215         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 216       </varlistentry>
 217
 218       <varlistentry>
 219         <term><option>--adjust-system-clock</option></term>
 220
 221         <listitem><para>If <command>set-local-rtc</command> is invoked
 222         and this option is passed, the system clock is synchronized
 223         from the RTC again, taking the new setting into account.
 224         Otherwise, the RTC is synchronized from the system
 225         clock.</para>
 226
 227         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 228       </varlistentry>
 229
 230       <varlistentry>
 231         <term><option>--monitor</option></term>
 232
 233         <listitem><para>If <command>timesync-status</command> is invoked and this option is passed, then
 234         <command>timedatectl</command> monitors the status of
 235         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 236         and updates the outputs. Use <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> to terminate the
 237         monitoring.</para>
 238
 239         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 240       </varlistentry>
 241
 242       <varlistentry>
 243         <term><option>-a</option></term>
 244         <term><option>--all</option></term>
 245
 246         <listitem><para>When showing properties of
 247         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 248         show all properties regardless of whether they are set or not.</para>
 249
 250         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 251       </varlistentry>
 252
 253       <varlistentry>
 254         <term><option>-p</option></term>
 255         <term><option>--property=</option></term>
 256
 257         <listitem><para>When showing properties of
 258         <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 259         limit display to certain properties as specified as argument. If not specified, all set properties are shown.
 260         The argument should be a property name, such as <literal>ServerName</literal>. If specified more than once,
 261         all properties with the specified names are shown.</para>
 262
 263         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><option>--value</option></term>
 268
 269         <listitem>
 270           <para>When printing properties with <command>show-timesync</command>, only print the value, and skip the
 271           property name and <literal>=</literal>.</para>
 272
 273         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 274       </varlistentry>
 275
 276       <varlistentry id='option-P'>
 277         <term><option>-P</option></term>
 278
 279         <listitem>
 280           <xi:include href="standard-options.xml" xpointer="xpointer(//varlistentry[@id='option-P']/listitem/para)" />
 281           <xi:include href="version-info.xml" xpointer="v256"/>
 282         </listitem>
 283       </varlistentry>
 284
 285       <xi:include href="user-system-options.xml" xpointer="host" />
 286       <xi:include href="user-system-options.xml" xpointer="machine" />
 287
 288       <xi:include href="standard-options.xml" xpointer="help" />
 289       <xi:include href="standard-options.xml" xpointer="version" />
 290       <xi:include href="standard-options.xml" xpointer="no-pager" />
 291     </variablelist>
 292   </refsect1>
 293
 294   <refsect1>
 295     <title>Exit status</title>
 296
 297     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 298   </refsect1>
 299
 300   <xi:include href="common-variables.xml" />
 301
 302   <refsect1>
 303     <title>Examples</title>
 304     <para>Show current settings:
 305     <programlisting>$ timedatectl
 306                Local time: Thu 2017-09-21 16:08:56 CEST
 307            Universal time: Thu 2017-09-21 14:08:56 UTC
 308                  RTC time: Thu 2017-09-21 14:08:56
 309                 Time zone: Europe/Warsaw (CEST, +0200)
 310 System clock synchronized: yes
 311               NTP service: active
 312           RTC in local TZ: no</programlisting>
 313     </para>
 314
 315     <para>Enable network time synchronization:
 316     <programlisting>$ timedatectl set-ntp true
 317 ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp ===
 318 Authentication is required to control whether network time synchronization shall be enabled.
 319 Authenticating as: user
 320 Password: ********
 321 ==== AUTHENTICATION COMPLETE ===</programlisting>
 322
 323     <programlisting>$ systemctl status systemd-timesyncd.service
 324 ● systemd-timesyncd.service - Network Time Synchronization
 325    Loaded: loaded (/usr/lib/systemd/system/systemd-timesyncd.service; enabled)
 326    Active: active (running) since Mo 2015-03-30 14:20:38 CEST; 5s ago
 327      Docs: man:systemd-timesyncd.service(8)
 328  Main PID: 595 (systemd-timesyn)
 329    Status: "Using Time Server 216.239.38.15:123 (time4.google.com)."
 330    CGroup: /system.slice/systemd-timesyncd.service
 331            └─595 /usr/lib/systemd/systemd-timesyncd
 332 …</programlisting>
 333     </para>
 334
 335     <para>Show current status of
 336     <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>:
 337     <programlisting>$ timedatectl timesync-status
 338        Server: 216.239.38.15 (time4.google.com)
 339 Poll interval: 1min 4s (min: 32s; max 34min 8s)
 340          Leap: normal
 341       Version: 4
 342       Stratum: 1
 343     Reference: GPS
 344     Precision: 1us (-20)
 345 Root distance: 335us (max: 5s)
 346        Offset: +316us
 347         Delay: 349us
 348        Jitter: 0
 349  Packet count: 1
 350     Frequency: -8.802ppm</programlisting>
 351     </para>
 352
 353   </refsect1>
 354
 355   <refsect1>
 356     <title>See Also</title>
 357     <para><simplelist type="inline">
 358       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 359       <member><citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 360       <member><citerefentry project='man-pages'><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 361       <member><citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 362       <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 363       <member><citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 364       <member><citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 365       <member><citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 366     </simplelist></para>
 367   </refsect1>
 368
 369 </refentry>