man/systemd.timer.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="systemd.timer">
   7   <refentryinfo>
   8     <title>systemd.timer</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>systemd.timer</refentrytitle>
  14     <manvolnum>5</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>systemd.timer</refname>
  19     <refpurpose>Timer unit configuration</refpurpose>
  20   </refnamediv>
  21
  22   <refsynopsisdiv>
  23     <para><filename><replaceable>timer</replaceable>.timer</filename></para>
  24   </refsynopsisdiv>
  25
  26   <refsect1>
  27     <title>Description</title>
  28
  29     <para>A unit configuration file whose name ends in
  30     <literal>.timer</literal> encodes information about a timer
  31     controlled and supervised by systemd, for timer-based
  32     activation.</para>
  33
  34     <para>This man page lists the configuration options specific to
  35     this unit type. See
  36     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  37     for the common options of all unit configuration files. The common
  38     configuration items are configured in the generic <literal>[Unit]</literal> and
  39     <literal>[Install]</literal> sections. The timer specific configuration options are
  40     configured in the <literal>[Timer]</literal> section.</para>
  41
  42     <para>For each timer file, a matching unit file must exist,
  43     describing the unit to activate when the timer elapses. By
  44     default, a service by the same name as the timer (except for the
  45     suffix) is activated. Example: a timer file
  46     <filename>foo.timer</filename> activates a matching service
  47     <filename>foo.service</filename>. The unit to activate may be
  48     controlled by <varname>Unit=</varname> (see below).</para>
  49
  50     <para>Note that in case the unit to activate is already active at the time the timer elapses it is not restarted,
  51     but simply left running. There is no concept of spawning new service instances in this case. Due to this, services
  52     with <varname>RemainAfterExit=</varname> set (which stay around continuously even after the service's main process
  53     exited) are usually not suitable for activation via repetitive timers, as they will only be activated once, and
  54     then stay around forever.</para>
  55   </refsect1>
  56
  57   <refsect1>
  58     <title>Automatic Dependencies</title>
  59
  60     <refsect2>
  61       <title>Implicit Dependencies</title>
  62
  63       <para>The following dependencies are implicitly added:</para>
  64
  65       <itemizedlist>
  66         <listitem><para>Timer units automatically gain a <varname>Before=</varname>
  67         dependency on the service they are supposed to activate.</para></listitem>
  68       </itemizedlist>
  69     </refsect2>
  70
  71     <refsect2>
  72       <title>Default Dependencies</title>
  73
  74       <para>The following dependencies are added unless <varname>DefaultDependencies=no</varname> is set:</para>
  75
  76       <itemizedlist>
  77         <listitem><para>Timer units will automatically have dependencies of type <varname>Requires=</varname> and
  78         <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>Before=</varname>
  79         on <filename>timers.target</filename>, as well as <varname>Conflicts=</varname> and <varname>Before=</varname> on
  80         <filename>shutdown.target</filename> to ensure that they are stopped cleanly prior to system shutdown. Only timer
  81         units involved with early boot or late system shutdown should disable the
  82         <varname>DefaultDependencies=</varname> option.</para></listitem>
  83
  84         <listitem><para>Timer units
  85         with at least one <varname>OnCalendar=</varname> directive will have an additional <varname>After=</varname>
  86         dependency on <filename>time-sync.target</filename> to avoid being started before the system clock has been
  87         correctly set.</para></listitem>
  88       </itemizedlist>
  89     </refsect2>
  90   </refsect1>
  91
  92   <refsect1>
  93     <title>Options</title>
  94
  95     <para>Timer files must include a [Timer] section, which carries
  96     information about the timer it defines. The options specific to
  97     the [Timer] section of timer units are the following:</para>
  98
  99     <variablelist class='unit-directives'>
 100       <varlistentry>
 101         <term><varname>OnActiveSec=</varname></term>
 102         <term><varname>OnBootSec=</varname></term>
 103         <term><varname>OnStartupSec=</varname></term>
 104         <term><varname>OnUnitActiveSec=</varname></term>
 105         <term><varname>OnUnitInactiveSec=</varname></term>
 106
 107         <listitem><para>Defines monotonic timers relative to different
 108         starting points:</para>
 109
 110         <table>
 111           <title>Settings and their starting points</title>
 112
 113           <tgroup cols='2'>
 114             <thead>
 115               <row>
 116                 <entry>Setting</entry>
 117                 <entry>Meaning</entry>
 118               </row>
 119             </thead>
 120             <tbody>
 121               <row>
 122                 <entry><varname>OnActiveSec=</varname></entry>
 123                 <entry>Defines a timer relative to the moment the timer unit itself is activated.</entry>
 124               </row>
 125               <row>
 126                 <entry><varname>OnBootSec=</varname></entry>
 127                 <entry>Defines a timer relative to when the machine was booted up. In containers, for the system manager instance, this is mapped to <varname>OnStartupSec=</varname>, making both equivalent.</entry>
 128               </row>
 129               <row>
 130                 <entry><varname>OnStartupSec=</varname></entry>
 131                 <entry>Defines a timer relative to when the service manager was first started. For system timer units this is very similar to <varname>OnBootSec=</varname> as the system service manager is generally started very early at boot. It's primarily useful when configured in units running in the per-user service manager, as the user service manager is generally started on first login only, not already during boot.</entry>
 132               </row>
 133               <row>
 134                 <entry><varname>OnUnitActiveSec=</varname></entry>
 135                 <entry>Defines a timer relative to when the unit the timer unit is activating was last activated.</entry>
 136               </row>
 137               <row>
 138                 <entry><varname>OnUnitInactiveSec=</varname></entry>
 139                 <entry>Defines a timer relative to when the unit the timer unit is activating was last deactivated.</entry>
 140               </row>
 141             </tbody>
 142           </tgroup>
 143         </table>
 144
 145         <para>Multiple directives may be combined of the same and of different types, in which case the timer
 146         unit will trigger whenever any of the specified timer expressions elapse. For example, by combining
 147         <varname>OnBootSec=</varname> and <varname>OnUnitActiveSec=</varname>, it is possible to define a
 148         timer that elapses in regular intervals and activates a specific service each time. Moreover, both
 149         monotonic time expressions and <varname>OnCalendar=</varname> calendar expressions may be combined in
 150         the same timer unit.</para>
 151
 152         <para>The arguments to the directives are time spans
 153         configured in seconds. Example: "OnBootSec=50" means 50s after
 154         boot-up. The argument may also include time units. Example:
 155         "OnBootSec=5h 30min" means 5 hours and 30 minutes after
 156         boot-up. For details about the syntax of time spans, see
 157         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 158
 159         <para>If a timer configured with <varname>OnBootSec=</varname>
 160         or <varname>OnStartupSec=</varname> is already in the past
 161         when the timer unit is activated, it will immediately elapse
 162         and the configured unit is started. This is not the case for
 163         timers defined in the other directives.</para>
 164
 165         <para>These are monotonic timers, independent of wall-clock time and timezones. If the computer is
 166         temporarily suspended, the monotonic clock pauses, too.</para>
 167
 168         <para>If the empty string is assigned to any of these options, the list of timers is reset (both
 169         monotonic timers and <varname>OnCalendar=</varname> timers, see below), and all prior assignments
 170         will have no effect.</para>
 171
 172         <para>Note that timers do not necessarily expire at the
 173         precise time configured with these settings, as they are
 174         subject to the <varname>AccuracySec=</varname> setting
 175         below.</para></listitem>
 176
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term><varname>OnCalendar=</varname></term>
 181
 182         <listitem><para>Defines realtime (i.e. wallclock) timers with
 183         calendar event expressions. See
 184         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 185         for more information on the syntax of calendar event
 186         expressions. Otherwise, the semantics are similar to
 187         <varname>OnActiveSec=</varname> and related settings.</para>
 188
 189         <para>Note that timers do not necessarily expire at the
 190         precise time configured with this setting, as it is subject to
 191         the <varname>AccuracySec=</varname> setting
 192         below.</para>
 193
 194         <para>May be specified more than once, in which case the timer unit will trigger whenever any of the
 195         specified expressions elapse. Moreover calendar timers and monotonic timers (see above) may be
 196         combined within the same timer unit.</para>
 197
 198         <para>If the empty string is assigned to any of these options, the list of timers is reset (both
 199         <varname>OnCalendar=</varname> timers and monotonic timers, see above), and all prior assignments
 200         will have no effect.</para></listitem>
 201       </varlistentry>
 202
 203       <varlistentry>
 204         <term><varname>AccuracySec=</varname></term>
 205
 206         <listitem><para>Specify the accuracy the timer shall elapse
 207         with. Defaults to 1min. The timer is scheduled to elapse
 208         within a time window starting with the time specified in
 209         <varname>OnCalendar=</varname>,
 210         <varname>OnActiveSec=</varname>,
 211         <varname>OnBootSec=</varname>,
 212         <varname>OnStartupSec=</varname>,
 213         <varname>OnUnitActiveSec=</varname> or
 214         <varname>OnUnitInactiveSec=</varname> and ending the time
 215         configured with <varname>AccuracySec=</varname> later. Within
 216         this time window, the expiry time will be placed at a
 217         host-specific, randomized, but stable position that is
 218         synchronized between all local timer units. This is done in
 219         order to optimize power consumption to suppress unnecessary
 220         CPU wake-ups. To get best accuracy, set this option to
 221         1us. Note that the timer is still subject to the timer slack
 222         configured via
 223         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s
 224         <varname>TimerSlackNSec=</varname> setting. See
 225         <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 226         for details. To optimize power consumption, make sure to set
 227         this value as high as possible and as low as
 228         necessary.</para></listitem>
 229       </varlistentry>
 230
 231       <varlistentry>
 232         <term><varname>RandomizedDelaySec=</varname></term>
 233
 234         <listitem><para>Delay the timer by a randomly selected, evenly
 235         distributed amount of time between 0 and the specified time
 236         value. Defaults to 0, indicating that no randomized delay
 237         shall be applied. Each timer unit will determine this delay
 238         randomly before each iteration, and the delay will simply be
 239         added on top of the next determined elapsing time. This is
 240         useful to stretch dispatching of similarly configured timer
 241         events over a certain amount time, to avoid that they all fire
 242         at the same time, possibly resulting in resource
 243         congestion. Note the relation to
 244         <varname>AccuracySec=</varname> above: the latter allows the
 245         service manager to coalesce timer events within a specified
 246         time range in order to minimize wakeups, the former does the
 247         opposite: it stretches timer events over a time range, to make
 248         it unlikely that they fire simultaneously. If
 249         <varname>RandomizedDelaySec=</varname> and
 250         <varname>AccuracySec=</varname> are used in conjunction, first
 251         the randomized delay is added, and then the result is
 252         possibly further shifted to coalesce it with other timer
 253         events happening on the system. As mentioned above
 254         <varname>AccuracySec=</varname> defaults to 1min and
 255         <varname>RandomizedDelaySec=</varname> to 0, thus encouraging
 256         coalescing of timer events. In order to optimally stretch
 257         timer events over a certain range of time, make sure to set
 258         <varname>RandomizedDelaySec=</varname> to a higher value, and
 259         <varname>AccuracySec=1us</varname>.</para></listitem>
 260       </varlistentry>
 261
 262       <varlistentry>
 263         <term><varname>OnClockChange=</varname></term>
 264         <term><varname>OnTimezoneChange=</varname></term>
 265
 266         <listitem><para>These options take boolean arguments. When true, the service unit will be triggered
 267         when the system clock (<constant>CLOCK_REALTIME</constant>) jumps relative to the monotonic clock
 268         (<constant>CLOCK_MONOTONIC</constant>), or when the local system timezone is modified. These options
 269         can be used alone or in combination with other timer expressions (see above) within the same timer
 270         unit. These options default to false.</para></listitem>
 271       </varlistentry>
 272
 273       <varlistentry>
 274         <term><varname>Unit=</varname></term>
 275
 276         <listitem><para>The unit to activate when this timer elapses.
 277         The argument is a unit name, whose suffix is not
 278         <literal>.timer</literal>. If not specified, this value
 279         defaults to a service that has the same name as the timer
 280         unit, except for the suffix. (See above.) It is recommended
 281         that the unit name that is activated and the unit name of the
 282         timer unit are named identically, except for the
 283         suffix.</para></listitem>
 284       </varlistentry>
 285
 286       <varlistentry>
 287         <term><varname>Persistent=</varname></term>
 288
 289         <listitem><para>Takes a boolean argument. If true, the time
 290         when the service unit was last triggered is stored on disk.
 291         When the timer is activated, the service unit is triggered
 292         immediately if it would have been triggered at least once
 293         during the time when the timer was inactive. This is useful to
 294         catch up on missed runs of the service when the machine was
 295         off. Note that this setting only has an effect on timers
 296         configured with <varname>OnCalendar=</varname>. Defaults
 297         to <varname>false</varname>.
 298         </para></listitem>
 299       </varlistentry>
 300
 301       <varlistentry>
 302         <term><varname>WakeSystem=</varname></term>
 303
 304         <listitem><para>Takes a boolean argument. If true, an elapsing
 305         timer will cause the system to resume from suspend, should it
 306         be suspended and if the system supports this. Note that this
 307         option will only make sure the system resumes on the
 308         appropriate times, it will not take care of suspending it
 309         again after any work that is to be done is finished. Defaults
 310         to <varname>false</varname>.</para></listitem>
 311       </varlistentry>
 312
 313       <varlistentry>
 314         <term><varname>RemainAfterElapse=</varname></term>
 315
 316         <listitem><para>Takes a boolean argument. If true, an elapsed
 317         timer will stay loaded, and its state remains queryable. If
 318         false, an elapsed timer unit that cannot elapse anymore is
 319         unloaded. Turning this off is particularly useful for
 320         transient timer units that shall disappear after they first
 321         elapse. Note that this setting has an effect on repeatedly
 322         starting a timer unit that only elapses once: if
 323         <varname>RemainAfterElapse=</varname> is on, it will not be
 324         started again, and is guaranteed to elapse only once. However,
 325         if <varname>RemainAfterElapse=</varname> is off, it might be
 326         started again if it is already elapsed, and thus be triggered
 327         multiple times. Defaults to
 328         <varname>yes</varname>.</para></listitem>
 329       </varlistentry>
 330     </variablelist>
 331   </refsect1>
 332
 333   <refsect1>
 334       <title>See Also</title>
 335       <para>
 336         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 337         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 338         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 339         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 340         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 341         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 342         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 343         <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 344       </para>
 345   </refsect1>
 346
 347 </refentry>