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