| <?xml version='1.0'?> <!--*-nxml-*--> |
| <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| |
| <!-- |
| This file is part of systemd. |
| |
| Copyright 2010 Lennart Poettering |
| |
| systemd is free software; you can redistribute it and/or modify it |
| under the terms of the GNU Lesser General Public License as published by |
| the Free Software Foundation; either version 2.1 of the License, or |
| (at your option) any later version. |
| |
| systemd is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| Lesser General Public License for more details. |
| |
| You should have received a copy of the GNU Lesser General Public License |
| along with systemd; If not, see <http://www.gnu.org/licenses/>. |
| --> |
| |
| <refentry id="systemd.timer"> |
| <refentryinfo> |
| <title>systemd.timer</title> |
| <productname>systemd</productname> |
| |
| <authorgroup> |
| <author> |
| <contrib>Developer</contrib> |
| <firstname>Lennart</firstname> |
| <surname>Poettering</surname> |
| <email>lennart@poettering.net</email> |
| </author> |
| </authorgroup> |
| </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>Unless <varname>DefaultDependencies=</varname> |
| is set to <option>false</option>, all timer units will |
| implicitly have dependencies of type |
| <varname>Conflicts=</varname> and |
| <varname>Before=</varname> on |
| <filename>shutdown.target</filename> to ensure that |
| they are stopped cleanly prior to system shutdown. |
| Timer units with at least one |
| <varname>OnCalendar=</varname> directive will have an |
| additional <varname>After=</varname> dependency on |
| <filename>timer-sync.target</filename> to avoid |
| being started before the system clock has been |
| correctly set. Only timer units involved with early |
| boot or late system shutdown should disable the |
| <varname>DefaultDependencies=</varname> option.</para> |
| </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.unit</refentrytitle><manvolnum>5</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></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 distribute the wake-up time |
| in networked installations, as well as |
| optimizing 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>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>. |
| </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> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</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> |