ryantimwilson / rpms / systemd

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