| 1 | # | ||
| 2 | # This file is part of Config-Model-Systemd | ||
| 3 | # | ||
| 4 | # This software is Copyright (c) 2008-2026 by Dominique Dumont. | ||
| 5 | # | ||
| 6 | # This is free software, licensed under: | ||
| 7 | # | ||
| 8 | # The GNU Lesser General Public License, Version 2.1, February 1999 | ||
| 9 | # | ||
| 10 | 1 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 11 | 1 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 12 | 1 | ▶ | use v5.20; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 13 | 1 | ▶ | use utf8; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 14 | |||
| 15 | return [ | ||
| 16 | { | ||
| 17 | 1 | 'accept' => [ | |
| 18 | '.*', | ||
| 19 | { | ||
| 20 | 'type' => 'leaf', | ||
| 21 | 'value_type' => 'uniline', | ||
| 22 | 'warn' => 'Unexpected systemd parameter. Please contact cme author to update systemd model.' | ||
| 23 | } | ||
| 24 | ], | ||
| 25 | 'class_description' => 'A unit configuration file whose name ends in | ||
| 26 | C<.timer> encodes information about a timer | ||
| 27 | controlled and supervised by systemd, for timer-based | ||
| 28 | activation. | ||
| 29 | |||
| 30 | This man page lists the configuration options specific to | ||
| 31 | this unit type. See | ||
| 32 | L<systemd.unit(5)> | ||
| 33 | for the common options of all unit configuration files. The common | ||
| 34 | configuration items are configured in the generic [Unit] and | ||
| 35 | [Install] sections. The timer specific configuration options are | ||
| 36 | configured in the [Timer] section. | ||
| 37 | |||
| 38 | For each timer file, a matching unit file must exist, | ||
| 39 | describing the unit to activate when the timer elapses. By | ||
| 40 | default, a service by the same name as the timer (except for the | ||
| 41 | suffix) is activated. Example: a timer file | ||
| 42 | C<foo.timer> activates a matching service | ||
| 43 | C<foo.service>. The unit to activate may be | ||
| 44 | controlled by C<Unit> (see below). | ||
| 45 | |||
| 46 | Note that in case the unit to activate is already active at the time the timer elapses it is not restarted, | ||
| 47 | but simply left running. There is no concept of spawning new service instances in this case. Due to this, services | ||
| 48 | with C<RemainAfterExit=yes> set (which stay around continuously even after the service\'s main | ||
| 49 | process exited) are usually not suitable for activation via repetitive timers, as they will only be activated | ||
| 50 | once, and then stay around forever. Target units, which by default do not deactivate on their own, can be | ||
| 51 | activated repeatedly by timers by setting C<StopWhenUnneeded=yes> on them. This will cause a | ||
| 52 | target unit to be stopped immediately after its activation, if it is not a dependency of another running unit. | ||
| 53 | This configuration class was generated from systemd documentation. | ||
| 54 | by L<parse-man.pl|https://github.com/dod38fr/config-model-systemd/contrib/parse-man.pl> | ||
| 55 | ', | ||
| 56 | 'copyright' => [ | ||
| 57 | '2010-2016 Lennart Poettering and others', | ||
| 58 | '2016 Dominique Dumont' | ||
| 59 | ], | ||
| 60 | 'description' => { | ||
| 61 | 'AccuracySec' => 'Specify the accuracy the timer shall elapse | ||
| 62 | with. Defaults to 1min. The timer is scheduled to elapse | ||
| 63 | within a time window starting with the time specified in | ||
| 64 | C<OnCalendar>, | ||
| 65 | C<OnActiveSec>, | ||
| 66 | C<OnBootSec>, | ||
| 67 | C<OnStartupSec>, | ||
| 68 | C<OnUnitActiveSec> or | ||
| 69 | C<OnUnitInactiveSec> and ending the time | ||
| 70 | configured with C<AccuracySec> later. Within | ||
| 71 | this time window, the expiry time will be placed at a | ||
| 72 | host-specific, randomized, but stable position that is | ||
| 73 | synchronized between all local timer units. This is done in | ||
| 74 | order to optimize power consumption to suppress unnecessary | ||
| 75 | CPU wake-ups. To get best accuracy, set this option to | ||
| 76 | 1us. Note that the timer is still subject to the timer slack | ||
| 77 | configured via | ||
| 78 | L<systemd-system.conf(5)>\'s | ||
| 79 | C<TimerSlackNSec> setting. See | ||
| 80 | L<prctl(2)> | ||
| 81 | for details. To optimize power consumption, make sure to set | ||
| 82 | this value as high as possible and as low as | ||
| 83 | necessary. | ||
| 84 | |||
| 85 | Note that this setting is primarily a power saving option that allows coalescing CPU | ||
| 86 | wake-ups. It should not be confused with C<RandomizedDelaySec> (see below) which | ||
| 87 | adds a random value to the time the timer shall elapse next and whose purpose is the opposite: to | ||
| 88 | stretch elapsing of timer events over a longer period to reduce workload spikes. For further details | ||
| 89 | and explanations and how both settings play together, see below.', | ||
| 90 | 'DeferReactivation' => 'Takes a boolean argument. When enabled, the timer schedules the next elapse based on | ||
| 91 | the trigger unit entering inactivity, instead of the last trigger time. | ||
| 92 | This is most apparent in the case where the service unit takes longer to run than the timer interval. | ||
| 93 | With this setting enabled, the timer will schedule the next elapse based on when the service finishes | ||
| 94 | running, and so it will have to wait until the next realtime elapse time to trigger. | ||
| 95 | Otherwise, the default behavior is for the timer unit to immediately trigger again once the service | ||
| 96 | finishes running. This happens because the timer schedules the next elapse based on the previous trigger | ||
| 97 | time, and since the interval is shorter than the service runtime, that elapse will be in the past, | ||
| 98 | causing it to immediately trigger once done. | ||
| 99 | |||
| 100 | This setting has an effect only if a realtime timer has been specified with | ||
| 101 | C<OnCalendar>. Defaults to C<false>.', | ||
| 102 | 'FixedRandomDelay' => 'Takes a boolean argument. When enabled, the randomized delay specified by | ||
| 103 | C<RandomizedDelaySec> is chosen deterministically, and remains stable between all | ||
| 104 | firings of the same timer, even if the manager is restarted. The delay is derived from the machine | ||
| 105 | ID, the manager\'s user identifier, and the timer unit\'s name. This effectively creates a unique fixed | ||
| 106 | offset for each timer, reducing the jitter in firings of an individual timer while still avoiding | ||
| 107 | firing at the same time as other similarly configured timers. | ||
| 108 | |||
| 109 | This setting has an effect only if C<RandomizedDelaySec> is not 0. Defaults to | ||
| 110 | C<false>.', | ||
| 111 | 'OnActiveSec' => 'Defines monotonic timers relative to different | ||
| 112 | starting points: | ||
| 113 | |||
| 114 | Multiple directives may be combined of the same and of different types, in which case the timer | ||
| 115 | unit will trigger whenever any of the specified timer expressions elapse. For example, by combining | ||
| 116 | C<OnBootSec> and C<OnUnitActiveSec>, it is possible to define a | ||
| 117 | timer that elapses in regular intervals and activates a specific service each time. Moreover, both | ||
| 118 | monotonic time expressions and C<OnCalendar> calendar expressions may be combined in | ||
| 119 | the same timer unit. | ||
| 120 | |||
| 121 | The arguments to the directives are time spans | ||
| 122 | configured in seconds. Example: "OnBootSec=50" means 50s after | ||
| 123 | boot-up. The argument may also include time units. Example: | ||
| 124 | "OnBootSec=5h 30min" means 5 hours and 30 minutes after | ||
| 125 | boot-up. For details about the syntax of time spans, see | ||
| 126 | L<systemd.time(7)>. | ||
| 127 | |||
| 128 | If a timer configured with C<OnBootSec> | ||
| 129 | or C<OnStartupSec> is already in the past | ||
| 130 | when the timer unit is activated, it will immediately elapse | ||
| 131 | and the configured unit is started. This is not the case for | ||
| 132 | timers defined in the other directives. | ||
| 133 | |||
| 134 | These are monotonic timers, independent of wall-clock time and timezones. If the computer is | ||
| 135 | temporarily suspended, the monotonic clock generally pauses, too. Note that if | ||
| 136 | C<WakeSystem> is used, a different monotonic clock is selected that continues to | ||
| 137 | advance while the system is suspended and thus can be used as the trigger to resume the | ||
| 138 | system. | ||
| 139 | |||
| 140 | If the empty string is assigned to any of these options, the list of timers is reset (both | ||
| 141 | monotonic timers and C<OnCalendar> timers, see below), and all prior assignments | ||
| 142 | will have no effect. | ||
| 143 | |||
| 144 | Note that timers do not necessarily expire at the | ||
| 145 | precise time configured with these settings, as they are | ||
| 146 | subject to the C<AccuracySec> setting | ||
| 147 | below.', | ||
| 148 | 'OnBootSec' => '*OnActiveSec', | ||
| 149 | 'OnCalendar' => 'Defines realtime (i.e. wallclock) timers with calendar event expressions. See | ||
| 150 | L<systemd.time(7)> for | ||
| 151 | more information on the syntax of calendar event expressions. Otherwise, the semantics are similar to | ||
| 152 | C<OnActiveSec> and related settings. | ||
| 153 | |||
| 154 | Note that timers do not necessarily expire at the precise time configured with this setting, as | ||
| 155 | it is subject to the C<AccuracySec> setting below. | ||
| 156 | |||
| 157 | May be specified more than once, in which case the timer unit will trigger whenever any of the | ||
| 158 | specified expressions elapse. Moreover, calendar timers and monotonic timers (see above) may be | ||
| 159 | combined within the same timer unit. | ||
| 160 | |||
| 161 | If the empty string is assigned to any of these options, the list of timers is reset (both | ||
| 162 | C<OnCalendar> timers and monotonic timers, see above), and all prior assignments | ||
| 163 | will have no effect. | ||
| 164 | |||
| 165 | Note that calendar timers might be triggered at unexpected times if the system\'s realtime clock | ||
| 166 | is not set correctly. Specifically, on systems that lack a battery-buffered Realtime Clock (RTC) it | ||
| 167 | might be wise to enable C<systemd-time-wait-sync.service> to ensure the clock is | ||
| 168 | adjusted to a network time source before the timer event is set up. Timer units | ||
| 169 | with at least one C<OnCalendar> expression are automatically ordered after | ||
| 170 | C<time-sync.target>, which C<systemd-time-wait-sync.service> is | ||
| 171 | ordered before. | ||
| 172 | |||
| 173 | When a system is temporarily put to sleep (i.e. system suspend or hibernation) the realtime | ||
| 174 | clock does not pause. When a calendar timer elapses while the system is sleeping it will not be acted | ||
| 175 | on immediately, but once the system is later resumed it will catch up and process all timers that | ||
| 176 | triggered while the system was sleeping. Note that if a calendar timer elapsed more than once while | ||
| 177 | the system was continuously sleeping the timer will only result in a single service activation. If | ||
| 178 | C<WakeSystem> (see below) is enabled a calendar time event elapsing while the system | ||
| 179 | is suspended will cause the system to wake up (under the condition the system\'s hardware supports | ||
| 180 | time-triggered wake-up functionality).', | ||
| 181 | 'OnClockChange' => 'These options take boolean arguments. When true, the service unit will be triggered | ||
| 182 | when the system clock (C<CLOCK_REALTIME>) jumps relative to the monotonic clock | ||
| 183 | (C<CLOCK_MONOTONIC>), or when the local system timezone is modified. These options | ||
| 184 | can be used alone or in combination with other timer expressions (see above) within the same timer | ||
| 185 | unit. These options default to C<false>.', | ||
| 186 | 'OnStartupSec' => '*OnActiveSec', | ||
| 187 | 'OnTimezoneChange' => '*OnClockChange', | ||
| 188 | 'OnUnitActiveSec' => '*OnActiveSec', | ||
| 189 | 'OnUnitInactiveSec' => '*OnActiveSec', | ||
| 190 | 'Persistent' => "Takes a boolean argument. If true, the time when the service unit was last triggered | ||
| 191 | is stored on disk. When the timer is activated, the service unit is triggered immediately if it | ||
| 192 | would have been triggered at least once during the time when the timer was inactive. Such triggering | ||
| 193 | is nonetheless subject to the delay imposed by C<RandomizedDelaySec>. | ||
| 194 | This is useful to catch up on missed runs of the service when the system was powered down. Note that | ||
| 195 | this setting only has an effect on timers configured with C<OnCalendar>. Defaults to | ||
| 196 | C<false>. | ||
| 197 | |||
| 198 | Use systemctl clean --what=state \x{2026} on the timer unit to remove the timestamp | ||
| 199 | file maintained by this option from disk. In particular, use this command before uninstalling a timer | ||
| 200 | unit. See | ||
| 201 | L<systemctl(1)> for | ||
| 202 | details.", | ||
| 203 | 'RandomizedDelaySec' => 'Delay the timer by a randomly selected, evenly distributed amount of time between 0 | ||
| 204 | and the specified time value. Defaults to 0, indicating that no randomized delay shall be applied. | ||
| 205 | Each timer unit will determine this delay randomly before each iteration, unless modified with | ||
| 206 | C<FixedRandomDelay>, see below. The delay is added on top of the next determined | ||
| 207 | elapsing time or the service manager\'s startup time, whichever is later. | ||
| 208 | |||
| 209 | This setting is useful to stretch dispatching of similarly configured timer events over a | ||
| 210 | certain time interval, to prevent them from firing all at the same time, possibly resulting in | ||
| 211 | resource congestion on the local system. | ||
| 212 | |||
| 213 | Note the relation to C<AccuracySec> above: the latter allows the service | ||
| 214 | manager to coalesce timer events within a specified time range in order to minimize wakeups, while | ||
| 215 | this setting does the opposite: it stretches timer events over an interval, to make it unlikely that | ||
| 216 | they fire simultaneously. If C<RandomizedDelaySec> and | ||
| 217 | C<AccuracySec> are used in conjunction, first the randomized delay is added, and | ||
| 218 | then the result is possibly further shifted to coalesce it with other timer events happening on the | ||
| 219 | system. As mentioned above C<AccuracySec> defaults to 1 minute and | ||
| 220 | C<RandomizedDelaySec> to 0, thus encouraging coalescing of timer events. In order to | ||
| 221 | optimally stretch timer events over a certain range of time, set | ||
| 222 | C<AccuracySec=1us> and C<RandomizedDelaySec> to some higher value. | ||
| 223 | ', | ||
| 224 | 'RandomizedOffsetSec' => 'Offsets the timer by a stable, randomly-selected, and evenly distributed amount of | ||
| 225 | time between 0 and the specified time value. Defaults to 0, indicating that no such offset shall be | ||
| 226 | applied. The offset is chosen deterministically, and is derived the same way as | ||
| 227 | C<FixedRandomDelay>, see above. The offset is added on top of the next determined | ||
| 228 | elapsing time. This setting only has an effect on timers configured with C<OnCalendar>, | ||
| 229 | and it can be combined with C<RandomizedDelaySec>. | ||
| 230 | |||
| 231 | Much like C<RandomizedDelaySec>, this setting is for distributing timer events | ||
| 232 | to prevent them from firing all at once. However, this setting is most useful to prevent resource | ||
| 233 | congestion on a remote service, from a fleet of similarly-configured clients. Unlike | ||
| 234 | C<RandomizedDelaySec>, this setting applies its offset with no regard to manager | ||
| 235 | startup time. This maintains the periodicity of configured C<OnCalendar> events | ||
| 236 | across manager restarts. | ||
| 237 | |||
| 238 | For example, let\'s say you\'re running a backup service and have a fleet of laptops that wish | ||
| 239 | to make backups weekly. To distribute load on the backup service, each laptop should randomly pick | ||
| 240 | a weekday to upload its backups. This could be achieved by setting C<OnCalendar> to | ||
| 241 | C<weekly>, and then configuring a C<RandomizedDelaySec> of | ||
| 242 | C<5 days> with C<FixedRandomDelay> enabled. Let\'s say that some | ||
| 243 | laptop randomly chooses a delay of 4 days. If this laptop is restarted more often than that, then the | ||
| 244 | timer will never fire: on each fresh boot, the 4 day delay is restarted and will not be finished by | ||
| 245 | the time of the next shutdown. Instead, you should use C<RandomizedOffsetSec>, which | ||
| 246 | will maintain the configured weekly cadence of timer events, even across reboots.', | ||
| 247 | 'RemainAfterElapse' => 'Takes a boolean argument. If true, a timer will stay loaded, and its state remains | ||
| 248 | queryable even after it elapsed and the associated unit (as configured with C<Unit>, | ||
| 249 | see above) deactivated again. If false, an elapsed timer unit that cannot elapse anymore is unloaded | ||
| 250 | once its associated unit deactivated again. Turning this off is particularly useful for transient | ||
| 251 | timer units. Note that this setting has an effect when repeatedly starting a timer unit: if | ||
| 252 | C<RemainAfterElapse> is on, starting the timer a second time has no effect. However, | ||
| 253 | if C<RemainAfterElapse> is off and the timer unit was already unloaded, it can be | ||
| 254 | started again, and thus the service can be triggered multiple times. Defaults to | ||
| 255 | C<true>.', | ||
| 256 | 'Unit' => 'The unit to activate when this timer elapses. | ||
| 257 | The argument is a unit name, whose suffix is not | ||
| 258 | C<.timer>. If not specified, this value | ||
| 259 | defaults to a service that has the same name as the timer | ||
| 260 | unit, except for the suffix. (See above.) It is recommended | ||
| 261 | that the unit name that is activated and the unit name of the | ||
| 262 | timer unit are named identically, except for the | ||
| 263 | suffix.', | ||
| 264 | 'WakeSystem' => 'Takes a boolean argument. If true, an elapsing timer will cause the system to resume | ||
| 265 | from suspend, should it be suspended and if the system supports this. Note that this option will only | ||
| 266 | make sure the system resumes on the appropriate times, it will not take care of suspending it again | ||
| 267 | after any work that is to be done is finished. Defaults to | ||
| 268 | C<false>. | ||
| 269 | |||
| 270 | Note that this functionality requires privileges and is thus generally only available in the | ||
| 271 | system service manager. | ||
| 272 | |||
| 273 | Note that behaviour of monotonic clock timers (as configured with | ||
| 274 | C<OnActiveSec>, C<OnBootSec>, C<OnStartupSec>, | ||
| 275 | C<OnUnitActiveSec>, C<OnUnitInactiveSec>, see above) is altered | ||
| 276 | depending on this option. If false, a monotonic clock is used that is paused during system suspend | ||
| 277 | (C<CLOCK_MONOTONIC>), if true a different monotonic clock is used that continues | ||
| 278 | advancing during system suspend (C<CLOCK_BOOTTIME>), see | ||
| 279 | L<clock_getres(2)> for | ||
| 280 | details.' | ||
| 281 | }, | ||
| 282 | 'element' => [ | ||
| 283 | 'OnActiveSec', | ||
| 284 | { | ||
| 285 | 'type' => 'leaf', | ||
| 286 | 'value_type' => 'uniline' | ||
| 287 | }, | ||
| 288 | 'OnBootSec', | ||
| 289 | '*OnActiveSec', | ||
| 290 | 'OnStartupSec', | ||
| 291 | '*OnActiveSec', | ||
| 292 | 'OnUnitActiveSec', | ||
| 293 | '*OnActiveSec', | ||
| 294 | 'OnUnitInactiveSec', | ||
| 295 | '*OnActiveSec', | ||
| 296 | 'OnCalendar', | ||
| 297 | { | ||
| 298 | 'cargo' => { | ||
| 299 | 'type' => 'leaf', | ||
| 300 | 'value_type' => 'uniline' | ||
| 301 | }, | ||
| 302 | 'type' => 'list' | ||
| 303 | }, | ||
| 304 | 'AccuracySec', | ||
| 305 | { | ||
| 306 | 'type' => 'leaf', | ||
| 307 | 'value_type' => 'uniline' | ||
| 308 | }, | ||
| 309 | 'RandomizedDelaySec', | ||
| 310 | '*AccuracySec', | ||
| 311 | 'FixedRandomDelay', | ||
| 312 | { | ||
| 313 | 'type' => 'leaf', | ||
| 314 | 'upstream_default' => 'no', | ||
| 315 | 'value_type' => 'boolean', | ||
| 316 | 'write_as' => [ | ||
| 317 | 'no', | ||
| 318 | 'yes' | ||
| 319 | ] | ||
| 320 | }, | ||
| 321 | 'RandomizedOffsetSec', | ||
| 322 | { | ||
| 323 | 'type' => 'leaf', | ||
| 324 | 'value_type' => 'uniline' | ||
| 325 | }, | ||
| 326 | 'DeferReactivation', | ||
| 327 | { | ||
| 328 | 'type' => 'leaf', | ||
| 329 | 'upstream_default' => 'no', | ||
| 330 | 'value_type' => 'boolean', | ||
| 331 | 'write_as' => [ | ||
| 332 | 'no', | ||
| 333 | 'yes' | ||
| 334 | ] | ||
| 335 | }, | ||
| 336 | 'OnClockChange', | ||
| 337 | { | ||
| 338 | 'type' => 'leaf', | ||
| 339 | 'value_type' => 'uniline' | ||
| 340 | }, | ||
| 341 | 'OnTimezoneChange', | ||
| 342 | '*OnClockChange', | ||
| 343 | 'Unit', | ||
| 344 | '*OnClockChange', | ||
| 345 | 'Persistent', | ||
| 346 | { | ||
| 347 | 'type' => 'leaf', | ||
| 348 | 'upstream_default' => 'no', | ||
| 349 | 'value_type' => 'boolean', | ||
| 350 | 'write_as' => [ | ||
| 351 | 'no', | ||
| 352 | 'yes' | ||
| 353 | ] | ||
| 354 | }, | ||
| 355 | 'WakeSystem', | ||
| 356 | '*Persistent', | ||
| 357 | 'RemainAfterElapse', | ||
| 358 | { | ||
| 359 | 'type' => 'leaf', | ||
| 360 | 'upstream_default' => 'yes', | ||
| 361 | 'value_type' => 'boolean', | ||
| 362 | 'write_as' => [ | ||
| 363 | 'no', | ||
| 364 | 'yes' | ||
| 365 | ] | ||
| 366 | } | ||
| 367 | ], | ||
| 368 | 'generated_by' => 'parse-man.pl from systemd 261 doc', | ||
| 369 | 'license' => 'LGPLv2.1+', | ||
| 370 | 'name' => 'Systemd::Section::Timer' | ||
| 371 | } | ||
| 372 | ] | ||
| 373 | ; | ||