man: systemd.service(5): clarify behavior of SuccessExitStatus

[elogind.git] / man / systemd.service.xml

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 22c0d5ae9fc33e212b8b35307f9c554f38955b11..72b872beced11be7146da478c10c6dd3913b548e 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -139,9 +139,11 @@
 
                                 <para>If set to
                                 <option>simple</option> (the default
 
                                 <para>If set to
                                 <option>simple</option> (the default

-                                value if <varname>BusName=</varname>
-                                is not specified), it is expected that
-                                the process configured with
+                                value if neither
+                                <varname>Type=</varname> nor
+                                <varname>BusName=</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
                                 <varname>ExecStart=</varname> is the
                                 main process of the service. In this
                                 mode, if the process offers


@@ -305,9 +307,10 @@
                                 <term><varname>ExecStart=</varname></term>
                                 <listitem><para>Commands with their
                                 arguments that are executed when this
                                 <term><varname>ExecStart=</varname></term>
                                 <listitem><para>Commands with their
                                 arguments that are executed when this

-                                service is started. The first
-                                argument must be an absolute path
-                                name.</para>
+                                service is started. For each of the
+                                specified commands, the first argument
+                                must be an absolute and literal path
+                                to an executable.</para>

 
                                 <para>When <varname>Type</varname> is
                                 not <option>oneshot</option>, only one
 
                                 <para>When <varname>Type</varname> is
                                 not <option>oneshot</option>, only one


@@ -320,11 +323,7 @@
                                 (these semicolons must be passed as
                                 separate words). Alternatively, this
                                 directive may be specified more than
                                 (these semicolons must be passed as
                                 separate words). Alternatively, this
                                 directive may be specified more than

-                                once with the same effect. However,
-                                the latter syntax is not recommended
-                                for compatibility with parsers
-                                suitable for XDG
-                                <filename>.desktop</filename> files.
+                                once with the same effect.

                                 Lone semicolons may be escaped as
                                 <literal>\;</literal>. If the empty
                                 string is assigned to this option, the
                                 Lone semicolons may be escaped as
                                 <literal>\;</literal>. If the empty
                                 string is assigned to this option, the


@@ -332,6 +331,35 @@
                                 prior assignments of this option will
                                 have no effect.</para>
 
                                 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>
+

                                 <para>If more than one command is
                                 specified, the commands are invoked
                                 one by one sequentially in the order
                                 <para>If more than one command is
                                 specified, the commands are invoked
                                 one by one sequentially in the order


@@ -350,10 +378,11 @@
                                 <para>The command line accepts
                                 <literal>%</literal> specifiers as
                                 described in
                                 <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>
+                                <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
 
                                 <para>Basic environment variable
                                 substitution is supported. Use


@@ -363,18 +392,32 @@
                                 replaced by the value of the
                                 environment variable including all
                                 whitespace it contains, resulting in a
                                 replaced by the value of the
                                 environment variable including all
                                 whitespace it contains, resulting in a

-                                single argument.  Use
+                                single argument. Use

                                 <literal>$FOO</literal> as a separate
                                 word on the command line, in which
                                 case it will be replaced by the value
                                 <literal>$FOO</literal> as a separate
                                 word on the command line, in which
                                 case it will be replaced by the value

-                                of the environment variable split up
-                                at whitespace, resulting in zero or
-                                more arguments. To pass a literal dollar sign,
-                                use <literal>$$</literal>. Note that the first
-                                argument (i.e. the program to execute)
-                                may not be a variable, since it must
-                                be a literal and absolute path
-                                name.</para>
+                                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
+                                section "Environment variables in
+                                spawned processes" in
+                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                which are considered "static
+                                configuration" may used (this includes
+                                e.g. <varname>$USER</varname>, but not
+                                <varname>$TERM</varname>).</para>

 
                                 <para>Optionally, if the absolute file
                                 name is prefixed with
 
                                 <para>Optionally, if the absolute file
                                 name is prefixed with


@@ -402,13 +445,42 @@
                                 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
                                 </programlisting>
 
                                 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
                                 </programlisting>
 

-                                <para>For services run by a user
-                                instance of systemd the special
-                                environment variable
-                                <varname>$MANAGERPID</varname> is set
-                                to the PID of the systemd
-                                instance.</para>
-                                </listitem>
+                                <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. Since two commands are
+                                specified,
+                                <varname>Type=oneshot</varname> must
+                                be used.</para>
+
+                                <para>Example:</para>
+                                <programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \
+/bin/ls
+                                </programlisting>
+                                <para>This will execute
+                                <command>/bin/echo</command> with five
+                                arguments: <literal>/</literal>,
+                                <literal>&gt;/dev/null</literal>,
+                                <literal>&amp;</literal>,
+                                <literal>;</literal>, and
+                                <literal>/bin/ls</literal>.</para>
+
+                                <para>Example:</para>
+                                <programlisting>Environment="ONE=one" 'TWO=two two'
+ExecStart=/bin/echo $ONE $TWO ${TWO}
+                                </programlisting>
+                                <para>This will execute
+                                <command>/bin/echo</command> with four
+                                arguments: <literal>one</literal>,
+                                <literal>two</literal>,
+                                <literal>two</literal>, and
+                                <literal>two two</literal>.</para>
+                              </listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -653,7 +725,7 @@
                                 timeout for the service expires.
                                 If set to
                                 <option>always</option>, the service
                                 timeout for the service expires.
                                 If set to
                                 <option>always</option>, the service

-                                will be restarted regardless whether
+                                will be restarted regardless of whether

                                 it exited cleanly or not, got
                                 terminated abnormally by a signal or
                                 hit a timeout.</para>
                                 it exited cleanly or not, got
                                 terminated abnormally by a signal or
                                 hit a timeout.</para>


@@ -673,22 +745,36 @@
                                 considered successful termination, in
                                 addition to the normal successful exit
                                 code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
                                 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
+                                <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status

                                 definitions can either be numeric exit
                                 codes or termination signal names,
                                 definitions can either be numeric exit
                                 codes or termination signal names,

-                                separated by spaces. Example:
-                                <literal>SuccessExitStatus=1 2 8
-                                <constant>SIGKILL</constant></literal>, ensures that exit
-                                codes 1, 2, 8 and the termination
-                                signal <constant>SIGKILL</constant> are considered clean
-                                service terminations. This option may
-                                appear more than once in which case
-                                the list of successful exit statuses
-                                is merged. If the empty string is
-                                assigned to this option, the list is
-                                reset, all prior assignments of this
-                                option will have no
-                                effect.</para></listitem>
+                                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>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>