1SYSTEMD.TIMER(5) systemd.timer SYSTEMD.TIMER(5)
2
6 systemd.timer - Timer unit configuration
7
9 timer.timer
10
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 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 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 Unless DefaultDependencies= is set to false, all timer units will
29 implicitly have dependencies of type Conflicts= and Before= on
30 shutdown.target to ensure that they are stopped cleanly prior to system
31 shutdown. Timer units with at least one OnCalendar= directive will have
32 an additional After= dependency on timer-sync.target to avoid being
33 started before the system clock has been correctly set. Only timer
34 units involved with early boot or late system shutdown should disable
35 the DefaultDependencies= option.
36
38 Timer files must include a [Timer] section, which carries information
39 about the timer it defines. The options specific to the [Timer] section
40 of timer units are the following:
41 OnActiveSec=, OnBootSec=, OnStartupSec=, OnUnitActiveSec=,
43 OnUnitInactiveSec=
44 Defines monotonic timers relative to different starting points:
45 OnActiveSec= defines a timer relative to the moment the timer
46 itself is activated. OnBootSec= defines a timer relative to when
47 the machine was booted up. OnStartupSec= defines a timer relative
48 to when systemd was first started. OnUnitActiveSec= defines a
49 timer relative to when the unit the timer is activating was last
50 activated. OnUnitInactiveSec= defines a timer relative to when the
51 unit the timer is activating was last deactivated.
52 Multiple directives may be combined of the same and of different
54 types. For example, by combining OnBootSec= and OnUnitActiveSec=,
55 it is possible to define a timer that elapses in regular intervals
56 and activates a specific service each time.
57 The arguments to the directives are time spans configured in
59 seconds. Example: "OnBootSec=50" means 50s after boot-up. The
60 argument may also include time units. Example: "OnBootSec=5h 30min"
61 means 5 hours and 30 minutes after boot-up. For details about the
62 syntax of time spans, see systemd.unit(5).
63 If a timer configured with OnBootSec= or OnStartupSec= is already
65 in the past when the timer unit is activated, it will immediately
66 elapse and the configured unit is started. This is not the case for
67 timers defined in the other directives.
68 These are monotonic timers, independent of wall-clock time and
70 timezones. If the computer is temporarily suspended, the monotonic
71 clock stops too.
72 If the empty string is assigned to any of these options, the list
74 of timers is reset, and all prior assignments will have no effect.
75 Note that timers do not necessarily expire at the precise time
77 configured with these settings, as they are subject to the
78 AccuracySec= setting below.
79 OnCalendar=
81 Defines realtime (i.e. wallclock) timers with calendar event
82 expressions. See systemd.time(7) for more information on the syntax
83 of calendar event expressions. Otherwise, the semantics are similar
84 to OnActiveSec= and related settings.
85 Note that timers do not necessarily expire at the precise time
87 configured with this setting, as it is subject to the AccuracySec=
88 setting below.
89 AccuracySec=
91 Specify the accuracy the timer shall elapse with. Defaults to 1min.
92 The timer is scheduled to elapse within a time window starting with
93 the time specified in OnCalendar=, OnActiveSec=, OnBootSec=,
94 OnStartupSec=, OnUnitActiveSec= or OnUnitInactiveSec= and ending
95 the time configured with AccuracySec= later. Within this time
96 window, the expiry time will be placed at a host-specific,
97 randomized, but stable position that is synchronized between all
98 local timer units. This is done in order to optimize power
99 consumption to suppress unnecessary CPU wake-ups. To get best
100 accuracy, set this option to 1us. Note that the timer is still
101 subject to the timer slack configured via systemd-system.conf(5)'s
102 TimerSlackNSec= setting. See prctl(2) for details. To optimize
103 power consumption, make sure to set this value as high as possible
104 and as low as necessary.
105 RandomizedDelaySec=
107 Delay the timer by a randomly selected, evenly distributed amount
108 of time between 0 and the specified time value. Defaults to 0,
109 indicating that no randomized delay shall be applied. Each timer
110 unit will determine this delay randomly each time it is started,
111 and the delay will simply be added on top of the next determined
112 elapsing time. This is useful to stretch dispatching of similarly
113 configured timer events over a certain amount time, to avoid that
114 they all fire at the same time, possibly resulting in resource
115 congestion. Note the relation to AccuracySec= above: the latter
116 allows the service manager to coalesce timer events within a
117 specified time range in order to minimize wakeups, the former does
118 the opposite: it stretches timer events over a time range, to make
119 it unlikely that they fire simultaneously. If RandomizedDelaySec=
120 and AccuracySec= are used in conjunction, first the a randomized
121 time is added, and the result is then possibly shifted further to
122 coalesce it with other timer events possibly happening on the
123 system. As mentioned above AccuracySec= defaults to 1min and
124 RandomizedDelaySec= to 0, thus encouraging coalescing of timer
125 events. In order to optimally stretch timer events over a certain
126 range of time, make sure to set RandomizedDelaySec= to a higher
127 value, and AccuracySec=1us.
128 Unit=
130 The unit to activate when this timer elapses. The argument is a
131 unit name, whose suffix is not ".timer". If not specified, this
132 value defaults to a service that has the same name as the timer
133 unit, except for the suffix. (See above.) It is recommended that
134 the unit name that is activated and the unit name of the timer unit
135 are named identically, except for the suffix.
136 Persistent=
138 Takes a boolean argument. If true, the time when the service unit
139 was last triggered is stored on disk. When the timer is activated,
140 the service unit is triggered immediately if it would have been
141 triggered at least once during the time when the timer was
142 inactive. This is useful to catch up on missed runs of the service
143 when the machine was off. Note that this setting only has an effect
144 on timers configured with OnCalendar=.
145 WakeSystem=
147 Takes a boolean argument. If true, an elapsing timer will cause the
148 system to resume from suspend, should it be suspended and if the
149 system supports this. Note that this option will only make sure the
150 system resumes on the appropriate times, it will not take care of
151 suspending it again after any work that is to be done is finished.
152 Defaults to false.
153
155 systemd(1), systemctl(1), systemd.unit(5), systemd.service(5),
156 systemd.time(7), systemd.directives(7), systemd-system.conf(5),
157 prctl(2)
158systemd 219 SYSTEMD.TIMER(5)