daandemeyer / rpms / systemd

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