<?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">

<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>