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') 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 From 4d7ae2557ba681db13087f18f3c1c60c3d8352aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 2 Apr 2023 20:16:01 +0200 Subject: man/systemd.service: add example for char prefixes The prefixes can be specified for any part of the command. The docs imply this, but it's not entirely obvious. Let's add an example. --- man/systemd.service.xml | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'man') diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 036ac66b2d..f64a8e538f 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1249,7 +1249,7 @@ @ - 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 @, 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. @@ -1364,6 +1364,17 @@ ExecStart=/bin/echo $ONE $TWO $THREE Example: + Type=oneshot +ExecStart=:echo $USER ; -false ; +:@true $TEST + + This will execute /usr/bin/echo with the literal argument + $USER (: suppresses variable expansion), and then + /usr/bin/false (the return value will be ignored because - + suppresses checking of the return value), and /usr/bin/true (with elevated privileges, + with $TEST as argv[0]). + + Example: + ExecStart=echo / >/dev/null & \; \ ls -- cgit v1.2.1 From 6db00b5de149ec06efdc4b92bc3df40cabb58ba5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 2 Apr 2023 20:53:51 +0200 Subject: man/sd_bus_message_open_container: mention two common errors --- man/sd_bus_message_open_container.xml | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'man') diff --git a/man/sd_bus_message_open_container.xml b/man/sd_bus_message_open_container.xml index 688f43227b..0b9164e9bf 100644 --- a/man/sd_bus_message_open_container.xml +++ b/man/sd_bus_message_open_container.xml @@ -91,7 +91,7 @@ with sd_bus_message_enter_container(). It behaves mostly the same as sd_bus_message_close_container(). Note that sd_bus_message_exit_container() may only be called after iterating through all - members of the container, i.e. reading or skipping them. Use + members of the container, i.e. reading or skipping over them. Use sd_bus_message_skip3 to skip over fields of a container in order to be able to exit the container with sd_bus_message_exit_container() without reading all members. @@ -121,6 +121,20 @@ NULL or type is invalid. + + -EBADMSG + + Message m has invalid structure. + + + + -ENXIO + + Message m does not have a container of type + type at the current position, or the contents do not match + contents. + + -EPERM -- cgit v1.2.1 From 91053fc94e9697cdbe610f6c8593d78568b5b573 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 2 Apr 2023 23:07:33 +0200 Subject: sd-bus: use macros for standard bus error names consistently Also add definitions for a few names that didn't have them and update the list in the man page. --- man/rules/meson.build | 4 +++ man/sd-bus-errors.xml | 72 +++++++++++++++++++++++++++++---------------------- 2 files changed, 45 insertions(+), 31 deletions(-) (limited to 'man') diff --git a/man/rules/meson.build b/man/rules/meson.build index 39cc55a929..63a68c3211 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -85,6 +85,7 @@ manpages = [ 'SD_BUS_ERROR_INCONSISTENT_MESSAGE', 'SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED', 'SD_BUS_ERROR_INVALID_ARGS', + 'SD_BUS_ERROR_INVALID_FILE_CONTENT', 'SD_BUS_ERROR_INVALID_SIGNATURE', 'SD_BUS_ERROR_IO_ERROR', 'SD_BUS_ERROR_LIMITS_EXCEEDED', @@ -96,8 +97,11 @@ manpages = [ 'SD_BUS_ERROR_NO_NETWORK', 'SD_BUS_ERROR_NO_REPLY', 'SD_BUS_ERROR_NO_SERVER', + 'SD_BUS_ERROR_OBJECT_PATH_IN_USE', 'SD_BUS_ERROR_PROPERTY_READ_ONLY', + 'SD_BUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN', 'SD_BUS_ERROR_SERVICE_UNKNOWN', + 'SD_BUS_ERROR_TIMED_OUT', 'SD_BUS_ERROR_TIMEOUT', 'SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN', 'SD_BUS_ERROR_UNKNOWN_INTERFACE', diff --git a/man/sd-bus-errors.xml b/man/sd-bus-errors.xml index f3b1515c78..dc9d9fc63b 100644 --- a/man/sd-bus-errors.xml +++ b/man/sd-bus-errors.xml @@ -45,9 +45,13 @@ SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN SD_BUS_ERROR_INVALID_SIGNATURE SD_BUS_ERROR_INCONSISTENT_MESSAGE + SD_BUS_ERROR_TIMED_OUT SD_BUS_ERROR_MATCH_RULE_NOT_FOUND SD_BUS_ERROR_MATCH_RULE_INVALID SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED + SD_BUS_ERROR_INVALID_FILE_CONTENT + SD_BUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN + SD_BUS_ERROR_OBJECT_PATH_IN_USE Standard D-Bus error names @@ -56,38 +60,44 @@ #include <systemd/sd-bus.h> -#define SD_BUS_ERROR_FAILED "org.freedesktop.DBus.Error.Failed" -#define SD_BUS_ERROR_NO_MEMORY "org.freedesktop.DBus.Error.NoMemory" -#define SD_BUS_ERROR_SERVICE_UNKNOWN "org.freedesktop.DBus.Error.ServiceUnknown" -#define SD_BUS_ERROR_NAME_HAS_NO_OWNER "org.freedesktop.DBus.Error.NameHasNoOwner" -#define SD_BUS_ERROR_NO_REPLY "org.freedesktop.DBus.Error.NoReply" -#define SD_BUS_ERROR_IO_ERROR "org.freedesktop.DBus.Error.IOError" -#define SD_BUS_ERROR_BAD_ADDRESS "org.freedesktop.DBus.Error.BadAddress" -#define SD_BUS_ERROR_NOT_SUPPORTED "org.freedesktop.DBus.Error.NotSupported" -#define SD_BUS_ERROR_LIMITS_EXCEEDED "org.freedesktop.DBus.Error.LimitsExceeded" -#define SD_BUS_ERROR_ACCESS_DENIED "org.freedesktop.DBus.Error.AccessDenied" -#define SD_BUS_ERROR_AUTH_FAILED "org.freedesktop.DBus.Error.AuthFailed" -#define SD_BUS_ERROR_NO_SERVER "org.freedesktop.DBus.Error.NoServer" -#define SD_BUS_ERROR_TIMEOUT "org.freedesktop.DBus.Error.Timeout" -#define SD_BUS_ERROR_NO_NETWORK "org.freedesktop.DBus.Error.NoNetwork" -#define SD_BUS_ERROR_ADDRESS_IN_USE "org.freedesktop.DBus.Error.AddressInUse" -#define SD_BUS_ERROR_DISCONNECTED "org.freedesktop.DBus.Error.Disconnected" -#define SD_BUS_ERROR_INVALID_ARGS "org.freedesktop.DBus.Error.InvalidArgs" -#define SD_BUS_ERROR_FILE_NOT_FOUND "org.freedesktop.DBus.Error.FileNotFound" -#define SD_BUS_ERROR_FILE_EXISTS "org.freedesktop.DBus.Error.FileExists" -#define SD_BUS_ERROR_UNKNOWN_METHOD "org.freedesktop.DBus.Error.UnknownMethod" -#define SD_BUS_ERROR_UNKNOWN_OBJECT "org.freedesktop.DBus.Error.UnknownObject" -#define SD_BUS_ERROR_UNKNOWN_INTERFACE "org.freedesktop.DBus.Error.UnknownInterface" -#define SD_BUS_ERROR_UNKNOWN_PROPERTY "org.freedesktop.DBus.Error.UnknownProperty" -#define SD_BUS_ERROR_PROPERTY_READ_ONLY "org.freedesktop.DBus.Error.PropertyReadOnly" -#define SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN "org.freedesktop.DBus.Error.UnixProcessIdUnknown" -#define SD_BUS_ERROR_INVALID_SIGNATURE "org.freedesktop.DBus.Error.InvalidSignature" -#define SD_BUS_ERROR_INCONSISTENT_MESSAGE "org.freedesktop.DBus.Error.InconsistentMessage" -#define SD_BUS_ERROR_MATCH_RULE_NOT_FOUND "org.freedesktop.DBus.Error.MatchRuleNotFound" -#define SD_BUS_ERROR_MATCH_RULE_INVALID "org.freedesktop.DBus.Error.MatchRuleInvalid" + +#define SD_BUS_ERROR_FAILED "org.freedesktop.DBus.Error.Failed" +#define SD_BUS_ERROR_NO_MEMORY "org.freedesktop.DBus.Error.NoMemory" +#define SD_BUS_ERROR_SERVICE_UNKNOWN "org.freedesktop.DBus.Error.ServiceUnknown" +#define SD_BUS_ERROR_NAME_HAS_NO_OWNER "org.freedesktop.DBus.Error.NameHasNoOwner" +#define SD_BUS_ERROR_NO_REPLY "org.freedesktop.DBus.Error.NoReply" +#define SD_BUS_ERROR_IO_ERROR "org.freedesktop.DBus.Error.IOError" +#define SD_BUS_ERROR_BAD_ADDRESS "org.freedesktop.DBus.Error.BadAddress" +#define SD_BUS_ERROR_NOT_SUPPORTED "org.freedesktop.DBus.Error.NotSupported" +#define SD_BUS_ERROR_LIMITS_EXCEEDED "org.freedesktop.DBus.Error.LimitsExceeded" +#define SD_BUS_ERROR_ACCESS_DENIED "org.freedesktop.DBus.Error.AccessDenied" +#define SD_BUS_ERROR_AUTH_FAILED "org.freedesktop.DBus.Error.AuthFailed" +#define SD_BUS_ERROR_NO_SERVER "org.freedesktop.DBus.Error.NoServer" +#define SD_BUS_ERROR_TIMEOUT "org.freedesktop.DBus.Error.Timeout" +#define SD_BUS_ERROR_NO_NETWORK "org.freedesktop.DBus.Error.NoNetwork" +#define SD_BUS_ERROR_ADDRESS_IN_USE "org.freedesktop.DBus.Error.AddressInUse" +#define SD_BUS_ERROR_DISCONNECTED "org.freedesktop.DBus.Error.Disconnected" +#define SD_BUS_ERROR_INVALID_ARGS "org.freedesktop.DBus.Error.InvalidArgs" +#define SD_BUS_ERROR_FILE_NOT_FOUND "org.freedesktop.DBus.Error.FileNotFound" +#define SD_BUS_ERROR_FILE_EXISTS "org.freedesktop.DBus.Error.FileExists" +#define SD_BUS_ERROR_UNKNOWN_METHOD "org.freedesktop.DBus.Error.UnknownMethod" +#define SD_BUS_ERROR_UNKNOWN_OBJECT "org.freedesktop.DBus.Error.UnknownObject" +#define SD_BUS_ERROR_UNKNOWN_INTERFACE "org.freedesktop.DBus.Error.UnknownInterface" +#define SD_BUS_ERROR_UNKNOWN_PROPERTY "org.freedesktop.DBus.Error.UnknownProperty" +#define SD_BUS_ERROR_PROPERTY_READ_ONLY "org.freedesktop.DBus.Error.PropertyReadOnly" +#define SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN "org.freedesktop.DBus.Error.UnixProcessIdUnknown" +#define SD_BUS_ERROR_INVALID_SIGNATURE "org.freedesktop.DBus.Error.InvalidSignature" +#define SD_BUS_ERROR_INCONSISTENT_MESSAGE "org.freedesktop.DBus.Error.InconsistentMessage" +#define SD_BUS_ERROR_TIMED_OUT "org.freedesktop.DBus.Error.TimedOut" +#define SD_BUS_ERROR_MATCH_RULE_NOT_FOUND "org.freedesktop.DBus.Error.MatchRuleNotFound" +#define SD_BUS_ERROR_MATCH_RULE_INVALID "org.freedesktop.DBus.Error.MatchRuleInvalid" #define SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED \ - "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired" - + "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired" +#define SD_BUS_ERROR_INVALID_FILE_CONTENT "org.freedesktop.DBus.Error.InvalidFileContent" +#define SD_BUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN \ + "org.freedesktop.DBus.Error.SELinuxSecurityContextUnknown" +#define SD_BUS_ERROR_OBJECT_PATH_IN_USE "org.freedesktop.DBus.Error.ObjectPathInUse" + -- cgit v1.2.1