mirror of
https://git.proxmox.com/git/systemd
synced 2026-01-22 04:07:46 +00:00
844 lines
67 KiB
HTML
844 lines
67 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>systemd.service</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 214</span><hr><div class="refentry"><a name="systemd.service"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>systemd.service — Service unit configuration</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><p><code class="filename"><em class="replaceable"><code>service</code></em>.service</code></p></div><div class="refsect1"><a name="idm214184384128"></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="filename">.service</code> encodes information
|
||
about a process controlled and supervised by
|
||
systemd.</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 "<code class="literal">[Unit]</code>" and
|
||
"<code class="literal">[Install]</code>" sections. The service
|
||
specific configuration options are configured in the
|
||
"<code class="literal">[Service]</code>" section.</p><p>Additional options are listed in
|
||
<a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>,
|
||
which define the execution environment the commands
|
||
are executed in, and in
|
||
<a href="systemd.kill.html"><span class="citerefentry"><span class="refentrytitle">systemd.kill</span>(5)</span></a>,
|
||
which define the way the processes of the service are
|
||
terminated, and in
|
||
<a href="systemd.resource-control.html"><span class="citerefentry"><span class="refentrytitle">systemd.resource-control</span>(5)</span></a>,
|
||
which configure resource control settings for the
|
||
processes of the service.</p><p>Unless <code class="varname">DefaultDependencies=</code>
|
||
is set to <code class="option">false</code>, service units will
|
||
implicitly have dependencies of type
|
||
<code class="varname">Requires=</code> and
|
||
<code class="varname">After=</code> on
|
||
<code class="filename">basic.target</code> as well as
|
||
dependencies of type <code class="varname">Conflicts=</code> and
|
||
<code class="varname">Before=</code> on
|
||
<code class="filename">shutdown.target</code>. These ensure
|
||
that normal service units pull in basic system
|
||
initialization, and are terminated cleanly prior to
|
||
system shutdown. Only services involved with early
|
||
boot or late system shutdown should disable this
|
||
option.</p><p>If a service is requested under a certain name
|
||
but no unit configuration file is found, systemd looks
|
||
for a SysV init script by the same name (with the
|
||
<code class="filename">.service</code> suffix removed) and
|
||
dynamically creates a service unit from that
|
||
script. This is useful for compatibility with
|
||
SysV. Note that this compatibility is quite
|
||
comprehensive but not 100%. For details about the
|
||
incompatibilities, see the <a class="ulink" href="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities" target="_top">Incompatibilities
|
||
with SysV</a> document.
|
||
</p></div><div class="refsect1"><a name="idm214188267056"></a><h2 id="Options">Options<a class="headerlink" title="Permalink to this headline" href="#Options">¶</a></h2><p>Service files must include a
|
||
"<code class="literal">[Service]</code>" section, which carries
|
||
information about the service and the process it
|
||
supervises. A number of options that may be used in
|
||
this section are shared with other unit types. These
|
||
options are documented in
|
||
<a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>
|
||
and
|
||
<a href="systemd.kill.html"><span class="citerefentry"><span class="refentrytitle">systemd.kill</span>(5)</span></a>. The
|
||
options specific to the "<code class="literal">[Service]</code>"
|
||
section of service units are the following:</p><div class="variablelist"><dl class="variablelist"><dt id="Type="><span class="term"><code class="varname">Type=</code></span><a class="headerlink" title="Permalink to this term" href="#Type=">¶</a></dt><dd><p>Configures the process
|
||
start-up type for this service
|
||
unit. One of <code class="option">simple</code>,
|
||
<code class="option">forking</code>,
|
||
<code class="option">oneshot</code>,
|
||
<code class="option">dbus</code>,
|
||
<code class="option">notify</code> or
|
||
<code class="option">idle</code>.</p><p>If set to
|
||
<code class="option">simple</code> (the default
|
||
value if neither
|
||
<code class="varname">Type=</code> nor
|
||
<code class="varname">BusName=</code> are
|
||
specified), it is expected that the
|
||
process configured with
|
||
<code class="varname">ExecStart=</code> is the
|
||
main process of the service. In this
|
||
mode, if the process offers
|
||
functionality to other processes on
|
||
the system, its communication channels
|
||
should be installed before the daemon
|
||
is started up (e.g. sockets set up by
|
||
systemd, via socket activation), as
|
||
systemd will immediately proceed
|
||
starting follow-up units.</p><p>If set to
|
||
<code class="option">forking</code>, it is
|
||
expected that the process configured
|
||
with <code class="varname">ExecStart=</code>
|
||
will call <code class="function">fork()</code>
|
||
as part of its start-up. The parent process is
|
||
expected to exit when start-up is
|
||
complete and all communication
|
||
channels are set up. The child continues
|
||
to run as the main daemon
|
||
process. This is the behavior of
|
||
traditional UNIX daemons. If this
|
||
setting is used, it is recommended to
|
||
also use the
|
||
<code class="varname">PIDFile=</code> option, so
|
||
that systemd can identify the main
|
||
process of the daemon. systemd will
|
||
proceed with starting follow-up units
|
||
as soon as the parent process
|
||
exits.</p><p>Behavior of
|
||
<code class="option">oneshot</code> is similar
|
||
to <code class="option">simple</code>; however,
|
||
it is expected that the process has to
|
||
exit before systemd starts follow-up
|
||
units. <code class="varname">RemainAfterExit=</code>
|
||
is particularly useful for this type
|
||
of service.</p><p>Behavior of
|
||
<code class="option">dbus</code> is similar to
|
||
<code class="option">simple</code>; however, it is
|
||
expected that the daemon acquires a
|
||
name on the D-Bus bus, as configured
|
||
by
|
||
<code class="varname">BusName=</code>. systemd
|
||
will proceed with starting follow-up
|
||
units after the D-Bus bus name has been
|
||
acquired. Service units with this
|
||
option configured implicitly gain
|
||
dependencies on the
|
||
<code class="filename">dbus.socket</code>
|
||
unit. This type is the default if
|
||
<code class="varname">BusName=</code> is
|
||
specified.</p><p>Behavior of
|
||
<code class="option">notify</code> is similar to
|
||
<code class="option">simple</code>; however, it is
|
||
expected that the daemon sends a
|
||
notification message via
|
||
<a href="sd_notify.html"><span class="citerefentry"><span class="refentrytitle">sd_notify</span>(3)</span></a>
|
||
or an equivalent call when it has finished
|
||
starting up. systemd will proceed with
|
||
starting follow-up units after this
|
||
notification message has been sent. If
|
||
this option is used,
|
||
<code class="varname">NotifyAccess=</code> (see
|
||
below) should be set to open access to
|
||
the notification socket provided by
|
||
systemd. If
|
||
<code class="varname">NotifyAccess=</code> is
|
||
not set, it will be implicitly set to
|
||
<code class="option">main</code>. Note that
|
||
currently
|
||
<code class="varname">Type=</code><code class="option">notify</code>
|
||
will not work if used in combination with
|
||
<code class="varname">PrivateNetwork=</code><code class="option">yes</code>.</p><p>Behavior of
|
||
<code class="option">idle</code> is very similar
|
||
to <code class="option">simple</code>; however,
|
||
actual execution of the service
|
||
binary is delayed until all jobs are
|
||
dispatched. This may be used to avoid
|
||
interleaving of output of shell
|
||
services with the status output on the
|
||
console.</p></dd><dt id="RemainAfterExit="><span class="term"><code class="varname">RemainAfterExit=</code></span><a class="headerlink" title="Permalink to this term" href="#RemainAfterExit=">¶</a></dt><dd><p>Takes a boolean value
|
||
that specifies whether the service
|
||
shall be considered active even when
|
||
all its processes exited. Defaults to
|
||
<code class="option">no</code>.</p></dd><dt id="GuessMainPID="><span class="term"><code class="varname">GuessMainPID=</code></span><a class="headerlink" title="Permalink to this term" href="#GuessMainPID=">¶</a></dt><dd><p>Takes a boolean value
|
||
that specifies whether systemd should
|
||
try to guess the main PID of a service
|
||
if it cannot be determined
|
||
reliably. This option is ignored
|
||
unless <code class="option">Type=forking</code>
|
||
is set and <code class="option">PIDFile=</code>
|
||
is unset because for the other types
|
||
or with an explicitly configured PID
|
||
file, the main PID is always known. The
|
||
guessing algorithm might come to
|
||
incorrect conclusions if a daemon
|
||
consists of more than one process. If
|
||
the main PID cannot be determined,
|
||
failure detection and automatic
|
||
restarting of a service will not work
|
||
reliably. Defaults to
|
||
<code class="option">yes</code>.</p></dd><dt id="PIDFile="><span class="term"><code class="varname">PIDFile=</code></span><a class="headerlink" title="Permalink to this term" href="#PIDFile=">¶</a></dt><dd><p>Takes an absolute file
|
||
name pointing to the PID file of this
|
||
daemon. Use of this option is
|
||
recommended for services where
|
||
<code class="varname">Type=</code> is set to
|
||
<code class="option">forking</code>. systemd will
|
||
read the PID of the main process of
|
||
the daemon after start-up of the
|
||
service. systemd will not write to the
|
||
file configured here.</p></dd><dt id="BusName="><span class="term"><code class="varname">BusName=</code></span><a class="headerlink" title="Permalink to this term" href="#BusName=">¶</a></dt><dd><p>Takes a D-Bus bus
|
||
name that this service is reachable
|
||
as. This option is mandatory for
|
||
services where
|
||
<code class="varname">Type=</code> is set to
|
||
<code class="option">dbus</code>, but its use
|
||
is otherwise recommended if the process
|
||
takes a name on the D-Bus bus.</p></dd><dt id="ExecStart="><span class="term"><code class="varname">ExecStart=</code></span><a class="headerlink" title="Permalink to this term" href="#ExecStart=">¶</a></dt><dd><p>Commands with their
|
||
arguments that are executed when this
|
||
service is started. For each of the
|
||
specified commands, the first argument
|
||
must be an absolute and literal path
|
||
to an executable.</p><p>When <code class="varname">Type</code> is
|
||
not <code class="option">oneshot</code>, only one
|
||
command may be given. When
|
||
<code class="varname">Type=oneshot</code> is
|
||
used, more than one command may be
|
||
specified. Multiple command lines may
|
||
be concatenated in a single directive
|
||
by separating them with semicolons
|
||
(these semicolons must be passed as
|
||
separate words). Alternatively, this
|
||
directive may be specified more than
|
||
once with the same effect.
|
||
Lone semicolons may be escaped as
|
||
"<code class="literal">\;</code>". If the empty
|
||
string is assigned to this option, the
|
||
list of commands to start is reset,
|
||
prior assignments of this option will
|
||
have no effect.</p><p>Each command line is split on
|
||
whitespace, with the first item being
|
||
the command to execute, and the
|
||
subsequent items being the arguments.
|
||
Double quotes ("...") and single
|
||
quotes ('...') may be used, in which
|
||
case everything until the next
|
||
matching quote becomes part of the
|
||
same argument. Quotes themselves are
|
||
removed after parsing. In addition, a
|
||
trailing backslash
|
||
("<code class="literal">\</code>") may be used to
|
||
merge lines. This syntax is intended
|
||
to be very similar to shell syntax,
|
||
but only the meta-characters and
|
||
expansions described in the following
|
||
paragraphs are understood.
|
||
Specifically, redirection using
|
||
"<code class="literal"><</code>",
|
||
"<code class="literal"><<</code>",
|
||
"<code class="literal">></code>", and
|
||
"<code class="literal">>></code>", pipes
|
||
using "<code class="literal">|</code>", and
|
||
running programs in the background
|
||
using "<code class="literal">&</code>"
|
||
and <span class="emphasis"><em>other elements of shell
|
||
syntax are not supported</em></span>.
|
||
</p><p>If more than one command is
|
||
specified, the commands are invoked
|
||
sequentially in the order they appear
|
||
in the unit file. If one of the
|
||
commands fails (and is not prefixed
|
||
with "<code class="literal">-</code>"), other lines
|
||
are not executed, and the unit is
|
||
considered failed.</p><p>Unless
|
||
<code class="varname">Type=forking</code> is
|
||
set, the process started via this
|
||
command line will be considered the
|
||
main process of the daemon.</p><p>The command line accepts
|
||
"<code class="literal">%</code>" specifiers as
|
||
described in
|
||
<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>.
|
||
Note that the first argument of the
|
||
command line (i.e. the program to
|
||
execute) may not include
|
||
specifiers.</p><p>Basic environment variable
|
||
substitution is supported. Use
|
||
"<code class="literal">${FOO}</code>" as part of a
|
||
word, or as a word of its own, on the
|
||
command line, in which case it will be
|
||
replaced by the value of the
|
||
environment variable including all
|
||
whitespace it contains, resulting in a
|
||
single argument. Use
|
||
"<code class="literal">$FOO</code>" as a separate
|
||
word on the command line, in which
|
||
case it will be replaced by the value
|
||
of the environment variable split at
|
||
whitespace, resulting in zero or more
|
||
arguments. To pass a literal dollar
|
||
sign, use "<code class="literal">$$</code>".
|
||
Variables whose value is not known at
|
||
expansion time are treated as empty
|
||
strings. Note that the first argument
|
||
(i.e. the program to execute) may not
|
||
be a variable.</p><p>Variables to be used in this
|
||
fashion may be defined through
|
||
<code class="varname">Environment=</code> and
|
||
<code class="varname">EnvironmentFile=</code>.
|
||
In addition, variables listed in the
|
||
section "Environment variables in
|
||
spawned processes" in
|
||
<a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>,
|
||
which are considered "static
|
||
configuration", may be used (this includes
|
||
e.g. <code class="varname">$USER</code>, but not
|
||
<code class="varname">$TERM</code>).</p><p>Optionally, if the absolute file
|
||
name is prefixed with
|
||
"<code class="literal">@</code>", the second token
|
||
will be passed as
|
||
"<code class="literal">argv[0]</code>" to the
|
||
executed process, followed by the
|
||
further arguments specified. If the
|
||
absolute filename is prefixed with
|
||
"<code class="literal">-</code>", an exit code of
|
||
the command normally considered a
|
||
failure (i.e. non-zero exit status or
|
||
abnormal exit due to signal) is ignored
|
||
and considered success. If both
|
||
"<code class="literal">-</code>" and
|
||
"<code class="literal">@</code>" are used, they
|
||
can appear in either order.</p><p>Note that this setting does not
|
||
directly support shell command
|
||
lines. If shell command lines are to
|
||
be used, they need to be passed
|
||
explicitly to a shell implementation
|
||
of some kind. Example:</p><pre class="programlisting">ExecStart=/bin/sh -c 'dmesg | tac'</pre><p>Example:</p><pre class="programlisting">ExecStart=/bin/echo one ; /bin/echo "two two"</pre><p>This will execute
|
||
<span class="command"><strong>/bin/echo</strong></span> two
|
||
times, each time with one argument:
|
||
"<code class="literal">one</code>" and
|
||
"<code class="literal">two two</code>",
|
||
respectively. Because two commands are
|
||
specified,
|
||
<code class="varname">Type=oneshot</code> must
|
||
be used.</p><p>Example:</p><pre class="programlisting">ExecStart=/bin/echo / >/dev/null & \; \
|
||
/bin/ls</pre><p>This will execute
|
||
<span class="command"><strong>/bin/echo</strong></span> with five
|
||
arguments: "<code class="literal">/</code>",
|
||
"<code class="literal">>/dev/null</code>",
|
||
"<code class="literal">&</code>",
|
||
"<code class="literal">;</code>", and
|
||
"<code class="literal">/bin/ls</code>".</p><p>Example:</p><pre class="programlisting">Environment="ONE=one" 'TWO=two two'
|
||
ExecStart=/bin/echo $ONE $TWO ${TWO}</pre><p>This will execute
|
||
<span class="command"><strong>/bin/echo</strong></span> with four
|
||
arguments: "<code class="literal">one</code>",
|
||
"<code class="literal">two</code>",
|
||
"<code class="literal">two</code>", and
|
||
"<code class="literal">two two</code>".</p></dd><dt id="ExecStartPre="><span class="term"><code class="varname">ExecStartPre=</code>, </span><span class="term"><code class="varname">ExecStartPost=</code></span><a class="headerlink" title="Permalink to this term" href="#ExecStartPre=">¶</a></dt><dd><p>Additional commands
|
||
that are executed before or after
|
||
the command in
|
||
<code class="varname">ExecStart=</code>, respectively.
|
||
Syntax is the same as for
|
||
<code class="varname">ExecStart=</code>, except
|
||
that multiple command lines are allowed
|
||
and the commands are executed one
|
||
after the other, serially.</p><p>If any of those commands (not
|
||
prefixed with "<code class="literal">-</code>")
|
||
fail, the rest are not executed and
|
||
the unit is considered failed.</p></dd><dt id="ExecReload="><span class="term"><code class="varname">ExecReload=</code></span><a class="headerlink" title="Permalink to this term" href="#ExecReload=">¶</a></dt><dd><p>Commands to execute to
|
||
trigger a configuration reload in the
|
||
service. This argument takes multiple
|
||
command lines, following the same
|
||
scheme as described for
|
||
<code class="varname">ExecStart=</code>
|
||
above. Use of this setting is
|
||
optional. Specifier and environment
|
||
variable substitution is supported
|
||
here following the same scheme as for
|
||
<code class="varname">ExecStart=</code>.</p><p>One additional, special
|
||
environment variable is set: if known,
|
||
<code class="varname">$MAINPID</code> is set to
|
||
the main process of the daemon, and
|
||
may be used for command lines like the
|
||
following:</p><pre class="programlisting">/bin/kill -HUP $MAINPID</pre><p>Note however that reloading a
|
||
daemon by sending a signal (as with
|
||
the example line above) is usually not
|
||
a good choice, because this is an
|
||
asynchronous operation and hence not
|
||
suitable to order reloads of multiple
|
||
services against each other. It is
|
||
strongly recommended to set
|
||
<code class="varname">ExecReload=</code> to a
|
||
command that not only triggers a
|
||
configuration reload of the daemon,
|
||
but also synchronously waits for it to
|
||
complete.</p></dd><dt id="ExecStop="><span class="term"><code class="varname">ExecStop=</code></span><a class="headerlink" title="Permalink to this term" href="#ExecStop=">¶</a></dt><dd><p>Commands to execute to
|
||
stop the service started via
|
||
<code class="varname">ExecStart=</code>. This
|
||
argument takes multiple command lines,
|
||
following the same scheme as described
|
||
for <code class="varname">ExecStart=</code>
|
||
above. Use of this setting is
|
||
optional. After the commands configured
|
||
in this option are run, all processes
|
||
remaining for a service are
|
||
terminated according to the
|
||
<code class="varname">KillMode=</code> setting
|
||
(see
|
||
<a href="systemd.kill.html"><span class="citerefentry"><span class="refentrytitle">systemd.kill</span>(5)</span></a>). If
|
||
this option is not specified, the
|
||
process is terminated immediately when
|
||
service stop is requested. Specifier
|
||
and environment variable substitution
|
||
is supported (including
|
||
<code class="varname">$MAINPID</code>, see
|
||
above).</p></dd><dt id="ExecStopPost="><span class="term"><code class="varname">ExecStopPost=</code></span><a class="headerlink" title="Permalink to this term" href="#ExecStopPost=">¶</a></dt><dd><p>Additional commands
|
||
that are executed after the service
|
||
was stopped. This includes cases where
|
||
the commands configured in
|
||
<code class="varname">ExecStop=</code> were used,
|
||
where the service does not have any
|
||
<code class="varname">ExecStop=</code> defined, or
|
||
where the service exited unexpectedly. This
|
||
argument takes multiple command lines,
|
||
following the same scheme as described
|
||
for <code class="varname">ExecStart</code>. Use
|
||
of these settings is
|
||
optional. Specifier and environment
|
||
variable substitution is
|
||
supported.</p></dd><dt id="RestartSec="><span class="term"><code class="varname">RestartSec=</code></span><a class="headerlink" title="Permalink to this term" href="#RestartSec=">¶</a></dt><dd><p>Configures the time to
|
||
sleep before restarting a service (as
|
||
configured with
|
||
<code class="varname">Restart=</code>). Takes a
|
||
unit-less value in seconds, or a time
|
||
span value such as "5min
|
||
20s". Defaults to
|
||
100ms.</p></dd><dt id="TimeoutStartSec="><span class="term"><code class="varname">TimeoutStartSec=</code></span><a class="headerlink" title="Permalink to this term" href="#TimeoutStartSec=">¶</a></dt><dd><p>Configures the time to
|
||
wait for start-up. If a
|
||
daemon service does not signal
|
||
start-up completion within the
|
||
configured time, the service will be
|
||
considered failed and will be shut
|
||
down again.
|
||
Takes a unit-less value in seconds, or a
|
||
time span value such as "5min
|
||
20s". Pass "<code class="literal">0</code>" to
|
||
disable the timeout logic. Defaults to
|
||
<code class="varname">TimeoutStartSec=</code> from
|
||
the manager configuration file, except
|
||
when <code class="varname">Type=oneshot</code> is
|
||
used, in which case the timeout
|
||
is disabled by default.
|
||
</p></dd><dt id="TimeoutStopSec="><span class="term"><code class="varname">TimeoutStopSec=</code></span><a class="headerlink" title="Permalink to this term" href="#TimeoutStopSec=">¶</a></dt><dd><p>Configures the time to
|
||
wait for stop. If a service is asked
|
||
to stop, but does not terminate in the
|
||
specified time, it will be terminated
|
||
forcibly via <code class="constant">SIGTERM</code>,
|
||
and after another timeout of equal duration
|
||
with <code class="constant">SIGKILL</code> (see
|
||
<code class="varname">KillMode=</code>
|
||
in <a href="systemd.kill.html"><span class="citerefentry"><span class="refentrytitle">systemd.kill</span>(5)</span></a>).
|
||
Takes a unit-less value in seconds, or a
|
||
time span value such as "5min
|
||
20s". Pass "<code class="literal">0</code>" to disable
|
||
the timeout logic. Defaults to
|
||
<code class="varname">TimeoutStartSec=</code> from the
|
||
manager configuration file.
|
||
</p></dd><dt id="TimeoutSec="><span class="term"><code class="varname">TimeoutSec=</code></span><a class="headerlink" title="Permalink to this term" href="#TimeoutSec=">¶</a></dt><dd><p>A shorthand for configuring
|
||
both <code class="varname">TimeoutStartSec=</code>
|
||
and <code class="varname">TimeoutStopSec=</code>
|
||
to the specified value.
|
||
</p></dd><dt id="WatchdogSec="><span class="term"><code class="varname">WatchdogSec=</code></span><a class="headerlink" title="Permalink to this term" href="#WatchdogSec=">¶</a></dt><dd><p>Configures the
|
||
watchdog timeout for a service. The
|
||
watchdog is activated when the start-up is
|
||
completed. The service must call
|
||
<a href="sd_notify.html"><span class="citerefentry"><span class="refentrytitle">sd_notify</span>(3)</span></a>
|
||
regularly with "<code class="literal">WATCHDOG=1</code>"
|
||
(i.e. the "keep-alive ping"). If the time
|
||
between two such calls is larger than
|
||
the configured time, then the service
|
||
is placed in a failed state. By
|
||
setting <code class="varname">Restart=</code> to
|
||
<code class="option">on-failure</code> or
|
||
<code class="option">always</code>, the service
|
||
will be automatically restarted. The
|
||
time configured here will be passed to
|
||
the executed service process in the
|
||
<code class="varname">WATCHDOG_USEC=</code>
|
||
environment variable. This allows
|
||
daemons to automatically enable the
|
||
keep-alive pinging logic if watchdog
|
||
support is enabled for the service. If
|
||
this option is used,
|
||
<code class="varname">NotifyAccess=</code> (see
|
||
below) should be set to open access to
|
||
the notification socket provided by
|
||
systemd. If
|
||
<code class="varname">NotifyAccess=</code> is
|
||
not set, it will be implicitly set to
|
||
<code class="option">main</code>. Defaults to 0,
|
||
which disables this
|
||
feature.</p></dd><dt id="Restart="><span class="term"><code class="varname">Restart=</code></span><a class="headerlink" title="Permalink to this term" href="#Restart=">¶</a></dt><dd><p>Configures whether the
|
||
service shall be restarted when the
|
||
service process exits, is killed,
|
||
or a timeout is reached. The service
|
||
process may be the main service
|
||
process, but it may also be one of the
|
||
processes specified with
|
||
<code class="varname">ExecStartPre=</code>,
|
||
<code class="varname">ExecStartPost=</code>,
|
||
<code class="varname">ExecStop=</code>,
|
||
<code class="varname">ExecStopPost=</code>, or
|
||
<code class="varname">ExecReload=</code>.
|
||
When the death of the process is a
|
||
result of systemd operation (e.g. service
|
||
stop or restart), the service will not be
|
||
restarted. Timeouts include missing
|
||
the watchdog "keep-alive ping"
|
||
deadline and a service start, reload,
|
||
and stop operation timeouts.</p><p>Takes one of
|
||
<code class="option">no</code>,
|
||
<code class="option">on-success</code>,
|
||
<code class="option">on-failure</code>,
|
||
<code class="option">on-abnormal</code>,
|
||
<code class="option">on-watchdog</code>,
|
||
<code class="option">on-abort</code>, or
|
||
<code class="option">always</code>. If set to
|
||
<code class="option">no</code> (the default), the
|
||
service will not be restarted. If set
|
||
to <code class="option">on-success</code>, it
|
||
will be restarted only when the
|
||
service process exits cleanly. In
|
||
this context, a clean exit means an
|
||
exit code of 0, or one of the signals
|
||
<code class="constant">SIGHUP</code>,
|
||
<code class="constant">SIGINT</code>,
|
||
<code class="constant">SIGTERM</code> or
|
||
<code class="constant">SIGPIPE</code>, and
|
||
additionally, exit statuses and
|
||
signals specified in
|
||
<code class="varname">SuccessExitStatus=</code>.
|
||
If set to <code class="option">on-failure</code>,
|
||
the service will be restarted when the
|
||
process exits with a non-zero exit
|
||
code, is terminated by a signal
|
||
(including on core dump, but excluding
|
||
the aforementiond four signals), when
|
||
an operation (such as service reload)
|
||
times out, and when the configured
|
||
watchdog timeout is triggered. If set
|
||
to <code class="option">on-abnormal</code>, the
|
||
service will be restarted when the
|
||
process is terminated by a signal
|
||
(including on core dump, excluding the
|
||
aforementioned four signals), when an
|
||
operation times out, or when the
|
||
watchdog timeout is triggered. If set
|
||
to <code class="option">on-abort</code>, the
|
||
service will be restarted only if the
|
||
service process exits due to an
|
||
uncaught signal not specified as a
|
||
clean exit status. If set to
|
||
<code class="option">on-watchdog</code>, the
|
||
service will be restarted only if the
|
||
watchdog timeout for the service
|
||
expires. If set to
|
||
<code class="option">always</code>, the service
|
||
will be restarted regardless of
|
||
whether it exited cleanly or not, got
|
||
terminated abnormally by a signal, or
|
||
hit a timeout.</p><div class="table"><a name="idm214183204432"></a><p class="title"><b>Table 1. Exit causes and the effect of the <code class="varname">Restart=</code> settings on them</b></p><div class="table-contents"><table summary="Exit causes and the effect of the Restart= settings on them" border="1"><colgroup><col class="path"><col class="expl"></colgroup><thead><tr><th>Restart settings/Exit causes</th><th><code class="option">no</code></th><th><code class="option">always</code></th><th><code class="option">on-success</code></th><th><code class="option">on-failure</code></th><th><code class="option">on-abnormal</code></th><th><code class="option">on-abort</code></th><th><code class="option">on-watchdog</code></th></tr></thead><tbody><tr><td>Clean exit code or signal</td><td> </td><td>X</td><td>X</td><td> </td><td> </td><td> </td><td> </td></tr><tr><td>Unclean exit code</td><td> </td><td>X</td><td> </td><td>X</td><td> </td><td> </td><td> </td></tr><tr><td>Unclean signal</td><td> </td><td>X</td><td> </td><td>X</td><td>X</td><td>X</td><td> </td></tr><tr><td>Timeout</td><td> </td><td>X</td><td> </td><td>X</td><td>X</td><td> </td><td> </td></tr><tr><td>Watchdog</td><td> </td><td>X</td><td> </td><td>X</td><td>X</td><td> </td><td>X</td></tr></tbody></table></div></div><br class="table-break"><p>In addition to the above settings,
|
||
the service will not be restarted if the
|
||
exit code or signal is specified in
|
||
<code class="varname">RestartPreventExitStatus=</code>
|
||
(see below).</p><p>Setting this to
|
||
<code class="option">on-failure</code> is the
|
||
recommended choice for long-running
|
||
services, in order to increase
|
||
reliability by attempting automatic
|
||
recovery from errors. For services
|
||
that shall be able to terminate on
|
||
their own choice (and avoiding
|
||
immediate restart)
|
||
<code class="option">on-abnormal</code> is an
|
||
alternative choice.</p></dd><dt id="SuccessExitStatus="><span class="term"><code class="varname">SuccessExitStatus=</code></span><a class="headerlink" title="Permalink to this term" href="#SuccessExitStatus=">¶</a></dt><dd><p>Takes a list of exit
|
||
status definitions that when returned
|
||
by the main service process will be
|
||
considered successful termination, in
|
||
addition to the normal successful exit
|
||
code 0 and the signals <code class="constant">SIGHUP</code>, <code class="constant">SIGINT</code>,
|
||
<code class="constant">SIGTERM</code>, and <code class="constant">SIGPIPE</code>. Exit status
|
||
definitions can either be numeric exit
|
||
codes or termination signal names,
|
||
separated by spaces. For example:
|
||
</p><pre class="programlisting">SuccessExitStatus=1 2 8 <code class="constant">SIGKILL</code></pre><p>
|
||
ensures that exit codes 1, 2, 8 and
|
||
the termination signal
|
||
<code class="constant">SIGKILL</code> are
|
||
considered clean service terminations.
|
||
</p><p>Note that if a process has a
|
||
signal handler installed and exits by
|
||
calling
|
||
<a href="_exit.html"><span class="citerefentry"><span class="refentrytitle">_exit</span>(2)</span></a>
|
||
in response to a signal, the
|
||
information about the signal is lost.
|
||
Programs should instead perform cleanup and kill themselves with the same signal instead. See
|
||
<a class="ulink" href="http://www.cons.org/cracauer/sigint.html" target="_top">Proper handling of SIGINT/SIGQUIT — How to be a proper program</a>.</p><p>This option may appear more than once,
|
||
in which case the list of successful
|
||
exit statuses is merged. If the empty
|
||
string is assigned to this option, the
|
||
list is reset, all prior assignments
|
||
of this option will have no
|
||
effect.</p></dd><dt id="RestartPreventExitStatus="><span class="term"><code class="varname">RestartPreventExitStatus=</code></span><a class="headerlink" title="Permalink to this term" href="#RestartPreventExitStatus=">¶</a></dt><dd><p>Takes a list of exit
|
||
status definitions that when returned
|
||
by the main service process will
|
||
prevent automatic service restarts,
|
||
regardless of the restart setting
|
||
configured with
|
||
<code class="varname">Restart=</code>. Exit
|
||
status definitions can either be
|
||
numeric exit codes or termination
|
||
signal names, and are separated by
|
||
spaces. Defaults to the empty list, so
|
||
that, by default, no exit status is
|
||
excluded from the configured restart
|
||
logic. Example:
|
||
"<code class="literal">RestartPreventExitStatus=1 6
|
||
SIGABRT</code>", ensures that exit
|
||
codes 1 and 6 and the termination
|
||
signal <code class="constant">SIGABRT</code> will
|
||
not result in automatic service
|
||
restarting. This
|
||
option may appear more than once, in
|
||
which case the list of restart-preventing
|
||
statuses is merged. If the empty
|
||
string is assigned to this option, the
|
||
list is reset and all prior assignments
|
||
of this option will have no
|
||
effect.</p></dd><dt id="PermissionsStartOnly="><span class="term"><code class="varname">PermissionsStartOnly=</code></span><a class="headerlink" title="Permalink to this term" href="#PermissionsStartOnly=">¶</a></dt><dd><p>Takes a boolean
|
||
argument. If true, the permission-related
|
||
execution options, as
|
||
configured with
|
||
<code class="varname">User=</code> and similar
|
||
options (see
|
||
<a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>
|
||
for more information), are only applied
|
||
to the process started with
|
||
<code class="varname">ExecStart=</code>, and not
|
||
to the various other
|
||
<code class="varname">ExecStartPre=</code>,
|
||
<code class="varname">ExecStartPost=</code>,
|
||
<code class="varname">ExecReload=</code>,
|
||
<code class="varname">ExecStop=</code>, and
|
||
<code class="varname">ExecStopPost=</code>
|
||
commands. If false, the setting is
|
||
applied to all configured commands the
|
||
same way. Defaults to
|
||
false.</p></dd><dt id="RootDirectoryStartOnly="><span class="term"><code class="varname">RootDirectoryStartOnly=</code></span><a class="headerlink" title="Permalink to this term" href="#RootDirectoryStartOnly=">¶</a></dt><dd><p>Takes a boolean
|
||
argument. If true, the root directory,
|
||
as configured with the
|
||
<code class="varname">RootDirectory=</code>
|
||
option (see
|
||
<a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>
|
||
for more information), is only applied
|
||
to the process started with
|
||
<code class="varname">ExecStart=</code>, and not
|
||
to the various other
|
||
<code class="varname">ExecStartPre=</code>,
|
||
<code class="varname">ExecStartPost=</code>,
|
||
<code class="varname">ExecReload=</code>,
|
||
<code class="varname">ExecStop=</code>, and
|
||
<code class="varname">ExecStopPost=</code>
|
||
commands. If false, the setting is
|
||
applied to all configured commands the
|
||
same way. Defaults to
|
||
false.</p></dd><dt id="NonBlocking="><span class="term"><code class="varname">NonBlocking=</code></span><a class="headerlink" title="Permalink to this term" href="#NonBlocking=">¶</a></dt><dd><p>Set the
|
||
<code class="constant">O_NONBLOCK</code> flag
|
||
for all file descriptors passed via
|
||
socket-based activation. If true, all
|
||
file descriptors >= 3 (i.e. all except
|
||
stdin, stdout, and stderr) will have
|
||
the <code class="constant">O_NONBLOCK</code> flag
|
||
set and hence are in
|
||
non-blocking mode. This option is only
|
||
useful in conjunction with a socket
|
||
unit, as described in
|
||
<a href="systemd.socket.html"><span class="citerefentry"><span class="refentrytitle">systemd.socket</span>(5)</span></a>. Defaults
|
||
to false.</p></dd><dt id="NotifyAccess="><span class="term"><code class="varname">NotifyAccess=</code></span><a class="headerlink" title="Permalink to this term" href="#NotifyAccess=">¶</a></dt><dd><p>Controls access to the
|
||
service status notification socket, as
|
||
accessible via the
|
||
<a href="sd_notify.html"><span class="citerefentry"><span class="refentrytitle">sd_notify</span>(3)</span></a>
|
||
call. Takes one of
|
||
<code class="option">none</code> (the default),
|
||
<code class="option">main</code> or
|
||
<code class="option">all</code>. If
|
||
<code class="option">none</code>, no daemon status
|
||
updates are accepted from the service
|
||
processes, all status update messages
|
||
are ignored. If <code class="option">main</code>,
|
||
only service updates sent from the
|
||
main process of the service are
|
||
accepted. If <code class="option">all</code>, all
|
||
services updates from all members of
|
||
the service's control group are
|
||
accepted. This option should be set to
|
||
open access to the notification socket
|
||
when using
|
||
<code class="varname">Type=notify</code> or
|
||
<code class="varname">WatchdogSec=</code> (see
|
||
above). If those options are used but
|
||
<code class="varname">NotifyAccess=</code> is not
|
||
configured, it will be implicitly set
|
||
to
|
||
<code class="option">main</code>.</p></dd><dt id="Sockets="><span class="term"><code class="varname">Sockets=</code></span><a class="headerlink" title="Permalink to this term" href="#Sockets=">¶</a></dt><dd><p>Specifies the name of
|
||
the socket units this service shall
|
||
inherit the sockets from when the
|
||
service is started. Normally it
|
||
should not be necessary to use this
|
||
setting as all sockets whose unit
|
||
shares the same name as the service
|
||
(ignoring the different suffix of course)
|
||
are passed to the spawned
|
||
process.</p><p>Note that the same socket may be
|
||
passed to multiple processes at the
|
||
same time. Also note that a different
|
||
service may be activated on incoming
|
||
traffic than that which inherits the
|
||
sockets. Or in other words: the
|
||
<code class="varname">Service=</code> setting of
|
||
<code class="filename">.socket</code> units
|
||
does not have to match the inverse of
|
||
the <code class="varname">Sockets=</code>
|
||
setting of the
|
||
<code class="filename">.service</code> it
|
||
refers to.</p><p>This option may appear more than
|
||
once, in which case the list of socket
|
||
units is merged. If the empty string
|
||
is assigned to this option, the list of
|
||
sockets is reset, and all prior uses of
|
||
this setting will have no
|
||
effect.</p></dd><dt id="StartLimitInterval="><span class="term"><code class="varname">StartLimitInterval=</code>, </span><span class="term"><code class="varname">StartLimitBurst=</code></span><a class="headerlink" title="Permalink to this term" href="#StartLimitInterval=">¶</a></dt><dd><p>Configure service
|
||
start rate limiting. By default,
|
||
services which are started more
|
||
than 5 times within 10 seconds are not
|
||
permitted to start any more times
|
||
until the 10 second interval ends. With
|
||
these two options, this rate limiting
|
||
may be modified. Use
|
||
<code class="varname">StartLimitInterval=</code>
|
||
to configure the checking interval (defaults to
|
||
<code class="varname">DefaultStartLimitInterval=</code> in
|
||
manager configuration file, set to 0 to disable
|
||
any kind of rate limiting). Use
|
||
<code class="varname">StartLimitBurst=</code> to
|
||
configure how many starts per interval
|
||
are allowed (defaults to
|
||
<code class="varname">DefaultStartLimitBurst=</code> in
|
||
manager configuration file). These
|
||
configuration options are particularly
|
||
useful in conjunction with
|
||
<code class="varname">Restart=</code>; however,
|
||
they apply to all kinds of starts
|
||
(including manual), not just those
|
||
triggered by the
|
||
<code class="varname">Restart=</code> logic.
|
||
Note that units which are configured
|
||
for <code class="varname">Restart=</code> and
|
||
which reach the start limit are not
|
||
attempted to be restarted anymore;
|
||
however, they may still be restarted
|
||
manually at a later point, from which
|
||
point on, the restart logic is again
|
||
activated. Note that
|
||
<span class="command"><strong>systemctl
|
||
reset-failed</strong></span> will cause the
|
||
restart rate counter for a service to
|
||
be flushed, which is useful if the
|
||
administrator wants to manually start
|
||
a service and the start limit
|
||
interferes with
|
||
that.</p></dd><dt id="StartLimitAction="><span class="term"><code class="varname">StartLimitAction=</code></span><a class="headerlink" title="Permalink to this term" href="#StartLimitAction=">¶</a></dt><dd><p>Configure the action
|
||
to take if the rate limit configured
|
||
with
|
||
<code class="varname">StartLimitInterval=</code>
|
||
and
|
||
<code class="varname">StartLimitBurst=</code> is
|
||
hit. Takes one of
|
||
<code class="option">none</code>,
|
||
<code class="option">reboot</code>,
|
||
<code class="option">reboot-force</code>, or
|
||
<code class="option">reboot-immediate</code>. If
|
||
<code class="option">none</code> is set,
|
||
hitting the rate limit will trigger no
|
||
action besides that the start will not
|
||
be permitted. <code class="option">reboot</code>
|
||
causes a reboot following the normal
|
||
shutdown procedure (i.e. equivalent to
|
||
<span class="command"><strong>systemctl reboot</strong></span>).
|
||
<code class="option">reboot-force</code> causes
|
||
a forced reboot which will terminate
|
||
all processes forcibly but should
|
||
cause no dirty file systems on reboot
|
||
(i.e. equivalent to <span class="command"><strong>systemctl
|
||
reboot -f</strong></span>) and
|
||
<code class="option">reboot-immediate</code>
|
||
causes immediate execution of the
|
||
<a href="reboot.html"><span class="citerefentry"><span class="refentrytitle">reboot</span>(2)</span></a>
|
||
system call, which might result in
|
||
data loss. Defaults to
|
||
<code class="option">none</code>.</p></dd><dt id="RebootArgument="><span class="term"><code class="varname">RebootArgument=</code></span><a class="headerlink" title="Permalink to this term" href="#RebootArgument=">¶</a></dt><dd><p>Configure the optional
|
||
argument for the
|
||
<a href="reboot.html"><span class="citerefentry"><span class="refentrytitle">reboot</span>(2)</span></a>
|
||
system call if
|
||
<code class="varname">StartLimitAction=</code>
|
||
is a reboot action. This works just
|
||
like the optional argument to
|
||
<span class="command"><strong>systemctl reboot</strong></span>
|
||
command.</p></dd><dt id="FailureAction="><span class="term"><code class="varname">FailureAction=</code></span><a class="headerlink" title="Permalink to this term" href="#FailureAction=">¶</a></dt><dd><p>Configure the action
|
||
to take when the service enters a failed
|
||
state. Takes the same values as
|
||
<code class="varname">StartLimitAction=</code>
|
||
and executes the same actions.
|
||
Defaults to <code class="option">none</code>.
|
||
</p></dd></dl></div><p>Check
|
||
<a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>
|
||
and
|
||
<a href="systemd.kill.html"><span class="citerefentry"><span class="refentrytitle">systemd.kill</span>(5)</span></a>
|
||
for more settings.</p></div><div class="refsect1"><a name="idm214183108928"></a><h2 id="Compatibility Options">Compatibility Options<a class="headerlink" title="Permalink to this headline" href="#Compatibility%20Options">¶</a></h2><p>The following options are also available in the
|
||
"<code class="literal">[Service]</code>" section, but exist purely
|
||
for compatibility reasons and should not be used in
|
||
newly written service files.</p><div class="variablelist"><dl class="variablelist"><dt id="SysVStartPriority="><span class="term"><code class="varname">SysVStartPriority=</code></span><a class="headerlink" title="Permalink to this term" href="#SysVStartPriority=">¶</a></dt><dd><p>Set the SysV start
|
||
priority to use to order this service
|
||
in relation to SysV services lacking
|
||
LSB headers. This option is only
|
||
necessary to fix ordering in relation
|
||
to legacy SysV services that have no
|
||
ordering information encoded in the
|
||
script headers. As such, it should only
|
||
be used as a temporary compatibility
|
||
option and should not be used in new unit
|
||
files. Almost always, it is a better
|
||
choice to add explicit ordering
|
||
directives via
|
||
<code class="varname">After=</code> or
|
||
<code class="varname">Before=</code>,
|
||
instead. For more details, see
|
||
<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>.
|
||
If used, pass an integer value in the
|
||
range 0-99.</p></dd></dl></div></div><div class="refsect1"><a name="idm214183102224"></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>(8)</span></a>,
|
||
<a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>,
|
||
<a href="systemd.exec.html"><span class="citerefentry"><span class="refentrytitle">systemd.exec</span>(5)</span></a>,
|
||
<a href="systemd.resource-control.html"><span class="citerefentry"><span class="refentrytitle">systemd.resource-control</span>(5)</span></a>,
|
||
<a href="systemd.kill.html"><span class="citerefentry"><span class="refentrytitle">systemd.kill</span>(5)</span></a>,
|
||
<a href="systemd.directives.html"><span class="citerefentry"><span class="refentrytitle">systemd.directives</span>(7)</span></a>
|
||
</p></div></div></body></html>
|