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 [Unit] and
  39     [Install] sections. The timer specific configuration options are
  40     configured in the [Timer] 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 generally pauses, too. Note that if
 167         <varname>WakeSystem=</varname> is used, a different monotonic clock is selected that continues to
 168         advance while the system is suspended and thus can be used as the trigger to resume the
 169         system.</para>
 170
 171         <para>If the empty string is assigned to any of these options, the list of timers is reset (both
 172         monotonic timers and <varname>OnCalendar=</varname> timers, see below), and all prior assignments
 173         will have no effect.</para>
 174
 175         <para>Note that timers do not necessarily expire at the
 176         precise time configured with these settings, as they are
 177         subject to the <varname>AccuracySec=</varname> setting
 178         below.</para></listitem>
 179
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><varname>OnCalendar=</varname></term>
 184
 185         <listitem><para>Defines realtime (i.e. wallclock) timers with
 186         calendar event expressions. See
 187         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 188         for more information on the syntax of calendar event
 189         expressions. Otherwise, the semantics are similar to
 190         <varname>OnActiveSec=</varname> and related settings.</para>
 191
 192         <para>Note that timers do not necessarily expire at the
 193         precise time configured with this setting, as it is subject to
 194         the <varname>AccuracySec=</varname> setting
 195         below.</para>
 196
 197         <para>May be specified more than once, in which case the timer unit will trigger whenever any of the
 198         specified expressions elapse. Moreover calendar timers and monotonic timers (see above) may be
 199         combined within the same timer unit.</para>
 200
 201         <para>If the empty string is assigned to any of these options, the list of timers is reset (both
 202         <varname>OnCalendar=</varname> timers and monotonic timers, see above), and all prior assignments
 203         will have no effect.</para></listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term><varname>AccuracySec=</varname></term>
 208
 209         <listitem><para>Specify the accuracy the timer shall elapse
 210         with. Defaults to 1min. The timer is scheduled to elapse
 211         within a time window starting with the time specified in
 212         <varname>OnCalendar=</varname>,
 213         <varname>OnActiveSec=</varname>,
 214         <varname>OnBootSec=</varname>,
 215         <varname>OnStartupSec=</varname>,
 216         <varname>OnUnitActiveSec=</varname> or
 217         <varname>OnUnitInactiveSec=</varname> and ending the time
 218         configured with <varname>AccuracySec=</varname> later. Within
 219         this time window, the expiry time will be placed at a
 220         host-specific, randomized, but stable position that is
 221         synchronized between all local timer units. This is done in
 222         order to optimize power consumption to suppress unnecessary
 223         CPU wake-ups. To get best accuracy, set this option to
 224         1us. Note that the timer is still subject to the timer slack
 225         configured via
 226         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s
 227         <varname>TimerSlackNSec=</varname> setting. See
 228         <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 229         for details. To optimize power consumption, make sure to set
 230         this value as high as possible and as low as
 231         necessary.</para>
 232
 233         <para>Note that this setting is primarily a power saving option that allows coalescing CPU
 234         wake-ups. It should not be confused with <varname>RandomizedDelaySec=</varname> (see below) which
 235         adds a random value to the time the timer shall elapse next and whose purpose is the opposite: to
 236         stretch elapsing of timer events over a longer period to reduce workload spikes. For further details
 237         and explanations and how both settings play together, see below.</para></listitem>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term><varname>RandomizedDelaySec=</varname></term>
 242
 243         <listitem><para>Delay the timer by a randomly selected, evenly
 244         distributed amount of time between 0 and the specified time
 245         value. Defaults to 0, indicating that no randomized delay
 246         shall be applied. Each timer unit will determine this delay
 247         randomly before each iteration, and the delay will simply be
 248         added on top of the next determined elapsing time. This is
 249         useful to stretch dispatching of similarly configured timer
 250         events over a certain amount time, to avoid that they all fire
 251         at the same time, possibly resulting in resource
 252         congestion. Note the relation to
 253         <varname>AccuracySec=</varname> above: the latter allows the
 254         service manager to coalesce timer events within a specified
 255         time range in order to minimize wakeups, the former does the
 256         opposite: it stretches timer events over a time range, to make
 257         it unlikely that they fire simultaneously. If
 258         <varname>RandomizedDelaySec=</varname> and
 259         <varname>AccuracySec=</varname> are used in conjunction, first
 260         the randomized delay is added, and then the result is
 261         possibly further shifted to coalesce it with other timer
 262         events happening on the system. As mentioned above
 263         <varname>AccuracySec=</varname> defaults to 1min and
 264         <varname>RandomizedDelaySec=</varname> to 0, thus encouraging
 265         coalescing of timer events. In order to optimally stretch
 266         timer events over a certain range of time, make sure to set
 267         <varname>RandomizedDelaySec=</varname> to a higher value, and
 268         <varname>AccuracySec=1us</varname>.</para></listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><varname>OnClockChange=</varname></term>
 273         <term><varname>OnTimezoneChange=</varname></term>
 274
 275         <listitem><para>These options take boolean arguments. When true, the service unit will be triggered
 276         when the system clock (<constant>CLOCK_REALTIME</constant>) jumps relative to the monotonic clock
 277         (<constant>CLOCK_MONOTONIC</constant>), or when the local system timezone is modified. These options
 278         can be used alone or in combination with other timer expressions (see above) within the same timer
 279         unit. These options default to false.</para></listitem>
 280       </varlistentry>
 281
 282       <varlistentry>
 283         <term><varname>Unit=</varname></term>
 284
 285         <listitem><para>The unit to activate when this timer elapses.
 286         The argument is a unit name, whose suffix is not
 287         <literal>.timer</literal>. If not specified, this value
 288         defaults to a service that has the same name as the timer
 289         unit, except for the suffix. (See above.) It is recommended
 290         that the unit name that is activated and the unit name of the
 291         timer unit are named identically, except for the
 292         suffix.</para></listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term><varname>Persistent=</varname></term>
 297
 298         <listitem><para>Takes a boolean argument. If true, the time when the service unit was last triggered
 299         is stored on disk.  When the timer is activated, the service unit is triggered immediately if it
 300         would have been triggered at least once during the time when the timer was inactive. Such triggering
 301         is nonetheless subject to the delay imposed by <varname>RandomizedDelaySec=</varname>.
 302         This is useful to catch up on missed runs of the service when the system was powered down. Note that
 303         this setting only has an effect on timers configured with <varname>OnCalendar=</varname>. Defaults to
 304         <varname>false</varname>.</para>
 305
 306         <para>Use <command>systemctl clean --what=state …</command> on the timer unit to remove the timestamp
 307         file maintained by this option from disk. In particular, use this command before uninstalling a timer
 308         unit. See
 309         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 310         details.</para></listitem>
 311       </varlistentry>
 312
 313       <varlistentry>
 314         <term><varname>WakeSystem=</varname></term>
 315
 316         <listitem><para>Takes a boolean argument. If true, an elapsing timer will cause the system to resume
 317         from suspend, should it be suspended and if the system supports this. Note that this option will only
 318         make sure the system resumes on the appropriate times, it will not take care of suspending it again
 319         after any work that is to be done is finished. Defaults to
 320         <varname>false</varname>.</para>
 321
 322         <para>Note that this functionality requires privileges and is thus generally only available in the
 323         system service manager.</para>
 324
 325         <para>Note that behaviour of monotonic clock timers (as configured with
 326         <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>,
 327         <varname>OnUnitActiveSec=</varname>, <varname>OnUnitInactiveSec=</varname>, see above) is altered
 328         depending on this option. If false, a monotonic clock is used that is paused during system suspend
 329         (<constant>CLOCK_MONOTONIC</constant>), if true a different monotonic clock is used that continues
 330         advancing during system suspend (<constant>CLOCK_BOOTTIME</constant>), see
 331         <citerefentry><refentrytitle>clock_getres</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
 332         details.</para></listitem>
 333       </varlistentry>
 334
 335       <varlistentry>
 336         <term><varname>RemainAfterElapse=</varname></term>
 337
 338         <listitem><para>Takes a boolean argument. If true, a timer will stay loaded, and its state remains
 339         queryable even after it elapsed and the associated unit (as configured with <varname>Unit=</varname>,
 340         see above) deactivated again. If false, an elapsed timer unit that cannot elapse anymore is unloaded
 341         once its associated unit deactivated again. Turning this off is particularly useful for transient
 342         timer units. Note that this setting has an effect when repeatedly starting a timer unit: if
 343         <varname>RemainAfterElapse=</varname> is on, starting the timer a second time has no effect. However,
 344         if <varname>RemainAfterElapse=</varname> is off and the timer unit was already unloaded, it can be
 345         started again, and thus the service can be triggered multiple times. Defaults to
 346         <varname>yes</varname>.</para></listitem>
 347       </varlistentry>
 348     </variablelist>
 349   </refsect1>
 350
 351   <refsect1>
 352       <title>See Also</title>
 353       <para>
 354         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 355         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 356         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 357         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 358         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 359         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 360         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 361         <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 362       </para>
 363   </refsect1>
 364
 365 </refentry>