</refnamediv>
<refsynopsisdiv>
- <para><filename>systemd.service</filename></para>
+ <para><filename><replaceable>service</replaceable>.service</filename></para>
</refsynopsisdiv>
<refsect1>
options specific to the <literal>[Service]</literal>
section of service units are the following:</para>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>Type=</varname></term>
<term><varname>ExecStart=</varname></term>
<listitem><para>Commands with their
arguments that are executed when this
- service is started.
- </para>
+ service is started. The first
+ argument must be an absolute path
+ name.</para>
- <para>When
+ <para>When <varname>Type</varname> is
+ not <option>oneshot</option>, only one
+ command may be given. When
<varname>Type=oneshot</varname> is
used, more than one command may be
specified. Multiple command lines may
for compatibility with parsers
suitable for XDG
<filename>.desktop</filename> files.
- The commands are invoked one by
- one sequentially in the order they
- appear in the unit file.
- When <varname>Type</varname> is
- not <option>oneshot</option>, only one
- command may be given. Lone semicolons
- may be escaped as
- '<literal>\;</literal>'.</para>
+ 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.</para>
+
+ <para>If more than one command is
+ specified, the commands are invoked
+ one by one 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
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 up
+ at whitespace, resulting in zero or
+ more arguments. Note that the first
+ argument (i.e. the program to execute)
+ may not be a variable, since it must
+ be a literal and absolute path
+ name.</para>
+
<para>Optionally, if the absolute file
name is prefixed with
'<literal>@</literal>', the second token
'<literal>@</literal>' are used they
can appear in either order.</para>
- <para>On top of that 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 up
- at whitespace, resulting in no or more
- arguments. Note that the first
- argument (i.e. the program to execute)
- may not be a variable, and must be a
- literal and absolute path
- name.</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:
- <literal>ExecStart=/bin/sh -c 'dmesg | tac'</literal></para>
+ of some kind. Example:</para>
+ <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
+ </programlisting>
<para>For services run by a user
instance of systemd the special
environment variable
- <literal>MANAGERPID</literal> is set
+ <varname>$MANAGERPID</varname> is set
to the PID of the systemd
instance.</para>
</listitem>
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>
optional. Specifier and environment
variable substitution is supported
here following the same scheme as for
- <varname>ExecStart=</varname>. One
- additional special environment
- variables is set: if known
- <literal>$MAINPID</literal> is set to
+ <varname>ExecStart=</varname>.</para>
+
+ <para>One additional special
+ environment variables 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: <command>/bin/kill -HUP
- $MAINPID</command>.</para></listitem>
+ following:</para>
+
+ <programlisting>/bin/kill -HUP $MAINPID</programlisting>
+ </listitem>
</varlistentry>
<varlistentry>
service stop is requested. Specifier
and environment variable substitution
is supported (including
- <literal>$MAINPID</literal>, see
+ <varname>$MAINPID</varname>, see
above).</para></listitem>
</varlistentry>
<term><varname>ExecStopPost=</varname></term>
<listitem><para>Additional commands
that are executed after the service
- was stopped using the commands
- configured in
- <varname>ExecStop=</varname>. This
+ was stopped. This includes cases where
+ the commands configured in
+ <varname>ExecStop=</varname> were used,
+ where the service doesn't 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
<varlistentry>
<term><varname>WatchdogSec=</varname></term>
<listitem><para>Configures the
- watchdog timeout for a service. This
- is activated when the start-up is
+ 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 "WATCHDOG=1" (i.e. the
<varlistentry>
<term><varname>Restart=</varname></term>
<listitem><para>Configures whether the
- main service process shall be
- restarted when it exits. Takes one of
+ 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 also one of the processes
+ specified with
+ <varname>ExecStartPre=</varname>,
+ <varname>ExecStartPost=</varname>,
+ <varname>ExecStopPre=</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-abort</option> or
+ <option>on-abort</option>, or
<option>always</option>. If set to
<option>no</option> (the default) the
- service will not be restarted when it
- exits. If set to
+ service will not be restarted. If set to
<option>on-success</option> it will be
- restarted only when it exited cleanly,
- i.e. terminated with an exit code of
- 0. If set to
- <option>on-failure</option> it will be
- restarted only when it exited with an
- exit code not equaling 0, when
- terminated by a signal (including on
+ 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
+ SIGHUP, SIGINT, SIGTERM, or SIGPIPE, 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 an nonzero exit code,
+ is terminated by a signal (including on
core dump), when an operation (such as
- service reload) times out or when the
- configured watchdog timeout is
- triggered. If set to
- <option>on-abort</option> it will be
- restarted only if it exits due to
- reception of an uncaught signal
- (including on core dump). If set to
+ service reload) times out, and when the
+ configured 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>always</option> the service
will be restarted regardless whether
it exited cleanly or not, got
terminated abnormally by a signal or
- hit a timeout.</para></listitem>
+ hit a timeout.</para>
+
+ <para>In addition to the above settings,
+ the service will not be restarted if the
+ exit code or signal is specified in
+ <varname>RestartPreventExitStatus=</varname>
+ (see below).</para></listitem>
</varlistentry>
<varlistentry>
code 0 and the signals SIGHUP, SIGINT,
SIGTERM and SIGPIPE. Exit status
definitions can either be numeric exit
- codes or termination signal names, and
- are separated by spaces. Example:
+ codes or termination signal names,
+ separated by spaces. Example:
"<literal>SuccessExitStatus=1 2 8
SIGKILL</literal>", ensures that exit
codes 1, 2, 8 and the termination
signal SIGKILL are considered clean
- service
- terminations.</para></listitem>
+ service terminations. 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>
logic. Example:
"<literal>RestartPreventExitStatus=1 6
SIGABRT</literal>", ensures that exit
- codes 1 and 6 and the termination signal
- SIGABRT will not result in automatic
- service restarting.</para></listitem>
+ codes 1 and 6 and the termination
+ signal SIGABRT 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, all prior assignments
+ of this option will have no
+ effect.</para></listitem>
</varlistentry>
<varlistentry>
open access to the notification socket
when using
<varname>Type=notify</varname> or
- <varname>WatchdogUsec=</varname> (see
+ <varname>WatchdogSec=</varname> (see
above). If those options are used but
<varname>NotifyAccess=</varname> not
configured it will be implicitly set
same time. Also note that a different
service may be activated on incoming
traffic than inherits the sockets. Or
- in other words: The
+ in other words: the
<varname>Service=</varname> setting of
<filename>.socket</filename> units
- doesn't have to match the inverse of the
- <varname>Sockets=</varname> setting of
- the <filename>.service</filename> it
- refers to.</para></listitem>
+ doesn't 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, all prior uses of
+ this setting will have no
+ effect.</para></listitem>
</varlistentry>
<varlistentry>
for compatibility reasons and should not be used in
newly written service files.</para>
- <variablelist>
+ <variablelist class='unit-directives'>
<varlistentry>
<term><varname>SysVStartPriority=</varname></term>
<listitem><para>Set the SysV start