From: Lennart Poettering Date: Tue, 1 Oct 2024 10:12:52 +0000 (+0200) Subject: man: soft deprecate use of ";" for separating multiple command lines in ExecStart= X-Git-Tag: v257-rc1~327^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=225f18b9a9d39331ea862478ab2ff893678e249d;p=thirdparty%2Fsystemd.git 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 047fb912e96..bbff40559a1 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -386,27 +386,23 @@ ExecStart= - 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. - - Unless Type= is , exactly one command must be given. When - Type=oneshot 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 ExecStart= is - specified, then the service must have RemainAfterExit=yes and at least one - ExecStop= line set. (Services lacking both ExecStart= and - ExecStop= are not valid.) - - 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 - -), other lines are not executed, and the - unit is considered failed. - - Unless Type=forking is set, the - process started via this command line will be considered the - main process of the daemon. + Commands that are executed when this service is started. + + Unless Type= is , exactly one command must be + given. When Type=oneshot 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 + ExecStart= is specified, then the service must have + RemainAfterExit=yes and at least one ExecStop= line + set. (Services lacking both ExecStart= and ExecStop= are not + valid.) + + 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 + -), other lines are not executed, and the unit is considered failed. + + Unless Type=forking is set, the process started via this command line will + be considered the main process of the daemon. @@ -1354,9 +1350,7 @@ ExecStopPost=, and ExecCondition= options. - 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 - \;. + Multiple command lines may be specified by using the relevant setting multiple times. Each command line is unquoted using the rules described in "Quoting" section in systemd.syntax7. The @@ -1445,6 +1439,8 @@ The command line accepts % specifiers as described in systemd.unit5. + An argument solely consisting of ; must be escaped, i.e. specified as \; + Basic environment variable substitution is supported. Use ${FOO} 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 Example: - ExecStart=echo one ; echo "two two" + ExecStart=echo one +ExecStart=echo "two two" This will execute echo two times, each time with one argument: one and @@ -1509,7 +1506,9 @@ ExecStart=/bin/echo $ONE $TWO $THREE Example: Type=oneshot -ExecStart=:echo $USER ; -false ; +:@true $TEST +ExecStart=:echo $USER +ExecStart=-false +ExecStart=+:@true $TEST This will execute /usr/bin/echo with the literal argument $USER (: suppresses variable expansion), and then diff --git a/src/core/load-fragment.c b/src/core/load-fragment.c index e49276eae5c..6e0762d7a24 100644 --- 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;