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, 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,
 130         including whether network time synchronization through
 131         <filename>systemd-timesyncd.service</filename> is active. Even if it is
 132         inactive, a different service might still synchronize the clock.
 133         If no command is specified, this is the implied default.
 134         </para></listitem>
 135       </varlistentry>
 136
 137       <varlistentry>
 138         <term><command>show</command></term>
 139
 140         <listitem><para>Show the same information as <option>status</option>, but in machine readable form.
 141         This command is intended to be used whenever computer-parsable output is required.
 142         Use <option>status</option> if you are looking for formatted human-readable output.</para>
 143         <para>By default, empty properties are suppressed. Use <option>--all</option> to show those too.
 144         To select specific properties to show, use <option>--property=</option>.</para></listitem>
 145       </varlistentry>
 146
 147       <varlistentry>
 148         <term><command>set-time [TIME]</command></term>
 149
 150         <listitem><para>Set the system clock to the specified time.
 151         This will also update the RTC time accordingly. The time may
 152         be specified in the format "2012-10-30
 153         18:17:16".</para></listitem>
 154       </varlistentry>
 155
 156       <varlistentry>
 157         <term><command>set-timezone [TIMEZONE]</command></term>
 158
 159         <listitem><para>Set the system time zone to the specified
 160         value. Available timezones can be listed with
 161         <command>list-timezones</command>. If the RTC is configured to
 162         be in the local time, this will also update the RTC time. This
 163         call will alter the <filename>/etc/localtime</filename>
 164         symlink. See
 165         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 166         for more information.</para></listitem>
 167       </varlistentry>
 168
 169       <varlistentry>
 170         <term><command>list-timezones</command></term>
 171
 172         <listitem><para>List available time zones, one per line.
 173         Entries from the list can be set as the system timezone with
 174         <command>set-timezone</command>.</para></listitem>
 175       </varlistentry>
 176
 177       <varlistentry>
 178         <term><command>set-local-rtc [BOOL]</command></term>
 179
 180         <listitem><para>Takes a boolean argument. If
 181         <literal>0</literal>, the system is configured to maintain the
 182         RTC in universal time. If <literal>1</literal>, it will
 183         maintain the RTC in local time instead. Note that maintaining
 184         the RTC in the local timezone is not fully supported and will
 185         create various problems with time zone changes and daylight
 186         saving adjustments. If at all possible, keep the RTC in UTC
 187         mode. Note that invoking this will also synchronize the RTC
 188         from the system clock, unless
 189         <option>--adjust-system-clock</option> is passed (see above).
 190         This command will change the 3rd line of
 191         <filename>/etc/adjtime</filename>, as documented in
 192         <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 193         </para></listitem>
 194       </varlistentry>
 195
 196       <varlistentry>
 197         <term><command>set-ntp [BOOL]</command></term>
 198
 199         <listitem><para>Takes a boolean argument. Controls whether network time synchronization is active
 200         and enabled (if available). If the argument is true, this enables and starts the first existed
 201         service listed in the environment variable <varname>$SYSTEMD_TIMEDATED_NTP_SERVICES</varname>
 202         of <filename>systemd-timedated.service</filename>. If the argument is false, then this disables and
 203         stops the all services listed in <varname>$SYSTEMD_TIMEDATED_NTP_SERVICES</varname>.</para></listitem>
 204       </varlistentry>
 205
 206     </variablelist>
 207
 208     <refsect2>
 209       <title>systemd-timesyncd Commands</title>
 210
 211       <para>The following commands are specific to
 212       <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 213       </para>
 214
 215       <variablelist>
 216         <varlistentry>
 217           <term><command>timesync-status</command></term>
 218
 219           <listitem><para>Show current status of
 220           <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 221           If <option>--monitor</option> is specified, then this will monitor the status updates.</para></listitem>
 222         </varlistentry>
 223
 224         <varlistentry>
 225           <term><command>show-timesync</command></term>
 226
 227           <listitem><para>Show the same information as <option>timesync-status</option>, but in machine readable form.
 228           This command is intended to be used whenever computer-parsable output is required.
 229           Use <option>timesync-status</option> if you are looking for formatted human-readable output.</para>
 230           <para>By default, empty properties are suppressed. Use <option>--all</option> to show those too.
 231           To select specific properties to show, use <option>--property=</option>.</para></listitem>
 232         </varlistentry>
 233       </variablelist>
 234
 235     </refsect2>
 236
 237   </refsect1>
 238
 239   <refsect1>
 240     <title>Exit status</title>
 241
 242     <para>On success, 0 is returned, a non-zero failure
 243     code otherwise.</para>
 244   </refsect1>
 245
 246   <xi:include href="less-variables.xml" />
 247
 248   <refsect1>
 249     <title>Examples</title>
 250     <para>Show current settings:
 251     <programlisting>$ timedatectl
 252                Local time: Thu 2017-09-21 16:08:56 CEST
 253            Universal time: Thu 2017-09-21 14:08:56 UTC
 254                  RTC time: Thu 2017-09-21 14:08:56
 255                 Time zone: Europe/Warsaw (CEST, +0200)
 256 System clock synchronized: yes
 257               NTP service: active
 258           RTC in local TZ: no</programlisting>
 259     </para>
 260
 261     <para>Enable network time synchronization:
 262     <programlisting>$ timedatectl set-ntp true
 263 ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp ===
 264 Authentication is required to control whether network time synchronization shall be enabled.
 265 Authenticating as: user
 266 Password: ********
 267 ==== AUTHENTICATION COMPLETE ===</programlisting>
 268
 269     <programlisting>$ systemctl status systemd-timesyncd.service
 270 ● systemd-timesyncd.service - Network Time Synchronization
 271    Loaded: loaded (/usr/lib/systemd/system/systemd-timesyncd.service; enabled)
 272    Active: active (running) since Mo 2015-03-30 14:20:38 CEST; 5s ago
 273      Docs: man:systemd-timesyncd.service(8)
 274  Main PID: 595 (systemd-timesyn)
 275    Status: "Using Time Server 216.239.38.15:123 (time4.google.com)."
 276    CGroup: /system.slice/systemd-timesyncd.service
 277            └─595 /usr/lib/systemd/systemd-timesyncd
 278 …</programlisting>
 279     </para>
 280
 281     <para>Show current status of
 282     <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>:
 283     <programlisting>$ timedatectl timesync-status
 284        Server: 216.239.38.15 (time4.google.com)
 285 Poll interval: 1min 4s (min: 32s; max 34min 8s)
 286          Leap: normal
 287       Version: 4
 288       Stratum: 1
 289     Reference: GPS
 290     Precision: 1us (-20)
 291 Root distance: 335us (max: 5s)
 292        Offset: +316us
 293         Delay: 349us
 294        Jitter: 0
 295  Packet count: 1
 296     Frequency: -8.802ppm</programlisting>
 297     </para>
 298
 299   </refsect1>
 300
 301   <refsect1>
 302     <title>See Also</title>
 303     <para>
 304       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 305       <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 306       <citerefentry project='man-pages'><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 307       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 308       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 309       <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 310       <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 311       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 312     </para>
 313   </refsect1>
 314
 315 </refentry>