1397 lines
63 KiB
XML
1397 lines
63 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
||
<!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, although
|
||
it will remove the file after the service has shut down if it
|
||
still exists.
|
||
</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 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. The value is split into
|
||
zero or more command lines 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>
|
||
|
||
<para><varname>ExecStart=</varname> commands are only run after
|
||
all <varname>ExecStartPre=</varname> commands that were not prefixed
|
||
with a <literal>-</literal> exit successfully.</para>
|
||
|
||
<para><varname>ExecStartPost=</varname> commands are only run after
|
||
the service has started, as determined by <varname>Type=</varname>
|
||
(i.e. the process has been started for <varname>Type=simple</varname>
|
||
or <varname>Type=idle</varname>, the process exits successfully for
|
||
<varname>Type=oneshot</varname>, the initial process exits successfully
|
||
for <varname>Type=forking</varname>, <literal>READY=1</literal> is sent
|
||
for <varname>Type=notify</varname>, or the <varname>BusName=</varname>
|
||
has been taken for <varname>Type=dbus</varname>).</para>
|
||
|
||
<para>Note that <varname>ExecStartPre=</varname> may not be
|
||
used to start long-running processes. All processes forked
|
||
off by processes invoked via <varname>ExecStartPre=</varname> will
|
||
be killed before the next service process is run.</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 by
|
||
sending the signal specified in <varname>KillSignal=</varname>
|
||
when service stop is requested. Specifier and environment
|
||
variable substitution is supported (including
|
||
<varname>$MAINPID</varname>, see above).</para>
|
||
|
||
<para>Note that it is usually not sufficient to specify a
|
||
command for this setting that only asks the service to
|
||
terminate (for example, by queuing some form of termination
|
||
signal for it), but does not wait for it to do so. Since the
|
||
remaining processes of the services are killed using
|
||
<constant>SIGKILL</constant> immediately after the command
|
||
exited, this would not result in a clean stop. The specified
|
||
command should hence be a synchronous operation, not an
|
||
asynchronous one.</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
|
||
<constant>SIGABRT</constant>. 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 aforementioned 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. Similarly,
|
||
<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>
|
||
|
||
<varlistentry>
|
||
<term><varname>USBFunctionDescriptors=</varname></term>
|
||
<listitem><para>Configure the location of a file containing
|
||
<ulink
|
||
url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
|
||
FunctionFS</ulink> descriptors, for implementation of USB
|
||
gadget functions. This is used only in conjunction with a
|
||
socket unit with <varname>ListenUSBFunction=</varname>
|
||
configured. The contents of this file are written to the
|
||
<filename>ep0</filename> file after it is
|
||
opened.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>USBFunctionStrings=</varname></term>
|
||
<listitem><para>Configure the location of a file containing
|
||
USB FunctionFS strings. Behavior is similar to
|
||
<varname>USBFunctionDescriptors=</varname>
|
||
above.</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 substitutions 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. The table below contains the list of allowed escape
|
||
patterns. Only patterns which match the syntax in the table are
|
||
allowed; others will result in an error, and must be escaped by
|
||
doubling the backslash. 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 be 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 are 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 cleanup 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 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>
|