diff options
Diffstat (limited to 'man/systemd.timer.xml')
| -rw-r--r-- | man/systemd.timer.xml | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml new file mode 100644 index 0000000..d254c77 --- /dev/null +++ b/man/systemd.timer.xml @@ -0,0 +1,308 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="systemd.timer"> + <refentryinfo> + <title>systemd.timer</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.timer</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.timer</refname> + <refpurpose>Timer unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>timer</replaceable>.timer</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.timer</literal> encodes information about a timer + controlled and supervised by systemd, for timer-based + activation.</para> + + <para>This man page lists the configuration options specific to + 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> + + <para>For each timer file, a matching unit file must exist, + describing the unit to activate when the timer elapses. By + default, a service by the same name as the timer (except for the + suffix) is activated. Example: a timer file + <filename>foo.timer</filename> activates a matching service + <filename>foo.service</filename>. The unit to activate may be + controlled by <varname>Unit=</varname> (see below).</para> + + <para>Note that in case the unit to activate is already active at the time the timer elapses it is not restarted, + but simply left running. There is no concept of spawning new service instances in this case. Due to this, services + with <varname>RemainAfterExit=</varname> set (which stay around continuously even after the service's main process + exited) are usually not suitable for activation via repetitive timers, as they will only be activated once, and + then stay around forever.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <refsect2> + <title>Implicit Dependencies</title> + + <para>The following dependencies are implicitly added:</para> + + <itemizedlist> + <listitem><para>Timer units automatically gain a <varname>Before=</varname> + dependency on the service they are supposed to activate.</para></listitem> + </itemizedlist> + </refsect2> + + <refsect2> + <title>Default Dependencies</title> + + <para>The following dependencies are added unless <varname>DefaultDependencies=no</varname> is set:</para> + + <itemizedlist> + <listitem><para>Timer units will automatically have dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>Before=</varname> + on <filename>timers.target</filename>, as well as <varname>Conflicts=</varname> and <varname>Before=</varname> on + <filename>shutdown.target</filename> to ensure that they are stopped cleanly prior to system shutdown. Only timer + units involved with early boot or late system shutdown should disable the + <varname>DefaultDependencies=</varname> option.</para></listitem> + + <listitem><para>Timer units + with at least one <varname>OnCalendar=</varname> directive will have an additional <varname>After=</varname> + dependency on <filename>time-sync.target</filename> to avoid being started before the system clock has been + correctly set.</para></listitem> + </itemizedlist> + </refsect2> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Timer files must include a [Timer] section, which carries + information about the timer it defines. The options specific to + the [Timer] section of timer units are the following:</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>OnActiveSec=</varname></term> + <term><varname>OnBootSec=</varname></term> + <term><varname>OnStartupSec=</varname></term> + <term><varname>OnUnitActiveSec=</varname></term> + <term><varname>OnUnitInactiveSec=</varname></term> + + <listitem><para>Defines monotonic timers relative to different + starting points: <varname>OnActiveSec=</varname> defines a + timer relative to the moment the timer itself is activated. + <varname>OnBootSec=</varname> defines a timer relative to when + the machine was booted up. <varname>OnStartupSec=</varname> + defines a timer relative to when systemd was first started. + <varname>OnUnitActiveSec=</varname> defines a timer relative + to when the unit the timer is activating was last activated. + <varname>OnUnitInactiveSec=</varname> defines a timer relative + to when the unit the timer is activating was last + deactivated.</para> + + <para>Multiple directives may be combined of the same and of + different types. For example, by combining + <varname>OnBootSec=</varname> and + <varname>OnUnitActiveSec=</varname>, it is possible to define + a timer that elapses in regular intervals and activates a + specific service each time.</para> + + <para>The arguments to the directives are time spans + configured in seconds. Example: "OnBootSec=50" means 50s after + boot-up. The argument may also include time units. Example: + "OnBootSec=5h 30min" means 5 hours and 30 minutes after + boot-up. For details about the syntax of time spans, see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>If a timer configured with <varname>OnBootSec=</varname> + or <varname>OnStartupSec=</varname> is already in the past + when the timer unit is activated, it will immediately elapse + and the configured unit is started. This is not the case for + 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 stops too.</para> + + <para>If the empty string is assigned to any of these options, + the list of timers is reset, and all prior assignments will + have no effect.</para> + + <para>Note that timers do not necessarily expire at the + precise time configured with these settings, as they are + subject to the <varname>AccuracySec=</varname> setting + below.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><varname>OnCalendar=</varname></term> + + <listitem><para>Defines realtime (i.e. wallclock) timers with + calendar event expressions. See + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information on the syntax of calendar event + expressions. Otherwise, the semantics are similar to + <varname>OnActiveSec=</varname> and related settings.</para> + + <para>Note that timers do not necessarily expire at the + precise time configured with this setting, as it is subject to + the <varname>AccuracySec=</varname> setting + below.</para> + + <para>May be specified more than once.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AccuracySec=</varname></term> + + <listitem><para>Specify the accuracy the timer shall elapse + with. Defaults to 1min. The timer is scheduled to elapse + within a time window starting with the time specified in + <varname>OnCalendar=</varname>, + <varname>OnActiveSec=</varname>, + <varname>OnBootSec=</varname>, + <varname>OnStartupSec=</varname>, + <varname>OnUnitActiveSec=</varname> or + <varname>OnUnitInactiveSec=</varname> and ending the time + configured with <varname>AccuracySec=</varname> later. Within + this time window, the expiry time will be placed at a + host-specific, randomized, but stable position that is + synchronized between all local timer units. This is done in + order to optimize power consumption to suppress unnecessary + CPU wake-ups. To get best accuracy, set this option to + 1us. Note that the timer is still subject to the timer slack + configured via + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s + <varname>TimerSlackNSec=</varname> setting. See + <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> + </varlistentry> + + <varlistentry> + <term><varname>RandomizedDelaySec=</varname></term> + + <listitem><para>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, and the delay will simply be + added on top of the next determined elapsing time. This is + useful to stretch dispatching of similarly configured timer + events over a certain amount time, to avoid that they all fire + at the same time, possibly resulting in resource + congestion. Note the relation to + <varname>AccuracySec=</varname> above: the latter allows the + service manager to coalesce timer events within a specified + time range in order to minimize wakeups, the former does the + opposite: it stretches timer events over a time range, to make + it unlikely that they fire simultaneously. If + <varname>RandomizedDelaySec=</varname> and + <varname>AccuracySec=</varname> 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 + <varname>AccuracySec=</varname> defaults to 1min and + <varname>RandomizedDelaySec=</varname> to 0, thus encouraging + coalescing of timer events. In order to optimally stretch + timer events over a certain range of time, make sure to set + <varname>RandomizedDelaySec=</varname> to a higher value, and + <varname>AccuracySec=1us</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Unit=</varname></term> + + <listitem><para>The unit to activate when this timer elapses. + The argument is a unit name, whose suffix is not + <literal>.timer</literal>. 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.</para></listitem> + </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> + </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> + </varlistentry> + + <varlistentry> + <term><varname>RemainAfterElapse=</varname></term> + + <listitem><para>Takes a boolean argument. If true, an elapsed + timer will stay loaded, and its state remains queriable. If + false, an elapsed timer unit that cannot elapse anymore is + unloaded. Turning this off is particularly useful for + transient timer units that shall disappear after they first + elapse. Note that this setting has an effect on repeatedly + starting a timer unit that only elapses once: if + <varname>RemainAfterElapse=</varname> is on, it will not be + started again, and is guaranteed to elapse only once. However, + if <varname>RemainAfterElapse=</varname> is off, it might be + started again if it is already elapsed, and thus be triggered + multiple times. Defaults to + <varname>yes</varname>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |