daandemeyer / rpms / systemd

Forked from rpms/systemd 2 years ago
Clone
9fc0f6
From 1e09f64d4735563be7b7f7e98d727ba15fe6a523 Mon Sep 17 00:00:00 2001
9fc0f6
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
9fc0f6
Date: Sat, 14 Dec 2013 17:21:55 -0500
9fc0f6
Subject: [PATCH] man: beef up ExecStart description
9fc0f6
9fc0f6
We have lots of questions from people who assume that shell syntax works
9fc0f6
here, so let's be very explicit what is allowed and what is not. A few
9fc0f6
examples should also help.
9fc0f6
9fc0f6
http://bugs.debian.org/732156
9fc0f6
---
9fc0f6
 man/systemd.service.xml | 97 ++++++++++++++++++++++++++++++++++++++++---------
9fc0f6
 1 file changed, 80 insertions(+), 17 deletions(-)
9fc0f6
9fc0f6
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
9fc0f6
index 3f31c11..ca297ba 100644
9fc0f6
--- a/man/systemd.service.xml
9fc0f6
+++ b/man/systemd.service.xml
9fc0f6
@@ -305,9 +305,10 @@
9fc0f6
                                 <term><varname>ExecStart=</varname></term>
9fc0f6
                                 <listitem><para>Commands with their
9fc0f6
                                 arguments that are executed when this
9fc0f6
-                                service is started. The first
9fc0f6
-                                argument must be an absolute path
9fc0f6
-                                name.</para>
9fc0f6
+                                service is started. For each of the
9fc0f6
+                                specified commands, the first argument
9fc0f6
+                                must be an absolute and literal path
9fc0f6
+                                to an executable.</para>
9fc0f6
 
9fc0f6
                                 <para>When <varname>Type</varname> is
9fc0f6
                                 not <option>oneshot</option>, only one
9fc0f6
@@ -332,6 +333,35 @@
9fc0f6
                                 prior assignments of this option will
9fc0f6
                                 have no effect.</para>
9fc0f6
 
9fc0f6
+                                <para>Each command line is split on
9fc0f6
+                                whitespace, with the first item being
9fc0f6
+                                the command to execute, and the
9fc0f6
+                                subsequent items being the arguments.
9fc0f6
+                                Double quotes ("...") and single
9fc0f6
+                                quotes ('...') may be used, in which
9fc0f6
+                                case everything until the next
9fc0f6
+                                matching quote becomes part of the
9fc0f6
+                                same argument. Quotes themselves are
9fc0f6
+                                removed after parsing. In addition, a
9fc0f6
+                                trailing backslash
9fc0f6
+                                (<literal>\</literal>) may be used to
9fc0f6
+                                merge lines. This syntax is intended
9fc0f6
+                                to be very similar to shell syntax,
9fc0f6
+                                but only the meta-characters and
9fc0f6
+                                expansions described in the following
9fc0f6
+                                paragraphs are understood.
9fc0f6
+                                Specifically, redirection using
9fc0f6
+                                <literal><</literal>,
9fc0f6
+                                <literal><<</literal>,
9fc0f6
+                                <literal>></literal>, and
9fc0f6
+                                <literal>>></literal>, pipes
9fc0f6
+                                using <literal>|</literal>, and
9fc0f6
+                                running programs in the background
9fc0f6
+                                using <literal>&</literal>
9fc0f6
+                                and <emphasis>other elements of shell
9fc0f6
+                                syntax are not supported</emphasis>.
9fc0f6
+                                </para>
9fc0f6
+
9fc0f6
                                 <para>If more than one command is
9fc0f6
                                 specified, the commands are invoked
9fc0f6
                                 one by one sequentially in the order
9fc0f6
@@ -350,10 +380,11 @@
9fc0f6
                                 <para>The command line accepts
9fc0f6
                                 <literal>%</literal> specifiers as
9fc0f6
                                 described in
9fc0f6
-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note
9fc0f6
-                                that the first argument of the command
9fc0f6
-                                line (i.e. the program to execute) may
9fc0f6
-                                not include specifiers.</para>
9fc0f6
+                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
9fc0f6
+                                Note that the first argument of the
9fc0f6
+                                command line (i.e. the program to
9fc0f6
+                                execute) may not include
9fc0f6
+                                specifiers.</para>
9fc0f6
 
9fc0f6
                                 <para>Basic environment variable
9fc0f6
                                 substitution is supported. Use
9fc0f6
@@ -372,9 +403,7 @@
9fc0f6
                                 more arguments. To pass literal dollar sign
9fc0f6
                                 use <literal>$$</literal>. Note that the first
9fc0f6
                                 argument (i.e. the program to execute)
9fc0f6
-                                may not be a variable, since it must
9fc0f6
-                                be a literal and absolute path
9fc0f6
-                                name.</para>
9fc0f6
+                                may not be a variable.</para>
9fc0f6
 
9fc0f6
                                 <para>Optionally, if the absolute file
9fc0f6
                                 name is prefixed with
9fc0f6
@@ -402,13 +431,47 @@
9fc0f6
                                 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
9fc0f6
                                 </programlisting>
9fc0f6
 
9fc0f6
-                                <para>For services run by a user
9fc0f6
-                                instance of systemd the special
9fc0f6
-                                environment variable
9fc0f6
-                                <varname>$MANAGERPID</varname> is set
9fc0f6
-                                to the PID of the systemd
9fc0f6
-                                instance.</para>
9fc0f6
-                                </listitem>
9fc0f6
+                                <para>Only select environment variables
9fc0f6
+                                are set for executed commands. See
9fc0f6
+                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
9fc0f6
+                                </para>
9fc0f6
+
9fc0f6
+                                <para>Example:</para>
9fc0f6
+                                <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"
9fc0f6
+                                </programlisting>
9fc0f6
+                                <para>This will execute
9fc0f6
+                                <command>/bin/echo</command> two
9fc0f6
+                                times, each time with one argument,
9fc0f6
+                                <literal>one</literal> and
9fc0f6
+                                <literal>two two</literal>,
9fc0f6
+                                respectively. Since two commands are
9fc0f6
+                                specified
9fc0f6
+                                <varname>Type=oneshot</varname> must
9fc0f6
+                                be used.</para>
9fc0f6
+
9fc0f6
+                                <para>Example:</para>
9fc0f6
+                                <programlisting>ExecStart=/bin/echo / >/dev/null & \; \
9fc0f6
+/bin/ls
9fc0f6
+                                </programlisting>
9fc0f6
+                                <para>This will execute
9fc0f6
+                                <command>/bin/echo</command> with five
9fc0f6
+                                arguments: <literal>/</literal>,
9fc0f6
+                                <literal>>/dev/null</literal>,
9fc0f6
+                                <literal>&</literal>,
9fc0f6
+                                <literal>;</literal>, and
9fc0f6
+                                <literal>/bin/ls</literal>.</para>
9fc0f6
+
9fc0f6
+                                <para>Example:</para>
9fc0f6
+                                <programlisting>Environment="ONE=one" 'TWO=two two'
9fc0f6
+ExecStart=/bin/echo $ONE $TWO ${TWO}
9fc0f6
+                                </programlisting>
9fc0f6
+                                <para>This will execute
9fc0f6
+                                <command>/bin/echo</command> with four
9fc0f6
+                                arguments: <literal>one</literal>,
9fc0f6
+                                <literal>two</literal>,
9fc0f6
+                                <literal>two</literal>, and
9fc0f6
+                                <literal>two two</literal>.</para>
9fc0f6
+                              </listitem>
9fc0f6
                         </varlistentry>
9fc0f6
 
9fc0f6
                         <varlistentry>