151 lines
8.3 KiB
Diff
151 lines
8.3 KiB
Diff
|
From a6ba849c002fc991a290d2792573a9145f02aaf6 Mon Sep 17 00:00:00 2001
|
||
|
|
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
|
||
|
|
Date: Sat, 14 Dec 2013 17:21:55 -0500
|
||
|
|
Subject: [PATCH] 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
|
||
|
|
---
|
||
|
|
man/systemd.service.xml | 97 ++++++++++++++++++++++++++++++++++++++++---------
|
||
|
|
1 file changed, 80 insertions(+), 17 deletions(-)
|
||
|
|
|
||
|
|
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
|
||
|
|
index 3f31c11..ca297ba 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><</literal>,
|
||
|
|
+ <literal><<</literal>,
|
||
|
|
+ <literal>></literal>, and
|
||
|
|
+ <literal>>></literal>, pipes
|
||
|
|
+ using <literal>|</literal>, and
|
||
|
|
+ running programs in the background
|
||
|
|
+ using <literal>&</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 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 / >/dev/null & \; \
|
||
|
|
+/bin/ls
|
||
|
|
+ </programlisting>
|
||
|
|
+ <para>This will execute
|
||
|
|
+ <command>/bin/echo</command> with five
|
||
|
|
+ arguments: <literal>/</literal>,
|
||
|
|
+ <literal>>/dev/null</literal>,
|
||
|
|
+ <literal>&</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>
|