view release on metacpan or  search on metacpan

lib/Config/Model/models/Systemd/Section/Timer.pl  view on Meta::CPAN

C<WakeSystem> (see below) is enabled a calendar time event elapsing while the system
is suspended will cause the system to wake up (under the condition the system\'s hardware supports
time-triggered wake-up functionality).',
      'OnClockChange' => 'These options take boolean arguments. When true, the service unit will be triggered
when the system clock (C<CLOCK_REALTIME>) jumps relative to the monotonic clock
(C<CLOCK_MONOTONIC>), or when the local system timezone is modified. These options
can be used alone or in combination with other timer expressions (see above) within the same timer
unit. These options default to C<false>.',
      'OnStartupSec' => '*OnActiveSec',
      'OnTimezoneChange' => '*OnClockChange',
      'OnUnitActiveSec' => '*OnActiveSec',
      'OnUnitInactiveSec' => '*OnActiveSec',
      'Persistent' => "Takes a boolean argument. If true, the time when the service unit was last triggered
is stored on disk.  When the timer is activated, the service unit is triggered immediately if it
would have been triggered at least once during the time when the timer was inactive. Such triggering
is nonetheless subject to the delay imposed by C<RandomizedDelaySec>.
This is useful to catch up on missed runs of the service when the system was powered down. Note that
this setting only has an effect on timers configured with C<OnCalendar>. Defaults to
C<false>.

Use systemctl clean --what=state \x{2026} on the timer unit to remove the timestamp
file maintained by this option from disk. In particular, use this command before uninstalling a timer
unit. See
L<systemctl(1)> for
details.",
      'RandomizedDelaySec' => 'Delay the timer by a randomly selected, evenly distributed amount of time between 0
and the specified time value. Defaults to 0, indicating that no randomized delay shall be applied.
Each timer unit will determine this delay randomly before each iteration, unless modified with
C<FixedRandomDelay>, see below. The delay is added on top of the next determined
elapsing time or the service manager\'s startup time, whichever is later.

This setting is useful to stretch dispatching of similarly configured timer events over a
certain time interval, to prevent them from firing all at the same time, possibly resulting in
resource congestion on the local system.

Note the relation to C<AccuracySec> above: the latter allows the service
manager to coalesce timer events within a specified time range in order to minimize wakeups, while
this setting does the opposite: it stretches timer events over an interval, to make it unlikely that
they fire simultaneously. If C<RandomizedDelaySec> and
C<AccuracySec> are used in conjunction, first the randomized delay is added, and
then the result is possibly further shifted to coalesce it with other timer events happening on the
system. As mentioned above C<AccuracySec> defaults to 1 minute and
C<RandomizedDelaySec> to 0, thus encouraging coalescing of timer events. In order to
optimally stretch timer events over a certain range of time, set
C<AccuracySec=1us> and C<RandomizedDelaySec> to some higher value.
',
      'RandomizedOffsetSec' => 'Offsets the timer by a stable, randomly-selected, and evenly distributed amount of
time between 0 and the specified time value. Defaults to 0, indicating that no such offset shall be
applied. The offset is chosen deterministically, and is derived the same way as
C<FixedRandomDelay>, see above. The offset is added on top of the next determined
elapsing time. This setting only has an effect on timers configured with C<OnCalendar>,
and it can be combined with C<RandomizedDelaySec>.

Much like C<RandomizedDelaySec>, this setting is for distributing timer events
to prevent them from firing all at once. However, this setting is most useful to prevent resource
congestion on a remote service, from a fleet of similarly-configured clients. Unlike
C<RandomizedDelaySec>, this setting applies its offset with no regard to manager
startup time. This maintains the periodicity of configured C<OnCalendar> events
across manager restarts.

For example, let\'s say you\'re running a backup service and have a fleet of laptops that wish
to make backups weekly. To distribute load on the backup service, each laptop should randomly pick
a weekday to upload its backups. This could be achieved by setting C<OnCalendar> to
C<weekly>, and then configuring a C<RandomizedDelaySec> of
C<5 days> with C<FixedRandomDelay> enabled. Let\'s say that some
laptop randomly chooses a delay of 4 days. If this laptop is restarted more often than that, then the
timer will never fire: on each fresh boot, the 4 day delay is restarted and will not be finished by
the time of the next shutdown. Instead, you should use C<RandomizedOffsetSec>, which
will maintain the configured weekly cadence of timer events, even across reboots.',
      'RemainAfterElapse' => 'Takes a boolean argument. If true, a timer will stay loaded, and its state remains
queryable even after it elapsed and the associated unit (as configured with C<Unit>,
see above) deactivated again. If false, an elapsed timer unit that cannot elapse anymore is unloaded
once its associated unit deactivated again. Turning this off is particularly useful for transient
timer units. Note that this setting has an effect when repeatedly starting a timer unit: if
C<RemainAfterElapse> is on, starting the timer a second time has no effect. However,
if C<RemainAfterElapse> is off and the timer unit was already unloaded, it can be
started again, and thus the service can be triggered multiple times. Defaults to
C<true>.',
      'Unit' => 'The unit to activate when this timer elapses.
The argument is a unit name, whose suffix is not
C<.timer>. If not specified, this value
defaults to a service that has the same name as the timer
unit, except for the suffix. (See above.) It is recommended
that the unit name that is activated and the unit name of the
timer unit are named identically, except for the
suffix.',
      'WakeSystem' => 'Takes a boolean argument. If true, an elapsing timer will cause the system to resume
from suspend, should it be suspended and if the system supports this. Note that this option will only
make sure the system resumes on the appropriate times, it will not take care of suspending it again
after any work that is to be done is finished. Defaults to
C<false>.

Note that this functionality requires privileges and is thus generally only available in the
system service manager.

Note that behaviour of monotonic clock timers (as configured with
C<OnActiveSec>, C<OnBootSec>, C<OnStartupSec>,
C<OnUnitActiveSec>, C<OnUnitInactiveSec>, see above) is altered
depending on this option. If false, a monotonic clock is used that is paused during system suspend
(C<CLOCK_MONOTONIC>), if true a different monotonic clock is used that continues
advancing during system suspend (C<CLOCK_BOOTTIME>), see
L<clock_getres(2)> for
details.'
    },
    'element' => [
      'OnActiveSec',
      {
        'type' => 'leaf',
        'value_type' => 'uniline'
      },
      'OnBootSec',
      '*OnActiveSec',
      'OnStartupSec',
      '*OnActiveSec',
      'OnUnitActiveSec',
      '*OnActiveSec',
      'OnUnitInactiveSec',
      '*OnActiveSec',
      'OnCalendar',
      {
        'cargo' => {
          'type' => 'leaf',
          'value_type' => 'uniline'