man/systemd.timer.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5
   6 <!--
   7   This file is part of systemd.
   8
   9   Copyright 2010 Lennart Poettering
  10
  11   systemd is free software; you can redistribute it and/or modify it
  12   under the terms of the GNU Lesser General Public License as published by
  13   the Free Software Foundation; either version 2.1 of the License, or
  14   (at your option) any later version.
  15
  16   systemd is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   Lesser General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 -->
  24
  25 <refentry id="systemd.timer">
  26   <refentryinfo>
  27     <title>systemd.timer</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>systemd.timer</refentrytitle>
  42     <manvolnum>5</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>systemd.timer</refname>
  47     <refpurpose>Timer unit configuration</refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <para><filename><replaceable>timer</replaceable>.timer</filename></para>
  52   </refsynopsisdiv>
  53
  54   <refsect1>
  55     <title>Description</title>
  56
  57     <para>A unit configuration file whose name ends in
  58     <literal>.timer</literal> encodes information about a timer
  59     controlled and supervised by systemd, for timer-based
  60     activation.</para>
  61
  62     <para>This man page lists the configuration options specific to
  63     this unit type. See
  64     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  65     for the common options of all unit configuration files. The common
  66     configuration items are configured in the generic [Unit] and
  67     [Install] sections. The timer specific configuration options are
  68     configured in the [Timer] section.</para>
  69
  70     <para>For each timer file, a matching unit file must exist,
  71     describing the unit to activate when the timer elapses. By
  72     default, a service by the same name as the timer (except for the
  73     suffix) is activated. Example: a timer file
  74     <filename>foo.timer</filename> activates a matching service
  75     <filename>foo.service</filename>. The unit to activate may be
  76     controlled by <varname>Unit=</varname> (see below).</para>
  77
  78     <para>Unless <varname>DefaultDependencies=</varname> is set to
  79     <option>false</option>, all timer units will implicitly have
  80     dependencies of type <varname>Conflicts=</varname> and
  81     <varname>Before=</varname> on <filename>shutdown.target</filename>
  82     to ensure that they are stopped cleanly prior to system shutdown.
  83     Timer units with at least one <varname>OnCalendar=</varname>
  84     directive will have an additional <varname>After=</varname>
  85     dependency on <filename>timer-sync.target</filename> to avoid
  86     being started before the system clock has been correctly set. Only
  87     timer units involved with early boot or late system shutdown
  88     should disable the <varname>DefaultDependencies=</varname>
  89     option.</para>
  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.unit</refentrytitle><manvolnum>5</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></listitem>
 168       </varlistentry>
 169
 170       <varlistentry>
 171         <term><varname>AccuracySec=</varname></term>
 172
 173         <listitem><para>Specify the accuracy the timer shall elapse
 174         with. Defaults to 1min. The timer is scheduled to elapse
 175         within a time window starting with the time specified in
 176         <varname>OnCalendar=</varname>,
 177         <varname>OnActiveSec=</varname>,
 178         <varname>OnBootSec=</varname>,
 179         <varname>OnStartupSec=</varname>,
 180         <varname>OnUnitActiveSec=</varname> or
 181         <varname>OnUnitInactiveSec=</varname> and ending the time
 182         configured with <varname>AccuracySec=</varname> later. Within
 183         this time window, the expiry time will be placed at a
 184         host-specific, randomized but stable position that is
 185         synchronized between all local timer units. This is done in
 186         order to distribute the wake-up time in networked
 187         installations, as well as optimizing power consumption to
 188         suppress unnecessary CPU wake-ups. To get best accuracy, set
 189         this option to 1us. Note that the timer is still subject to
 190         the timer slack configured via
 191         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s
 192         <varname>TimerSlackNSec=</varname> setting. See
 193         <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 194         for details. To optimize power consumption, make sure to set
 195         this value as high as possible and as low as
 196         necessary.</para></listitem>
 197       </varlistentry>
 198       <varlistentry>
 199         <term><varname>Unit=</varname></term>
 200
 201         <listitem><para>The unit to activate when this timer elapses.
 202         The argument is a unit name, whose suffix is not
 203         <literal>.timer</literal>. If not specified, this value
 204         defaults to a service that has the same name as the timer
 205         unit, except for the suffix. (See above.) It is recommended
 206         that the unit name that is activated and the unit name of the
 207         timer unit are named identically, except for the
 208         suffix.</para></listitem>
 209       </varlistentry>
 210
 211
 212       <varlistentry>
 213         <term><varname>Persistent=</varname></term>
 214
 215         <listitem><para>Takes a boolean argument. If true, the time
 216         when the service unit was last triggered is stored on disk.
 217         When the timer is activated, the service unit is triggered
 218         immediately if it would have been triggered at least once
 219         during the time when the timer was inactive. This is useful to
 220         catch up on missed runs of the service when the machine was
 221         off. Note that this setting only has an effect on timers
 222         configured with <varname>OnCalendar=</varname>.
 223         </para></listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term><varname>WakeSystem=</varname></term>
 228
 229         <listitem><para>Takes a boolean argument. If true, an elapsing
 230         timer will cause the system to resume from suspend, should it
 231         be suspended and if the system supports this. Note that this
 232         option will only make sure the system resumes on the
 233         appropriate times, it will not take care of suspending it
 234         again after any work that is to be done is finished. Defaults
 235         to <varname>false</varname>.</para></listitem>
 236       </varlistentry>
 237     </variablelist>
 238   </refsect1>
 239
 240   <refsect1>
 241       <title>See Also</title>
 242       <para>
 243         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 244         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 245         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 246         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 247         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 248         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 249         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 250         <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 251       </para>
 252   </refsect1>
 253
 254 </refentry>