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