man: add a note about propagating signals

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

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index d1f4a2d7d76c9f73b9b9dad540e1ec9da90a16cd..98507f405f96e96a632dd9d45031c5e99b5ff4dc 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


@@ -372,9 +401,7 @@
                                 more arguments. To pass a literal dollar sign,
                                 use <literal>$$</literal>. Note that the first
                                 argument (i.e. the program to execute)
                                 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>
+                                may not be a variable.</para>

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


@@ -402,13 +429,47 @@
                                 <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>Only select environment variables that
+                                are set for executed commands. See
+                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+                                </para>
+
+                                <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 +714,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 +734,33 @@
                                 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. 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>


@@ -863,12 +935,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