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