| <?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> |
| |
| <para>Note that this functionality requires privileges and is thus generally only available in the |
| system service manager.</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> |