summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2013-12-14 17:21:55 -0500
committerZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2013-12-14 17:33:10 -0500
commitec6039bc08f8e77f92427afec048e4f8ac4b81a8 (patch)
treed93ba2ac588a8ed978ce36557d7d9b8d2427d09a
parent5d5f8ffa077b0f4716d5178734601a0c27f575df (diff)
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
-rw-r--r--man/systemd.service.xml97
1 files changed, 80 insertions, 17 deletions
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 22c0d5ae9f..103c495fbe 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>