chiark / gitweb /
networkd: support vxlan parameters
[elogind.git] / man / systemd.service.xml
index be9bdca..da9079c 100644 (file)
 
                                 <para>If set to
                                 <option>simple</option> (the default
-                                value if neither
+                                if neither
                                 <varname>Type=</varname> nor
-                                <varname>BusName=</varname> are
+                                <varname>BusName=</varname>, but
+                                <varname>ExecStart=</varname> are
                                 specified), it is expected that the
                                 process configured with
                                 <varname>ExecStart=</varname> is the
                                 exits.</para>
 
                                 <para>Behavior of
-                                <option>oneshot</option> is similar
-                                to <option>simple</option>; however,
-                                it is expected that the process has to
+                                <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.</para>
+                                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
                                 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>
+                                <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>
 
                                 <term><varname>ExecStart=</varname></term>
                                 <listitem><para>Commands with their
                                 arguments that are executed when this
-                                service is started. For each of the
-                                specified commands, the first argument
-                                must be an absolute and literal path
-                                to an executable.</para>
+                                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 be given. When
+                                command may and must be given. When
                                 <varname>Type=oneshot</varname> is
-                                used, more than one command may be
-                                specified. Multiple command lines may
-                                be concatenated in a single directive
-                                by separating them with semicolons
-                                (these semicolons must be passed as
-                                separate words). Alternatively, this
-                                directive may be specified more than
-                                once with the same effect.
-                                Lone semicolons may be escaped as
-                                <literal>\;</literal>. If the empty
-                                string is assigned to this option, the
-                                list of commands to start is reset,
-                                prior assignments of this option will
-                                have no effect.</para>
-
-                                <para>Each command line is split on
-                                whitespace, with the first item being
-                                the command to execute, and the
-                                subsequent items being the arguments.
-                                Double quotes ("...") and single
-                                quotes ('...') may be used, in which
-                                case everything until the next
-                                matching quote becomes part of the
-                                same argument. Quotes themselves are
-                                removed after parsing. In addition, a
-                                trailing backslash
-                                (<literal>\</literal>) may be used to
-                                merge lines. This syntax is intended
-                                to be very similar to shell syntax,
-                                but only the meta-characters and
-                                expansions described in the following
-                                paragraphs are understood.
-                                Specifically, redirection using
-                                <literal>&lt;</literal>,
-                                <literal>&lt;&lt;</literal>,
-                                <literal>&gt;</literal>, and
-                                <literal>&gt;&gt;</literal>, pipes
-                                using <literal>|</literal>, and
-                                running programs in the background
-                                using <literal>&amp;</literal>
-                                and <emphasis>other elements of shell
-                                syntax are not supported</emphasis>.
-                                </para>
+                                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>
+                                with <literal>-</literal>), other
+                                lines are not executed, and the unit
+                                is considered failed.</para>
 
                                 <para>Unless
                                 <varname>Type=forking</varname> is
                                 command line will be considered the
                                 main process of the daemon.</para>
 
