From a6ba849c002fc991a290d2792573a9145f02aaf6 Mon Sep 17 00:00:00 2001

From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>

Date: Sat, 14 Dec 2013 17:21:55 -0500

Subject: [PATCH] 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

---

 man/systemd.service.xml | 97 ++++++++++++++++++++++++++++++++++++++++---------

 1 file changed, 80 insertions(+), 17 deletions(-)

diff --git a/man/systemd.service.xml b/man/systemd.service.xml

index 3f31c11..ca297ba 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><</literal>,

+                                <literal><<</literal>,

+                                <literal>></literal>, and

+                                <literal>>></literal>, pipes

+                                using <literal>|</literal>, and

+                                running programs in the background

+                                using <literal>&</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 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 / >/dev/null & \; \

+/bin/ls

+                                </programlisting>

+                                <para>This will execute

+                                <command>/bin/echo</command> with five

+                                arguments: <literal>/</literal>,

+                                <literal>>/dev/null</literal>,

+                                <literal>&</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>