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