view release on metacpan or  search on metacpan

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

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.
I< Optional. Type uniline.  > 

=head2 FixedRandomDelay

Takes a boolean argument. When enabled, the randomized delay specified by
C<RandomizedDelaySec> is chosen deterministically, and remains stable between all
firings of the same timer, even if the manager is restarted. The delay is derived from the machine
ID, the manager's user identifier, and the timer unit's name. This effectively creates a unique fixed
offset for each timer, reducing the jitter in firings of an individual timer while still avoiding
firing at the same time as other similarly configured timers.

This setting has an effect only if C<RandomizedDelaySec> is not 0. Defaults to
C<false>. I< Optional. Type boolean.  > 

=over 4

=item upstream_default value :

no

=back



=head2 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. I< Optional. Type uniline.  > 

=head2 DeferReactivation

Takes a boolean argument. When enabled, the timer schedules the next elapse based on
the trigger unit entering inactivity, instead of the last trigger time.
This is most apparent in the case where the service unit takes longer to run than the timer interval.
With this setting enabled, the timer will schedule the next elapse based on when the service finishes
running, and so it will have to wait until the next realtime elapse time to trigger.
Otherwise, the default behavior is for the timer unit to immediately trigger again once the service
finishes running. This happens because the timer schedules the next elapse based on the previous trigger
time, and since the interval is shorter than the service runtime, that elapse will be in the past,
causing it to immediately trigger once done.

This setting has an effect only if a realtime timer has been specified with
C<OnCalendar>. Defaults to C<false>. I< Optional. Type boolean.  > 

=over 4

=item upstream_default value :

no

=back



=head2 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>. I< Optional. Type uniline.  > 

=head2 OnTimezoneChange

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>. I< Optional. Type uniline.  > 

=head2 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. I< Optional. Type uniline.  > 

=head2 Persistent