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 c06e14efc23e1c64b30515cc78de8a612c44b83d..72b872beced11be7146da478c10c6dd3913b548e 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -76,8 +76,8 @@
                 <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.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                 which define the way the processes of the service are
                 terminated, and in

-                <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                which configure control group settings for the
+                <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>
                 processes of the service.</para>
 
                 <para>Unless <varname>DefaultDependencies=</varname>


@@ -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 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>


@@ -524,9 +596,10 @@
                                 Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout
                                 Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout

-                                logic. Defaults to 90s, except when
+                                logic. Defaults to <varname>TimeoutStartSec=</varname> from the
+                                manager configuration file, except when

                                 <varname>Type=oneshot</varname> is
                                 <varname>Type=oneshot</varname> is

-                                used in which case the timeout
+                                used, in which case the timeout

                                 is disabled by default.
                                 </para></listitem>
                         </varlistentry>
                                 is disabled by default.
                                 </para></listitem>
                         </varlistentry>


@@ -545,7 +618,8 @@
                                 Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout
                                 Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout

-                                logic. Defaults to 90s.
+                                logic. Defaults to <varname>TimeoutStartSec=</varname> from the
+                                manager configuration file.

                                 </para></listitem>
                         </varlistentry>
 
                                 </para></listitem>
                         </varlistentry>
 


@@ -651,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>


@@ -671,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>


@@ -861,12 +949,15 @@
                                 these two options, this rate limiting
                                 may be modified. Use
                                 <varname>StartLimitInterval=</varname>
                                 these two options, this rate limiting
                                 may be modified. Use
                                 <varname>StartLimitInterval=</varname>

-                                to configure the checking interval
-                                (defaults to 10s, set to 0 to disable
+                                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
                                 any kind of rate limiting). Use
                                 <varname>StartLimitBurst=</varname> to
                                 configure how many starts per interval

-                                are allowed (defaults to 5). These
+                                are allowed (defaults to
+                                <varname>DefaultStartLimitBurst=</varname> in
+                                manager configuration file). These

                                 configuration options are particularly
                                 useful in conjunction with
                                 <varname>Restart=</varname>, however
                                 configuration options are particularly
                                 useful in conjunction with
                                 <varname>Restart=</varname>, however


@@ -970,33 +1061,6 @@
                                 range 0-99.</para></listitem>
                         </varlistentry>
 
                                 range 0-99.</para></listitem>
                         </varlistentry>
 

-                        <varlistentry>
-                                <term><varname>FsckPassNo=</varname></term>
-                                <listitem><para>Set the fsck passno
-                                priority to use to order this service
-                                in relation to other file system
-                                checking services. This option is only
-                                necessary to fix ordering in relation
-                                to fsck jobs automatically created for
-                                all <filename>/etc/fstab</filename>
-                                entries with a value in the fs_passno
-                                column > 0. As such it should only be
-                                used as option for fsck
-                                services. 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
-                                same range as
-                                <filename>/etc/fstab</filename>'s
-                                fs_passno column. See
-                                <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                                for details.</para></listitem>
-                        </varlistentry>
-

                 </variablelist>
         </refsect1>
 
                 </variablelist>
         </refsect1>
 


@@ -1007,7 +1071,7 @@
                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

-                          <citerefentry><refentrytitle>systemd.cgroup</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>
                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                   </para>