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