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