-                                <para>The command line accepts
-                                <literal>%</literal> specifiers as
-                                described in
-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-                                Note that the first argument of the
-                                command line (i.e. the program to
-                                execute) may not include
-                                specifiers.</para>
-
-                                <para>Basic environment variable
-                                substitution is supported. Use
-                                <literal>${FOO}</literal> as part of a
-                                word, or as a word of its own, on the
-                                command line, in which case it will be
-                                replaced by the value of the
-                                environment variable including all
-                                whitespace it contains, resulting in a
-                                single argument. Use
-                                <literal>$FOO</literal> as a separate
-                                word on the command line, in which
-                                case it will be replaced by the value
-                                of the environment variable split at
-                                whitespace, resulting in zero or more
-                                arguments. To pass a literal dollar
-                                sign, use <literal>$$</literal>.
-                                Variables whose value is not known at
-                                expansion time are treated as empty
-                                strings. Note that the first argument
-                                (i.e. the program to execute) may not
-                                be a variable.</para>
-
-                                <para>Variables to be used in this
-                                fashion may be defined through
-                                <varname>Environment=</varname> and
-                                <varname>EnvironmentFile=</varname>.
-                                In addition, variables listed in the
-                                section "Environment variables in
-                                spawned processes" in
-                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                                which are considered "static
-                                configuration", may be used (this includes
-                                e.g. <varname>$USER</varname>, but not
-                                <varname>$TERM</varname>).</para>
-
-                                <para>Optionally, if the absolute file
-                                name is prefixed with
-                                <literal>@</literal>, the second token
-                                will be passed as
-                                <literal>argv[0]</literal> to the
-                                executed process, followed by the
-                                further arguments specified. If the
-                                absolute filename is prefixed with
-                                <literal>-</literal>, an exit code of
-                                the command normally considered a
-                                failure (i.e. non-zero exit status or
-                                abnormal exit due to signal) is ignored
-                                and considered success. If both
-                                <literal>-</literal> and
-                                <literal>@</literal> are used, they
-                                can appear in either order.</para>
-
-                                <para>Note that this setting does not
-                                directly support shell command
-                                lines. If shell command lines are to
-                                be used, they need to be passed
-                                explicitly to a shell implementation
-                                of some kind. Example:</para>
-                                <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>
-                                <para>Example:</para>
-                                <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
-                                <para>This will execute
-                                <command>/bin/echo</command> two
-                                times, each time with one argument:
-                                <literal>one</literal> and
-                                <literal>two two</literal>,
-                                respectively. Because two commands are
-                                specified,
-                                <varname>Type=oneshot</varname> must
-                                be used.</para>
-
-                                <para>Example:</para>
-                                <programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \
-/bin/ls</programlisting>
-                                <para>This will execute
-                                <command>/bin/echo</command> with five
-                                arguments: <literal>/</literal>,
-                                <literal>&gt;/dev/null</literal>,
-                                <literal>&amp;</literal>,
-                                <literal>;</literal>, and
-                                <literal>/bin/ls</literal>.</para>
-
-                                <para>Example:</para>
-                                <programlisting>Environment="ONE=one" 'TWO=two two'
-ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
-                                <para>This will execute
-                                <command>/bin/echo</command> with four
-                                arguments: <literal>one</literal>,
-                                <literal>two</literal>,
-                                <literal>two</literal>, and
-                                <literal>two two</literal>.</para>
                               </listitem>
                         </varlistentry>
 
@@ -519,6 +455,20 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 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>
 
@@ -591,11 +541,12 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 time span value such as "5min
                                 20s". Pass <literal>0</literal> to
                                 disable the timeout logic. Defaults to
-                                <varname>TimeoutStartSec=</varname> from
+                                <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.
+                                is disabled by default
+                                (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                 </para></listitem>
                         </varlistentry>
 
@@ -614,8 +565,9 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 time span value such as "5min
                                 20s". Pass <literal>0</literal> to disable
                                 the timeout logic. Defaults to
-                                <varname>TimeoutStartSec=</varname> from the
-                                manager configuration file.
+                                <varname>DefaultTimeoutStopSec=</varname> from the
+                                manager configuration file
+                                (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                 </para></listitem>
                         </varlistentry>
 
@@ -639,8 +591,9 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 (i.e. the "keep-alive ping"). If the time
                                 between two such calls is larger than
                                 the configured time, then the service
-                                is placed in a failed state. By
-                                setting <varname>Restart=</varname> to
+                                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
@@ -674,7 +627,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 processes specified with
                                 <varname>ExecStartPre=</varname>,
                                 <varname>ExecStartPost=</varname>,
-                                <varname>ExecStopPre=</varname>,
+                                <varname>ExecStop=</varname>,
                                 <varname>ExecStopPost=</varname>, or
                                 <varname>ExecReload=</varname>.
                                 When the death of the process is a
@@ -689,51 +642,151 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <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
+                                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>.
+                                <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), when an operation (such as
-                                service reload) times out, and when the
-                                configured watchdog timeout is triggered.
-                                If set to
-                                <option>on-abort</option>, the service
-                                will be restarted only if the service
-                                process exits due to an uncaught
-                                signal not specified as a clean exit
-                                status.
-                                If set to
-                                <option>on-watchdog</option>, the service
-                                will be restarted only if the watchdog
-                                timeout for the service expires.
-                                If set to
+                                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
+                                will be restarted regardless of
+                                whether it exited cleanly or not, got
                                 terminated abnormally by a signal, or
                                 hit a timeout.</para>
 
-                                <para>In addition to the above settings,
-                                the service will not be restarted if the
-                                exit code or signal is specified in
+                                <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).</para></listitem>
+                                (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>
@@ -747,33 +800,30 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
                                 definitions can either be numeric exit
                                 codes or termination signal names,
-                                separated by spaces. Signals will only
-                                be considered if the service does not implement
-                                a signal handler and exits as a direct result
-                                of receiving the signal. For example:
-                               <programlisting>SuccessExitStatus=1 2 8 <constant>SIGKILL</constant></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>
+                                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>
@@ -791,9 +841,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 spaces. Defaults to the empty list, so
                                 that, by default, no exit status is
                                 excluded from the configured restart
-                                logic. Example:
-                                <literal>RestartPreventExitStatus=1 6
-                                SIGABRT</literal>, ensures that exit
+                                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
@@ -808,6 +857,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                         </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
@@ -861,7 +922,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 for all file descriptors passed via
                                 socket-based activation. If true, all
                                 file descriptors >= 3 (i.e. all except
-                                STDIN/STDOUT/STDERR) will have
+                                stdin, stdout, and stderr) will have
                                 the <constant>O_NONBLOCK</constant> flag
                                 set and hence are in
                                 non-blocking mode. This option is only
