From 8202c017010090abf0c0777d10093ffba3c42811 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 2 Apr 2023 20:05:18 +0200 Subject: man: move description of command line substitution out of ExecStart= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The description was split — part was under ExecStart= and part in "Command lines". Now the whole generic part is moved to the separate section, and under ExecStart= only the stuff that is specific to that option is described. This just moves the text and removes some repetitions. --- man/systemd.service.xml | 145 +++++++++++++++++++++++------------------------- 1 file changed, 69 insertions(+), 76 deletions(-) (limited to 'man/systemd.service.xml') diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 665128ee77..036ac66b2d 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -356,11 +356,8 @@ ExecStart= - Commands with their arguments that are - executed when this service is started. The value is split into - zero or more command lines according to the rules described - below (see section "Command Lines" below). - + 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 @@ -371,66 +368,6 @@ ExecStop= line set. (Services lacking both ExecStart= and ExecStop= are not valid.) - For each of the specified commands, the first argument must be either an absolute path to an executable - or a simple file name without any slashes. Optionally, this filename may be prefixed with a number of special - characters: - - - Special executable prefixes - - - - - - - - Prefix - Effect - - - - - @ - If the executable path is prefixed with @, the second specified token will be passed as argv[0] to the executed process (instead of the actual filename), followed by the further arguments specified. - - - - - - If the executable path is prefixed with -, an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is recorded, but has no further effect and is considered equivalent to success. - - - - : - If the executable path is prefixed with :, environment variable substitution (as described by the "Command Lines" section below) is not applied. - - - - + - If the executable path is prefixed with + then the process is executed with full privileges. In this mode privilege restrictions configured with User=, Group=, CapabilityBoundingSet= or the various file system namespacing options (such as PrivateDevices=, PrivateTmp=) are not applied to the invoked command line (but still affect any other ExecStart=, ExecStop=, … lines). However, note that this will not bypass options that apply to the whole control group, such as DevicePolicy=, see systemd.resource-control5 for the full list. - - - - ! - - Similar to the + character discussed above this permits invoking command lines with elevated privileges. However, unlike + the ! character exclusively alters the effect of User=, Group= and SupplementaryGroups=, i.e. only the stanzas that affect user and group credentials. Note that this setting may be combined with DynamicUser=, in which case a dynamic user/group pair is allocated before the command is invoked, but credential changing is left to the executed process itself. - - - - !! - - This prefix is very similar to !, however it only has an effect on systems lacking support for ambient process capabilities, i.e. without support for AmbientCapabilities=. It's intended to be used for unit files that take benefit of ambient capabilities to run processes with minimal privileges wherever possible while remaining compatible with systems that lack ambient capabilities support. Note that when !! is used, and a system lacking ambient capability support is detected any configured SystemCallFilter= and CapabilityBoundingSet= stanzas are implicitly modified, in order to permit spawned processes to drop credentials and capabilities themselves, even if this is configured to not be allowed. Moreover, if this prefix is used and a system lacking ambient capability support is detected AmbientCapabilities= will be skipped and not be applied. On systems supporting ambient capabilities, !! has no effect and is redundant. - - - -
- - @, -, :, and one of - +/!/!! may be used together and they can appear in any - order. However, only one of +, !, !! may be used at a - time. Note that these prefixes are also supported for the other command line settings, - i.e. ExecStartPre=, ExecStartPost=, ExecReload=, - ExecStop= and ExecStopPost=. - 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 @@ -1294,6 +1231,73 @@ The command to execute may contain spaces, but control characters are not allowed. + Each command may be prefixed with a number of special characters: + + + Special executable prefixes + + + + + + + + Prefix + Effect + + + + + @ + If the executable path is prefixed with @, the second specified token will be passed as argv[0] to the executed process (instead of the actual filename), followed by the further arguments specified. + + + + - + If the executable path is prefixed with -, an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is recorded, but has no further effect and is considered equivalent to success. + + + + : + If the executable path is prefixed with :, environment variable substitution (as described by the "Command Lines" section below) is not applied. + + + + + + If the executable path is prefixed with + then the process is executed with full privileges. In this mode privilege restrictions configured with User=, Group=, CapabilityBoundingSet= or the various file system namespacing options (such as PrivateDevices=, PrivateTmp=) are not applied to the invoked command line (but still affect any other ExecStart=, ExecStop=, … lines). However, note that this will not bypass options that apply to the whole control group, such as DevicePolicy=, see systemd.resource-control5 for the full list. + + + + ! + + Similar to the + character discussed above this permits invoking command lines with elevated privileges. However, unlike + the ! character exclusively alters the effect of User=, Group= and SupplementaryGroups=, i.e. only the stanzas that affect user and group credentials. Note that this setting may be combined with DynamicUser=, in which case a dynamic user/group pair is allocated before the command is invoked, but credential changing is left to the executed process itself. + + + + !! + + This prefix is very similar to !, however it only has an effect on systems lacking support for ambient process capabilities, i.e. without support for AmbientCapabilities=. It's intended to be used for unit files that take benefit of ambient capabilities to run processes with minimal privileges wherever possible while remaining compatible with systems that lack ambient capabilities support. Note that when !! is used, and a system lacking ambient capability support is detected any configured SystemCallFilter= and CapabilityBoundingSet= stanzas are implicitly modified, in order to permit spawned processes to drop credentials and capabilities themselves, even if this is configured to not be allowed. Moreover, if this prefix is used and a system lacking ambient capability support is detected AmbientCapabilities= will be skipped and not be applied. On systems supporting ambient capabilities, !! has no effect and is redundant. + + + +
+ + @, -, :, and one of + +/!/!! may be used together and they can appear in any + order. However, only one of +, !, !! may be used at a + time. + + For each command, the first argument must be either an absolute path to an executable or a simple + file name without any slashes. If the command is not a full (absolute) path, it will be resolved to a + full path using a fixed search path determined at compilation time. Searched directories include + /usr/local/bin/, /usr/bin/, /bin/ on + systems using split /usr/bin/ and /bin/ directories, and their + sbin/ counterparts on systems using split bin/ and + sbin/. It is thus safe to use just the executable name in case of executables + located in any of the "standard" directories, and an absolute path must be used in other cases. Using an + absolute path is recommended to avoid ambiguity. Hint: this search path may be queried using + systemd-path search-binaries-default. + The command line accepts % specifiers as described in systemd.unit5. @@ -1308,17 +1312,6 @@ For this type of expansion, quotes are respected when splitting into words, and afterwards removed. - If the command is not a full (absolute) path, it will be resolved to a full path using a - fixed search path determined at compilation time. Searched directories include - /usr/local/bin/, /usr/bin/, /bin/ - on systems using split /usr/bin/ and /bin/ - directories, and their sbin/ counterparts on systems using split - bin/ and sbin/. It is thus safe to use just the - executable name in case of executables located in any of the "standard" directories, and an - absolute path must be used in other cases. Using an absolute path is recommended to avoid - ambiguity. Hint: this search path may be queried using - systemd-path search-binaries-default. - Example: Environment="ONE=one" 'TWO=two two' -- cgit v1.2.1