man/systemd.timer.xml

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