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: <varname>OnActiveSec=</varname> defines a
 109         timer relative to the moment the timer itself is activated.
 110         <varname>OnBootSec=</varname> defines a timer relative to when
 111         the machine was booted up. <varname>OnStartupSec=</varname>
 112         defines a timer relative to when systemd was first started.
 113         <varname>OnUnitActiveSec=</varname> defines a timer relative
 114         to when the unit the timer is activating was last activated.
 115         <varname>OnUnitInactiveSec=</varname> defines a timer relative
 116         to when the unit the timer is activating was last
 117         deactivated.</para>
 118
 119         <para>Multiple directives may be combined of the same and of
 120         different types. For example, by combining
 121         <varname>OnBootSec=</varname> and
 122         <varname>OnUnitActiveSec=</varname>, it is possible to define
 123         a timer that elapses in regular intervals and activates a
 124         specific service each time.</para>
 125
 126         <para>The arguments to the directives are time spans
 127         configured in seconds. Example: "OnBootSec=50" means 50s after
 128         boot-up. The argument may also include time units. Example:
 129         "OnBootSec=5h 30min" means 5 hours and 30 minutes after
 130         boot-up. For details about the syntax of time spans, see
 131         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 132
 133         <para>If a timer configured with <varname>OnBootSec=</varname>
 134         or <varname>OnStartupSec=</varname> is already in the past
 135         when the timer unit is activated, it will immediately elapse
 136         and the configured unit is started. This is not the case for
 137         timers defined in the other directives.</para>
 138
 139         <para>These are monotonic timers, independent of wall-clock
 140         time and timezones. If the computer is temporarily suspended,
 141         the monotonic clock stops too.</para>
 142
 143         <para>If the empty string is assigned to any of these options,
 144         the list of timers is reset, and all prior assignments will
 145         have no effect.</para>
 146
 147         <para>Note that timers do not necessarily expire at the
 148         precise time configured with these settings, as they are
 149         subject to the <varname>AccuracySec=</varname> setting
 150         below.</para></listitem>
 151
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term><varname>OnCalendar=</varname></term>
 156
 157         <listitem><para>Defines realtime (i.e. wallclock) timers with
 158         calendar event expressions. See
 159         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 160         for more information on the syntax of calendar event
 161         expressions. Otherwise, the semantics are similar to
 162         <varname>OnActiveSec=</varname> and related settings.</para>
 163
 164         <para>Note that timers do not necessarily expire at the
 165         precise time configured with this setting, as it is subject to
 166         the <varname>AccuracySec=</varname> setting
 167         below.</para>
 168
 169        <para>May be specified more than once.</para></listitem>
 170       </varlistentry>
 171
 172       <varlistentry>
 173         <term><varname>AccuracySec=</varname></term>
 174
 175         <listitem><para>Specify the accuracy the timer shall elapse
 176         with. Defaults to 1min. The timer is scheduled to elapse
 177         within a time window starting with the time specified in
 178         <varname>OnCalendar=</varname>,
 179         <varname>OnActiveSec=</varname>,
 180         <varname>OnBootSec=</varname>,
 181         <varname>OnStartupSec=</varname>,
 182         <varname>OnUnitActiveSec=</varname> or
 183         <varname>OnUnitInactiveSec=</varname> and ending the time
 184         configured with <varname>AccuracySec=</varname> later. Within
 185         this time window, the expiry time will be placed at a
 186         host-specific, randomized, but stable position that is
 187         synchronized between all local timer units. This is done in
 188         order to optimize power consumption to suppress unnecessary
 189         CPU wake-ups. To get best accuracy, set this option to
 190         1us. Note that the timer is still subject to the timer slack
 191         configured via
 192         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s
 193         <varname>TimerSlackNSec=</varname> setting. See
 194         <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 195         for details. To optimize power consumption, make sure to set
 196         this value as high as possible and as low as
 197         necessary.</para></listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term><varname>RandomizedDelaySec=</varname></term>
 202
 203         <listitem><para>Delay the timer by a randomly selected, evenly
 204         distributed amount of time between 0 and the specified time
 205         value. Defaults to 0, indicating that no randomized delay
 206         shall be applied. Each timer unit will determine this delay
 207         randomly before each iteration, and the delay will simply be
 208         added on top of the next determined elapsing time. This is
 209         useful to stretch dispatching of similarly configured timer
 210         events over a certain amount time, to avoid that they all fire
 211         at the same time, possibly resulting in resource
 212         congestion. Note the relation to
 213         <varname>AccuracySec=</varname> above: the latter allows the
 214         service manager to coalesce timer events within a specified
 215         time range in order to minimize wakeups, the former does the
 216         opposite: it stretches timer events over a time range, to make
 217         it unlikely that they fire simultaneously. If
 218         <varname>RandomizedDelaySec=</varname> and
 219         <varname>AccuracySec=</varname> are used in conjunction, first
 220         the randomized delay is added, and then the result is
 221         possibly further shifted to coalesce it with other timer
 222         events happening on the system. As mentioned above
 223         <varname>AccuracySec=</varname> defaults to 1min and
 224         <varname>RandomizedDelaySec=</varname> to 0, thus encouraging
 225         coalescing of timer events. In order to optimally stretch
 226         timer events over a certain range of time, make sure to set
 227         <varname>RandomizedDelaySec=</varname> to a higher value, and
 228         <varname>AccuracySec=1us</varname>.</para></listitem>
 229       </varlistentry>
 230
 231       <varlistentry>
 232         <term><varname>Unit=</varname></term>
 233
 234         <listitem><para>The unit to activate when this timer elapses.
 235         The argument is a unit name, whose suffix is not
 236         <literal>.timer</literal>. If not specified, this value
 237         defaults to a service that has the same name as the timer
 238         unit, except for the suffix. (See above.) It is recommended
 239         that the unit name that is activated and the unit name of the
 240         timer unit are named identically, except for the
 241         suffix.</para></listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term><varname>Persistent=</varname></term>
 246
 247         <listitem><para>Takes a boolean argument. If true, the time
 248         when the service unit was last triggered is stored on disk.
 249         When the timer is activated, the service unit is triggered
 250         immediately if it would have been triggered at least once
 251         during the time when the timer was inactive. This is useful to
 252         catch up on missed runs of the service when the machine was
 253         off. Note that this setting only has an effect on timers
 254         configured with <varname>OnCalendar=</varname>. Defaults
 255         to <varname>false</varname>.
 256         </para></listitem>
 257       </varlistentry>
 258
 259       <varlistentry>
 260         <term><varname>WakeSystem=</varname></term>
 261
 262         <listitem><para>Takes a boolean argument. If true, an elapsing
 263         timer will cause the system to resume from suspend, should it
 264         be suspended and if the system supports this. Note that this
 265         option will only make sure the system resumes on the
 266         appropriate times, it will not take care of suspending it
 267         again after any work that is to be done is finished. Defaults
 268         to <varname>false</varname>.</para></listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><varname>RemainAfterElapse=</varname></term>
 273
 274         <listitem><para>Takes a boolean argument. If true, an elapsed
 275         timer will stay loaded, and its state remains queriable. If
 276         false, an elapsed timer unit that cannot elapse anymore is
 277         unloaded. Turning this off is particularly useful for
 278         transient timer units that shall disappear after they first
 279         elapse. Note that this setting has an effect on repeatedly
 280         starting a timer unit that only elapses once: if
 281         <varname>RemainAfterElapse=</varname> is on, it will not be
 282         started again, and is guaranteed to elapse only once. However,
 283         if <varname>RemainAfterElapse=</varname> is off, it might be
 284         started again if it is already elapsed, and thus be triggered
 285         multiple times. Defaults to
 286         <varname>yes</varname>.</para></listitem>
 287       </varlistentry>
 288     </variablelist>
 289   </refsect1>
 290
 291   <refsect1>
 292       <title>See Also</title>
 293       <para>
 294         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 295         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 296         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 297         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 298         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 299         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 300         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 301         <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 302       </para>
 303   </refsect1>
 304
 305 </refentry>