| <?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 |
| <filename>.timer</filename> 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>, timer units will |
| implicitly have dependencies of type |
| <varname>Conflicts=</varname> and |
| <varname>Before=</varname> on |
| <filename>shutdown.target</filename>. These ensure |
| that timer units are stopped cleanly prior to system |
| shutdown. Only timer units involved with early boot or |
| late system shutdown should disable this |
| 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></listitem> |
| |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>OnCalendar=</varname></term> |
| |
| <listitem><para>Defines realtime |
| (i.e. wallclock) timers via 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></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 |
| <filename>.timer</filename>. 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> |
| </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> |
| </para> |
| </refsect1> |
| |
| </refentry> |