<?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">
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
-->
<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 specified, a custom
- <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>
- endpoint will be created and installed as the
- default bus node for the service. Such a custom
- endpoint can hold an own set of policy rules
- that are enforced on top of the bus-wide ones.
- The custom endpoint is named after the service
- it was created for, and its node will be
- bind-mounted over the default bus node
- location, so the service can only access the
- bus through its own endpoint. Note that custom
- bus endpoints default to a 'deny all' policy.
- Hence, if at least one
- <varname>BusPolicy=</varname> directive is
- given, you have to make sure to add explicit
- rules for everything the service should be able
- to do.</para>
- <para>The value of this directive is comprised
- of two parts; the bus name, and a verb to
- specify to granted access, which is one of
- <option>see</option>,
- <option>talk</option>, or
- <option>own</option>.
- <option>talk</option> implies
- <option>see</option>, and <option>own</option>
- implies both <option>talk</option> and
- <option>see</option>.
- If multiple access levels are specified for the
- same bus name, the most powerful one takes
- effect.
- </para>
- <para>Examples:</para>
- <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>
- <programlisting>BusPolicy=org.foo.bar see</programlisting>
- <para>This option is only available on kdbus enabled systems.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>ExecStart=</varname></term>
- <listitem><para>Commands with their
- arguments that are executed when this
- service is started. The value is split
- into zero or more command lines is
- according to the rules described below
- (see section "Command Lines" below).
- </para>
-
- <para>When <varname>Type</varname> is
- not <option>oneshot</option>, only one
- command may and must be given. When
- <varname>Type=oneshot</varname> is
- used, zero or more commands may be
- specified. This can be specified by
- providing multiple command lines in
- the same directive, or alternatively,
- this directive may be specified more
- than once with the same effect. If the
- empty string is assigned to this
- option, the list of commands to start
- is reset, prior assignments of this
- option will have no effect. If no
- <varname>ExecStart=</varname> is
- specified, then the service must have
- <varname>RemainAfterExit=yes</varname>
- set.</para>
-
- <para>For each of the specified
- commands, the first argument must be
- an absolute and literal path to an
- executable. 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>If more than one command is
- specified, the commands are invoked
- sequentially in the order they appear
- in the unit file. If one of the
- commands fails (and is not prefixed
- with <literal>-</literal>), other
- lines are not executed, and the unit
- is considered failed.</para>
-
- <para>Unless
- <varname>Type=forking</varname> is
- set, the process started via this
- command line will be considered the
- main process of the daemon.</para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>ExecStartPre=</varname></term>
- <term><varname>ExecStartPost=</varname></term>
- <listitem><para>Additional commands
- that are executed before or after
- the command in
- <varname>ExecStart=</varname>, respectively.
- Syntax is the same as for
- <varname>ExecStart=</varname>, except
- that multiple command lines are allowed
- and the commands are executed one
- after the other, serially.</para>
-
- <para>If any of those commands (not
- prefixed with <literal>-</literal>)
- fail, the rest are not executed and
- the unit is considered failed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>ExecReload=</varname></term>
- <listitem><para>Commands to execute to
- trigger a configuration reload in the
- service. This argument takes multiple
- command lines, following the same
- scheme as described for
- <varname>ExecStart=</varname>
- above. Use of this setting is
- optional. Specifier and environment
- variable substitution is supported
- here following the same scheme as for
- <varname>ExecStart=</varname>.</para>
-
- <para>One additional, special
- environment variable is set: if known,
- <varname>$MAINPID</varname> is set to
- the main process of the daemon, and
- may be used for command lines like the
- following:</para>
-
- <programlisting>/bin/kill -HUP $MAINPID</programlisting>
-
- <para>Note however that reloading a
- daemon by sending a signal (as with
- the example line above) is usually not
- a good choice, because this is an
- asynchronous operation and hence not
- suitable to order reloads of multiple
- services against each other. It is
- strongly recommended to set
- <varname>ExecReload=</varname> to a
- command that not only triggers a
- configuration reload of the daemon,
- but also synchronously waits for it to
- complete.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>ExecStop=</varname></term>
- <listitem><para>Commands to execute to
- stop the service started via
- <varname>ExecStart=</varname>. This
- argument takes multiple command lines,
- following the same scheme as described
- for <varname>ExecStart=</varname>
- above. Use of this setting is
- optional. After the commands configured
- in this option are run, all processes
- remaining for a service are
- terminated according to the
- <varname>KillMode=</varname> setting
- (see
- <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
- this option is not specified, the
- process is terminated immediately when
- service stop is requested. Specifier
- and environment variable substitution
- is supported (including
- <varname>$MAINPID</varname>, see
- above).</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>ExecStopPost=</varname></term>
- <listitem><para>Additional commands
- that are executed after the service
- was stopped. This includes cases where
- the commands configured in
- <varname>ExecStop=</varname> were used,
- where the service does not have any
- <varname>ExecStop=</varname> defined, or
- where the service exited unexpectedly. This
- argument takes multiple command lines,
- following the same scheme as described
- for <varname>ExecStart</varname>. Use
- of these settings is
- optional. Specifier and environment
- variable substitution is
- supported.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>RestartSec=</varname></term>
- <listitem><para>Configures the time to
- sleep before restarting a service (as
- configured with
- <varname>Restart=</varname>). Takes a
- unit-less value in seconds, or a time
- span value such as "5min
- 20s". Defaults to
- 100ms.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>TimeoutStartSec=</varname></term>
- <listitem><para>Configures the time to
- wait for start-up. If a
- daemon service does not signal
- start-up completion within the
- configured time, the service will be
- considered failed and will be shut
- down again.
- Takes a unit-less value in seconds, or a
- time span value such as "5min
- 20s". Pass <literal>0</literal> to
- disable the timeout logic. Defaults to
- <varname>DefaultTimeoutStartSec=</varname> from
- the manager configuration file, except
- when <varname>Type=oneshot</varname> is
- used, in which case the timeout
- is disabled by default
- (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>TimeoutStopSec=</varname></term>
- <listitem><para>Configures the time to
- wait for stop. If a service is asked
- to stop, but does not terminate in the
- specified time, it will be terminated
- forcibly via <constant>SIGTERM</constant>,
- and after another timeout of equal duration
- with <constant>SIGKILL</constant> (see
- <varname>KillMode=</varname>
- in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
- Takes a unit-less value in seconds, or a
- time span value such as "5min
- 20s". Pass <literal>0</literal> to disable
- the timeout logic. Defaults to
- <varname>DefaultTimeoutStopSec=</varname> from the
- manager configuration file
- (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>TimeoutSec=</varname></term>
- <listitem><para>A shorthand for configuring
- both <varname>TimeoutStartSec=</varname>
- and <varname>TimeoutStopSec=</varname>
- to the specified value.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>WatchdogSec=</varname></term>
- <listitem><para>Configures the
- watchdog timeout for a service. The
- watchdog is activated when the start-up is
- completed. The service must call
- <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- regularly with <literal>WATCHDOG=1</literal>
- (i.e. the "keep-alive ping"). If the time
- between two such calls is larger than
- the configured time, then the service
- is placed in a failed state and it will
- be terminated with <varname>SIGABRT</varname>.
- By setting <varname>Restart=</varname> to
- <option>on-failure</option> or
- <option>always</option>, the service
- will be automatically restarted. The
- time configured here will be passed to
- the executed service process in the
- <varname>WATCHDOG_USEC=</varname>
- environment variable. This allows
- daemons to automatically enable the
- keep-alive pinging logic if watchdog
- support is enabled for the service. If
- this option is used,
- <varname>NotifyAccess=</varname> (see
- below) should be set to open access to
- the notification socket provided by
- systemd. If
- <varname>NotifyAccess=</varname> is
- not set, it will be implicitly set to
- <option>main</option>. Defaults to 0,
- which disables this
- feature.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>Restart=</varname></term>
- <listitem><para>Configures whether the
- service shall be restarted when the
- service process exits, is killed,
- or a timeout is reached. The service
- process may be the main service
- process, but it may also be one of the
- processes specified with
- <varname>ExecStartPre=</varname>,
- <varname>ExecStartPost=</varname>,
- <varname>ExecStop=</varname>,
- <varname>ExecStopPost=</varname>, or
- <varname>ExecReload=</varname>.
- When the death of the process is a
- result of systemd operation (e.g. service
- stop or restart), the service will not be
- restarted. Timeouts include missing
- the watchdog "keep-alive ping"
- deadline and a service start, reload,
- and stop operation timeouts.</para>
-
- <para>Takes one of
- <option>no</option>,
- <option>on-success</option>,
- <option>on-failure</option>,
- <option>on-abnormal</option>,
- <option>on-watchdog</option>,
- <option>on-abort</option>, or
- <option>always</option>. If set to
- <option>no</option> (the default), the
- service will not be restarted. If set
- to <option>on-success</option>, it
- will be restarted only when the
- service process exits cleanly. In
- this context, a clean exit means an
- exit code of 0, or one of the signals
- <constant>SIGHUP</constant>,
- <constant>SIGINT</constant>,
- <constant>SIGTERM</constant> or
- <constant>SIGPIPE</constant>, and
- additionally, exit statuses and
- signals specified in
- <varname>SuccessExitStatus=</varname>.
- If set to <option>on-failure</option>,
- the service will be restarted when the
- process exits with a non-zero exit
- code, is terminated by a signal
- (including on core dump, but excluding
- the aforementiond four signals), when
- an operation (such as service reload)
- times out, and when the configured
- watchdog timeout is triggered. If set
- to <option>on-abnormal</option>, the
- service will be restarted when the
- process is terminated by a signal
- (including on core dump, excluding the
- aforementioned four signals), when an
- operation times out, or when the
- watchdog timeout is triggered. If set
- to <option>on-abort</option>, the
- service will be restarted only if the
- service process exits due to an
- uncaught signal not specified as a
- clean exit status. If set to
- <option>on-watchdog</option>, the
- service will be restarted only if the
- watchdog timeout for the service
- expires. If set to
- <option>always</option>, the service
- will be restarted regardless of
- whether it exited cleanly or not, got
- terminated abnormally by a signal, or
- hit a timeout.</para>
-
- <table>
- <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>
-
- <tgroup cols='2'>
- <colspec colname='path' />
- <colspec colname='expl' />
- <thead>
- <row>
- <entry>Restart settings/Exit causes</entry>
- <entry><option>no</option></entry>
- <entry><option>always</option></entry>
- <entry><option>on-success</option></entry>
- <entry><option>on-failure</option></entry>
- <entry><option>on-abnormal</option></entry>
- <entry><option>on-abort</option></entry>
- <entry><option>on-watchdog</option></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Clean exit code or signal</entry>
- <entry/>
- <entry>X</entry>
- <entry>X</entry>
- <entry/>
- <entry/>
- <entry/>
- <entry/>
- </row>
- <row>
- <entry>Unclean exit code</entry>
- <entry/>
- <entry>X</entry>
- <entry/>
- <entry>X</entry>
- <entry/>
- <entry/>
- <entry/>
- </row>
- <row>
- <entry>Unclean signal</entry>
- <entry/>
- <entry>X</entry>
- <entry/>
- <entry>X</entry>
- <entry>X</entry>
- <entry>X</entry>
- <entry/>
- </row>
- <row>
- <entry>Timeout</entry>
- <entry/>
- <entry>X</entry>
- <entry/>
- <entry>X</entry>
- <entry>X</entry>
- <entry/>
- <entry/>
- </row>
- <row>
- <entry>Watchdog</entry>
- <entry/>
- <entry>X</entry>
- <entry/>
- <entry>X</entry>
- <entry>X</entry>
- <entry/>
- <entry>X</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>As exceptions to the setting
- above the service will not be
- restarted if the exit code or signal
- is specified in
- <varname>RestartPreventExitStatus=</varname>
- (see below). Also, the services will
- always be restarted if the exit code
- or signal is specified in
- <varname>RestartForceExitStatus=</varname>
- (see below).</para>
-
- <para>Setting this to
- <option>on-failure</option> is the
- recommended choice for long-running
- services, in order to increase
- reliability by attempting automatic
- recovery from errors. For services
- that shall be able to terminate on
- their own choice (and avoid
- immediate restarting),
- <option>on-abnormal</option> is an
- alternative choice.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>SuccessExitStatus=</varname></term>
- <listitem><para>Takes a list of exit
- status definitions that when returned
- by the main service process will be
- considered successful termination, in
- addition to the normal successful exit
- code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
- <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
- definitions can either be numeric exit
- codes or termination signal names,
- separated by spaces. For example:
- <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>
- ensures that exit codes 1, 2, 8 and
- the termination signal
- <constant>SIGKILL</constant> are
- considered clean service terminations.
- </para>
-
- <para>Note that if a process has a
- signal handler installed and exits by
- calling
- <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- in response to a signal, the
- information about the signal is lost.
- Programs should instead perform cleanup and kill themselves with the same signal instead. See
- <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>
-
- <para>This option may appear more than once,
- in which case the list of successful
- exit statuses is merged. If the empty
- string is assigned to this option, the
- list is reset, all prior assignments
- of this option will have no
- effect.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>RestartPreventExitStatus=</varname></term>
- <listitem><para>Takes a list of exit
- status definitions that when returned
- by the main service process will
- prevent automatic service restarts,
- regardless of the restart setting
- configured with
- <varname>Restart=</varname>. Exit
- status definitions can either be
- numeric exit codes or termination
- signal names, and are separated by
- spaces. Defaults to the empty list, so
- that, by default, no exit status is
- excluded from the configured restart
- logic. For example:
- <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit
- codes 1 and 6 and the termination
- signal <constant>SIGABRT</constant> will
- not result in automatic service
- restarting. This
- option may appear more than once, in
- which case the list of restart-preventing
- statuses is merged. If the empty
- string is assigned to this option, the
- list is reset and all prior assignments
- of this option will have no
- effect.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>RestartForceExitStatus=</varname></term>
- <listitem><para>Takes a list of exit
- status definitions that when returned
- by the main service process will force
- automatic service restarts, regardless
- of the restart setting configured with
- <varname>Restart=</varname>. The
- argument format is similar to
- <varname>RestartPreventExitStatus=</varname>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>PermissionsStartOnly=</varname></term>
- <listitem><para>Takes a boolean
- argument. If true, the permission-related
- execution options, as
- configured with
- <varname>User=</varname> and similar
- options (see
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for more information), are only applied
- to the process started with
- <varname>ExecStart=</varname>, and not
- to the various other
- <varname>ExecStartPre=</varname>,
- <varname>ExecStartPost=</varname>,
- <varname>ExecReload=</varname>,
- <varname>ExecStop=</varname>, and
- <varname>ExecStopPost=</varname>
- commands. If false, the setting is
- applied to all configured commands the
- same way. Defaults to
- false.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>RootDirectoryStartOnly=</varname></term>
- <listitem><para>Takes a boolean
- argument. If true, the root directory,
- as configured with the
- <varname>RootDirectory=</varname>
- option (see
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for more information), is only applied
- to the process started with
- <varname>ExecStart=</varname>, and not
- to the various other
- <varname>ExecStartPre=</varname>,
- <varname>ExecStartPost=</varname>,
- <varname>ExecReload=</varname>,
- <varname>ExecStop=</varname>, and
- <varname>ExecStopPost=</varname>
- commands. If false, the setting is
- applied to all configured commands the
- same way. Defaults to
- false.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>NonBlocking=</varname></term>
- <listitem><para>Set the
- <constant>O_NONBLOCK</constant> flag
- for all file descriptors passed via
- socket-based activation. If true, all
- file descriptors >= 3 (i.e. all except
- stdin, stdout, and stderr) will have
- the <constant>O_NONBLOCK</constant> flag
- set and hence are in
- non-blocking mode. This option is only
- useful in conjunction with a socket
- unit, as described in
- <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
- to false.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>NotifyAccess=</varname></term>
- <listitem><para>Controls access to the
- service status notification socket, as
- accessible via the
- <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- call. Takes one of
- <option>none</option> (the default),
- <option>main</option> or
- <option>all</option>. If
- <option>none</option>, no daemon status
- updates are accepted from the service
- processes, all status update messages
- are ignored. If <option>main</option>,
- only service updates sent from the
- main process of the service are
- accepted. If <option>all</option>, all
- services updates from all members of
- the service's control group are
- accepted. This option should be set to
- open access to the notification socket
- when using
- <varname>Type=notify</varname> or
- <varname>WatchdogSec=</varname> (see
- above). If those options are used but
- <varname>NotifyAccess=</varname> is not
- configured, it will be implicitly set
- to
- <option>main</option>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>Sockets=</varname></term>
- <listitem><para>Specifies the name of
- the socket units this service shall
- inherit socket file descriptors
- from when the service is
- started. Normally it should not be
- necessary to use this setting as all
- socket file descriptors whose unit
- shares the same name as the service
- (subject to the different unit name
- suffix of course) are passed to the
- spawned process.</para>
-
- <para>Note that the same socket file
- descriptors may be passed to multiple
- processes simultaneously. Also note
- that a different service may be
- activated on incoming socket traffic
- than the one which is ultimately
- configured to inherit the socket file
- descriptors. Or in other words: the
- <varname>Service=</varname> setting of
- <filename>.socket</filename> units
- does not have to match the inverse of
- the <varname>Sockets=</varname>
- setting of the
- <filename>.service</filename> it
- refers to.</para>
-
- <para>This option may appear more than
- once, in which case the list of socket
- units is merged. If the empty string
- is assigned to this option, the list of
- sockets is reset, and all prior uses of
- this setting will have no
- effect.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>StartLimitInterval=</varname></term>
- <term><varname>StartLimitBurst=</varname></term>
-
- <listitem><para>Configure service
- start rate limiting. By default,
- services which are started more
- than 5 times within 10 seconds are not
- permitted to start any more times
- until the 10 second interval ends. With
- these two options, this rate limiting
- may be modified. Use
- <varname>StartLimitInterval=</varname>
- to configure the checking interval (defaults to
- <varname>DefaultStartLimitInterval=</varname> in
- manager configuration file, set to 0 to disable
- any kind of rate limiting). Use
- <varname>StartLimitBurst=</varname> to
- configure how many starts per interval
- are allowed (defaults to
- <varname>DefaultStartLimitBurst=</varname> in
- manager configuration file). These
- configuration options are particularly
- useful in conjunction with
- <varname>Restart=</varname>; however,
- they apply to all kinds of starts
- (including manual), not just those
- triggered by the
- <varname>Restart=</varname> logic.
- Note that units which are configured
- for <varname>Restart=</varname> and
- which reach the start limit are not
- attempted to be restarted anymore;
- however, they may still be restarted
- manually at a later point, from which
- point on, the restart logic is again
- activated. Note that
- <command>systemctl
- reset-failed</command> will cause the
- restart rate counter for a service to
- be flushed, which is useful if the
- administrator wants to manually start
- a service and the start limit
- interferes with
- that.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>StartLimitAction=</varname></term>
-
- <listitem><para>Configure the action
- to take if the rate limit configured
- with
- <varname>StartLimitInterval=</varname>
- and
- <varname>StartLimitBurst=</varname> is
- hit. Takes one of
- <option>none</option>,
- <option>reboot</option>,
- <option>reboot-force</option>,
- <option>reboot-immediate</option>,
- <option>poweroff</option>,
- <option>poweroff-force</option> or
- <option>poweroff-immediate</option>. If
- <option>none</option> is set, hitting
- the rate limit will trigger no action
- besides that the start will not be
- permitted. <option>reboot</option>
- causes a reboot following the normal
- shutdown procedure (i.e. equivalent to
- <command>systemctl reboot</command>).
- <option>reboot-force</option> causes a
- forced reboot which will terminate all
- processes forcibly but should cause no
- dirty file systems on reboot
- (i.e. equivalent to <command>systemctl
- reboot -f</command>) and
- <option>reboot-immediate</option>
- causes immediate execution of the
- <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system call, which might result in
- data loss. Similar,
- <option>poweroff</option>,
- <option>poweroff-force</option>,
- <option>poweroff-immediate</option>
- have the effect of powering down the
- system with similar
- semantics. Defaults to
- <option>none</option>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>FailureAction=</varname></term>
- <listitem><para>Configure the action
- to take when the service enters a failed
- state. Takes the same values as
- <varname>StartLimitAction=</varname>
- and executes the same actions.
- Defaults to <option>none</option>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>RebootArgument=</varname></term>
- <listitem><para>Configure the optional
- argument for the
- <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system call if
- <varname>StartLimitAction=</varname>
- or <varname>FailureAction=</varname>
- is a reboot action. This works just
- like the optional argument to
- <command>systemctl reboot</command>
- command.</para></listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>Check
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- and
- <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for more settings.</para>
-
- </refsect1>
-
- <refsect1>
- <title>Command lines</title>
-
- <para>This section describes command line parsing and
- variable and specifier substitions for
- <varname>ExecStart=</varname>,
- <varname>ExecStartPre=</varname>,
- <varname>ExecStartPost=</varname>,
- <varname>ExecReload=</varname>,
- <varname>ExecStop=</varname>, and
- <varname>ExecStopPost=</varname> options.</para>
-
- <para>Multiple command lines may be concatenated in a
- single directive by separating them with semicolons
- (these semicolons must be passed as separate words).
- Lone semicolons may be escaped as
- <literal>\;</literal>.</para>
-
- <para>Each command line is split on whitespace, with
- the first item being the command to execute, and the
- subsequent items being the arguments. Double quotes
- ("...") and single quotes ('...') may be used, in
- which case everything until the next matching quote
- becomes part of the same argument. Quotes themselves
- are removed after parsing. 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 line accepts <literal>%</literal>
- specifiers as described in
- <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
- Note that the first argument of the command line
- (i.e. the program to execute) may not include
- specifiers.</para>
-
- <para>Basic environment variable substitution is
- supported. Use <literal>${FOO}</literal> as part of a
- word, or as a word of its own, on the command line, in
- which case it will be replaced by the value of the
- environment variable including all whitespace it
- contains, resulting in a single argument. Use
- <literal>$FOO</literal> as a separate word on the
- command line, in which case it will be replaced by the
- value of the environment variable split at whitespace
- resulting in zero or more arguments. For this type of
- expansion, quotes and respected when splitting into
- words, and afterwards removed.</para>
-
- <para>Example:</para>
-
- <programlisting>Environment="ONE=one" 'TWO=two two'
+ <refentryinfo>
+ <title>systemd.service</title>
+ <productname>systemd</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Lennart</firstname>
+ <surname>Poettering</surname>
+ <email>lennart@poettering.net</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>systemd.service</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>systemd.service</refname>
+ <refpurpose>Service unit configuration</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <para><filename><replaceable>service</replaceable>.service</filename></para>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>A unit configuration file whose name ends in
+ <filename>.service</filename> encodes information about a process
+ controlled and supervised by systemd.</para>
+
+ <para>This man page lists the configuration options specific to
+ this unit type. See
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for the common options of all unit configuration files. The common
+ configuration items are configured in the generic
+ <literal>[Unit]</literal> and <literal>[Install]</literal>
+ sections. The service specific configuration options are
+ configured in the <literal>[Service]</literal> section.</para>
+
+ <para>Additional options are listed in
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ which define the execution environment the commands are executed
+ in, and in
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ which define the way the processes of the service are terminated,
+ and in
+ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ which configure resource control settings for the processes of the
+ service.</para>
+
+ <para>Unless <varname>DefaultDependencies=</varname> is set to
+ <option>false</option>, service units will implicitly have
+ dependencies of type <varname>Requires=</varname> and
+ <varname>After=</varname> on <filename>basic.target</filename> as
+ well as dependencies of type <varname>Conflicts=</varname> and
+ <varname>Before=</varname> on
+ <filename>shutdown.target</filename>. These ensure that normal
+ service units pull in basic system initialization, and are
+ terminated cleanly prior to system shutdown. Only services
+ involved with early boot or late system shutdown should disable
+ this option.</para>
+
+ <para>If a service is requested under a certain name but no unit
+ configuration file is found, systemd looks for a SysV init script
+ by the same name (with the <filename>.service</filename> suffix
+ removed) and dynamically creates a service unit from that script.
+ This is useful for compatibility with SysV. Note that this
+ compatibility is quite comprehensive but not 100%. For details
+ about the incompatibilities, see the <ulink
+ url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
+ with SysV</ulink> document.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Options</title>
+
+ <para>Service files must include a <literal>[Service]</literal>
+ section, which carries information about the service and the
+ process it supervises. A number of options that may be used in
+ this section are shared with other unit types. These options are
+ documented in
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ The options specific to the <literal>[Service]</literal> section
+ of service units are the following:</para>
+
+ <variablelist class='unit-directives'>
+ <varlistentry>
+ <term><varname>Type=</varname></term>
+
+ <listitem><para>Configures the process start-up type for this
+ service unit. One of
+ <option>simple</option>,
+ <option>forking</option>,
+ <option>oneshot</option>,
+ <option>dbus</option>,
+ <option>notify</option> or
+ <option>idle</option>.</para>
+
+ <para>If set to <option>simple</option> (the default if
+ neither <varname>Type=</varname> nor
+ <varname>BusName=</varname>, but <varname>ExecStart=</varname>
+ are specified), it is expected that the process configured
+ with <varname>ExecStart=</varname> is the main process of the
+ service. In this mode, if the process offers functionality to
+ other processes on the system, its communication channels
+ should be installed before the daemon is started up (e.g.
+ sockets set up by systemd, via socket activation), as systemd
+ will immediately proceed starting follow-up units.</para>
+
+ <para>If set to <option>forking</option>, it is expected that
+ the process configured with <varname>ExecStart=</varname> will
+ call <function>fork()</function> as part of its start-up. The
+ parent process is expected to exit when start-up is complete
+ and all communication channels are set up. The child continues
+ to run as the main daemon process. This is the behavior of
+ traditional UNIX daemons. If this setting is used, it is
+ recommended to also use the <varname>PIDFile=</varname>
+ option, so that systemd can identify the main process of the
+ daemon. systemd will proceed with starting follow-up units as
+ soon as the parent process exits.</para>
+
+ <para>Behavior of <option>oneshot</option> is similar to
+ <option>simple</option>; however, it is expected that the
+ process has to exit before systemd starts follow-up units.
+ <varname>RemainAfterExit=</varname> is particularly useful for
+ this type of service. This is the implied default if neither
+ <varname>Type=</varname> or <varname>ExecStart=</varname> are
+ specified.</para>
+
+ <para>Behavior of <option>dbus</option> is similar to
+ <option>simple</option>; however, it is expected that the
+ daemon acquires a name on the D-Bus bus, as configured by
+ <varname>BusName=</varname>. systemd will proceed with
+ starting follow-up units after the D-Bus bus name has been
+ acquired. Service units with this option configured implicitly
+ gain dependencies on the <filename>dbus.socket</filename>
+ unit. This type is the default if <varname>BusName=</varname>
+ is specified.</para>
+
+ <para>Behavior of <option>notify</option> is similar to
+ <option>simple</option>; however, it is expected that the
+ daemon sends a notification message via
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ or an equivalent call when it has finished starting up.
+ systemd will proceed with starting follow-up units after this
+ notification message has been sent. If this option is used,
+ <varname>NotifyAccess=</varname> (see below) should be set to
+ open access to the notification socket provided by systemd. If
+ <varname>NotifyAccess=</varname> is not set, it will be
+ implicitly set to <option>main</option>. Note that currently
+ <varname>Type=</varname><option>notify</option> will not work
+ if used in combination with
+ <varname>PrivateNetwork=</varname><option>yes</option>.</para>
+
+ <para>Behavior of <option>idle</option> is very similar to
+ <option>simple</option>; however, actual execution of the
+ service binary is delayed until all jobs are dispatched. This
+ may be used to avoid interleaving of output of shell services
+ with the status output on the console.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RemainAfterExit=</varname></term>
+
+ <listitem><para>Takes a boolean value that specifies whether
+ the service shall be considered active even when all its
+ processes exited. Defaults to <option>no</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>GuessMainPID=</varname></term>
+
+ <listitem><para>Takes a boolean value that specifies whether
+ systemd should try to guess the main PID of a service if it
+ cannot be determined reliably. This option is ignored unless
+ <option>Type=forking</option> is set and
+ <option>PIDFile=</option> is unset because for the other types
+ or with an explicitly configured PID file, the main PID is
+ always known. The guessing algorithm might come to incorrect
+ conclusions if a daemon consists of more than one process. If
+ the main PID cannot be determined, failure detection and
+ automatic restarting of a service will not work reliably.
+ Defaults to <option>yes</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>PIDFile=</varname></term>
+
+ <listitem><para>Takes an absolute file name pointing to the
+ PID file of this daemon. Use of this option is recommended for
+ services where <varname>Type=</varname> is set to
+ <option>forking</option>. systemd will read the PID of the
+ main process of the daemon after start-up of the service.
+ systemd will not write to the file configured here.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>BusName=</varname></term>
+
+ <listitem><para>Takes a D-Bus bus name that this service is
+ reachable as. This option is mandatory for services where
+ <varname>Type=</varname> is set to
+ <option>dbus</option>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>BusPolicy=</varname></term>
+
+ <listitem><para>If specified, a custom
+ <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>
+ endpoint will be created and installed as the default bus node
+ for the service. Such a custom endpoint can hold an own set of
+ policy rules that are enforced on top of the bus-wide ones.
+ The custom endpoint is named after the service it was created
+ for, and its node will be bind-mounted over the default bus
+ node location, so the service can only access the bus through
+ its own endpoint. Note that custom bus endpoints default to a
+ 'deny all' policy. Hence, if at least one
+ <varname>BusPolicy=</varname> directive is given, you have to
+ make sure to add explicit rules for everything the service
+ should be able to do.</para>
+ <para>The value of this directive is comprised
+ of two parts; the bus name, and a verb to
+ specify to granted access, which is one of
+ <option>see</option>,
+ <option>talk</option>, or
+ <option>own</option>.
+ <option>talk</option> implies
+ <option>see</option>, and <option>own</option>
+ implies both <option>talk</option> and
+ <option>see</option>.
+ If multiple access levels are specified for the
+ same bus name, the most powerful one takes
+ effect.
+ </para>
+ <para>Examples:</para>
+ <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>
+ <programlisting>BusPolicy=org.foo.bar see</programlisting>
+ <para>This option is only available on kdbus enabled systems.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ExecStart=</varname></term>
+ <listitem><para>Commands with their arguments that are
+ executed when this service is started. The value is split into
+ zero or more command lines is according to the rules described
+ below (see section "Command Lines" below).
+ </para>
+
+ <para>When <varname>Type</varname> is not
+ <option>oneshot</option>, only one command may and must be
+ given. When <varname>Type=oneshot</varname> is used, zero or
+ more commands may be specified. This can be specified by
+ providing multiple command lines in the same directive, or
+ alternatively, this directive may be specified more than once
+ with the same effect. If the empty string is assigned to this
+ option, the list of commands to start is reset, prior
+ assignments of this option will have no effect. If no
+ <varname>ExecStart=</varname> is specified, then the service
+ must have <varname>RemainAfterExit=yes</varname> set.</para>
+
+ <para>For each of the specified commands, the first argument
+ must be an absolute path to an executable. Optionally, if this
+ file name is prefixed with <literal>@</literal>, the second
+ token will be passed as <literal>argv[0]</literal> to the
+ executed process, followed by the further arguments specified.
+ If the absolute filename is prefixed with
+ <literal>-</literal>, an exit code of the command normally
+ considered a failure (i.e. non-zero exit status or abnormal
+ exit due to signal) is ignored and considered success. If both
+ <literal>-</literal> and <literal>@</literal> are used, they
+ can appear in either order.</para>
+
+ <para>If more than one command is specified, the commands are
+ invoked sequentially in the order they appear in the unit
+ file. If one of the commands fails (and is not prefixed with
+ <literal>-</literal>), other lines are not executed, and the
+ unit is considered failed.</para>
+
+ <para>Unless <varname>Type=forking</varname> is set, the
+ process started via this command line will be considered the
+ main process of the daemon.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ExecStartPre=</varname></term>
+ <term><varname>ExecStartPost=</varname></term>
+ <listitem><para>Additional commands that are executed before
+ or after the command in <varname>ExecStart=</varname>,
+ respectively. Syntax is the same as for
+ <varname>ExecStart=</varname>, except that multiple command
+ lines are allowed and the commands are executed one after the
+ other, serially.</para>
+
+ <para>If any of those commands (not prefixed with
+ <literal>-</literal>) fail, the rest are not executed and the
+ unit is considered failed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ExecReload=</varname></term>
+ <listitem><para>Commands to execute to trigger a configuration
+ reload in the service. This argument takes multiple command
+ lines, following the same scheme as described for
+ <varname>ExecStart=</varname> above. Use of this setting is
+ optional. Specifier and environment variable substitution is
+ supported here following the same scheme as for
+ <varname>ExecStart=</varname>.</para>
+
+ <para>One additional, special environment variable is set: if
+ known, <varname>$MAINPID</varname> is set to the main process
+ of the daemon, and may be used for command lines like the
+ following:</para>
+
+ <programlisting>/bin/kill -HUP $MAINPID</programlisting>
+
+ <para>Note however that reloading a daemon by sending a signal
+ (as with the example line above) is usually not a good choice,
+ because this is an asynchronous operation and hence not
+ suitable to order reloads of multiple services against each
+ other. It is strongly recommended to set
+ <varname>ExecReload=</varname> to a command that not only
+ triggers a configuration reload of the daemon, but also
+ synchronously waits for it to complete.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ExecStop=</varname></term>
+ <listitem><para>Commands to execute to stop the service
+ started via <varname>ExecStart=</varname>. This argument takes
+ multiple command lines, following the same scheme as described
+ for <varname>ExecStart=</varname> above. Use of this setting
+ is optional. After the commands configured in this option are
+ run, all processes remaining for a service are terminated
+ according to the <varname>KillMode=</varname> setting (see
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+ If this option is not specified, the process is terminated
+ immediately when service stop is requested. Specifier and
+ environment variable substitution is supported (including
+ <varname>$MAINPID</varname>, see above).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ExecStopPost=</varname></term>
+ <listitem><para>Additional commands that are executed after
+ the service was stopped. This includes cases where the
+ commands configured in <varname>ExecStop=</varname> were used,
+ where the service does not have any
+ <varname>ExecStop=</varname> defined, or where the service
+ exited unexpectedly. This argument takes multiple command
+ lines, following the same scheme as described for
+ <varname>ExecStart</varname>. Use of these settings is
+ optional. Specifier and environment variable substitution is
+ supported.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RestartSec=</varname></term>
+ <listitem><para>Configures the time to sleep before restarting
+ a service (as configured with <varname>Restart=</varname>).
+ Takes a unit-less value in seconds, or a time span value such
+ as "5min 20s". Defaults to 100ms.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>TimeoutStartSec=</varname></term>
+ <listitem><para>Configures the time to wait for start-up. If a
+ daemon service does not signal start-up completion within the
+ configured time, the service will be considered failed and
+ will be shut down again. Takes a unit-less value in seconds,
+ or a time span value such as "5min 20s". Pass
+ <literal>0</literal> to disable the timeout logic. Defaults to
+ <varname>DefaultTimeoutStartSec=</varname> from the manager
+ configuration file, except when
+ <varname>Type=oneshot</varname> is used, in which case the
+ timeout is disabled by default (see
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>TimeoutStopSec=</varname></term>
+ <listitem><para>Configures the time to wait for stop. If a
+ service is asked to stop, but does not terminate in the
+ specified time, it will be terminated forcibly via
+ <constant>SIGTERM</constant>, and after another timeout of
+ equal duration with <constant>SIGKILL</constant> (see
+ <varname>KillMode=</varname> in
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+ Takes a unit-less value in seconds, or a time span value such
+ as "5min 20s". Pass <literal>0</literal> to disable the
+ timeout logic. Defaults to
+ <varname>DefaultTimeoutStopSec=</varname> from the manager
+ configuration file (see
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>TimeoutSec=</varname></term>
+ <listitem><para>A shorthand for configuring both
+ <varname>TimeoutStartSec=</varname> and
+ <varname>TimeoutStopSec=</varname> to the specified value.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>WatchdogSec=</varname></term>
+ <listitem><para>Configures the watchdog timeout for a service.
+ The watchdog is activated when the start-up is completed. The
+ service must call
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ regularly with <literal>WATCHDOG=1</literal> (i.e. the
+ "keep-alive ping"). If the time between two such calls is
+ larger than the configured time, then the service is placed in
+ a failed state and it will be terminated with
+ <varname>SIGABRT</varname>. By setting
+ <varname>Restart=</varname> to <option>on-failure</option> or
+ <option>always</option>, the service will be automatically
+ restarted. The time configured here will be passed to the
+ executed service process in the
+ <varname>WATCHDOG_USEC=</varname> environment variable. This
+ allows daemons to automatically enable the keep-alive pinging
+ logic if watchdog support is enabled for the service. If this
+ option is used, <varname>NotifyAccess=</varname> (see below)
+ should be set to open access to the notification socket
+ provided by systemd. If <varname>NotifyAccess=</varname> is
+ not set, it will be implicitly set to <option>main</option>.
+ Defaults to 0, which disables this feature.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Restart=</varname></term>
+ <listitem><para>Configures whether the service shall be
+ restarted when the service process exits, is killed, or a
+ timeout is reached. The service process may be the main
+ service process, but it may also be one of the processes
+ specified with <varname>ExecStartPre=</varname>,
+ <varname>ExecStartPost=</varname>,
+ <varname>ExecStop=</varname>,
+ <varname>ExecStopPost=</varname>, or
+ <varname>ExecReload=</varname>. When the death of the process
+ is a result of systemd operation (e.g. service stop or
+ restart), the service will not be restarted. Timeouts include
+ missing the watchdog "keep-alive ping" deadline and a service
+ start, reload, and stop operation timeouts.</para>
+
+ <para>Takes one of
+ <option>no</option>,
+ <option>on-success</option>,
+ <option>on-failure</option>,
+ <option>on-abnormal</option>,
+ <option>on-watchdog</option>,
+ <option>on-abort</option>, or
+ <option>always</option>.
+ If set to <option>no</option> (the default), the service will
+ not be restarted. If set to <option>on-success</option>, it
+ will be restarted only when the service process exits cleanly.
+ In this context, a clean exit means an exit code of 0, or one
+ of the signals
+ <constant>SIGHUP</constant>,
+ <constant>SIGINT</constant>,
+ <constant>SIGTERM</constant> or
+ <constant>SIGPIPE</constant>, and
+ additionally, exit statuses and signals specified in
+ <varname>SuccessExitStatus=</varname>. If set to
+ <option>on-failure</option>, the service will be restarted
+ when the process exits with a non-zero exit code, is
+ terminated by a signal (including on core dump, but excluding
+ the aforementiond four signals), when an operation (such as
+ service reload) times out, and when the configured watchdog
+ timeout is triggered. If set to <option>on-abnormal</option>,
+ the service will be restarted when the process is terminated
+ by a signal (including on core dump, excluding the
+ aforementioned four signals), when an operation times out, or
+ when the watchdog timeout is triggered. If set to
+ <option>on-abort</option>, the service will be restarted only
+ if the service process exits due to an uncaught signal not
+ specified as a clean exit status. If set to
+ <option>on-watchdog</option>, the service will be restarted
+ only if the watchdog timeout for the service expires. If set
+ to <option>always</option>, the service will be restarted
+ regardless of whether it exited cleanly or not, got terminated
+ abnormally by a signal, or hit a timeout.</para>
+
+ <table>
+ <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>
+
+ <tgroup cols='2'>
+ <colspec colname='path' />
+ <colspec colname='expl' />
+ <thead>
+ <row>
+ <entry>Restart settings/Exit causes</entry>
+ <entry><option>no</option></entry>
+ <entry><option>always</option></entry>
+ <entry><option>on-success</option></entry>
+ <entry><option>on-failure</option></entry>
+ <entry><option>on-abnormal</option></entry>
+ <entry><option>on-abort</option></entry>
+ <entry><option>on-watchdog</option></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Clean exit code or signal</entry>
+ <entry/>
+ <entry>X</entry>
+ <entry>X</entry>
+ <entry/>
+ <entry/>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>Unclean exit code</entry>
+ <entry/>
+ <entry>X</entry>
+ <entry/>
+ <entry>X</entry>
+ <entry/>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>Unclean signal</entry>
+ <entry/>
+ <entry>X</entry>
+ <entry/>
+ <entry>X</entry>
+ <entry>X</entry>
+ <entry>X</entry>
+ <entry/>
+ </row>
+ <row>
+ <entry>Timeout</entry>
+ <entry/>
+ <entry>X</entry>
+ <entry/>
+ <entry>X</entry>
+ <entry>X</entry>
+ <entry/>
+ <entry/>
+ </row>
+ <row>
+ <entry>Watchdog</entry>
+ <entry/>
+ <entry>X</entry>
+ <entry/>
+ <entry>X</entry>
+ <entry>X</entry>
+ <entry/>
+ <entry>X</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>As exceptions to the setting above the service will not
+ be restarted if the exit code or signal is specified in
+ <varname>RestartPreventExitStatus=</varname> (see below).
+ Also, the services will always be restarted if the exit code
+ or signal is specified in
+ <varname>RestartForceExitStatus=</varname> (see below).</para>
+
+ <para>Setting this to <option>on-failure</option> is the
+ recommended choice for long-running services, in order to
+ increase reliability by attempting automatic recovery from
+ errors. For services that shall be able to terminate on their
+ own choice (and avoid immediate restarting),
+ <option>on-abnormal</option> is an alternative choice.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>SuccessExitStatus=</varname></term>
+ <listitem><para>Takes a list of exit status definitions that
+ when returned by the main service process will be considered
+ successful termination, in addition to the normal successful
+ exit code 0 and the signals <constant>SIGHUP</constant>,
+ <constant>SIGINT</constant>, <constant>SIGTERM</constant>, and
+ <constant>SIGPIPE</constant>. Exit status definitions can
+ either be numeric exit codes or termination signal names,
+ separated by spaces. For example:
+ <programlisting>SuccessExitStatus=1 2 8
+ SIGKILL</programlisting> ensures that exit codes 1, 2, 8 and
+ the termination signal <constant>SIGKILL</constant> are
+ considered clean service terminations.
+ </para>
+
+ <para>Note that if a process has a signal handler installed
+ and exits by calling
+ <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ in response to a signal, the information about the signal is
+ lost. Programs should instead perform cleanup and kill
+ themselves with the same signal instead. See
+ <ulink url="http://www.cons.org/cracauer/sigint.html">Proper
+ handling of SIGINT/SIGQUIT — How to be a proper
+ program</ulink>.</para>
+
+ <para>This option may appear more than once, in which case the
+ list of successful exit statuses is merged. If the empty
+ string is assigned to this option, the list is reset, all
+ prior assignments of this option will have no
+ effect.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RestartPreventExitStatus=</varname></term>
+ <listitem><para>Takes a list of exit status definitions that
+ when returned by the main service process will prevent
+ automatic service restarts, regardless of the restart setting
+ configured with <varname>Restart=</varname>. Exit status
+ definitions can either be numeric exit codes or termination
+ signal names, and are separated by spaces. Defaults to the
+ empty list, so that, by default, no exit status is excluded
+ from the configured restart logic. For example:
+ <programlisting>RestartPreventExitStatus=1 6
+ SIGABRT</programlisting> ensures that exit codes 1 and 6 and
+ the termination signal <constant>SIGABRT</constant> will not
+ result in automatic service restarting. This option may appear
+ more than once, in which case the list of restart-preventing
+ statuses is merged. If the empty string is assigned to this
+ option, the list is reset and all prior assignments of this
+ option will have no effect.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RestartForceExitStatus=</varname></term>
+ <listitem><para>Takes a list of exit status definitions that
+ when returned by the main service process will force automatic
+ service restarts, regardless of the restart setting configured
+ with <varname>Restart=</varname>. The argument format is
+ similar to
+ <varname>RestartPreventExitStatus=</varname>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>PermissionsStartOnly=</varname></term>
+ <listitem><para>Takes a boolean argument. If true, the
+ permission-related execution options, as configured with
+ <varname>User=</varname> and similar options (see
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for more information), are only applied to the process started
+ with
+ <varname>ExecStart=</varname>, and not to the various other
+ <varname>ExecStartPre=</varname>,
+ <varname>ExecStartPost=</varname>,
+ <varname>ExecReload=</varname>,
+ <varname>ExecStop=</varname>, and
+ <varname>ExecStopPost=</varname>
+ commands. If false, the setting is applied to all configured
+ commands the same way. Defaults to false.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RootDirectoryStartOnly=</varname></term>
+ <listitem><para>Takes a boolean argument. If true, the root
+ directory, as configured with the
+ <varname>RootDirectory=</varname> option (see
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for more information), is only applied to the process started
+ with <varname>ExecStart=</varname>, and not to the various
+ other <varname>ExecStartPre=</varname>,
+ <varname>ExecStartPost=</varname>,
+ <varname>ExecReload=</varname>, <varname>ExecStop=</varname>,
+ and <varname>ExecStopPost=</varname> commands. If false, the
+ setting is applied to all configured commands the same way.
+ Defaults to false.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>NonBlocking=</varname></term>
+ <listitem><para>Set the <constant>O_NONBLOCK</constant> flag
+ for all file descriptors passed via socket-based activation.
+ If true, all file descriptors >= 3 (i.e. all except stdin,
+ stdout, and stderr) will have the
+ <constant>O_NONBLOCK</constant> flag set and hence are in
+ non-blocking mode. This option is only useful in conjunction
+ with a socket unit, as described in
+ <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ Defaults to false.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>NotifyAccess=</varname></term>
+ <listitem><para>Controls access to the service status
+ notification socket, as accessible via the
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ call. Takes one of <option>none</option> (the default),
+ <option>main</option> or <option>all</option>. If
+ <option>none</option>, no daemon status updates are accepted
+ from the service processes, all status update messages are
+ ignored. If <option>main</option>, only service updates sent
+ from the main process of the service are accepted. If
+ <option>all</option>, all services updates from all members of
+ the service's control group are accepted. This option should
+ be set to open access to the notification socket when using
+ <varname>Type=notify</varname> or
+ <varname>WatchdogSec=</varname> (see above). If those options
+ are used but <varname>NotifyAccess=</varname> is not
+ configured, it will be implicitly set to
+ <option>main</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>Sockets=</varname></term>
+ <listitem><para>Specifies the name of the socket units this
+ service shall inherit socket file descriptors from when the
+ service is started. Normally it should not be necessary to use
+ this setting as all socket file descriptors whose unit shares
+ the same name as the service (subject to the different unit
+ name suffix of course) are passed to the spawned
+ process.</para>
+
+ <para>Note that the same socket file descriptors may be passed
+ to multiple processes simultaneously. Also note that a
+ different service may be activated on incoming socket traffic
+ than the one which is ultimately configured to inherit the
+ socket file descriptors. Or in other words: the
+ <varname>Service=</varname> setting of
+ <filename>.socket</filename> units does not have to match the
+ inverse of the <varname>Sockets=</varname> setting of the
+ <filename>.service</filename> it refers to.</para>
+
+ <para>This option may appear more than once, in which case the
+ list of socket units is merged. If the empty string is
+ assigned to this option, the list of sockets is reset, and all
+ prior uses of this setting will have no
+ effect.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>StartLimitInterval=</varname></term>
+ <term><varname>StartLimitBurst=</varname></term>
+
+ <listitem><para>Configure service start rate limiting. By
+ default, services which are started more than 5 times within
+ 10 seconds are not permitted to start any more times until the
+ 10 second interval ends. With these two options, this rate
+ limiting may be modified. Use
+ <varname>StartLimitInterval=</varname> to configure the
+ checking interval (defaults to
+ <varname>DefaultStartLimitInterval=</varname> in manager
+ configuration file, set to 0 to disable any kind of rate
+ limiting). Use <varname>StartLimitBurst=</varname> to
+ configure how many starts per interval are allowed (defaults
+ to <varname>DefaultStartLimitBurst=</varname> in manager
+ configuration file). These configuration options are
+ particularly useful in conjunction with
+ <varname>Restart=</varname>; however, they apply to all kinds
+ of starts (including manual), not just those triggered by the
+ <varname>Restart=</varname> logic. Note that units which are
+ configured for <varname>Restart=</varname> and which reach the
+ start limit are not attempted to be restarted anymore;
+ however, they may still be restarted manually at a later
+ point, from which point on, the restart logic is again
+ activated. Note that <command>systemctl reset-failed</command>
+ will cause the restart rate counter for a service to be
+ flushed, which is useful if the administrator wants to
+ manually start a service and the start limit interferes with
+ that.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>StartLimitAction=</varname></term>
+
+ <listitem><para>Configure the action to take if the rate limit
+ configured with <varname>StartLimitInterval=</varname> and
+ <varname>StartLimitBurst=</varname> is hit. Takes one of
+ <option>none</option>,
+ <option>reboot</option>,
+ <option>reboot-force</option>,
+ <option>reboot-immediate</option>,
+ <option>poweroff</option>,
+ <option>poweroff-force</option> or
+ <option>poweroff-immediate</option>. If
+ <option>none</option> is set, hitting the rate limit will
+ trigger no action besides that the start will not be
+ permitted. <option>reboot</option> causes a reboot following
+ the normal shutdown procedure (i.e. equivalent to
+ <command>systemctl reboot</command>).
+ <option>reboot-force</option> causes a forced reboot which
+ will terminate all processes forcibly but should cause no
+ dirty file systems on reboot (i.e. equivalent to
+ <command>systemctl reboot -f</command>) and
+ <option>reboot-immediate</option> causes immediate execution
+ of the
+ <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ system call, which might result in data loss. Similar,
+ <option>poweroff</option>, <option>poweroff-force</option>,
+ <option>poweroff-immediate</option> have the effect of
+ powering down the system with similar semantics. Defaults to
+ <option>none</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>FailureAction=</varname></term>
+ <listitem><para>Configure the action to take when the service
+ enters a failed state. Takes the same values as
+ <varname>StartLimitAction=</varname> and executes the same
+ actions. Defaults to <option>none</option>. </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RebootArgument=</varname></term>
+ <listitem><para>Configure the optional argument for the
+ <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ system call if <varname>StartLimitAction=</varname> or
+ <varname>FailureAction=</varname> is a reboot action. This
+ works just like the optional argument to <command>systemctl
+ reboot</command> command.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>FileDescriptorStoreMax=</varname></term>
+ <listitem><para>Configure how many file descriptors may be
+ stored in the service manager for the service using
+ <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
+ <literal>FDSTORE=1</literal> messages. This is useful for
+ implementing service restart schemes where the state is
+ serialized to <filename>/run</filename> and the file
+ descriptors passed to the service manager, to allow restarts
+ without losing state. Defaults to 0, i.e. no file descriptors
+ may be stored in the service manager by default. All file
+ descriptors passed to the service manager from a specific
+ service are passed back to the service's main process on the
+ next service restart. Any file descriptors passed to the
+ service manager are automatically closed when POLLHUP or
+ POLLERR is seen on them, or when the service is fully stopped
+ and no job queued or being executed for it.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>Check
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for more settings.</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Command lines</title>
+
+ <para>This section describes command line parsing and
+ variable and specifier substitions for
+ <varname>ExecStart=</varname>,
+ <varname>ExecStartPre=</varname>,
+ <varname>ExecStartPost=</varname>,
+ <varname>ExecReload=</varname>,
+ <varname>ExecStop=</varname>, and
+ <varname>ExecStopPost=</varname> options.</para>
+
+ <para>Multiple command lines may be concatenated in a single
+ directive by separating them with semicolons (these semicolons
+ must be passed as separate words). Lone semicolons may be escaped
+ as <literal>\;</literal>.</para>
+
+ <para>Each command line is split on whitespace, with the first
+ item being the command to execute, and the subsequent items being
+ the arguments. Double quotes ("...") and single quotes ('...') may
+ be used, in which case everything until the next matching quote
+ becomes part of the same argument. C-style escapes are also
+ supported, see table below. Quotes themselves are removed after
+ parsing and escape sequences substituted. In addition, a trailing
+ backslash (<literal>\</literal>) may be used to merge lines.
+ </para>
+
+ <para>This syntax is intended to be very similar to shell syntax,
+ but only the meta-characters and expansions described in the
+ following paragraphs are understood. Specifically, redirection
+ using
+ <literal><</literal>,
+ <literal><<</literal>,
+ <literal>></literal>, and
+ <literal>>></literal>, pipes using
+ <literal>|</literal>, running programs in the background using
+ <literal>&</literal>, and <emphasis>other elements of shell
+ syntax are not supported</emphasis>.</para>
+
+ <para>The command to execute must an absolute path name. It may
+ contain spaces, but control characters are not allowed.</para>
+
+ <para>The command line accepts <literal>%</literal> specifiers as
+ described in
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ Note that the first argument of the command line (i.e. the program
+ to execute) may not include specifiers.</para>
+
+ <para>Basic environment variable substitution is supported. Use
+ <literal>${FOO}</literal> as part of a word, or as a word of its
+ own, on the command line, in which case it will be replaced by the
+ value of the environment variable including all whitespace it
+ contains, resulting in a single argument. Use
+ <literal>$FOO</literal> as a separate word on the command line, in
+ which case it will be replaced by the value of the environment
+ variable split at whitespace resulting in zero or more arguments.
+ For this type of expansion, quotes and respected when splitting
+ into words, and afterwards removed.</para>
+
+ <para>Example:</para>
+
+ <programlisting>Environment="ONE=one" 'TWO=two two'
ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
- <para>This will execute <command>/bin/echo</command>
- with four arguments: <literal>one</literal>,
- <literal>two</literal>, <literal>two</literal>, and
- <literal>two two</literal>.</para>
+ <para>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>
-
<programlisting>Environment=ONE='one' "TWO='two two' too" THREE=
+ <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 & \; \
+ <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>
- </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>
+ <para>This will execute <command>/bin/echo</command>
+ with five arguments: <literal>/</literal>,
+ <literal>>/dev/null</literal>,
+ <literal>&</literal>, <literal>;</literal>, and
+ <literal>/bin/ls</literal>.</para>
+
+ <table>
+ <title>C escapes supported in command lines and environment variables</title>
+ <tgroup cols='2'>
+ <colspec colname='escape' />
+ <colspec colname='meaning' />
+ <thead>
+ <row>
+ <entry>Literal</entry>
+ <entry>Actual value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>\a</literal></entry>
+ <entry>bell</entry>
+ </row>
+ <row>
+ <entry><literal>\b</literal></entry>
+ <entry>backspace</entry>
+ </row>
+ <row>
+ <entry><literal>\f</literal></entry>
+ <entry>form feed</entry>
+ </row>
+ <row>
+ <entry><literal>\n</literal></entry>
+ <entry>newline</entry>
+ </row>
+ <row>
+ <entry><literal>\r</literal></entry>
+ <entry>carriage return</entry>
+ </row>
+ <row>
+ <entry><literal>\t</literal></entry>
+ <entry>tab</entry>
+ </row>
+ <row>
+ <entry><literal>\v</literal></entry>
+ <entry>vertical tab</entry>
+ </row>
+ <row>
+ <entry><literal>\\</literal></entry>
+ <entry>backslash</entry>
+ </row>
+ <row>
+ <entry><literal>\"</literal></entry>
+ <entry>double quotation mark</entry>
+ </row>
+ <row>
+ <entry><literal>\'</literal></entry>
+ <entry>single quotation mark</entry>
+ </row>
+ <row>
+ <entry><literal>\s</literal></entry>
+ <entry>space</entry>
+ </row>
+ <row>
+ <entry><literal>\x<replaceable>xx</replaceable></literal></entry>
+ <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
+ </row>
+ <row>
+ <entry><literal>\<replaceable>nnn</replaceable></literal></entry>
+ <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+
+ <example>
+ <title>Simple service</title>
+
+ <para>The following unit file creates a service that will
+ execute <filename>/usr/sbin/foo-daemon</filename>. Since no
+ <varname>Type=</varname> is specified, the default
+ <varname>Type=</varname><option>simple</option> will be assumed.
+ systemd will assume the unit to be started immediately after the
+ program has begun executing.</para>
+
+ <programlisting>[Unit]
+Description=Foo
+
+[Service]
+ExecStart=/usr/sbin/foo-daemon
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>Note that systemd assumes here that the process started by
+ systemd will continue running until the service terminates. If
+ the program daemonizes itself (i.e. forks), please use
+ <varname>Type=</varname><option>forking</option> instead.</para>
+
+ <para>Since no <varname>ExecStop=</varname> was specified,
+ systemd will send SIGTERM to all processes started from this
+ service, and after a timeout also SIGKILL. This behavior can be
+ modified, see
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details.</para>
+
+ <para>Note that this unit type does not include any type of
+ notification when a service has completed initialization. For
+ this, you should use other unit types, such as
+ <varname>Type=</varname><option>notify</option> if the service
+ understands systemd's notification protocol,
+ <varname>Type=</varname><option>forking</option> if the service
+ can background itself or
+ <varname>Type=</varname><option>dbus</option> if the unit
+ acquires a DBus name once initialization is complete. See
+ below.</para>
+ </example>
+
+ <example>
+ <title>Oneshot service</title>
+
+ <para>Sometimes units should just execute an action without
+ keeping active processes, such as a filesystem check or a
+ cleanup action on boot. For this,
+ <varname>Type=</varname><option>oneshot</option> exists. Units
+ of this type will wait until the process specified terminates
+ and then fall back to being inactive. The following unit will
+ perform a clenaup action:</para>
+
+ <programlisting>[Unit]
+Description=Cleanup old Foo data
+
+[Service]
+Type=oneshot
+ExecStart=/usr/sbin/foo-cleanup
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>Note that systemd will consider the unit to be in the
+ state 'starting' until the program has terminated, so ordered
+ dependencies will wait for the program to finish before starting
+ themselves. The unit will revert to the 'inactive' state after
+ the execution is done, never reaching the 'active' state. That
+ means another request to start the unit will perform the action
+ again.</para>
+
+ <para><varname>Type=</varname><option>oneshot</option> are the
+ only service units that may have more than one
+ <varname>ExecStart=</varname> specified. They will be executed
+ in order until either they are all successful or one of them
+ fails.</para>
+ </example>
+
+ <example>
+ <title>Stoppable oneshot service</title>
+
+ <para>Similarly to the oneshot services, there are sometimes
+ units that need to execute a program to set up something and
+ then execute another to shut it down, but no process remains
+ active while they are considered 'started'. Network
+ configuration can sometimes fall into this category. Another use
+ case is if a oneshot service shall not be executed a each time
+ when they are pulled in as a dependency, but only the first
+ time.</para>
+
+ <para>For this, systemd knows the setting
+ <varname>RemainAfterExit=</varname><option>yes</option>, which
+ causes systemd to consider the unit to be active if the start
+ action exited successfully. This directive can be used with all
+ types, but is most useful with
+ <varname>Type=</varname><option>oneshot</option> and
+ <varname>Type=</varname><option>simple</option>. With
+ <varname>Type=</varname><option>oneshot</option> systemd waits
+ until the start action has completed before it considers the
+ unit to be active, so dependencies start only after the start
+ action has succeeded. With
+ <varname>Type=</varname><option>simple</option> dependencies
+ will start immediately after the start action has been
+ dispatched. The following unit provides an example for a simple
+ static firewall.</para>
+
+ <programlisting>[Unit]
+Description=Simple firewall
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/local/sbin/simple-firewall-start
+ExecStop=/usr/local/sbin/simple-firewall-stop
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>Since the unit is considered to be running after the start
+ action has exited, invoking <command>systemctl start</command>
+ on that unit again will cause no action to be taken.</para>
+ </example>
+
+ <example>
+ <title>Traditional forking services</title>
+
+ <para>Many traditional daemons/services background (i.e. fork,
+ daemonize) themselves when starting. Set
+ <varname>Type=</varname><option>forking</option> in the
+ service's unit file to support this mode of operation. systemd
+ will consider the service to be in the process of initialization
+ while the original program is still running. Once it exits
+ successfully and at least a process remains (and
+ <varname>RemainAfterExit=</varname><option>no</option>), the
+ service is considered started.</para>
+
+ <para>Often a traditional daemon only consists of one process.
+ Therefore, if only one process is left after the original
+ process terminates, systemd will consider that process the main
+ process of the service. In that case, the
+ <varname>$MAINPID</varname> variable will be available in
+ <varname>ExecReload=</varname>, <varname>ExecStop=</varname>,
+ etc.</para>
+
+ <para>In case more than one process remains, systemd will be
+ unable to determine the main process, so it will not assume
+ there is one. In that case, <varname>$MAINPID</varname> will not
+ expand to anything. However, if the process decides to write a
+ traditional PID file, systemd will be able to read the main PID
+ from there. Please set <varname>PIDFile=</varname> accordingly.
+ Note that the daemon should write that file before finishing
+ with its initialization, otherwise systemd might try to read the
+ file before it exists.</para>
+
+ <para>The following example shows a simple daemon that forks and
+ just starts one process in the background:</para>
+
+ <programlisting>[Unit]
+Description=Some simple daemon
+
+[Service]
+Type=forking
+ExecStart=/usr/sbin/my-simple-daemon -d
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>Please see
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details on how you can influence the way systemd terminates
+ the service.</para>
+ </example>
+
+ <example>
+ <title>DBus services</title>
+
+ <para>For services that acquire a name on the DBus system bus,
+ use <varname>Type=</varname><option>dbus</option> and set
+ <varname>BusName=</varname> accordingly. The service should not
+ fork (daemonize). systemd will consider the service to be
+ initialized once the name has been acquired on the system bus.
+ The following example shows a typical DBus service:</para>
+
+ <programlisting>[Unit]
+Description=Simple DBus service
+
+[Service]
+Type=dbus
+BusName=org.example.simple-dbus-service
+ExecStart=/usr/sbin/simple-dbus-service
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>For <emphasis>bus-activatable</emphasis> services, don't
+ include a <literal>[Install]</literal> section in the systemd
+ service file, but use the <varname>SystemdService=</varname>
+ option in the corresponding DBus service file, for example
+ (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para>
+
+ <programlisting>[D-BUS Service]
+Name=org.example.simple-dbus-service
+Exec=/usr/sbin/simple-dbus-service
+User=root
+SystemdService=simple-dbus-service.service</programlisting>
+
+ <para>Please see
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details on how you can influence the way systemd terminates
+ the service.</para>
+ </example>
+
+ <example>
+ <title>Services that notify systemd about their initialization</title>
+
+ <para><varname>Type=</varname><option>simple</option> services
+ are really easy to write, but have the major disadvantage of
+ systemd not being able to tell when initialization of the given
+ service is complete. For this reason, systemd supports a simple
+ notification protocol that allows daemons to make systemd aware
+ that they are done initializing. Use
+ <varname>Type=</varname><option>notify</option> for this. A
+ typical service file for such a daemon would look like
+ this:</para>
+
+ <programlisting>[Unit]
+Description=Simple notifying service
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/simple-notifying-service
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+ <para>Note that the daemon has to support systemd's notification
+ protocol, else systemd will think the service hasn't started yet
+ and kill it after a timeout. For an example of how to update
+ daemons to support this protocol transparently, take a look at
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ systemd will consider the unit to be in the 'starting' state
+ until a readiness notification has arrived.</para>
+
+ <para>Please see
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details on how you can influence the way systemd terminates
+ the service.</para>
+ </example>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ </para>
+ </refsect1>
</refentry>
~ianmdlvl / elogind.git / blobdiff