1
0
mirror of https://github.com/systemd/systemd.git synced 2024-11-14 15:21:37 +03:00
systemd/man/systemd.service.xml
Daniel Mack 5019962312 bus: parse BusPolicy directive in service files
Add a new directive called BusPolicy to define custom endpoint policies. If
one such directive is given, an endpoint object in the service's ExecContext is
created and the given policy is added to it.
2014-09-08 14:12:54 +02:00

1289 lines
76 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>, but its use
is otherwise recommended if the process
takes a name on the D-Bus bus.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>BusPolicy=</varname></term>
<listitem><para>If specfied, a custom kdbus
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. For each of the
specified commands, the first argument
must be an absolute and literal path
to an executable.</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, none or more than one command
may be specified. Multiple command
lines may be concatenated in a single
directive by separating them with
semicolons (these semicolons must be
passed as separate
words). Alternatively, this directive
may be specified more than once with
the same effect. Lone semicolons may
be escaped as
<literal>\;</literal>. 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>Each command line is split on
whitespace, with the first item being
the command to execute, and the
subsequent items being the arguments.
Double quotes ("...") and single
quotes ('...') may be used, in which
case everything until the next
matching quote becomes part of the
same argument. Quotes themselves are
removed after parsing. In addition, a
trailing backslash
(<literal>\</literal>) may be used to
merge lines. This syntax is intended
to be very similar to shell syntax,
but only the meta-characters and
expansions described in the following
paragraphs are understood.
Specifically, redirection using
<literal>&lt;</literal>,
<literal>&lt;&lt;</literal>,
<literal>&gt;</literal>, and
<literal>&gt;&gt;</literal>, pipes
using <literal>|</literal>, and
running programs in the background
using <literal>&amp;</literal>
and <emphasis>other elements of shell
syntax are not supported</emphasis>.
</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>
<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. 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>Optionally, if the absolute 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>Note that this setting does not
directly support shell command
lines. If shell command lines are to
be used, they need to be passed
explicitly to a shell implementation
of some kind. Example:</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 / &gt;/dev/null &amp; \; \
/bin/ls</programlisting>
<para>This will execute
<command>/bin/echo</command> with five
arguments: <literal>/</literal>,
<literal>&gt;/dev/null</literal>,
<literal>&amp;</literal>,
<literal>;</literal>, and
<literal>/bin/ls</literal>.</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>
</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-systemd.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-systemd.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. 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 the sockets from when the
service is started. Normally it
should not be necessary to use this
setting as all sockets whose unit
shares the same name as the service
(ignoring the different suffix of course)
are passed to the spawned
process.</para>
<para>Note that the same socket may be
passed to multiple processes at the
same time. Also note that a different
service may be activated on incoming
traffic than that which inherits the
sockets. Or in other words: the
<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>
</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>Compatibility Options</title>
<para>The following options are also available in the
<literal>[Service]</literal> section, but exist purely
for compatibility reasons and should not be used in
newly written service files.</para>
<variablelist class='unit-directives'>
<varlistentry>
<term><varname>SysVStartPriority=</varname></term>
<listitem><para>Set the SysV start
priority to use to order this service
in relation to SysV services lacking
LSB headers. This option is only
necessary to fix ordering in relation
to legacy SysV services that have no
ordering information encoded in the
script headers. As such, it should only
be used as a temporary compatibility
option and should not be used in new unit
files. Almost always, it is a better
choice to add explicit ordering
directives via
<varname>After=</varname> or
<varname>Before=</varname>,
instead. For more details, see
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
If used, pass an integer value in the
range 0-99.</para></listitem>
</varlistentry>
</variablelist>
</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>