@@ -906,21 +967,24 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <term><varname>Sockets=</varname></term>
                                 <listitem><para>Specifies the name of
                                 the socket units this service shall
-                                inherit the sockets from when the
-                                service is started. Normally it
-                                should not be necessary to use this
-                                setting as all sockets whose unit
+                                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
-                                (ignoring the different suffix of course)
-                                are passed to the spawned
-                                process.</para>
-
-                                <para>Note that the same socket may be
-                                passed to multiple processes at the
-                                same time. Also note that a different
-                                service may be activated on incoming
-                                traffic than that which inherits the
-                                sockets. Or in other words: the
+                                (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
@@ -997,29 +1061,63 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 hit. Takes one of
                                 <option>none</option>,
                                 <option>reboot</option>,
-                                <option>reboot-force</option>, or
-                                <option>reboot-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>
+                                <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
+                                <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. Defaults to
+                                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
@@ -1031,44 +1129,137 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
         </refsect1>
 
         <refsect1>
-                <title>Compatibility Options</title>
+                <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>&lt;</literal>, <literal>&lt;&lt;</literal>,
+                <literal>&gt;</literal>, and
+                <literal>&gt;&gt;</literal>, pipes using
+                <literal>|</literal>, running programs in the
+                background using <literal>&amp;</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'
+ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
 
-                <para>The following options are also available in the
-                <literal>[Service]</literal> section, but exist purely
-                for compatibility reasons and should not be used in
-                newly written service files.</para>
+                <para>This will execute <command>/bin/echo</command>
+                with four arguments: <literal>one</literal>,
+                <literal>two</literal>, <literal>two</literal>, and
+                <literal>two two</literal>.</para>
+
+                <para>Example:</para>
+                <programlisting>Environment=ONE='one' "TWO='two two' too" THREE=
+ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
+ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
+                <para>This results in <filename>echo</filename> being
+                called twice, the first time with arguments
+                <literal>'one'</literal>,
+                <literal>'two two' too</literal>, <literal></literal>,
+                and the second time with arguments
+                <literal>one</literal>, <literal>two two</literal>,
+                <literal>too</literal>.
+                </para>
 
-                <variablelist class='unit-directives'>
-                        <varlistentry>
-                                <term><varname>SysVStartPriority=</varname></term>
-                                <listitem><para>Set the SysV start
-                                priority to use to order this service
-                                in relation to SysV services lacking
-                                LSB headers. This option is only
-                                necessary to fix ordering in relation
-                                to legacy SysV services that have no
-                                ordering information encoded in the
-                                script headers. As such, it should only
-                                be used as a temporary compatibility
-                                option and should not be used in new unit
-                                files. Almost always, it is a better
-                                choice to add explicit ordering
-                                directives via
-                                <varname>After=</varname> or
-                                <varname>Before=</varname>,
-                                instead. For more details, see
-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-                                If used, pass an integer value in the
-                                range 0-99.</para></listitem>
-                        </varlistentry>
-                </variablelist>
+                <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 / &gt;/dev/null &amp; \; \
+/bin/ls</programlisting>
+
+                <para>This will execute <command>/bin/echo</command>
+                with five arguments: <literal>/</literal>,
+                <literal>&gt;/dev/null</literal>,
+                <literal>&amp;</literal>, <literal>;</literal>, and
+                <literal>/bin/ls</literal>.</para>
         </refsect1>
 
         <refsect1>
                   <title>See Also</title>
                   <para>
                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</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>,