this unit type. See
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for the common options of all unit configuration files. The common
- configuration items are configured in the generic [Unit] and
- [Install] sections. The timer specific configuration options are
- configured in the [Timer] section.</para>
+ configuration items are configured in the generic <literal>[Unit]</literal> and
+ <literal>[Install]</literal> sections. The timer specific configuration options are
+ configured in the <literal>[Timer]</literal> section.</para>
<para>For each timer file, a matching unit file must exist,
describing the unit to activate when the timer elapses. By
timers defined in the other directives.</para>
<para>These are monotonic timers, independent of wall-clock time and timezones. If the computer is
- temporarily suspended, the monotonic clock pauses, too.</para>
+ temporarily suspended, the monotonic clock generally pauses, too. Note that if
+ <varname>WakeSystem=</varname> is used, a different monotonic clock is selected that continues to
+ advance while the system is suspended and thus can be used as the trigger to resume the
+ system.</para>
<para>If the empty string is assigned to any of these options, the list of timers is reset (both
monotonic timers and <varname>OnCalendar=</varname> timers, see below), and all prior assignments
<citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for details. To optimize power consumption, make sure to set
this value as high as possible and as low as
- necessary.</para></listitem>
+ necessary.</para>
+
+ <para>Note that this setting is primarily a power saving option that allows coalescing CPU
+ wake-ups. It should not be confused with <varname>RandomizedDelaySec=</varname> (see below) which
+ adds a random value to the time the timer shall elapse next and whose purpose is the opposite: to
+ stretch elapsing of timer events over a longer period to reduce workload spikes. For further details
+ and explanations and how both settings play together, see below.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>Persistent=</varname></term>
- <listitem><para>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. This is useful to
- catch up on missed runs of the service when the machine was
- off. Note that this setting only has an effect on timers
- configured with <varname>OnCalendar=</varname>. Defaults
- to <varname>false</varname>.
- </para></listitem>
+ <listitem><para>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. 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 <varname>OnCalendar=</varname>. Defaults to
+ <varname>false</varname>.</para>
+
+ <para>Use <command>systemctl clean --what=state …</command> 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
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+ details.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>WakeSystem=</varname></term>
- <listitem><para>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 <varname>false</varname>.</para></listitem>
+ <listitem><para>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
+ <varname>false</varname>.</para>
+
+ <para>Note that this functionality requires privileges and is thus generally only available in the
+ system service manager.</para>
+
+ <para>Note that behaviour of monotonic clock timers (as configured with
+ <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>,
+ <varname>OnUnitActiveSec=</varname>, <varname>OnUnitInactiveSec=</varname>, see above) is altered
+ depending on this option. If false, a monotonic clock is used that is paused during system suspend
+ (<constant>CLOCK_MONOTONIC</constant>), if true a different monotonic clock is used that continues
+ advancing during system suspend (<constant>CLOCK_BOOTTIME</constant>), see
+ <citerefentry><refentrytitle>clock_getres</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
+ details.</para></listitem>
</varlistentry>
<varlistentry>
projects / thirdparty / systemd.git / blobdiff