<para>If set to
<option>simple</option> (the default
- value if <varname>BusName=</varname>
- is not specified), it is expected that
- the process configured with
+ value if neither
+ <varname>Type=</varname> nor
+ <varname>BusName=</varname> are
+ specified), it is expected that the
+ process configured with
<varname>ExecStart=</varname> is the
main process of the service. In this
mode, if the process offers
<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
(these semicolons must be passed as
separate words). Alternatively, this
directive may be specified more than
- once with the same effect. However,
- the latter syntax is not recommended
- for compatibility with parsers
- suitable for XDG
- <filename>.desktop</filename> files.
+ once with the same effect.
Lone semicolons may be escaped as
<literal>\;</literal>. If the empty
string is assigned to this option, the
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
<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
replaced by the value of the
environment variable including all
whitespace it contains, resulting in a
- single argument. Use
+ single argument. Use
<literal>$FOO</literal> as a separate
word on the command line, in which
case it will be replaced by the value
- of the environment variable split up
- at whitespace, resulting in zero or
- 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>
+ of the environment variable split at
+ whitespace, resulting in zero or more
+ arguments. To pass a literal dollar
+ sign, use <literal>$$</literal>.
+ Variables whose value is not known at
+ expansion time are treated as empty
+ strings. Note that the first argument
+ (i.e. the program to execute) may not
+ be a variable.</para>
+
+ <para>Variables to be used in this
+ fashion may be defined through
+ <varname>Environment=</varname> and
+ <varname>EnvironmentFile=</varname>.
+ In addition, variables listed in
+ section "Environment variables in
+ spawned processes" in
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ which are considered "static
+ configuration" may used (this includes
+ e.g. <varname>$USER</varname>, but not
+ <varname>$TERM</varname>).</para>
<para>Optionally, if the absolute file
name is prefixed with
<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>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>
timeout for the service expires.
If set to
<option>always</option>, the service
- will be restarted regardless whether
+ will be restarted regardless of whether
it exited cleanly or not, got
terminated abnormally by a signal or
hit a timeout.</para>
considered successful termination, in
addition to the normal successful exit
code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
- <constant>SIGTERM</constant> and <constant>SIGPIPE</constant>. Exit status
+ <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
definitions can either be numeric exit
codes or termination signal names,
- separated by spaces. Example:
- <literal>SuccessExitStatus=1 2 8
- <constant>SIGKILL</constant></literal>, ensures that exit
- codes 1, 2, 8 and the termination
- signal <constant>SIGKILL</constant> are considered clean
- service terminations. This option may
- appear more than once in which case
- the list of successful exit statuses
- is merged. If the empty string is
- assigned to this option, the list is
- reset, all prior assignments of this
- option will have no
- effect.</para></listitem>
+ separated by spaces. Signals will only
+ be considered if the service does not implement
+ a signal handler and exits as a direct result
+ of receiving the signal. For example:
+ <programlisting>SuccessExitStatus=1 2 8 <constant>SIGKILL</constant></programlisting>
+ ensures that exit codes 1, 2, 8 and
+ the termination signal
+ <constant>SIGKILL</constant> are
+ considered clean service terminations.
+ </para>
+
+ <para>Note that if a process has a
+ signal handler installed and exits by
+ calling
+ <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ in response to a signal, the
+ information about the signal is lost.
+ Programs should instead perform cleanup and kill themselves with the same signal instead. See
+ <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>
+
+ <para>This option may appear more than once
+ in which case the list of successful
+ exit statuses is merged. If the empty
+ string is assigned to this option, the
+ list is reset, all prior assignments
+ of this option will have no
+ effect.</para></listitem>
</varlistentry>
<varlistentry>
~ianmdlvl / elogind.git / blobdiff