mirror of
https://git.proxmox.com/git/systemd
synced 2025-06-05 05:39:28 +00:00
790 lines
64 KiB
HTML
790 lines
64 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 219</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="idm140251584833616"></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="idm140251588714624"></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 if
|
||
neither <code class="varname">Type=</code> nor
|
||
<code class="varname">BusName=</code>, but <code class="varname">ExecStart=</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. This is the implied default if neither
|
||
<code class="varname">Type=</code> or <code class="varname">ExecStart=</code> are
|
||
specified.</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>.</p></dd><dt id="BusPolicy="><span class="term"><code class="varname">BusPolicy=</code></span><a class="headerlink" title="Permalink to this term" href="#BusPolicy=">¶</a></dt><dd><p>If specified, a custom
|
||
<a class="ulink" href="https://code.google.com/p/d-bus/" target="_top">kdbus</a>
|
||
endpoint will be created and installed as the default bus node
|
||
for the service. Such a custom endpoint can hold an own set of
|
||
policy rules that are enforced on top of the bus-wide ones.
|
||
The custom endpoint is named after the service it was created
|
||
for, and its node will be bind-mounted over the default bus
|
||
node location, so the service can only access the bus through
|
||
its own endpoint. Note that custom bus endpoints default to a
|
||
'deny all' policy. Hence, if at least one
|
||
<code class="varname">BusPolicy=</code> directive is given, you have to
|
||
make sure to add explicit rules for everything the service
|
||
should be able to do.</p><p>The value of this directive is comprised
|
||
of two parts; the bus name, and a verb to
|
||
specify to granted access, which is one of
|
||
<code class="option">see</code>,
|
||
<code class="option">talk</code>, or
|
||
<code class="option">own</code>.
|
||
<code class="option">talk</code> implies
|
||
<code class="option">see</code>, and <code class="option">own</code>
|
||
implies both <code class="option">talk</code> and
|
||
<code class="option">see</code>.
|
||
If multiple access levels are specified for the
|
||
same bus name, the most powerful one takes
|
||
effect.
|
||
</p><p>Examples:</p><pre class="programlisting">BusPolicy=org.freedesktop.systemd1 talk</pre><pre class="programlisting">BusPolicy=org.foo.bar see</pre><p>This option is only available on kdbus enabled systems.</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. The value is split into
|
||
zero or more command lines is according to the rules described
|
||
below (see section "Command Lines" below).
|
||
</p><p>When <code class="varname">Type</code> is not
|
||
<code class="option">oneshot</code>, only one command may and must be
|
||
given. When <code class="varname">Type=oneshot</code> is used, zero or
|
||
more commands may be specified. This can be specified by
|
||
providing multiple command lines in the same directive, or
|
||
alternatively, this directive may be specified more than once
|
||
with the same effect. 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. If no
|
||
<code class="varname">ExecStart=</code> is specified, then the service
|
||
must have <code class="varname">RemainAfterExit=yes</code> set.</p><p>For each of the specified commands, the first argument
|
||
must be an absolute path to an executable. Optionally, if this
|
||
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>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></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">DefaultTimeoutStartSec=</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 (see
|
||
<a href="systemd-system.conf.html"><span class="citerefentry"><span class="refentrytitle">systemd-system.conf</span>(5)</span></a>).
|
||
</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">DefaultTimeoutStopSec=</code> from the manager
|
||
configuration file (see
|
||
<a href="systemd-system.conf.html"><span class="citerefentry"><span class="refentrytitle">systemd-system.conf</span>(5)</span></a>).
|
||
</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 and it will be terminated with
|
||
<code class="varname">SIGABRT</code>. 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="idm140251583688528"></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>As exceptions to the setting above the service will not
|
||
be restarted if the exit code or signal is specified in
|
||
<code class="varname">RestartPreventExitStatus=</code> (see below).
|
||
Also, the services will always be restarted if the exit code
|
||
or signal is specified in
|
||
<code class="varname">RestartForceExitStatus=</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 avoid immediate restarting),
|
||
<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
|
||
SIGKILL</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="http://man7.org/linux/man-pages/man2/_exit.2.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. For example:
|
||
</p><pre class="programlisting">RestartPreventExitStatus=1 6
|
||
SIGABRT</pre><p> 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="RestartForceExitStatus="><span class="term"><code class="varname">RestartForceExitStatus=</code></span><a class="headerlink" title="Permalink to this term" href="#RestartForceExitStatus=">¶</a></dt><dd><p>Takes a list of exit status definitions that
|
||
when returned by the main service process will force automatic
|
||
service restarts, regardless of the restart setting configured
|
||
with <code class="varname">Restart=</code>. The argument format is
|
||
similar to
|
||
<code class="varname">RestartPreventExitStatus=</code>.</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 socket file descriptors from when the
|
||
service is started. Normally it should not be necessary to use
|
||
this setting as all socket file descriptors whose unit shares
|
||
the same name as the service (subject to the different unit
|
||
name suffix of course) are passed to the spawned
|
||
process.</p><p>Note that the same socket file descriptors may be passed
|
||
to multiple processes simultaneously. Also note that a
|
||
different service may be activated on incoming socket traffic
|
||
than the one which is ultimately configured to inherit the
|
||
socket file descriptors. 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>,
|
||
<code class="option">reboot-immediate</code>,
|
||
<code class="option">poweroff</code>,
|
||
<code class="option">poweroff-force</code> or
|
||
<code class="option">poweroff-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="http://man7.org/linux/man-pages/man2/reboot.2.html"><span class="citerefentry"><span class="refentrytitle">reboot</span>(2)</span></a>
|
||
system call, which might result in data loss. Similar,
|
||
<code class="option">poweroff</code>, <code class="option">poweroff-force</code>,
|
||
<code class="option">poweroff-immediate</code> have the effect of
|
||
powering down the system with similar semantics. Defaults to
|
||
<code class="option">none</code>.</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><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="http://man7.org/linux/man-pages/man2/reboot.2.html"><span class="citerefentry"><span class="refentrytitle">reboot</span>(2)</span></a>
|
||
system call if <code class="varname">StartLimitAction=</code> or
|
||
<code class="varname">FailureAction=</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="FileDescriptorStoreMax="><span class="term"><code class="varname">FileDescriptorStoreMax=</code></span><a class="headerlink" title="Permalink to this term" href="#FileDescriptorStoreMax=">¶</a></dt><dd><p>Configure how many file descriptors may be
|
||
stored in the service manager for the service using
|
||
<a href="sd_pid_notify_with_fds.html"><span class="citerefentry"><span class="refentrytitle">sd_pid_notify_with_fds</span>(3)</span></a>'s
|
||
"<code class="literal">FDSTORE=1</code>" messages. This is useful for
|
||
implementing service restart schemes where the state is
|
||
serialized to <code class="filename">/run</code> and the file
|
||
descriptors passed to the service manager, to allow restarts
|
||
without losing state. Defaults to 0, i.e. no file descriptors
|
||
may be stored in the service manager by default. All file
|
||
descriptors passed to the service manager from a specific
|
||
service are passed back to the service's main process on the
|
||
next service restart. Any file descriptors passed to the
|
||
service manager are automatically closed when POLLHUP or
|
||
POLLERR is seen on them, or when the service is fully stopped
|
||
and no job queued or being executed for it.</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="idm140251583593072"></a><h2 id="Command lines">Command lines<a class="headerlink" title="Permalink to this headline" href="#Command%20lines">¶</a></h2><p>This section describes command line parsing and
|
||
variable and specifier substitions for
|
||
<code class="varname">ExecStart=</code>,
|
||
<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> options.</p><p>Multiple command lines may be concatenated in a single
|
||
directive by separating them with semicolons (these semicolons
|
||
must be passed as separate words). Lone semicolons may be escaped
|
||
as "<code class="literal">\;</code>".</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. C-style escapes are also
|
||
supported, see table below. Quotes themselves are removed after
|
||
parsing and escape sequences substituted. In addition, a trailing
|
||
backslash ("<code class="literal">\</code>") may be used to merge lines.
|
||
</p><p>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>", 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>The command to execute must an absolute path name. It may
|
||
contain spaces, but control characters are not allowed.</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.
|
||
For this type of expansion, quotes and respected when splitting
|
||
into words, and afterwards removed.</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><p>Example:</p><pre class="programlisting">Environment=ONE='one' "TWO='two two' too" THREE=
|
||
ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
|
||
ExecStart=/bin/echo $ONE $TWO $THREE</pre><p>This results in <code class="filename">echo</code> being
|
||
called twice, the first time with arguments
|
||
"<code class="literal">'one'</code>",
|
||
"<code class="literal">'two two' too</code>", "<code class="literal"></code>",
|
||
and the second time with arguments
|
||
"<code class="literal">one</code>", "<code class="literal">two two</code>",
|
||
"<code class="literal">too</code>".
|
||
</p><p>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>Note that shell command lines are not directly supported. 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><div class="table"><a name="idm140251583543648"></a><p class="title"><b>Table 2. C escapes supported in command lines and environment variables</b></p><div class="table-contents"><table summary="C escapes supported in command lines and environment variables" border="1"><colgroup><col class="escape"><col class="meaning"></colgroup><thead><tr><th>Literal</th><th>Actual value</th></tr></thead><tbody><tr><td>"<code class="literal">\a</code>"</td><td>bell</td></tr><tr><td>"<code class="literal">\b</code>"</td><td>backspace</td></tr><tr><td>"<code class="literal">\f</code>"</td><td>form feed</td></tr><tr><td>"<code class="literal">\n</code>"</td><td>newline</td></tr><tr><td>"<code class="literal">\r</code>"</td><td>carriage return</td></tr><tr><td>"<code class="literal">\t</code>"</td><td>tab</td></tr><tr><td>"<code class="literal">\v</code>"</td><td>vertical tab</td></tr><tr><td>"<code class="literal">\\</code>"</td><td>backslash</td></tr><tr><td>"<code class="literal">\"</code>"</td><td>double quotation mark</td></tr><tr><td>"<code class="literal">\'</code>"</td><td>single quotation mark</td></tr><tr><td>"<code class="literal">\s</code>"</td><td>space</td></tr><tr><td>"<code class="literal">\x<em class="replaceable"><code>xx</code></em></code>"</td><td>character number <em class="replaceable"><code>xx</code></em> in hexadecimal encoding</td></tr><tr><td>"<code class="literal">\<em class="replaceable"><code>nnn</code></em></code>"</td><td>character number <em class="replaceable"><code>nnn</code></em> in octal encoding</td></tr></tbody></table></div></div><br class="table-break"></div><div class="refsect1"><a name="idm140251583518096"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm140251583517456"></a><p class="title"><b>Example 1. Simple service</b></p><div class="example-contents"><p>The following unit file creates a service that will
|
||
execute <code class="filename">/usr/sbin/foo-daemon</code>. Since no
|
||
<code class="varname">Type=</code> is specified, the default
|
||
<code class="varname">Type=</code><code class="option">simple</code> will be assumed.
|
||
systemd will assume the unit to be started immediately after the
|
||
program has begun executing.</p><pre class="programlisting">[Unit]
|
||
Description=Foo
|
||
|
||
[Service]
|
||
ExecStart=/usr/sbin/foo-daemon
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target</pre><p>Note that systemd assumes here that the process started by
|
||
systemd will continue running until the service terminates. If
|
||
the program daemonizes itself (i.e. forks), please use
|
||
<code class="varname">Type=</code><code class="option">forking</code> instead.</p><p>Since no <code class="varname">ExecStop=</code> was specified,
|
||
systemd will send SIGTERM to all processes started from this
|
||
service, and after a timeout also SIGKILL. This behavior can be
|
||
modified, see
|
||
<a href="systemd.kill.html"><span class="citerefentry"><span class="refentrytitle">systemd.kill</span>(5)</span></a>
|
||
for details.</p><p>Note that this unit type does not include any type of
|
||
notification when a service has completed initialization. For
|
||
this, you should use other unit types, such as
|
||
<code class="varname">Type=</code><code class="option">notify</code> if the service
|
||
understands systemd's notification protocol,
|
||
<code class="varname">Type=</code><code class="option">forking</code> if the service
|
||
can background itself or
|
||
<code class="varname">Type=</code><code class="option">dbus</code> if the unit
|
||
acquires a DBus name once initialization is complete. See
|
||
below.</p></div></div><br class="example-break"><div class="example"><a name="idm140251583508032"></a><p class="title"><b>Example 2. Oneshot service</b></p><div class="example-contents"><p>Sometimes units should just execute an action without
|
||
keeping active processes, such as a filesystem check or a
|
||
cleanup action on boot. For this,
|
||
<code class="varname">Type=</code><code class="option">oneshot</code> exists. Units
|
||
of this type will wait until the process specified terminates
|
||
and then fall back to being inactive. The following unit will
|
||
perform a clenaup action:</p><pre class="programlisting">[Unit]
|
||
Description=Cleanup old Foo data
|
||
|
||
[Service]
|
||
Type=oneshot
|
||
ExecStart=/usr/sbin/foo-cleanup
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target</pre><p>Note that systemd will consider the unit to be in the
|
||
state 'starting' until the program has terminated, so ordered
|
||
dependencies will wait for the program to finish before starting
|
||
themselves. The unit will revert to the 'inactive' state after
|
||
the execution is done, never reaching the 'active' state. That
|
||
means another request to start the unit will perform the action
|
||
again.</p><p><code class="varname">Type=</code><code class="option">oneshot</code> are the
|
||
only service units that may have more than one
|
||
<code class="varname">ExecStart=</code> specified. They will be executed
|
||
in order until either they are all successful or one of them
|
||
fails.</p></div></div><br class="example-break"><div class="example"><a name="idm140251583502800"></a><p class="title"><b>Example 3. Stoppable oneshot service</b></p><div class="example-contents"><p>Similarly to the oneshot services, there are sometimes
|
||
units that need to execute a program to set up something and
|
||
then execute another to shut it down, but no process remains
|
||
active while they are considered 'started'. Network
|
||
configuration can sometimes fall into this category. Another use
|
||
case is if a oneshot service shall not be executed a each time
|
||
when they are pulled in as a dependency, but only the first
|
||
time.</p><p>For this, systemd knows the setting
|
||
<code class="varname">RemainAfterExit=</code><code class="option">yes</code>, which
|
||
causes systemd to consider the unit to be active if the start
|
||
action exited successfully. This directive can be used with all
|
||
types, but is most useful with
|
||
<code class="varname">Type=</code><code class="option">oneshot</code> and
|
||
<code class="varname">Type=</code><code class="option">simple</code>. With
|
||
<code class="varname">Type=</code><code class="option">oneshot</code> systemd waits
|
||
until the start action has completed before it considers the
|
||
unit to be active, so dependencies start only after the start
|
||
action has succeeded. With
|
||
<code class="varname">Type=</code><code class="option">simple</code> dependencies
|
||
will start immediately after the start action has been
|
||
dispatched. The following unit provides an example for a simple
|
||
static firewall.</p><pre class="programlisting">[Unit]
|
||
Description=Simple firewall
|
||
|
||
[Service]
|
||
Type=oneshot
|
||
RemainAfterExit=yes
|
||
ExecStart=/usr/local/sbin/simple-firewall-start
|
||
ExecStop=/usr/local/sbin/simple-firewall-stop
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target</pre><p>Since the unit is considered to be running after the start
|
||
action has exited, invoking <span class="command"><strong>systemctl start</strong></span>
|
||
on that unit again will cause no action to be taken.</p></div></div><br class="example-break"><div class="example"><a name="idm140251583494944"></a><p class="title"><b>Example 4. Traditional forking services</b></p><div class="example-contents"><p>Many traditional daemons/services background (i.e. fork,
|
||
daemonize) themselves when starting. Set
|
||
<code class="varname">Type=</code><code class="option">forking</code> in the
|
||
service's unit file to support this mode of operation. systemd
|
||
will consider the service to be in the process of initialization
|
||
while the original program is still running. Once it exits
|
||
successfully and at least a process remains (and
|
||
<code class="varname">RemainAfterExit=</code><code class="option">no</code>), the
|
||
service is considered started.</p><p>Often a traditional daemon only consists of one process.
|
||
Therefore, if only one process is left after the original
|
||
process terminates, systemd will consider that process the main
|
||
process of the service. In that case, the
|
||
<code class="varname">$MAINPID</code> variable will be available in
|
||
<code class="varname">ExecReload=</code>, <code class="varname">ExecStop=</code>,
|
||
etc.</p><p>In case more than one process remains, systemd will be
|
||
unable to determine the main process, so it will not assume
|
||
there is one. In that case, <code class="varname">$MAINPID</code> will not
|
||
expand to anything. However, if the process decides to write a
|
||
traditional PID file, systemd will be able to read the main PID
|
||
from there. Please set <code class="varname">PIDFile=</code> accordingly.
|
||
Note that the daemon should write that file before finishing
|
||
with its initialization, otherwise systemd might try to read the
|
||
file before it exists.</p><p>The following example shows a simple daemon that forks and
|
||
just starts one process in the background:</p><pre class="programlisting">[Unit]
|
||
Description=Some simple daemon
|
||
|
||
[Service]
|
||
Type=forking
|
||
ExecStart=/usr/sbin/my-simple-daemon -d
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target</pre><p>Please see
|
||
<a href="systemd.kill.html"><span class="citerefentry"><span class="refentrytitle">systemd.kill</span>(5)</span></a>
|
||
for details on how you can influence the way systemd terminates
|
||
the service.</p></div></div><br class="example-break"><div class="example"><a name="idm140251583486032"></a><p class="title"><b>Example 5. DBus services</b></p><div class="example-contents"><p>For services that acquire a name on the DBus system bus,
|
||
use <code class="varname">Type=</code><code class="option">dbus</code> and set
|
||
<code class="varname">BusName=</code> accordingly. The service should not
|
||
fork (daemonize). systemd will consider the service to be
|
||
initialized once the name has been acquired on the system bus.
|
||
The following example shows a typical DBus service:</p><pre class="programlisting">[Unit]
|
||
Description=Simple DBus service
|
||
|
||
[Service]
|
||
Type=dbus
|
||
BusName=org.example.simple-dbus-service
|
||
ExecStart=/usr/sbin/simple-dbus-service
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target</pre><p>For <span class="emphasis"><em>bus-activatable</em></span> services, don't
|
||
include a "<code class="literal">[Install]</code>" section in the systemd
|
||
service file, but use the <code class="varname">SystemdService=</code>
|
||
option in the corresponding DBus service file, for example
|
||
(<code class="filename">/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</code>):</p><pre class="programlisting">[D-BUS Service]
|
||
Name=org.example.simple-dbus-service
|
||
Exec=/usr/sbin/simple-dbus-service
|
||
User=root
|
||
SystemdService=simple-dbus-service.service</pre><p>Please see
|
||
<a href="systemd.kill.html"><span class="citerefentry"><span class="refentrytitle">systemd.kill</span>(5)</span></a>
|
||
for details on how you can influence the way systemd terminates
|
||
the service.</p></div></div><br class="example-break"><div class="example"><a name="idm140251583478000"></a><p class="title"><b>Example 6. Services that notify systemd about their initialization</b></p><div class="example-contents"><p><code class="varname">Type=</code><code class="option">simple</code> services
|
||
are really easy to write, but have the major disadvantage of
|
||
systemd not being able to tell when initialization of the given
|
||
service is complete. For this reason, systemd supports a simple
|
||
notification protocol that allows daemons to make systemd aware
|
||
that they are done initializing. Use
|
||
<code class="varname">Type=</code><code class="option">notify</code> for this. A
|
||
typical service file for such a daemon would look like
|
||
this:</p><pre class="programlisting">[Unit]
|
||
Description=Simple notifying service
|
||
|
||
[Service]
|
||
Type=notify
|
||
ExecStart=/usr/sbin/simple-notifying-service
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target</pre><p>Note that the daemon has to support systemd's notification
|
||
protocol, else systemd will think the service hasn't started yet
|
||
and kill it after a timeout. For an example of how to update
|
||
daemons to support this protocol transparently, take a look at
|
||
<a href="sd_notify.html"><span class="citerefentry"><span class="refentrytitle">sd_notify</span>(3)</span></a>.
|
||
systemd will consider the unit to be in the 'starting' state
|
||
until a readiness notification has arrived.</p><p>Please see
|
||
<a href="systemd.kill.html"><span class="citerefentry"><span class="refentrytitle">systemd.kill</span>(5)</span></a>
|
||
for details on how you can influence the way systemd terminates
|
||
the service.</p></div></div><br class="example-break"></div><div class="refsect1"><a name="idm140251583471504"></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.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>
|