systemd.timer.xml revision 479fe882ae92e4c2eac3c995cd0d23d4c604889f
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu<?xml version='1.0'?> <!--*-nxml-*-->
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu This file is part of systemd.
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu Copyright 2010 Lennart Poettering
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu systemd is free software; you can redistribute it and/or modify it
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu under the terms of the GNU Lesser General Public License as published by
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu the Free Software Foundation; either version 2.1 of the License, or
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu (at your option) any later version.
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu systemd is distributed in the hope that it will be useful, but
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu WITHOUT ANY WARRANTY; without even the implied warranty of
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu Lesser General Public License for more details.
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu You should have received a copy of the GNU Lesser General Public License
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu along with systemd; If not, see <http://www.gnu.org/licenses/>.
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <email>lennart@poettering.net</email>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu </refentryinfo>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <refentrytitle>systemd.timer</refentrytitle>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <refpurpose>Timer unit configuration</refpurpose>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <refsynopsisdiv>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para><filename><replaceable>timer</replaceable>.timer</filename></para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu </refsynopsisdiv>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>A unit configuration file whose name ends in
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <literal>.timer</literal> encodes information about
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu a timer controlled and supervised by systemd, for
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu timer-based activation.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>This man page lists the configuration options
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu specific to this unit type. See
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu for the common options of all unit configuration
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu files. The common configuration items are configured
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu in the generic [Unit] and [Install] sections. The
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu timer specific configuration options are configured in
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu the [Timer] section.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>For each timer file, a matching unit file must
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu exist, describing the unit to activate when the timer
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu elapses. By default, a service by the same name as the
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu timer (except for the suffix) is activated. Example: a
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu timer file <filename>foo.timer</filename> activates a
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu matching service <filename>foo.service</filename>. The
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu unit to activate may be controlled by
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <varname>Unit=</varname> (see below).</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>Unless <varname>DefaultDependencies=</varname>
9475501a6acf48434052d9e6f4a05ed6681eaaabFrancisc Nicolae Bungiu is set to <option>false</option>, timer units will
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu implicitly have dependencies of type
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <filename>shutdown.target</filename>. These ensure
9475501a6acf48434052d9e6f4a05ed6681eaaabFrancisc Nicolae Bungiu that timer units are stopped cleanly prior to system
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu shutdown. Only timer units involved with early boot or
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu late system shutdown should disable this
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>Timer files must include a [Timer] section,
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu which carries information about the timer it
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu defines. The options specific to the [Timer] section
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu of timer units are the following:</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <variablelist class='unit-directives'>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <term><varname>OnActiveSec=</varname></term>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <term><varname>OnBootSec=</varname></term>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <term><varname>OnStartupSec=</varname></term>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <term><varname>OnUnitActiveSec=</varname></term>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <term><varname>OnUnitInactiveSec=</varname></term>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <listitem><para>Defines monotonic timers
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu relative to different starting points:
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <varname>OnActiveSec=</varname> defines a
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu timer relative to the moment the timer
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu activated. <varname>OnBootSec=</varname>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu defines a timer relative to when the
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu machine was booted
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu up. <varname>OnStartupSec=</varname>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu defines a timer relative to when
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu systemd was first
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu started. <varname>OnUnitActiveSec=</varname>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu defines a timer relative to when the
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu unit the timer is activating was last
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu activated. <varname>OnUnitInactiveSec=</varname>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu defines a timer relative to when the
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu unit the timer is activating was last
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu deactivated.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>Multiple directives may be
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu combined of the same and of different
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu types. For example, by combining
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <varname>OnUnitActiveSec=</varname> it is
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu possible to define a timer that
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu elapses in regular intervals and
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu activates a specific service each
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>The arguments to the directives
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu are time spans configured in
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu seconds. Example: "OnBootSec=50" means
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu 50s after boot-up. The argument may
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu also include time units. Example:
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu "OnBootSec=5h 30min" means 5 hours and
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu 30 minutes after boot-up. For details
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu about the syntax of time spans see
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>If a timer configured with
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu already in the past when the timer
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu unit is activated, it will immediately
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu elapse and the configured unit is
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu started. This is not the case for
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu timers defined in the other
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu directives.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>These are monotonic timers,
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu independent of wall-clock time and timezones. If the
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu computer is temporarily suspended, the
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu monotonic clock stops too.</para>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <para>If the empty string is assigned
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu to any of these options, the list of
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu timers is reset, and all prior
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu assignments will have no
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu </varlistentry>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <term><varname>OnCalendar=</varname></term>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu (i.e. wallclock) timers via calendar
86f318f607745d1f40cbf87048a13ac1c65100e6Felix Gabriel Mance event expressions. See
86f318f607745d1f40cbf87048a13ac1c65100e6Felix Gabriel Mance <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
86f318f607745d1f40cbf87048a13ac1c65100e6Felix Gabriel Mance for more information on the syntax of
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu calendar event expressions. Otherwise
86f318f607745d1f40cbf87048a13ac1c65100e6Felix Gabriel Mance the semantics are similar to
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu </varlistentry>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <term><varname>Unit=</varname></term>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <listitem><para>The unit to activate
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu when this timer elapses. The argument is a
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu unit name, whose suffix is not
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu specified, this value defaults to a
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu service that has the same name as the
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu timer unit, except for the
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu suffix. (See above.) It is recommended
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu that the unit name that is activated
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu and the unit name of the timer unit
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu are named identically, except for the
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu </varlistentry>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu </variablelist>
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
ee93ea764a2b8189253e912c8447f9419033f6d4Francisc Nicolae Bungiu <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>