mirror of
https://github.com/systemd/systemd.git
synced 2024-11-23 18:23:32 +08:00
d44efb621a
Add a couple of exampels, at least one for each service type that include some explanations and pointers to various relevant options.
1670 lines
94 KiB
XML
1670 lines
94 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
||
<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
|
||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||
|
||
<!--
|
||
This file is part of systemd.
|
||
|
||
Copyright 2010 Lennart Poettering
|
||
|
||
systemd is free software; you can redistribute it and/or modify it
|
||
under the terms of the GNU Lesser General Public License as published by
|
||
the Free Software Foundation; either version 2.1 of the License, or
|
||
(at your option) any later version.
|
||
|
||
systemd is distributed in the hope that it will be useful, but
|
||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
Lesser General Public License for more details.
|
||
|
||
You should have received a copy of the GNU Lesser General Public License
|
||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||
-->
|
||
|
||
<refentry id="systemd.service">
|
||
<refentryinfo>
|
||
<title>systemd.service</title>
|
||
<productname>systemd</productname>
|
||
|
||
<authorgroup>
|
||
<author>
|
||
<contrib>Developer</contrib>
|
||
<firstname>Lennart</firstname>
|
||
<surname>Poettering</surname>
|
||
<email>lennart@poettering.net</email>
|
||
</author>
|
||
</authorgroup>
|
||
</refentryinfo>
|
||
|
||
<refmeta>
|
||
<refentrytitle>systemd.service</refentrytitle>
|
||
<manvolnum>5</manvolnum>
|
||
</refmeta>
|
||
|
||
<refnamediv>
|
||
<refname>systemd.service</refname>
|
||
<refpurpose>Service unit configuration</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsynopsisdiv>
|
||
<para><filename><replaceable>service</replaceable>.service</filename></para>
|
||
</refsynopsisdiv>
|
||
|
||
<refsect1>
|
||
<title>Description</title>
|
||
|
||
<para>A unit configuration file whose name ends in
|
||
<filename>.service</filename> encodes information
|
||
about a process controlled and supervised by
|
||
systemd.</para>
|
||
|
||
<para>This man page lists the configuration options
|
||
specific to this unit type. See
|
||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||
for the common options of all unit configuration
|
||
files. The common configuration items are configured
|
||
in the generic <literal>[Unit]</literal> and
|
||
<literal>[Install]</literal> sections. The service
|
||
specific configuration options are configured in the
|
||
<literal>[Service]</literal> section.</para>
|
||
|
||
<para>Additional options are listed in
|
||
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||
which define the execution environment the commands
|
||
are executed in, and in
|
||
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||
which define the way the processes of the service are
|
||
terminated, and in
|
||
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||
which configure resource control settings for the
|
||
processes of the service.</para>
|
||
|
||
<para>Unless <varname>DefaultDependencies=</varname>
|
||
is set to <option>false</option>, service units will
|
||
implicitly have dependencies of type
|
||
<varname>Requires=</varname> and
|
||
<varname>After=</varname> on
|
||
<filename>basic.target</filename> as well as
|
||
dependencies of type <varname>Conflicts=</varname> and
|
||
<varname>Before=</varname> on
|
||
<filename>shutdown.target</filename>. 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.</para>
|
||
|
||
<para>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
|
||
<filename>.service</filename> 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 <ulink
|
||
url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
|
||
with SysV</ulink> document.
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Options</title>
|
||
|
||
<para>Service files must include a
|
||
<literal>[Service]</literal> 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
|
||
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||
and
|
||
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
|
||
options specific to the <literal>[Service]</literal>
|
||
section of service units are the following:</para>
|
||
|
||
<variablelist class='unit-directives'>
|
||
<varlistentry>
|
||
<term><varname>Type=</varname></term>
|
||
|
||
<listitem><para>Configures the process
|
||
start-up type for this service
|
||
unit. One of <option>simple</option>,
|
||
<option>forking</option>,
|
||
<option>oneshot</option>,
|
||
<option>dbus</option>,
|
||
<option>notify</option> or
|
||
<option>idle</option>.</para>
|
||
|
||
<para>If set to
|
||
<option>simple</option> (the default
|
||
if neither
|
||
<varname>Type=</varname> nor
|
||
<varname>BusName=</varname>, but
|
||
<varname>ExecStart=</varname> are
|
||
specified), it is expected that the
|
||
process configured with
|
||
<varname>ExecStart=</varname> 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.</para>
|
||
|
||
<para>If set to
|
||
<option>forking</option>, it is
|
||
expected that the process configured
|
||
with <varname>ExecStart=</varname>
|
||
will call <function>fork()</function>
|
||
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
|
||
<varname>PIDFile=</varname> 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.</para>
|
||
|
||
<para>Behavior of
|
||
<option>oneshot</option> is similar to
|
||
<option>simple</option>; however, it
|
||
is expected that the process has to
|
||
exit before systemd starts follow-up
|
||
units. <varname>RemainAfterExit=</varname>
|
||
is particularly useful for this type
|
||
of service. This is the implied
|
||
default if neither
|
||
<varname>Type=</varname> or
|
||
<varname>ExecStart=</varname> are
|
||
specified.</para>
|
||
|
||
<para>Behavior of
|
||
<option>dbus</option> is similar to
|
||
<option>simple</option>; however, it is
|
||
expected that the daemon acquires a
|
||
name on the D-Bus bus, as configured
|
||
by
|
||
<varname>BusName=</varname>. 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
|
||
<filename>dbus.socket</filename>
|
||
unit. This type is the default if
|
||
<varname>BusName=</varname> is
|
||
specified.</para>
|
||
|
||
<para>Behavior of
|
||
<option>notify</option> is similar to
|
||
<option>simple</option>; however, it is
|
||
expected that the daemon sends a
|
||
notification message via
|
||
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||
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,
|
||
<varname>NotifyAccess=</varname> (see
|
||
below) should be set to open access to
|
||
the notification socket provided by
|
||
systemd. If
|
||
<varname>NotifyAccess=</varname> is
|
||
not set, it will be implicitly set to
|
||
<option>main</option>. Note that
|
||
currently
|
||
<varname>Type=</varname><option>notify</option>
|
||
will not work if used in combination with
|
||
<varname>PrivateNetwork=</varname><option>yes</option>.</para>
|
||
|
||
<para>Behavior of
|
||
<option>idle</option> is very similar
|
||
to <option>simple</option>; 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.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>RemainAfterExit=</varname></term>
|
||
|
||
<listitem><para>Takes a boolean value
|
||
that specifies whether the service
|
||
shall be considered active even when
|
||
all its processes exited. Defaults to
|
||
<option>no</option>.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>GuessMainPID=</varname></term>
|
||
|
||
<listitem><para>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 <option>Type=forking</option>
|
||
is set and <option>PIDFile=</option>
|
||
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
|
||
<option>yes</option>.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>PIDFile=</varname></term>
|
||
|
||
<listitem><para>Takes an absolute file
|
||
name pointing to the PID file of this
|
||
daemon. Use of this option is
|
||
recommended for services where
|
||
<varname>Type=</varname> is set to
|
||
<option>forking</option>. 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.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>BusName=</varname></term>
|
||
|
||
<listitem><para>Takes a D-Bus bus
|
||
name that this service is reachable
|
||
as. This option is mandatory for
|
||
services where
|
||
<varname>Type=</varname> is set to
|
||
<option>dbus</option>.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>BusPolicy=</varname></term>
|
||
|
||
<listitem><para>If specified, a custom
|
||
<ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>
|
||
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
|
||
<varname>BusPolicy=</varname> directive is
|
||
given, you have to make sure to add explicit
|
||
rules for everything the service should be able
|
||
to do.</para>
|
||
<para>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
|
||
<option>see</option>,
|
||
<option>talk</option>, or
|
||
<option>own</option>.
|
||
<option>talk</option> implies
|
||
<option>see</option>, and <option>own</option>
|
||
implies both <option>talk</option> and
|
||
<option>see</option>.
|
||
If multiple access levels are specified for the
|
||
same bus name, the most powerful one takes
|
||
effect.
|
||
</para>
|
||
<para>Examples:</para>
|
||
<programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>
|
||
<programlisting>BusPolicy=org.foo.bar see</programlisting>
|
||
<para>This option is only available on kdbus enabled systems.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>ExecStart=</varname></term>
|
||
<listitem><para>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).
|
||
</para>
|
||
|
||
<para>When <varname>Type</varname> is
|
||
not <option>oneshot</option>, only one
|
||
command may and must be given. When
|
||
<varname>Type=oneshot</varname> 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
|
||
<varname>ExecStart=</varname> is
|
||
specified, then the service must have
|
||
<varname>RemainAfterExit=yes</varname>
|
||
set.</para>
|
||
|
||
<para>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 <literal>@</literal>,
|
||
the second token will be passed as
|
||
<literal>argv[0]</literal> to the
|
||
executed process, followed by the
|
||
further arguments specified. If the
|
||
absolute filename is prefixed with
|
||
<literal>-</literal>, 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 <literal>-</literal> and
|
||
<literal>@</literal> are used, they
|
||
can appear in either order.</para>
|
||
|
||
<para>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 <literal>-</literal>), other
|
||
lines are not executed, and the unit
|
||
is considered failed.</para>
|
||
|
||
<para>Unless
|
||
<varname>Type=forking</varname> is
|
||
set, the process started via this
|
||
command line will be considered the
|
||
main process of the daemon.</para>
|
||
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>ExecStartPre=</varname></term>
|
||
<term><varname>ExecStartPost=</varname></term>
|
||
<listitem><para>Additional commands
|
||
that are executed before or after
|
||
the command in
|
||
<varname>ExecStart=</varname>, respectively.
|
||
Syntax is the same as for
|
||
<varname>ExecStart=</varname>, except
|
||
that multiple command lines are allowed
|
||
and the commands are executed one
|
||
after the other, serially.</para>
|
||
|
||
<para>If any of those commands (not
|
||
prefixed with <literal>-</literal>)
|
||
fail, the rest are not executed and
|
||
the unit is considered failed.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>ExecReload=</varname></term>
|
||
<listitem><para>Commands to execute to
|
||
trigger a configuration reload in the
|
||
service. This argument takes multiple
|
||
command lines, following the same
|
||
scheme as described for
|
||
<varname>ExecStart=</varname>
|
||
above. Use of this setting is
|
||
optional. Specifier and environment
|
||
variable substitution is supported
|
||
here following the same scheme as for
|
||
<varname>ExecStart=</varname>.</para>
|
||
|
||
<para>One additional, special
|
||
environment variable is set: if known,
|
||
<varname>$MAINPID</varname> is set to
|
||
the main process of the daemon, and
|
||
may be used for command lines like the
|
||
following:</para>
|
||
|
||
<programlisting>/bin/kill -HUP $MAINPID</programlisting>
|
||
|
||
<para>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
|
||
<varname>ExecReload=</varname> to a
|
||
command that not only triggers a
|
||
configuration reload of the daemon,
|
||
but also synchronously waits for it to
|
||
complete.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>ExecStop=</varname></term>
|
||
<listitem><para>Commands to execute to
|
||
stop the service started via
|
||
<varname>ExecStart=</varname>. This
|
||
argument takes multiple command lines,
|
||
following the same scheme as described
|
||
for <varname>ExecStart=</varname>
|
||
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
|
||
<varname>KillMode=</varname> setting
|
||
(see
|
||
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
|
||
this option is not specified, the
|
||
process is terminated immediately when
|
||
service stop is requested. Specifier
|
||
and environment variable substitution
|
||
is supported (including
|
||
<varname>$MAINPID</varname>, see
|
||
above).</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>ExecStopPost=</varname></term>
|
||
<listitem><para>Additional commands
|
||
that are executed after the service
|
||
was stopped. This includes cases where
|
||
the commands configured in
|
||
<varname>ExecStop=</varname> were used,
|
||
where the service does not have any
|
||
<varname>ExecStop=</varname> defined, or
|
||
where the service exited unexpectedly. This
|
||
argument takes multiple command lines,
|
||
following the same scheme as described
|
||
for <varname>ExecStart</varname>. Use
|
||
of these settings is
|
||
optional. Specifier and environment
|
||
variable substitution is
|
||
supported.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>RestartSec=</varname></term>
|
||
<listitem><para>Configures the time to
|
||
sleep before restarting a service (as
|
||
configured with
|
||
<varname>Restart=</varname>). Takes a
|
||
unit-less value in seconds, or a time
|
||
span value such as "5min
|
||
20s". Defaults to
|
||
100ms.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>TimeoutStartSec=</varname></term>
|
||
<listitem><para>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 <literal>0</literal> to
|
||
disable the timeout logic. Defaults to
|
||
<varname>DefaultTimeoutStartSec=</varname> from
|
||
the manager configuration file, except
|
||
when <varname>Type=oneshot</varname> is
|
||
used, in which case the timeout
|
||
is disabled by default
|
||
(see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>TimeoutStopSec=</varname></term>
|
||
<listitem><para>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 <constant>SIGTERM</constant>,
|
||
and after another timeout of equal duration
|
||
with <constant>SIGKILL</constant> (see
|
||
<varname>KillMode=</varname>
|
||
in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
|
||
Takes a unit-less value in seconds, or a
|
||
time span value such as "5min
|
||
20s". Pass <literal>0</literal> to disable
|
||
the timeout logic. Defaults to
|
||
<varname>DefaultTimeoutStopSec=</varname> from the
|
||
manager configuration file
|
||
(see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>TimeoutSec=</varname></term>
|
||
<listitem><para>A shorthand for configuring
|
||
both <varname>TimeoutStartSec=</varname>
|
||
and <varname>TimeoutStopSec=</varname>
|
||
to the specified value.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>WatchdogSec=</varname></term>
|
||
<listitem><para>Configures the
|
||
watchdog timeout for a service. The
|
||
watchdog is activated when the start-up is
|
||
completed. The service must call
|
||
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||
regularly with <literal>WATCHDOG=1</literal>
|
||
(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 <varname>SIGABRT</varname>.
|
||
By setting <varname>Restart=</varname> to
|
||
<option>on-failure</option> or
|
||
<option>always</option>, the service
|
||
will be automatically restarted. The
|
||
time configured here will be passed to
|
||
the executed service process in the
|
||
<varname>WATCHDOG_USEC=</varname>
|
||
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,
|
||
<varname>NotifyAccess=</varname> (see
|
||
below) should be set to open access to
|
||
the notification socket provided by
|
||
systemd. If
|
||
<varname>NotifyAccess=</varname> is
|
||
not set, it will be implicitly set to
|
||
<option>main</option>. Defaults to 0,
|
||
which disables this
|
||
feature.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>Restart=</varname></term>
|
||
<listitem><para>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
|
||
<varname>ExecStartPre=</varname>,
|
||
<varname>ExecStartPost=</varname>,
|
||
<varname>ExecStop=</varname>,
|
||
<varname>ExecStopPost=</varname>, or
|
||
<varname>ExecReload=</varname>.
|
||
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.</para>
|
||
|
||
<para>Takes one of
|
||
<option>no</option>,
|
||
<option>on-success</option>,
|
||
<option>on-failure</option>,
|
||
<option>on-abnormal</option>,
|
||
<option>on-watchdog</option>,
|
||
<option>on-abort</option>, or
|
||
<option>always</option>. If set to
|
||
<option>no</option> (the default), the
|
||
service will not be restarted. If set
|
||
to <option>on-success</option>, 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
|
||
<constant>SIGHUP</constant>,
|
||
<constant>SIGINT</constant>,
|
||
<constant>SIGTERM</constant> or
|
||
<constant>SIGPIPE</constant>, and
|
||
additionally, exit statuses and
|
||
signals specified in
|
||
<varname>SuccessExitStatus=</varname>.
|
||
If set to <option>on-failure</option>,
|
||
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 <option>on-abnormal</option>, 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 <option>on-abort</option>, 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
|
||
<option>on-watchdog</option>, the
|
||
service will be restarted only if the
|
||
watchdog timeout for the service
|
||
expires. If set to
|
||
<option>always</option>, the service
|
||
will be restarted regardless of
|
||
whether it exited cleanly or not, got
|
||
terminated abnormally by a signal, or
|
||
hit a timeout.</para>
|
||
|
||
<table>
|
||
<title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>
|
||
|
||
<tgroup cols='2'>
|
||
<colspec colname='path' />
|
||
<colspec colname='expl' />
|
||
<thead>
|
||
<row>
|
||
<entry>Restart settings/Exit causes</entry>
|
||
<entry><option>no</option></entry>
|
||
<entry><option>always</option></entry>
|
||
<entry><option>on-success</option></entry>
|
||
<entry><option>on-failure</option></entry>
|
||
<entry><option>on-abnormal</option></entry>
|
||
<entry><option>on-abort</option></entry>
|
||
<entry><option>on-watchdog</option></entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry>Clean exit code or signal</entry>
|
||
<entry/>
|
||
<entry>X</entry>
|
||
<entry>X</entry>
|
||
<entry/>
|
||
<entry/>
|
||
<entry/>
|
||
<entry/>
|
||
</row>
|
||
<row>
|
||
<entry>Unclean exit code</entry>
|
||
<entry/>
|
||
<entry>X</entry>
|
||
<entry/>
|
||
<entry>X</entry>
|
||
<entry/>
|
||
<entry/>
|
||
<entry/>
|
||
</row>
|
||
<row>
|
||
<entry>Unclean signal</entry>
|
||
<entry/>
|
||
<entry>X</entry>
|
||
<entry/>
|
||
<entry>X</entry>
|
||
<entry>X</entry>
|
||
<entry>X</entry>
|
||
<entry/>
|
||
</row>
|
||
<row>
|
||
<entry>Timeout</entry>
|
||
<entry/>
|
||
<entry>X</entry>
|
||
<entry/>
|
||
<entry>X</entry>
|
||
<entry>X</entry>
|
||
<entry/>
|
||
<entry/>
|
||
</row>
|
||
<row>
|
||
<entry>Watchdog</entry>
|
||
<entry/>
|
||
<entry>X</entry>
|
||
<entry/>
|
||
<entry>X</entry>
|
||
<entry>X</entry>
|
||
<entry/>
|
||
<entry>X</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>As exceptions to the setting
|
||
above the service will not be
|
||
restarted if the exit code or signal
|
||
is specified in
|
||
<varname>RestartPreventExitStatus=</varname>
|
||
(see below). Also, the services will
|
||
always be restarted if the exit code
|
||
or signal is specified in
|
||
<varname>RestartForceExitStatus=</varname>
|
||
(see below).</para>
|
||
|
||
<para>Setting this to
|
||
<option>on-failure</option> 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),
|
||
<option>on-abnormal</option> is an
|
||
alternative choice.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>SuccessExitStatus=</varname></term>
|
||
<listitem><para>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 <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
|
||
<constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
|
||
definitions can either be numeric exit
|
||
codes or termination signal names,
|
||
separated by spaces. For example:
|
||
<programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>
|
||
ensures that exit codes 1, 2, 8 and
|
||
the termination signal
|
||
<constant>SIGKILL</constant> are
|
||
considered clean service terminations.
|
||
</para>
|
||
|
||
<para>Note that if a process has a
|
||
signal handler installed and exits by
|
||
calling
|
||
<citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
||
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
|
||
<ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>
|
||
|
||
<para>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.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>RestartPreventExitStatus=</varname></term>
|
||
<listitem><para>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
|
||
<varname>Restart=</varname>. 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:
|
||
<programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit
|
||
codes 1 and 6 and the termination
|
||
signal <constant>SIGABRT</constant> 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.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>RestartForceExitStatus=</varname></term>
|
||
<listitem><para>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
|
||
<varname>Restart=</varname>. The
|
||
argument format is similar to
|
||
<varname>RestartPreventExitStatus=</varname>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>PermissionsStartOnly=</varname></term>
|
||
<listitem><para>Takes a boolean
|
||
argument. If true, the permission-related
|
||
execution options, as
|
||
configured with
|
||
<varname>User=</varname> and similar
|
||
options (see
|
||
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||
for more information), are only applied
|
||
to the process started with
|
||
<varname>ExecStart=</varname>, and not
|
||
to the various other
|
||
<varname>ExecStartPre=</varname>,
|
||
<varname>ExecStartPost=</varname>,
|
||
<varname>ExecReload=</varname>,
|
||
<varname>ExecStop=</varname>, and
|
||
<varname>ExecStopPost=</varname>
|
||
commands. If false, the setting is
|
||
applied to all configured commands the
|
||
same way. Defaults to
|
||
false.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>RootDirectoryStartOnly=</varname></term>
|
||
<listitem><para>Takes a boolean
|
||
argument. If true, the root directory,
|
||
as configured with the
|
||
<varname>RootDirectory=</varname>
|
||
option (see
|
||
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||
for more information), is only applied
|
||
to the process started with
|
||
<varname>ExecStart=</varname>, and not
|
||
to the various other
|
||
<varname>ExecStartPre=</varname>,
|
||
<varname>ExecStartPost=</varname>,
|
||
<varname>ExecReload=</varname>,
|
||
<varname>ExecStop=</varname>, and
|
||
<varname>ExecStopPost=</varname>
|
||
commands. If false, the setting is
|
||
applied to all configured commands the
|
||
same way. Defaults to
|
||
false.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>NonBlocking=</varname></term>
|
||
<listitem><para>Set the
|
||
<constant>O_NONBLOCK</constant> 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 <constant>O_NONBLOCK</constant> flag
|
||
set and hence are in
|
||
non-blocking mode. This option is only
|
||
useful in conjunction with a socket
|
||
unit, as described in
|
||
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
|
||
to false.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>NotifyAccess=</varname></term>
|
||
<listitem><para>Controls access to the
|
||
service status notification socket, as
|
||
accessible via the
|
||
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||
call. Takes one of
|
||
<option>none</option> (the default),
|
||
<option>main</option> or
|
||
<option>all</option>. If
|
||
<option>none</option>, no daemon status
|
||
updates are accepted from the service
|
||
processes, all status update messages
|
||
are ignored. If <option>main</option>,
|
||
only service updates sent from the
|
||
main process of the service are
|
||
accepted. If <option>all</option>, 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
|
||
<varname>Type=notify</varname> or
|
||
<varname>WatchdogSec=</varname> (see
|
||
above). If those options are used but
|
||
<varname>NotifyAccess=</varname> is not
|
||
configured, it will be implicitly set
|
||
to
|
||
<option>main</option>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>Sockets=</varname></term>
|
||
<listitem><para>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.</para>
|
||
|
||
<para>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
|
||
<varname>Service=</varname> setting of
|
||
<filename>.socket</filename> units
|
||
does not have to match the inverse of
|
||
the <varname>Sockets=</varname>
|
||
setting of the
|
||
<filename>.service</filename> it
|
||
refers to.</para>
|
||
|
||
<para>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.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>StartLimitInterval=</varname></term>
|
||
<term><varname>StartLimitBurst=</varname></term>
|
||
|
||
<listitem><para>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
|
||
<varname>StartLimitInterval=</varname>
|
||
to configure the checking interval (defaults to
|
||
<varname>DefaultStartLimitInterval=</varname> in
|
||
manager configuration file, set to 0 to disable
|
||
any kind of rate limiting). Use
|
||
<varname>StartLimitBurst=</varname> to
|
||
configure how many starts per interval
|
||
are allowed (defaults to
|
||
<varname>DefaultStartLimitBurst=</varname> in
|
||
manager configuration file). These
|
||
configuration options are particularly
|
||
useful in conjunction with
|
||
<varname>Restart=</varname>; however,
|
||
they apply to all kinds of starts
|
||
(including manual), not just those
|
||
triggered by the
|
||
<varname>Restart=</varname> logic.
|
||
Note that units which are configured
|
||
for <varname>Restart=</varname> 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
|
||
<command>systemctl
|
||
reset-failed</command> 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.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>StartLimitAction=</varname></term>
|
||
|
||
<listitem><para>Configure the action
|
||
to take if the rate limit configured
|
||
with
|
||
<varname>StartLimitInterval=</varname>
|
||
and
|
||
<varname>StartLimitBurst=</varname> is
|
||
hit. Takes one of
|
||
<option>none</option>,
|
||
<option>reboot</option>,
|
||
<option>reboot-force</option>,
|
||
<option>reboot-immediate</option>,
|
||
<option>poweroff</option>,
|
||
<option>poweroff-force</option> or
|
||
<option>poweroff-immediate</option>. If
|
||
<option>none</option> is set, hitting
|
||
the rate limit will trigger no action
|
||
besides that the start will not be
|
||
permitted. <option>reboot</option>
|
||
causes a reboot following the normal
|
||
shutdown procedure (i.e. equivalent to
|
||
<command>systemctl reboot</command>).
|
||
<option>reboot-force</option> causes a
|
||
forced reboot which will terminate all
|
||
processes forcibly but should cause no
|
||
dirty file systems on reboot
|
||
(i.e. equivalent to <command>systemctl
|
||
reboot -f</command>) and
|
||
<option>reboot-immediate</option>
|
||
causes immediate execution of the
|
||
<citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
||
system call, which might result in
|
||
data loss. Similar,
|
||
<option>poweroff</option>,
|
||
<option>poweroff-force</option>,
|
||
<option>poweroff-immediate</option>
|
||
have the effect of powering down the
|
||
system with similar
|
||
semantics. Defaults to
|
||
<option>none</option>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>FailureAction=</varname></term>
|
||
<listitem><para>Configure the action
|
||
to take when the service enters a failed
|
||
state. Takes the same values as
|
||
<varname>StartLimitAction=</varname>
|
||
and executes the same actions.
|
||
Defaults to <option>none</option>.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>RebootArgument=</varname></term>
|
||
<listitem><para>Configure the optional
|
||
argument for the
|
||
<citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
||
system call if
|
||
<varname>StartLimitAction=</varname>
|
||
or <varname>FailureAction=</varname>
|
||
is a reboot action. This works just
|
||
like the optional argument to
|
||
<command>systemctl reboot</command>
|
||
command.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>FileDescriptorStoreMax=</varname></term>
|
||
<listitem><para>Configure how many
|
||
file descriptors may be stored in the
|
||
service manager for the service using
|
||
<citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
|
||
<literal>FDSTORE=1</literal>
|
||
messages. This is useful for
|
||
implementing service restart schemes
|
||
where the state is serialized to
|
||
<filename>/run</filename> 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.</para></listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
|
||
<para>Check
|
||
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||
and
|
||
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||
for more settings.</para>
|
||
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Command lines</title>
|
||
|
||
<para>This section describes command line parsing and
|
||
variable and specifier substitions for
|
||
<varname>ExecStart=</varname>,
|
||
<varname>ExecStartPre=</varname>,
|
||
<varname>ExecStartPost=</varname>,
|
||
<varname>ExecReload=</varname>,
|
||
<varname>ExecStop=</varname>, and
|
||
<varname>ExecStopPost=</varname> options.</para>
|
||
|
||
<para>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
|
||
<literal>\;</literal>.</para>
|
||
|
||
<para>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
|
||
(<literal>\</literal>) may be used to merge lines.
|
||
</para>
|
||
|
||
<para>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
|
||
<literal><</literal>, <literal><<</literal>,
|
||
<literal>></literal>, and
|
||
<literal>>></literal>, pipes using
|
||
<literal>|</literal>, running programs in the
|
||
background using <literal>&</literal>, and
|
||
<emphasis>other elements of shell syntax are not
|
||
supported</emphasis>.</para>
|
||
|
||
<para>The command to execute must an absolute path
|
||
name. It may contain spaces, but control characters
|
||
are not allowed.</para>
|
||
|
||
<para>The command line accepts <literal>%</literal>
|
||
specifiers as described in
|
||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
|
||
Note that the first argument of the command line
|
||
(i.e. the program to execute) may not include
|
||
specifiers.</para>
|
||
|
||
<para>Basic environment variable substitution is
|
||
supported. Use <literal>${FOO}</literal> 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
|
||
<literal>$FOO</literal> 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.</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<programlisting>Environment="ONE=one" 'TWO=two two'
|
||
ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
|
||
|
||
<para>This will execute <command>/bin/echo</command>
|
||
with four arguments: <literal>one</literal>,
|
||
<literal>two</literal>, <literal>two</literal>, and
|
||
<literal>two two</literal>.</para>
|
||
|
||
<para>Example:</para>
|
||
<programlisting>Environment=ONE='one' "TWO='two two' too" THREE=
|
||
ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
|
||
ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
|
||
<para>This results in <filename>echo</filename> being
|
||
called twice, the first time with arguments
|
||
<literal>'one'</literal>,
|
||
<literal>'two two' too</literal>, <literal></literal>,
|
||
and the second time with arguments
|
||
<literal>one</literal>, <literal>two two</literal>,
|
||
<literal>too</literal>.
|
||
</para>
|
||
|
||
<para>To pass a literal dollar sign, use
|
||
<literal>$$</literal>. 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.</para>
|
||
|
||
<para>Variables to be used in this fashion may be
|
||
defined through <varname>Environment=</varname> and
|
||
<varname>EnvironmentFile=</varname>. In addition,
|
||
variables listed in the section "Environment variables
|
||
in spawned processes" in
|
||
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||
which are considered "static configuration", may be
|
||
used (this includes e.g. <varname>$USER</varname>, but
|
||
not <varname>$TERM</varname>).</para>
|
||
|
||
<para>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:</para>
|
||
<programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>
|
||
|
||
<para>Example:</para>
|
||
|
||
<programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
|
||
|
||
<para>This will execute <command>/bin/echo</command>
|
||
two times, each time with one argument:
|
||
<literal>one</literal> and <literal>two two</literal>,
|
||
respectively. Because two commands are specified,
|
||
<varname>Type=oneshot</varname> must be used.</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<programlisting>ExecStart=/bin/echo / >/dev/null & \; \
|
||
/bin/ls</programlisting>
|
||
|
||
<para>This will execute <command>/bin/echo</command>
|
||
with five arguments: <literal>/</literal>,
|
||
<literal>>/dev/null</literal>,
|
||
<literal>&</literal>, <literal>;</literal>, and
|
||
<literal>/bin/ls</literal>.</para>
|
||
|
||
<table>
|
||
<title>C escapes supported in command lines and environment variables</title>
|
||
<tgroup cols='2'>
|
||
<colspec colname='escape' />
|
||
<colspec colname='meaning' />
|
||
<thead>
|
||
<row>
|
||
<entry>Literal</entry>
|
||
<entry>Actual value</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry><literal>\a</literal></entry>
|
||
<entry>bell</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\b</literal></entry>
|
||
<entry>backspace</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\f</literal></entry>
|
||
<entry>form feed</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\n</literal></entry>
|
||
<entry>newline</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\r</literal></entry>
|
||
<entry>carriage return</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\t</literal></entry>
|
||
<entry>tab</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\v</literal></entry>
|
||
<entry>vertical tab</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\\</literal></entry>
|
||
<entry>backslash</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\"</literal></entry>
|
||
<entry>double quotation mark</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\'</literal></entry>
|
||
<entry>single quotation mark</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\s</literal></entry>
|
||
<entry>space</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\x<replaceable>xx</replaceable></literal></entry>
|
||
<entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
|
||
</row>
|
||
<row>
|
||
<entry><literal>\<replaceable>nnn</replaceable></literal></entry>
|
||
<entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Examples</title>
|
||
|
||
<example>
|
||
<title>Simple service</title>
|
||
|
||
<para>The following unit file creates a service
|
||
that will execute
|
||
<filename>/usr/sbin/foo-daemon</filename>.
|
||
Since no <varname>Type=</varname> is specified,
|
||
the default
|
||
<varname>Type=</varname><option>simple</option>
|
||
will be assumed. systemd will assume the unit
|
||
to be started immediately after the program has
|
||
begun executing.</para>
|
||
|
||
<programlisting>[Unit]
|
||
Description=Foo
|
||
|
||
[Service]
|
||
ExecStart=/usr/sbin/foo-daemon
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target</programlisting>
|
||
|
||
<para>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
|
||
<varname>Type=</varname><option>forking</option>
|
||
instead.</para>
|
||
|
||
<para>Since no <varname>ExecStop=</varname> 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
|
||
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||
for details.</para>
|
||
|
||
<para>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
|
||
<varname>Type=</varname><option>notify</option>
|
||
if the service understands systemd's
|
||
notification protocol,
|
||
<varname>Type=</varname><option>forking</option>
|
||
if the service can background itself or
|
||
<varname>Type=</varname><option>dbus</option>
|
||
if the unit acquires a DBus name once
|
||
initialization is complete. See below.</para>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Oneshot service</title>
|
||
|
||
<para>Sometimes units should just execute an
|
||
action without keeping active processes, such
|
||
as a filesystem check or a cleanup action on
|
||
boot. For this,
|
||
<varname>Type=</varname><option>oneshot</option>
|
||
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:</para>
|
||
|
||
<programlisting>[Unit]
|
||
Description=Cleanup old Foo data
|
||
|
||
[Service]
|
||
Type=oneshot
|
||
ExecStart=/usr/sbin/foo-cleanup
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target</programlisting>
|
||
|
||
<para>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.</para>
|
||
|
||
<para><varname>Type=</varname><option>oneshot</option>
|
||
are the only service units that may have more
|
||
than one <varname>ExecStart=</varname>
|
||
specified. They will be executed in order until
|
||
either they are all successful or one of them
|
||
fails.</para>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Stoppable oneshot service</title>
|
||
|
||
<para>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.</para>
|
||
|
||
<para>For this, systemd knows the setting
|
||
<varname>RemainAfterExit=</varname><option>yes</option>,
|
||
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
|
||
<varname>Type=</varname><option>oneshot</option>
|
||
and
|
||
<varname>Type=</varname><option>simple</option>.
|
||
With
|
||
<varname>Type=</varname><option>oneshot</option>
|
||
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
|
||
<varname>Type=</varname><option>simple</option>
|
||
dependencies will start immediately after the
|
||
start action has been dispatched. The following
|
||
unit provides an example for a simple static
|
||
firewall.</para>
|
||
|
||
<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</programlisting>
|
||
|
||
<para>Since the unit is considered to be
|
||
running after the start action has exited,
|
||
invoking <command>systemctl start</command> on
|
||
that unit again will cause no action to be
|
||
taken.</para>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Traditional forking services</title>
|
||
|
||
<para>Many traditional daemons/services
|
||
background (i.e. fork, daemonize) themselves
|
||
when starting. Set
|
||
<varname>Type=</varname><option>forking</option>
|
||
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
|
||
<varname>RemainAfterExit=</varname><option>no</option>),
|
||
the service is considered started.</para>
|
||
|
||
<para>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
|
||
<varname>$MAINPID</varname> variable will be
|
||
available in <varname>ExecReload=</varname>,
|
||
<varname>ExecStop=</varname>, etc.</para>
|
||
|
||
<para>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, <varname>$MAINPID</varname> 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 <varname>PIDFile=</varname>
|
||
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.</para>
|
||
|
||
<para>The following example shows a simple
|
||
daemon that forks and just starts one process
|
||
in the background:</para>
|
||
|
||
<programlisting>[Unit]
|
||
Description=Some simple daemon
|
||
|
||
[Service]
|
||
Type=forking
|
||
ExecStart=/usr/sbin/my-simple-daemon -d
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target</programlisting>
|
||
|
||
<para>Please see
|
||
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||
for details on how you can influence the way
|
||
systemd terminates the service.</para>
|
||
</example>
|
||
|
||
<example>
|
||
<title>DBus services</title>
|
||
|
||
<para>For services that acquire a name on the
|
||
DBus system bus, use
|
||
<varname>Type=</varname><option>dbus</option>
|
||
and set <varname>BusName=</varname>
|
||
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:</para>
|
||
|
||
<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</programlisting>
|
||
|
||
<para>For <emphasis>bus-activatable</emphasis>
|
||
services, don't include a
|
||
<literal>[Install]</literal> section in the
|
||
systemd service file, but use the
|
||
<varname>SystemdService=</varname> option in
|
||
the corresponding DBus service file, for
|
||
example
|
||
(<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para>
|
||
|
||
<programlisting>[D-BUS Service]
|
||
Name=org.example.simple-dbus-service
|
||
Exec=/usr/sbin/simple-dbus-service
|
||
User=root
|
||
SystemdService=simple-dbus-service.service</programlisting>
|
||
|
||
<para>Please see
|
||
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||
for details on how you can influence the way
|
||
systemd terminates the service.</para>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Services that notify systemd about their initialization</title>
|
||
|
||
<para><varname>Type=</varname><option>simple</option>
|
||
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
|
||
<varname>Type=</varname><option>notify</option>
|
||
for this. A typical service file for such a
|
||
daemon would look like this:</para>
|
||
|
||
<programlisting>[Unit]
|
||
Description=Simple notifying service
|
||
|
||
[Service]
|
||
Type=notify
|
||
ExecStart=/usr/sbin/simple-notifying-service
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target</programlisting>
|
||
|
||
<para>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
|
||
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||
systemd will consider the unit to be in the
|
||
'starting' state until a readiness notification
|
||
has arrived.</para>
|
||
|
||
<para>Please see
|
||
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||
for details on how you can influence the way
|
||
systemd terminates the service.</para>
|
||
</example>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>See Also</title>
|
||
<para>
|
||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||
</para>
|
||
</refsect1>
|
||
|
||
</refentry>
|