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