man: beef up ExecStart description

We have lots of questions from people who assume that shell syntax works
here, so let's be very explicit what is allowed and what is not. A few
examples should also help.

http://bugs.debian.org/732156

1 files changed, 80 insertions, 17 deletions

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 22c0d5ae9..103c495fb 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -305,9 +305,10 @@
                                 <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
@@ -332,6 +333,35 @@
                                 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
@@ -350,10 +380,11 @@
                                 <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
@@ -372,9 +403,7 @@
                                 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
@@ -402,13 +431,47 @@
                                 <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
+                                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>