mirror of
https://git.proxmox.com/git/systemd
synced 2025-05-29 19:22:47 +00:00
143 lines
12 KiB
HTML
143 lines
12 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>systemd.timer</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
|
|
a.headerlink {
|
|
color: #c60f0f;
|
|
font-size: 0.8em;
|
|
padding: 0 4px 0 4px;
|
|
text-decoration: none;
|
|
visibility: hidden;
|
|
}
|
|
|
|
a.headerlink:hover {
|
|
background-color: #c60f0f;
|
|
color: white;
|
|
}
|
|
|
|
h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
|
|
visibility: visible;
|
|
}
|
|
</style><a href="index.html">Index </a>·
|
|
<a href="systemd.directives.html">Directives </a>·
|
|
<a href="../python-systemd/index.html">Python </a>·
|
|
<a href="../libudev/index.html">libudev </a>·
|
|
<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 219</span><hr><div class="refentry"><a name="systemd.timer"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>systemd.timer — Timer unit configuration</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><p><code class="filename"><em class="replaceable"><code>timer</code></em>.timer</code></p></div><div class="refsect1"><a name="idm139903850608352"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p>A unit configuration file whose name ends in
|
|
"<code class="literal">.timer</code>" encodes information about a timer
|
|
controlled and supervised by systemd, for timer-based
|
|
activation.</p><p>This man page lists the configuration options specific to
|
|
this unit type. See
|
|
<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
|
|
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.</p><p>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
|
|
<code class="filename">foo.timer</code> activates a matching service
|
|
<code class="filename">foo.service</code>. The unit to activate may be
|
|
controlled by <code class="varname">Unit=</code> (see below).</p><p>Unless <code class="varname">DefaultDependencies=</code> is set to
|
|
<code class="option">false</code>, all timer units will implicitly have
|
|
dependencies of type <code class="varname">Conflicts=</code> and
|
|
<code class="varname">Before=</code> on <code class="filename">shutdown.target</code>
|
|
to ensure that they are stopped cleanly prior to system shutdown.
|
|
Timer units with at least one <code class="varname">OnCalendar=</code>
|
|
directive will have an additional <code class="varname">After=</code>
|
|
dependency on <code class="filename">timer-sync.target</code> 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 <code class="varname">DefaultDependencies=</code>
|
|
option.</p></div><div class="refsect1"><a name="idm139903850597168"></a><h2 id="Options">Options<a class="headerlink" title="Permalink to this headline" href="#Options">¶</a></h2><p>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:</p><div class="variablelist"><dl class="variablelist"><dt id="OnActiveSec="><span class="term"><code class="varname">OnActiveSec=</code>, </span><span class="term"><code class="varname">OnBootSec=</code>, </span><span class="term"><code class="varname">OnStartupSec=</code>, </span><span class="term"><code class="varname">OnUnitActiveSec=</code>, </span><span class="term"><code class="varname">OnUnitInactiveSec=</code></span><a class="headerlink" title="Permalink to this term" href="#OnActiveSec=">¶</a></dt><dd><p>Defines monotonic timers relative to different
|
|
starting points: <code class="varname">OnActiveSec=</code> defines a
|
|
timer relative to the moment the timer itself is activated.
|
|
<code class="varname">OnBootSec=</code> defines a timer relative to when
|
|
the machine was booted up. <code class="varname">OnStartupSec=</code>
|
|
defines a timer relative to when systemd was first started.
|
|
<code class="varname">OnUnitActiveSec=</code> defines a timer relative
|
|
to when the unit the timer is activating was last activated.
|
|
<code class="varname">OnUnitInactiveSec=</code> defines a timer relative
|
|
to when the unit the timer is activating was last
|
|
deactivated.</p><p>Multiple directives may be combined of the same and of
|
|
different types. For example, by combining
|
|
<code class="varname">OnBootSec=</code> and
|
|
<code class="varname">OnUnitActiveSec=</code>, it is possible to define
|
|
a timer that elapses in regular intervals and activates a
|
|
specific service each time.</p><p>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
|
|
<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>.</p><p>If a timer configured with <code class="varname">OnBootSec=</code>
|
|
or <code class="varname">OnStartupSec=</code> 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.</p><p>These are monotonic timers, independent of wall-clock
|
|
time and timezones. If the computer is temporarily suspended,
|
|
the monotonic clock stops too.</p><p>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.</p><p>Note that timers do not necessarily expire at the
|
|
precise time configured with these settings, as they are
|
|
subject to the <code class="varname">AccuracySec=</code> setting
|
|
below.</p></dd><dt id="OnCalendar="><span class="term"><code class="varname">OnCalendar=</code></span><a class="headerlink" title="Permalink to this term" href="#OnCalendar=">¶</a></dt><dd><p>Defines realtime (i.e. wallclock) timers with
|
|
calendar event expressions. See
|
|
<a href="systemd.time.html"><span class="citerefentry"><span class="refentrytitle">systemd.time</span>(7)</span></a>
|
|
for more information on the syntax of calendar event
|
|
expressions. Otherwise, the semantics are similar to
|
|
<code class="varname">OnActiveSec=</code> and related settings.</p><p>Note that timers do not necessarily expire at the
|
|
precise time configured with this setting, as it is subject to
|
|
the <code class="varname">AccuracySec=</code> setting
|
|
below.</p></dd><dt id="AccuracySec="><span class="term"><code class="varname">AccuracySec=</code></span><a class="headerlink" title="Permalink to this term" href="#AccuracySec=">¶</a></dt><dd><p>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
|
|
<code class="varname">OnCalendar=</code>,
|
|
<code class="varname">OnActiveSec=</code>,
|
|
<code class="varname">OnBootSec=</code>,
|
|
<code class="varname">OnStartupSec=</code>,
|
|
<code class="varname">OnUnitActiveSec=</code> or
|
|
<code class="varname">OnUnitInactiveSec=</code> and ending the time
|
|
configured with <code class="varname">AccuracySec=</code> 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
|
|
<a href="systemd-system.conf.html"><span class="citerefentry"><span class="refentrytitle">systemd-system.conf</span>(5)</span></a>'s
|
|
<code class="varname">TimerSlackNSec=</code> setting. See
|
|
<a href="http://man7.org/linux/man-pages/man2/prctl.2.html"><span class="citerefentry"><span class="refentrytitle">prctl</span>(2)</span></a>
|
|
for details. To optimize power consumption, make sure to set
|
|
this value as high as possible and as low as
|
|
necessary.</p></dd><dt id="Unit="><span class="term"><code class="varname">Unit=</code></span><a class="headerlink" title="Permalink to this term" href="#Unit=">¶</a></dt><dd><p>The unit to activate when this timer elapses.
|
|
The argument is a unit name, whose suffix is not
|
|
"<code class="literal">.timer</code>". 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.</p></dd><dt id="Persistent="><span class="term"><code class="varname">Persistent=</code></span><a class="headerlink" title="Permalink to this term" href="#Persistent=">¶</a></dt><dd><p>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 <code class="varname">OnCalendar=</code>.
|
|
</p></dd><dt id="WakeSystem="><span class="term"><code class="varname">WakeSystem=</code></span><a class="headerlink" title="Permalink to this term" href="#WakeSystem=">¶</a></dt><dd><p>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 <code class="varname">false</code>.</p></dd></dl></div></div><div class="refsect1"><a name="idm139903854455120"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
|
|
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
|
|
<a href="systemctl.html"><span class="citerefentry"><span class="refentrytitle">systemctl</span>(1)</span></a>,
|
|
<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>,
|
|
<a href="systemd.service.html"><span class="citerefentry"><span class="refentrytitle">systemd.service</span>(5)</span></a>,
|
|
<a href="systemd.time.html"><span class="citerefentry"><span class="refentrytitle">systemd.time</span>(7)</span></a>,
|
|
<a href="systemd.directives.html"><span class="citerefentry"><span class="refentrytitle">systemd.directives</span>(7)</span></a>,
|
|
<a href="systemd-system.conf.html"><span class="citerefentry"><span class="refentrytitle">systemd-system.conf</span>(5)</span></a>,
|
|
<a href="http://man7.org/linux/man-pages/man2/prctl.2.html"><span class="citerefentry"><span class="refentrytitle">prctl</span>(2)</span></a>
|
|
</p></div></div></body></html>
|