man: soft deprecate use of ";" for separating multiple command lines in ExecStart=

So far we supported this syntax:

    ExecStart=foo ; bar

as equivalent to:

    ExecStart=foo
    ExecStart=bar

With this change we'll "soft" deprecate the first syntax. i.e. it's
still supported in code, but not documented anymore.

The concept was originally added to make things easier for 3rd party
.ini readers, as it allowed writing unit files with a .ini framework
that doesn't allow multiple assignments for the same key. But frankly,
this is kinda pointless, as so many other of our knobs require the
double assignment.

Hence, let's just stop advertising the concept, let's simplify the docs,
by removing one entirely redundant feature from it.

Replaces: #34570

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 047fb912e967748685dfb9ff90299ec857171804..bbff40559a10c1b2b8bde344fe05892b5a67ae57 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -386,27 +386,23 @@
 
       <varlistentry>
         <term><varname>ExecStart=</varname></term>
-        <listitem><para>Commands that are executed when this service is started. The value is split into zero
-        or more command lines according to the rules described in the section "Command Lines" below.</para>
-
-        <para>Unless <varname>Type=</varname> is <option>oneshot</option>, exactly one command must be given. When
-        <varname>Type=oneshot</varname> is used, zero or more commands may be specified. Commands may be specified by
-        providing multiple command lines in the same directive, or alternatively, this directive may be specified more
-        than once with the same effect. If the empty string is assigned to this option, the list of commands to start
-        is reset, prior assignments of this option will have no effect. If no <varname>ExecStart=</varname> is
-        specified, then the service must have <varname>RemainAfterExit=yes</varname> and at least one
-        <varname>ExecStop=</varname> line set. (Services lacking both <varname>ExecStart=</varname> and
-        <varname>ExecStop=</varname> are not valid.)</para>
-
-        <para>If more than one command is specified, the commands are
-        invoked sequentially in the order they appear in the unit
-        file. If one of the commands fails (and is not prefixed with
-        <literal>-</literal>), other lines are not executed, and the
-        unit is considered failed.</para>
-
-        <para>Unless <varname>Type=forking</varname> is set, the
-        process started via this command line will be considered the
-        main process of the daemon.</para>
+        <listitem><para>Commands that are executed when this service is started.</para>
+
+        <para>Unless <varname>Type=</varname> is <option>oneshot</option>, exactly one command must be
+        given. When <varname>Type=oneshot</varname> is used, this setting may be used multiple times to
+        define multiple commands to execute. If the empty string is assigned to this option, the list of
+        commands to start is reset, prior assignments of this option will have no effect. If no
+        <varname>ExecStart=</varname> is specified, then the service must have
+        <varname>RemainAfterExit=yes</varname> and at least one <varname>ExecStop=</varname> line
+        set. (Services lacking both <varname>ExecStart=</varname> and <varname>ExecStop=</varname> are not
+        valid.)</para>
+
+        <para>If more than one command is configured, the commands are invoked sequentially in the order they
+        appear in the unit file. If one of the commands fails (and is not prefixed with
+        <literal>-</literal>), other lines are not executed, and the unit is considered failed.</para>
+
+        <para>Unless <varname>Type=forking</varname> is set, the process started via this command line will
+        be considered the main process of the daemon.</para>
         </listitem>
       </varlistentry>
 
@@ -1354,9 +1350,7 @@
     <varname>ExecStopPost=</varname>, and
     <varname>ExecCondition=</varname> options.</para>
 
-    <para>Multiple command lines may be concatenated in a single directive by separating them with semicolons
-    (these semicolons must be passed as separate words). Lone semicolons may be escaped as
-    <literal>\;</literal>.</para>
+    <para>Multiple command lines may be specified by using the relevant setting multiple times.</para>
 
     <para>Each command line is unquoted using the rules described in "Quoting" section in
     <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
@@ -1445,6 +1439,8 @@
     <para>The command line accepts <literal>%</literal> specifiers as described in
     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 
+    <para>An argument solely consisting of <literal>;</literal> must be escaped, i.e. specified as <literal>\;</literal></para>
+
     <para>Basic environment variable substitution is supported. Use
     <literal>${FOO}</literal> as part of a word, or as a word of its
     own, on the command line, in which case it will be erased and replaced
@@ -1499,7 +1495,8 @@ ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
 
     <para>Example:</para>
 
-    <programlisting>ExecStart=echo one ; echo "two two"</programlisting>
+    <programlisting>ExecStart=echo one
+ExecStart=echo "two two"</programlisting>
 
     <para>This will execute <command>echo</command> two times,
     each time with one argument: <literal>one</literal> and
@@ -1509,7 +1506,9 @@ ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
     <para>Example:</para>
 
     <programlisting>Type=oneshot
-ExecStart=:echo $USER ; -false ; +:@true $TEST</programlisting>
+ExecStart=:echo $USER
+ExecStart=-false
+ExecStart=+:@true $TEST</programlisting>
 
     <para>This will execute <command>/usr/bin/echo</command> with the literal argument
     <literal>$USER</literal> (<literal>:</literal> suppresses variable expansion), and then

diff --git a/src/core/load-fragment.c b/src/core/load-fragment.c
index e49276eae5c705cc31f97439a2de5fa352e6c60d..6e0762d7a24ce6a293994b7df701be95ab726c5d 100644 (file)
--- a/src/core/load-fragment.c
+++ b/src/core/load-fragment.c
@@ -920,7 +920,11 @@ int config_parse_exec(
                 if (r <= 0)
                         return 0;
 
-                /* A lone ";" is a separator. Let's make sure we don't treat it as an executable name. */
+                /* A lone ";" is a separator. Let's make sure we don't treat it as an executable name.
+                 *
+                 * SOFT DEPRECATION: We support multiple command lines in one ExecStart= line for
+                 * compatibility with older versions, but we no longer document this exists, it's deprecated
+                 * in a soft way. New unit files, should not use this feature. */
                 if (streq(firstword, ";")) {
                         semicolon = true;
                         continue;