From 46d362f406e1a75fc8f924b9b16d5d352be6d081 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 4 Mar 2022 14:03:50 +0100 Subject: [PATCH 1/7] man: drop outdated info about polkit in pid1 Fixes #22648. --- man/org.freedesktop.systemd1.xml | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml index fdf8ca3cc8..f6d6cf1384 100644 --- a/man/org.freedesktop.systemd1.xml +++ b/man/org.freedesktop.systemd1.xml @@ -30,23 +30,19 @@ The service manager exposes a number of objects on the bus: one Manager object as a central entry point for clients along with individual objects - for each unit and for each queued job. The unit objects each implement a generic + for each unit and for each queued job. The unit objects implement a generic Unit interface as well as a type-specific interface. For example, service units implement both org.freedesktop.systemd1.Unit and org.freedesktop.system1.Service. The manager object can list - unit and job objects or directly convert a unit name or job id into a bus path of the corresponding + unit and job objects or directly convert a unit name or job identifier to a bus path of the corresponding D-Bus object. - Properties exposing time values are usually encoded in microseconds (usec) on the bus, even if + Properties exposing time values are usually encoded in microseconds (µs) on the bus, even if their corresponding settings in the unit files are in seconds. - In contrast to most of the other services of the systemd suite, PID 1 does not use - polkit - for controlling access to privileged operations, but relies exclusively on the low-level D-Bus policy - language. (This is done in order to avoid a cyclic dependency between polkit and systemd/PID 1.) This - means that sensitive operations exposed by PID 1 on the bus are generally not available to unprivileged - processes directly. However, some operations (such as shutdown/reboot/suspend) are made available through the D-Bus - API of logind, see + PID 1 uses polkit to + allow access to privileged operations for unprivileged processes. Some operations (such as + shutdown/reboot/suspend) are also available through the D-Bus API of logind, see org.freedesktop.login15. From 382586894b9c09974aa734a1f77d3f6f69126d76 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 4 Mar 2022 14:13:56 +0100 Subject: [PATCH 2/7] man: say that we ignore ignored options Fixes #22057. --- man/systemd.unit.xml | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index b36f36be7e..b20072f0a2 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -126,13 +126,11 @@ @ and the unit type suffix. In the unit file itself, the instance parameter may be referred to using %i and other specifiers, see below. - Unit files may contain additional options on top of those - listed here. If systemd encounters an unknown option, it will - write a warning log message but continue loading the unit. If an - option or section name is prefixed with , it is - ignored completely by systemd. Options within an ignored section - do not need the prefix. Applications may use this to include - additional information in the unit files. + Unit files may contain additional options on top of those listed here. If systemd encounters an + unknown option, it will write a warning log message but continue loading the unit. If an option or + section name is prefixed with , it is ignored completely by systemd. Options within an + ignored section do not need the prefix. Applications may use this to include additional information in + the unit files. To access those options, applications need to parse the unit files on their own. Units can be aliased (have an alternative name), by creating a symlink from the new name to the existing name in one of the unit search paths. For example, systemd-networkd.service From 3c080282e928a7edfcdb74feb2139ef1ac6f2ad0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 4 Mar 2022 15:23:17 +0100 Subject: [PATCH 3/7] man: fix formatting of macros in sd_bus_add_object docbook would convert the newline to a space before the first argument: SD_BUS_METHOD_WITH_ARGS( member, args, result, handler) And we need each item in a separate , otherwise they'll all be in one line. --- man/sd_bus_add_object.xml | 41 ++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/man/sd_bus_add_object.xml b/man/sd_bus_add_object.xml index 54683e4f11..dcf9377ffd 100644 --- a/man/sd_bus_add_object.xml +++ b/man/sd_bus_add_object.xml @@ -128,8 +128,7 @@ SD_BUS_VTABLE_END - SD_BUS_METHOD_WITH_ARGS_OFFSET( - member, + SD_BUS_METHOD_WITH_ARGS_OFFSET(member, args, result, handler, @@ -138,8 +137,7 @@ - SD_BUS_METHOD_WITH_ARGS( - member, + SD_BUS_METHOD_WITH_ARGS(member, args, result, handler, @@ -147,8 +145,7 @@ - SD_BUS_METHOD_WITH_NAMES_OFFSET( - member, + SD_BUS_METHOD_WITH_NAMES_OFFSET(member, signature, in_names, result, @@ -159,8 +156,7 @@ - SD_BUS_METHOD_WITH_NAMES( - member, + SD_BUS_METHOD_WITH_NAMES(member, signature, in_names, result, @@ -170,8 +166,7 @@ - SD_BUS_METHOD_WITH_OFFSET( - member, + SD_BUS_METHOD_WITH_OFFSET(member, signature, result, handler, @@ -180,8 +175,7 @@ - SD_BUS_METHOD( - member, + SD_BUS_METHOD(member, signature, result, handler, @@ -189,30 +183,26 @@ - SD_BUS_SIGNAL_WITH_ARGS( - member, + SD_BUS_SIGNAL_WITH_ARGS(member, args, flags) - SD_BUS_SIGNAL_WITH_NAMES( - member, + SD_BUS_SIGNAL_WITH_NAMES(member, signature, names, flags) - SD_BUS_SIGNAL( - member, + SD_BUS_SIGNAL(member, signature, flags) - SD_BUS_WRITABLE_PROPERTY( - member, + SD_BUS_WRITABLE_PROPERTY(member, signature, get, set, @@ -221,8 +211,7 @@ - SD_BUS_PROPERTY( - member, + SD_BUS_PROPERTY(member, signature, get, offset, @@ -231,9 +220,17 @@ SD_BUS_PARAM(name) + + SD_BUS_ARGS(...) + + SD_BUS_RESULT(...) + + SD_BUS_NO_ARGS + + SD_BUS_NO_RESULT From b4e7d7555e6266ff566a17eb5f616b365771028f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 4 Mar 2022 15:41:31 +0100 Subject: [PATCH 4/7] man: describe capability checks on the bus A description of SD_BUS_VTABLE_CAPABILITY is added, and the discussion on SD_BUS_VTABLE_UNPRIVILEGED in expanded. I think it would be nice to add longer description of how access is checked (maybe in sd-bus(3)), but I'm leaving that for later. I think the text that was added here describes everything, even if tersely. Fixes #21882. --- man/rules/meson.build | 1 + man/sd_bus_add_object.xml | 61 ++++++++++++++++++++++++----- src/libsystemd/sd-bus/bus-objects.c | 8 ++-- 3 files changed, 55 insertions(+), 15 deletions(-) diff --git a/man/rules/meson.build b/man/rules/meson.build index 793010f75f..2e334ff331 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -158,6 +158,7 @@ manpages = [ 'SD_BUS_PROPERTY', 'SD_BUS_SIGNAL', 'SD_BUS_SIGNAL_WITH_NAMES', + 'SD_BUS_VTABLE_CAPABILITY', 'SD_BUS_VTABLE_END', 'SD_BUS_VTABLE_START', 'SD_BUS_WRITABLE_PROPERTY', diff --git a/man/sd_bus_add_object.xml b/man/sd_bus_add_object.xml index dcf9377ffd..3249b7f98d 100644 --- a/man/sd_bus_add_object.xml +++ b/man/sd_bus_add_object.xml @@ -22,6 +22,7 @@ sd_bus_add_object_vtable sd_bus_add_fallback_vtable sd_bus_add_filter + SD_BUS_VTABLE_CAPABILITY SD_BUS_VTABLE_START SD_BUS_VTABLE_END SD_BUS_METHOD_WITH_NAMES_OFFSET @@ -121,6 +122,10 @@ void *userdata + + SD_BUS_VTABLE_CAPABILITY(capability) + + SD_BUS_VTABLE_START(flags) @@ -334,10 +339,12 @@ - SD_BUS_VTABLE_START() + SD_BUS_VTABLE_START(flags) SD_BUS_VTABLE_END - Those must always be the first and last element. + Those must always be the first and last element. The + flags parameter can be used to set attributes that apply to the whole + array; see the "Flags" section below. @@ -494,14 +501,6 @@ hidden. - - SD_BUS_VTABLE_UNPRIVILEGED - - Mark this vtable entry as unprivileged. If not specified, the - org.freedesktop.systemd1.Privileged annotation with value - true will be shown in introspection data. - - SD_BUS_VTABLE_METHOD_NO_REPLY @@ -558,6 +557,48 @@ passed directly, converted to a pointer, without taking the user data pointer specified during vtable registration into account. + + + SD_BUS_VTABLE_CAPABILITY(capability) + + Access to this vtable entry will be allowed if the calling proccess has the + capability capability, as described in + sd_bus_query_sender_privilege3. + If used for SD_BUS_VTABLE_START(), provides a default for all entries in the + array. If not specified, either for an individual entry or the whole array, + CAP_SYS_ADMIN is checked by default. See capabilities7 + for information about capabilities. + + Note that vtable entries may be marked as unprivileged and the whole bus may be marked as + trusted, see the discussion of SD_BUS_VTABLE_UNPRIVILEGED below. + + + + + SD_BUS_VTABLE_UNPRIVILEGED + + Mark this vtable entry as unprivileged. Access to privileged entries is limited to + users with appropriate capabilities as described above. In practice many vtable entries are marked + as unprivileged, and either are open to everyone, or the decision whether to allow access is taken + later, e.g. by delegating to polkit. + + The whole bus may be marked as trusted, in which case annotations at the entry level are + ignored, see + sd_bus_set_trusted3. + + + When not specified, the + org.freedesktop.systemd1.Privileged annotation with value + true will be shown in introspection data. + + Note that this page describes checks implemented in the D-Bus client. The D-Bus server has an + additional policy that may permit or deny connections, see + "CONFIGURATION FILE" in + dbus-daemon1. + + diff --git a/src/libsystemd/sd-bus/bus-objects.c b/src/libsystemd/sd-bus/bus-objects.c index 40158a7326..b852475419 100644 --- a/src/libsystemd/sd-bus/bus-objects.c +++ b/src/libsystemd/sd-bus/bus-objects.c @@ -315,11 +315,9 @@ static int check_access(sd_bus *bus, sd_bus_message *m, struct vtable_member *c, if (c->vtable->flags & SD_BUS_VTABLE_UNPRIVILEGED) return 0; - /* Check have the caller has the requested capability - * set. Note that the flags value contains the capability - * number plus one, which we need to subtract here. We do this - * so that we have 0 as special value for "default - * capability". */ + /* Check that the caller has the requested capability set. Note that the flags value contains the + * capability number plus one, which we need to subtract here. We do this so that we have 0 as + * special value for the default. */ cap = CAPABILITY_SHIFT(c->vtable->flags); if (cap == 0) cap = CAPABILITY_SHIFT(c->parent->vtable[0].flags); From 55fabe92e2efb1a907d4c3c93dc63b96ff5b6860 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 4 Mar 2022 16:07:19 +0100 Subject: [PATCH 5/7] man: tweak description of auto/noauto I think the current behaviour is stupid: 'x-systemd.automount,noauto' should mean that we create the units, but don't add .mount or .automount to any targets. Instead, we completely ignore 'noauto'. But let's at least describe the implementation. Text suggested by dpartrid in the bug. Fixes #21040. --- man/systemd.mount.xml | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index 6b0efb68df..6d21d32778 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -399,11 +399,13 @@ With , the mount unit will not be added as a dependency for - local-fs.target or remote-fs.target. This means that it will not be - mounted automatically during boot, unless it is pulled in by some other unit. The option - has the opposite meaning and is the default. Note that the option has an effect on the - mount unit itself only — if is used (see above), then the matching - automount unit will still be pulled in by these targets. + local-fs.target or remote-fs.target. This means that it + will not be mounted automatically during boot, unless it is pulled in by some other unit. The + option has the opposite meaning and is the default. + + Note that if (see above) is used, neither + nor have any effect. The matching automount unit will + be added as a dependency to the appropriate target. From c1d1742a7f6a65f60dce1a4f22a22d443493757c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 4 Mar 2022 16:26:12 +0100 Subject: [PATCH 6/7] man: describe UNIT=/USER_UNIT= Fixes 17538. --- man/systemd.journal-fields.xml | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index 241d60f673..d50e89f0bb 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -145,7 +145,7 @@ A documentation URL with further information about the topic of the log message. Tools such as journalctl will include a hyperlink to an URL specified this way in their - output. Should be a http://, https://, + output. Should be an http://, https://, file:/, man: or info: URL. @@ -156,6 +156,21 @@ The numeric thread ID (TID) the log message originates from. + + + UNIT= + USER_UNIT= + + The name of a unit. Used by the system and user managers when logging about specific + units. + + When or + are used with + journalctl1, a + match pattern that includes UNIT=name.service or + USER_UNIT=name.service will be generated. + + From 367a5e8a67bbc2b5e03ca1a3e5a601ef49b5bd2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 4 Mar 2022 16:39:34 +0100 Subject: [PATCH 7/7] journalctl: advertise --header a bit more Fixes #2738. --- man/journalctl.xml | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/man/journalctl.xml b/man/journalctl.xml index 9e784f3d3c..424acc9f16 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -85,10 +85,10 @@ , , etc., to further limit what entries will be shown (logical AND). - Output is interleaved from all accessible journal files, - whether they are rotated or currently being written, and - regardless of whether they belong to the system itself or are - accessible user journals. + Output is interleaved from all accessible journal files, whether they are rotated or currently + being written, and regardless of whether they belong to the system itself or are accessible user + journals. The option can be used to identify which files + are being shown. The set of journal files which will be used can be modified using the , @@ -794,9 +794,11 @@ - Instead of showing journal contents, show - internal header information of the journal fields - accessed. + Instead of showing journal contents, show internal header information of the journal + fields accessed. + + This option is particularly useful when trying to identify out-of-order journal entries, as + happens for example when the machine is booted with the wrong system time.