]> git.proxmox.com Git - systemd.git/blame - man/systemd.timer.xml
Merge tag 'upstream/229'
[systemd.git] / man / systemd.timer.xml
CommitLineData
db2df898 1<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
663996b3 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
e735f4d4 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
663996b3
MS
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">
e735f4d4
MP
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>
db2df898
MP
76 </refsect1>
77
78 <refsect1>
79 <title>Automatic Dependencies</title>
80
81 <para>Timer units automatically gain a <varname>Before=</varname>
82 dependency on the service they are supposed to activate.</para>
e735f4d4
MP
83
84 <para>Unless <varname>DefaultDependencies=</varname> is set to
85 <option>false</option>, all timer units will implicitly have
db2df898
MP
86 dependencies of type <varname>Requires=</varname> and
87 <varname>After=</varname> on <filename>sysinit.target</filename>,
88 a dependency of type <varname>Before=</varname> on
89 <filename>timers.target</filename>, as well as
90 <varname>Conflicts=</varname> and <varname>Before=</varname> on
91 <filename>shutdown.target</filename> to ensure that they are
92 stopped cleanly prior to system shutdown. Timer units with at
93 least one <varname>OnCalendar=</varname> directive will have an
94 additional <varname>After=</varname> dependency on
95 <filename>timer-sync.target</filename> to avoid being started
96 before the system clock has been correctly set. Only timer units
97 involved with early boot or late system shutdown should disable
98 the <varname>DefaultDependencies=</varname> option.</para>
e735f4d4
MP
99 </refsect1>
100
101 <refsect1>
102 <title>Options</title>
103
104 <para>Timer files must include a [Timer] section, which carries
105 information about the timer it defines. The options specific to
106 the [Timer] section of timer units are the following:</para>
107
108 <variablelist class='unit-directives'>
109 <varlistentry>
110 <term><varname>OnActiveSec=</varname></term>
111 <term><varname>OnBootSec=</varname></term>
112 <term><varname>OnStartupSec=</varname></term>
113 <term><varname>OnUnitActiveSec=</varname></term>
114 <term><varname>OnUnitInactiveSec=</varname></term>
115
116 <listitem><para>Defines monotonic timers relative to different
117 starting points: <varname>OnActiveSec=</varname> defines a
118 timer relative to the moment the timer itself is activated.
119 <varname>OnBootSec=</varname> defines a timer relative to when
120 the machine was booted up. <varname>OnStartupSec=</varname>
121 defines a timer relative to when systemd was first started.
122 <varname>OnUnitActiveSec=</varname> defines a timer relative
123 to when the unit the timer is activating was last activated.
124 <varname>OnUnitInactiveSec=</varname> defines a timer relative
125 to when the unit the timer is activating was last
126 deactivated.</para>
127
128 <para>Multiple directives may be combined of the same and of
129 different types. For example, by combining
130 <varname>OnBootSec=</varname> and
131 <varname>OnUnitActiveSec=</varname>, it is possible to define
132 a timer that elapses in regular intervals and activates a
133 specific service each time.</para>
134
135 <para>The arguments to the directives are time spans
136 configured in seconds. Example: "OnBootSec=50" means 50s after
137 boot-up. The argument may also include time units. Example:
138 "OnBootSec=5h 30min" means 5 hours and 30 minutes after
139 boot-up. For details about the syntax of time spans, see
db2df898 140 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
e735f4d4
MP
141
142 <para>If a timer configured with <varname>OnBootSec=</varname>
143 or <varname>OnStartupSec=</varname> is already in the past
144 when the timer unit is activated, it will immediately elapse
145 and the configured unit is started. This is not the case for
146 timers defined in the other directives.</para>
147
148 <para>These are monotonic timers, independent of wall-clock
149 time and timezones. If the computer is temporarily suspended,
150 the monotonic clock stops too.</para>
151
152 <para>If the empty string is assigned to any of these options,
153 the list of timers is reset, and all prior assignments will
154 have no effect.</para>
155
156 <para>Note that timers do not necessarily expire at the
157 precise time configured with these settings, as they are
158 subject to the <varname>AccuracySec=</varname> setting
159 below.</para></listitem>
160
161 </varlistentry>
162
163 <varlistentry>
164 <term><varname>OnCalendar=</varname></term>
165
166 <listitem><para>Defines realtime (i.e. wallclock) timers with
167 calendar event expressions. See
168 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
169 for more information on the syntax of calendar event
170 expressions. Otherwise, the semantics are similar to
171 <varname>OnActiveSec=</varname> and related settings.</para>
172
173 <para>Note that timers do not necessarily expire at the
174 precise time configured with this setting, as it is subject to
175 the <varname>AccuracySec=</varname> setting
176 below.</para></listitem>
177 </varlistentry>
178
179 <varlistentry>
180 <term><varname>AccuracySec=</varname></term>
181
182 <listitem><para>Specify the accuracy the timer shall elapse
183 with. Defaults to 1min. The timer is scheduled to elapse
184 within a time window starting with the time specified in
185 <varname>OnCalendar=</varname>,
186 <varname>OnActiveSec=</varname>,
187 <varname>OnBootSec=</varname>,
188 <varname>OnStartupSec=</varname>,
189 <varname>OnUnitActiveSec=</varname> or
190 <varname>OnUnitInactiveSec=</varname> and ending the time
191 configured with <varname>AccuracySec=</varname> later. Within
192 this time window, the expiry time will be placed at a
4c89c718 193 host-specific, randomized, but stable position that is
e735f4d4 194 synchronized between all local timer units. This is done in
4c89c718
MP
195 order to optimize power consumption to suppress unnecessary
196 CPU wake-ups. To get best accuracy, set this option to
197 1us. Note that the timer is still subject to the timer slack
198 configured via
e735f4d4
MP
199 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s
200 <varname>TimerSlackNSec=</varname> setting. See
201 <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
202 for details. To optimize power consumption, make sure to set
203 this value as high as possible and as low as
204 necessary.</para></listitem>
205 </varlistentry>
4c89c718
MP
206
207 <varlistentry>
208 <term><varname>RandomizedDelaySec=</varname></term>
209
210 <listitem><para>Delay the timer by a randomly selected, evenly
211 distributed amount of time between 0 and the specified time
212 value. Defaults to 0, indicating that no randomized delay
213 shall be applied. Each timer unit will determine this delay
214 randomly each time it is started, and the delay will simply be
215 added on top of the next determined elapsing time. This is
216 useful to stretch dispatching of similarly configured timer
217 events over a certain amount time, to avoid that they all fire
218 at the same time, possibly resulting in resource
219 congestion. Note the relation to
220 <varname>AccuracySec=</varname> above: the latter allows the
221 service manager to coalesce timer events within a specified
222 time range in order to minimize wakeups, the former does the
223 opposite: it stretches timer events over a time range, to make
224 it unlikely that they fire simultaneously. If
225 <varname>RandomizedDelaySec=</varname> and
226 <varname>AccuracySec=</varname> are used in conjunction, first
227 the randomized delay is added, and then the result is
228 possibly further shifted to coalesce it with other timer
229 events happening on the system. As mentioned above
230 <varname>AccuracySec=</varname> defaults to 1min and
231 <varname>RandomizedDelaySec=</varname> to 0, thus encouraging
232 coalescing of timer events. In order to optimally stretch
233 timer events over a certain range of time, make sure to set
234 <varname>RandomizedDelaySec=</varname> to a higher value, and
235 <varname>AccuracySec=1us</varname>.</para></listitem>
236 </varlistentry>
237
e735f4d4
MP
238 <varlistentry>
239 <term><varname>Unit=</varname></term>
240
241 <listitem><para>The unit to activate when this timer elapses.
242 The argument is a unit name, whose suffix is not
243 <literal>.timer</literal>. If not specified, this value
244 defaults to a service that has the same name as the timer
245 unit, except for the suffix. (See above.) It is recommended
246 that the unit name that is activated and the unit name of the
247 timer unit are named identically, except for the
248 suffix.</para></listitem>
249 </varlistentry>
250
251
252 <varlistentry>
253 <term><varname>Persistent=</varname></term>
254
255 <listitem><para>Takes a boolean argument. If true, the time
256 when the service unit was last triggered is stored on disk.
257 When the timer is activated, the service unit is triggered
258 immediately if it would have been triggered at least once
259 during the time when the timer was inactive. This is useful to
260 catch up on missed runs of the service when the machine was
261 off. Note that this setting only has an effect on timers
262 configured with <varname>OnCalendar=</varname>.
263 </para></listitem>
264 </varlistentry>
265
266 <varlistentry>
267 <term><varname>WakeSystem=</varname></term>
268
269 <listitem><para>Takes a boolean argument. If true, an elapsing
270 timer will cause the system to resume from suspend, should it
271 be suspended and if the system supports this. Note that this
272 option will only make sure the system resumes on the
273 appropriate times, it will not take care of suspending it
274 again after any work that is to be done is finished. Defaults
275 to <varname>false</varname>.</para></listitem>
db2df898
MP
276 </varlistentry>
277
278 <varlistentry>
4c89c718 279 <term><varname>RemainAfterElapse=</varname></term>
db2df898
MP
280
281 <listitem><para>Takes a boolean argument. If true, an elapsed
4c89c718
MP
282 timer will stay loaded, and its state remains queriable. If
283 false, an elapsed timer unit that cannot elapse anymore is
284 unloaded. Turning this off is particularly useful for
285 transient timer units that shall disappear after they first
286 elapse. Note that this setting has an effect on repeatedly
287 starting a timer unit that only elapses once: if
288 <varname>RemainAfterElapse=</varname> is on, it will not be
289 started again, and is guaranteed to elapse only once. However,
290 if <varname>RemainAfterLeapse=</varname> is off, it might be
291 started again if it is already elapsed, and thus be triggered
292 multiple times. Defaults to
db2df898 293 <varname>yes</varname>.</para></listitem>
e735f4d4
MP
294 </varlistentry>
295 </variablelist>
296 </refsect1>
297
298 <refsect1>
299 <title>See Also</title>
300 <para>
301 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
302 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
303 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
304 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
305 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
306 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
307 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
308 <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
309 </para>
310 </refsect1>
663996b3
MS
311
312</refentry>