1SYSTEMD.TIMER(5)                 systemd.timer                SYSTEMD.TIMER(5)
2
3
4

NAME

6       systemd.timer - Timer unit configuration
7

SYNOPSIS

9       timer.timer
10

DESCRIPTION

12       A unit configuration file whose name ends in ".timer" encodes
13       information about a timer controlled and supervised by systemd, for
14       timer-based activation.
15
16       This man page lists the configuration options specific to this unit
17       type. See systemd.unit(5) for the common options of all unit
18       configuration files. The common configuration items are configured in
19       the generic [Unit] and [Install] sections. The timer specific
20       configuration options are configured in the [Timer] section.
21
22       For each timer file, a matching unit file must exist, describing the
23       unit to activate when the timer elapses. By default, a service by the
24       same name as the timer (except for the suffix) is activated. Example: a
25       timer file foo.timer activates a matching service foo.service. The unit
26       to activate may be controlled by Unit= (see below).
27
28       Note that in case the unit to activate is already active at the time
29       the timer elapses it is not restarted, but simply left running. There
30       is no concept of spawning new service instances in this case. Due to
31       this, services with RemainAfterExit= set (which stay around
32       continuously even after the service's main process exited) are usually
33       not suitable for activation via repetitive timers, as they will only be
34       activated once, and then stay around forever.
35

AUTOMATIC DEPENDENCIES

37   Implicit Dependencies
38       The following dependencies are implicitly added:
39
40       •   Timer units automatically gain a Before= dependency on the service
41           they are supposed to activate.
42
43   Default Dependencies
44       The following dependencies are added unless DefaultDependencies=no is
45       set:
46
47       •   Timer units will automatically have dependencies of type Requires=
48           and After= on sysinit.target, a dependency of type Before= on
49           timers.target, as well as Conflicts= and Before= on shutdown.target
50           to ensure that they are stopped cleanly prior to system shutdown.
51           Only timer units involved with early boot or late system shutdown
52           should disable the DefaultDependencies= option.
53
54       •   Timer units with at least one OnCalendar= directive acquire a pair
55           of additional After= dependencies on time-set.target and
56           time-sync.target, in order to avoid being started before the system
57           clock has been correctly set. See systemd.special(7) for details on
58           these two targets.
59

OPTIONS

61       Timer unit files may include [Unit] and [Install] sections, which are
62       described in systemd.unit(5).
63
64       Timer unit files must include a [Timer] section, which carries
65       information about the timer it defines. The options specific to the
66       [Timer] section of timer units are the following:
67
68       OnActiveSec=, OnBootSec=, OnStartupSec=, OnUnitActiveSec=,
69       OnUnitInactiveSec=
70           Defines monotonic timers relative to different starting points:
71
72           Table 1. Settings and their starting points
73           ┌───────────────────┬────────────────────────────┐
74Setting            Meaning                    
75           ├───────────────────┼────────────────────────────┤
76OnActiveSec=       │ Defines a timer relative   │
77           │                   │ to the moment the timer    │
78           │                   │ unit itself is activated.  │
79           ├───────────────────┼────────────────────────────┤
80OnBootSec=         │ Defines a timer relative   │
81           │                   │ to when the machine was    │
82           │                   │ booted up. In containers,  │
83           │                   │ for the system manager     │
84           │                   │ instance, this is mapped   │
85           │                   │ to OnStartupSec=, making   │
86           │                   │ both equivalent.           │
87           ├───────────────────┼────────────────────────────┤
88OnStartupSec=      │ Defines a timer relative   │
89           │                   │ to when the service        │
90           │                   │ manager was first started. │
91           │                   │ For system timer units     │
92           │                   │ this is very similar to    │
93           │                   │ OnBootSec= as the system   │
94           │                   │ service manager is         │
95           │                   │ generally started very     │
96           │                   │ early at boot. It's        │
97           │                   │ primarily useful when      │
98           │                   │ configured in units        │
99           │                   │ running in the per-user    │
100           │                   │ service manager, as the    │
101           │                   │ user service manager is    │
102           │                   │ generally started on first │
103           │                   │ login only, not already    │
104           │                   │ during boot.               │
105           ├───────────────────┼────────────────────────────┤
106OnUnitActiveSec=   │ Defines a timer relative   │
107           │                   │ to when the unit the timer │
108           │                   │ unit is activating was     │
109           │                   │ last activated.            │
110           ├───────────────────┼────────────────────────────┤
111OnUnitInactiveSec= │ Defines a timer relative   │
112           │                   │ to when the unit the timer │
113           │                   │ unit is activating was     │
114           │                   │ last deactivated.          │
115           └───────────────────┴────────────────────────────┘
116           Multiple directives may be combined of the same and of different
117           types, in which case the timer unit will trigger whenever any of
118           the specified timer expressions elapse. For example, by combining
119           OnBootSec= and OnUnitActiveSec=, it is possible to define a timer
120           that elapses in regular intervals and activates a specific service
121           each time. Moreover, both monotonic time expressions and
122           OnCalendar= calendar expressions may be combined in the same timer
123           unit.
124
125           The arguments to the directives are time spans configured in
126           seconds. Example: "OnBootSec=50" means 50s after boot-up. The
127           argument may also include time units. Example: "OnBootSec=5h 30min"
128           means 5 hours and 30 minutes after boot-up. For details about the
129           syntax of time spans, see systemd.time(7).
130
131           If a timer configured with OnBootSec= or OnStartupSec= is already
132           in the past when the timer unit is activated, it will immediately
133           elapse and the configured unit is started. This is not the case for
134           timers defined in the other directives.
135
136           These are monotonic timers, independent of wall-clock time and
137           timezones. If the computer is temporarily suspended, the monotonic
138           clock generally pauses, too. Note that if WakeSystem= is used, a
139           different monotonic clock is selected that continues to advance
140           while the system is suspended and thus can be used as the trigger
141           to resume the system.
142
143           If the empty string is assigned to any of these options, the list
144           of timers is reset (both monotonic timers and OnCalendar= timers,
145           see below), and all prior assignments will have no effect.
146
147           Note that timers do not necessarily expire at the precise time
148           configured with these settings, as they are subject to the
149           AccuracySec= setting below.
150
151       OnCalendar=
152           Defines realtime (i.e. wallclock) timers with calendar event
153           expressions. See systemd.time(7) for more information on the syntax
154           of calendar event expressions. Otherwise, the semantics are similar
155           to OnActiveSec= and related settings.
156
157           Note that timers do not necessarily expire at the precise time
158           configured with this setting, as it is subject to the AccuracySec=
159           setting below.
160
161           May be specified more than once, in which case the timer unit will
162           trigger whenever any of the specified expressions elapse. Moreover
163           calendar timers and monotonic timers (see above) may be combined
164           within the same timer unit.
165
166           If the empty string is assigned to any of these options, the list
167           of timers is reset (both OnCalendar= timers and monotonic timers,
168           see above), and all prior assignments will have no effect.
169
170       AccuracySec=
171           Specify the accuracy the timer shall elapse with. Defaults to 1min.
172           The timer is scheduled to elapse within a time window starting with
173           the time specified in OnCalendar=, OnActiveSec=, OnBootSec=,
174           OnStartupSec=, OnUnitActiveSec= or OnUnitInactiveSec= and ending
175           the time configured with AccuracySec= later. Within this time
176           window, the expiry time will be placed at a host-specific,
177           randomized, but stable position that is synchronized between all
178           local timer units. This is done in order to optimize power
179           consumption to suppress unnecessary CPU wake-ups. To get best
180           accuracy, set this option to 1us. Note that the timer is still
181           subject to the timer slack configured via systemd-system.conf(5)'s
182           TimerSlackNSec= setting. See prctl(2) for details. To optimize
183           power consumption, make sure to set this value as high as possible
184           and as low as necessary.
185
186           Note that this setting is primarily a power saving option that
187           allows coalescing CPU wake-ups. It should not be confused with
188           RandomizedDelaySec= (see below) which adds a random value to the
189           time the timer shall elapse next and whose purpose is the opposite:
190           to stretch elapsing of timer events over a longer period to reduce
191           workload spikes. For further details and explanations and how both
192           settings play together, see below.
193
194       RandomizedDelaySec=
195           Delay the timer by a randomly selected, evenly distributed amount
196           of time between 0 and the specified time value. Defaults to 0,
197           indicating that no randomized delay shall be applied. Each timer
198           unit will determine this delay randomly before each iteration, and
199           the delay will simply be added on top of the next determined
200           elapsing time, unless modified with FixedRandomDelay=, see below.
201
202           This setting is useful to stretch dispatching of similarly
203           configured timer events over a certain time interval, to prevent
204           them from firing all at the same time, possibly resulting in
205           resource congestion.
206
207           Note the relation to AccuracySec= above: the latter allows the
208           service manager to coalesce timer events within a specified time
209           range in order to minimize wakeups, while this setting does the
210           opposite: it stretches timer events over an interval, to make it
211           unlikely that they fire simultaneously. If RandomizedDelaySec= and
212           AccuracySec= are used in conjunction, first the randomized delay is
213           added, and then the result is possibly further shifted to coalesce
214           it with other timer events happening on the system. As mentioned
215           above AccuracySec= defaults to 1 minute and RandomizedDelaySec= to
216           0, thus encouraging coalescing of timer events. In order to
217           optimally stretch timer events over a certain range of time, set
218           AccuracySec=1us and RandomizedDelaySec= to some higher value.
219
220       FixedRandomDelay=
221           Takes a boolean argument. When enabled, the randomized offset
222           specified by RandomizedDelaySec= is reused for all firings of the
223           same timer. For a given timer unit, the offset depends on the
224           machine ID, user identifier and timer name, which means that it is
225           stable between restarts of the manager. This effectively creates a
226           fixed offset for an individual timer, reducing the jitter in
227           firings of this timer, while still avoiding firing at the same time
228           as other similarly configured timers.
229
230           This setting has no effect if RandomizedDelaySec= is set to 0.
231           Defaults to false.
232
233       OnClockChange=, OnTimezoneChange=
234           These options take boolean arguments. When true, the service unit
235           will be triggered when the system clock (CLOCK_REALTIME) jumps
236           relative to the monotonic clock (CLOCK_MONOTONIC), or when the
237           local system timezone is modified. These options can be used alone
238           or in combination with other timer expressions (see above) within
239           the same timer unit. These options default to false.
240
241       Unit=
242           The unit to activate when this timer elapses. The argument is a
243           unit name, whose suffix is not ".timer". If not specified, this
244           value defaults to a service that has the same name as the timer
245           unit, except for the suffix. (See above.) It is recommended that
246           the unit name that is activated and the unit name of the timer unit
247           are named identically, except for the suffix.
248
249       Persistent=
250           Takes a boolean argument. If true, the time when the service unit
251           was last triggered is stored on disk. When the timer is activated,
252           the service unit is triggered immediately if it would have been
253           triggered at least once during the time when the timer was
254           inactive. Such triggering is nonetheless subject to the delay
255           imposed by RandomizedDelaySec=. This is useful to catch up on
256           missed runs of the service when the system was powered down. Note
257           that this setting only has an effect on timers configured with
258           OnCalendar=. Defaults to false.
259
260           Use systemctl clean --what=state ...  on the timer unit to remove
261           the timestamp file maintained by this option from disk. In
262           particular, use this command before uninstalling a timer unit. See
263           systemctl(1) for details.
264
265       WakeSystem=
266           Takes a boolean argument. If true, an elapsing timer will cause the
267           system to resume from suspend, should it be suspended and if the
268           system supports this. Note that this option will only make sure the
269           system resumes on the appropriate times, it will not take care of
270           suspending it again after any work that is to be done is finished.
271           Defaults to false.
272
273           Note that this functionality requires privileges and is thus
274           generally only available in the system service manager.
275
276           Note that behaviour of monotonic clock timers (as configured with
277           OnActiveSec=, OnBootSec=, OnStartupSec=, OnUnitActiveSec=,
278           OnUnitInactiveSec=, see above) is altered depending on this option.
279           If false, a monotonic clock is used that is paused during system
280           suspend (CLOCK_MONOTONIC), if true a different monotonic clock is
281           used that continues advancing during system suspend
282           (CLOCK_BOOTTIME), see clock_getres(2) for details.
283
284       RemainAfterElapse=
285           Takes a boolean argument. If true, a timer will stay loaded, and
286           its state remains queryable even after it elapsed and the
287           associated unit (as configured with Unit=, see above) deactivated
288           again. If false, an elapsed timer unit that cannot elapse anymore
289           is unloaded once its associated unit deactivated again. Turning
290           this off is particularly useful for transient timer units. Note
291           that this setting has an effect when repeatedly starting a timer
292           unit: if RemainAfterElapse= is on, starting the timer a second time
293           has no effect. However, if RemainAfterElapse= is off and the timer
294           unit was already unloaded, it can be started again, and thus the
295           service can be triggered multiple times. Defaults to true.
296
297       Check systemd.unit(5), systemd.exec(5), and systemd.kill(5) for more
298       settings.
299

SEE ALSO

301       systemd(1), systemctl(1), systemd.unit(5), systemd.service(5),
302       systemd.time(7), systemd.directives(7), systemd-system.conf(5),
303       prctl(2)
304
305
306
307systemd 250                                                   SYSTEMD.TIMER(5)
Impressum