From 2e290d55fd1ff9483315dcbe86cae091f333d68f Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 8 Nov 2023 10:31:55 +0100 Subject: [PATCH 1/9] man: add missing unit file section name to example Fixes: #29917 --- man/systemd-creds.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/systemd-creds.xml b/man/systemd-creds.xml index f2dff10ff1..d48f667b8b 100644 --- a/man/systemd-creds.xml +++ b/man/systemd-creds.xml @@ -475,7 +475,7 @@ SetCredentialEncrypted=mysql-password: \ xyz.service: # mkdir -p /etc/systemd/system/xyz.service.d -# systemd-ask-password -n | systemd-creds encrypt --name=mysql-password -p - - >/etc/systemd/system/xyz.service.d/50-password.conf +# systemd-ask-password -n | ( echo "[Service]" && systemd-creds encrypt --name=mysql-password -p - - ) >/etc/systemd/system/xyz.service.d/50-password.conf # systemctl daemon-reload # systemctl restart xyz.service From a9d54de66d62b1180aef845fae2eabde4968dda5 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 8 Nov 2023 10:48:41 +0100 Subject: [PATCH 2/9] man: update COREDUMP_xyz journal fields docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This completes/corrects the documentation for the following fields: COREDUMP_CGROUP= - doc where wrong, actually covered COREDUMP_PROC_CGROUP= COREDUMP_CMDLINE= → undocumented so far COREDUMP_PROC_CGROUP= → docs where there but incorrectly assigned to COREDUMP_CGROUP= COREDUMP_PROC_AUXV= → undocumented so far COREDUMP_SESSION= → undocumented so far Fixes: #29832 --- man/systemd-coredump.xml | 47 ++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 14 deletions(-) diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml index 0c1efabcc1..dafdc01a49 100644 --- a/man/systemd-coredump.xml +++ b/man/systemd-coredump.xml @@ -223,6 +223,18 @@ COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst COREDUMP_CGROUP= + + The primary cgroup of the unit of the crashed process. + + When the crashed process was in a container, this is the full path, as seen outside of the + container. + + + + + + + COREDUMP_PROC_CGROUP= Control group information in the format used in /proc/self/cgroup. On systems with the unified cgroup hierarchy, this is a single path prefixed with 0::, and multiple paths prefixed with controller numbers @@ -238,9 +250,10 @@ COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web….552351.….zst COREDUMP_OWNER_UID= COREDUMP_USER_UNIT= + COREDUMP_SESSION= The numerical UID of the user owning the login session or systemd user unit of the - crashed process, and the user manager unit. Both fields are only present for user processes. - + crashed process, the user manager unit, and the sesion identifier. All three fields are only present + for user processes. When the crashed process was in container, those are the values outside, in the main system. @@ -315,23 +328,29 @@ flags: ... + COREDUMP_CMDLINE= COREDUMP_COMM= - COREDUMP_PROC_STATUS= - COREDUMP_PROC_MAPS= - COREDUMP_PROC_LIMITS= - COREDUMP_PROC_MOUNTINFO= COREDUMP_ENVIRON= + COREDUMP_PROC_AUXV= + COREDUMP_PROC_LIMITS= + COREDUMP_PROC_MAPS= + COREDUMP_PROC_MOUNTINFO= + COREDUMP_PROC_STATUS= Fields that map the per-process entries in the /proc/ - filesystem: /proc/pid/comm (the command name - associated with the process), /proc/pid/exe (the - filename of the executed command), /proc/pid/status - (various metadata about the process), /proc/pid/maps - (memory regions visible to the process and their access permissions), + filesystem: /proc/pid/cmdline (the command line of + the crashed process), /proc/pid/comm (the command + name associated with the process), /proc/pid/environ + (the environment block of the crashed process), + /proc/pid/auxv (the auxiliary vector of the crashed + process, see getauxval3), /proc/pid/limits (the soft and hard resource limits), - /proc/pid/mountinfo (mount points in the process's - mount namespace), /proc/pid/environ - (the environment block of the crashed process). + /proc/pid/maps (memory regions visible to the process + and their access permissions), /proc/pid/mountinfo + (mount points in the process's mount namespace), + /proc/pid/status (various metadata about the + process). See proc5 From 3cb938bd12b3603984b982e9b73e4cabd4a608e3 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 8 Nov 2023 10:56:07 +0100 Subject: [PATCH 3/9] man: be even clearer that tmpfiles user/group/mode are applied on existing inodes I think it was clear already, but let's be even clearer. Fixes: #29774 --- man/tmpfiles.d.xml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index 38999ec00e..971b7e6a9e 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -574,9 +574,10 @@ w- /proc/sys/vm/swappiness - - - - 10 removed unless applied to a directory. This functionality is particularly useful in conjunction with Z. - Optionally, if prefixed with :, the configured access mode is only used when - creating new inodes. If the inode the line refers to already exists, its access mode is left in place - unmodified. + By default the access mode of listed inodes is set to the specified mode regardless if it is + created anew, or already existed. Optionally, if prefixed with :, the configured + access mode is only applied when creating new inodes, and if the inode the line refers to + already exists, its access mode is left in place unmodified. @@ -599,9 +600,10 @@ w- /proc/sys/vm/swappiness - - - - 10 Resolvability of User and Group Names for more information on requirements on system user/group definitions. - Optionally, if prefixed with :, the configured user/group information is only - used when creating new inodes. If the inode the line refers to already exists, its user/group is left - in place unmodified. + By default the ownership of listed inodes is set to the specified user/group regardless if it is + created anew, or already existed. Optionally, if prefixed with :, the configured + user/group information is only applied when creating new inodes, and if the inode the line refers to + already exists, its user/group is left in place unmodified. From 7480859a11718093db573c41c5ce5f0fc9f816e6 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 8 Nov 2023 11:11:22 +0100 Subject: [PATCH 4/9] man,doc: document some aspects of user record management/homed a bit better Fixes: #29759 --- docs/USER_RECORD.md | 40 +++++++++++++++++++++++------------ man/org.freedesktop.home1.xml | 11 +++++++--- 2 files changed, 34 insertions(+), 17 deletions(-) diff --git a/docs/USER_RECORD.md b/docs/USER_RECORD.md index 381c981a07..d5d1566267 100644 --- a/docs/USER_RECORD.md +++ b/docs/USER_RECORD.md @@ -704,28 +704,40 @@ for other purposes too. The `perMachine` field in the top-level object is an array of objects. When processing the user record first the various fields on the top-level object -should be used. Then this array should be iterated in order, and the various -settings be applied that match either the indicated machine ID or host -name. There may be multiple array entries that match a specific system, in -which case all the object's setting should be applied. If the same option is -set in the top-level object as in a per-machine object the latter wins and -entirely undoes the setting in the top-level object (i.e. no merging of -properties that are arrays themselves is done). If the same option is set in -multiple per-machine objects the one specified later in the array wins (and -here too no merging of individual fields is done, the later field always wins -in full). +should be parsed. Then, the `perMachine` array should be iterated in order, and +the various settings within each contained object should be applied that match +either the indicated machine ID or host name, overriding any corresponding +settings previously parsed from the top-level object. There may be multiple +array entries that match a specific system, in which case all settings should +be applied. If the same option is set in the top-level object as in a +per-machine object then the per-machine setting wins and entirely undoes the +setting in the top-level object (i.e. no merging of properties that are arrays +is done). If the same option is set in multiple per-machine objects the one +specified later in the array wins (and here too no merging of individual fields +is done, the later field always wins in full). To summarize, the order of +application is (last one wins): + +1. Settings in the top-level object +2. Settings in the first matching `perMachine` array entry +3. Settings in the second matching `perMachine` array entry +4. … +5. Settings in the last matching `perMachine` array entry The following fields are defined in this section: `matchMachineId` → An array of strings that are formatted 128-bit IDs in hex. If any of the specified IDs match the system's local machine ID -(i.e. matches `/etc/machine-id`) the fields in this object are honored. +(i.e. matches `/etc/machine-id`) the fields in this object are honored. (As a +special case, if only a single machine ID is listed this field may be a single +string rather than an array of strings.) -`matchHostname` → An array of strings that are valid hostnames. If any of -the specified hostnames match the system's local hostname, the fields in this +`matchHostname` → An array of strings that are valid hostnames. If any of the +specified hostnames match the system's local hostname, the fields in this object are honored. If both `matchHostname` and `matchMachineId` are used within the same array entry, the object is honored when either match succeeds, -i.e. the two match types are combined in OR, not in AND. +i.e. the two match types are combined in OR, not in AND. (As a special case, if +only a single machine ID is listed this field may be a single string rather +than an array of strings.) These two are the only two fields specific to this section. All other fields that may be used in this section are identical to the equally named ones in the diff --git a/man/org.freedesktop.home1.xml b/man/org.freedesktop.home1.xml index 2ca97eff34..f217fb8d52 100644 --- a/man/org.freedesktop.home1.xml +++ b/man/org.freedesktop.home1.xml @@ -305,9 +305,14 @@ node /org/freedesktop/home1 { user record with the new passwords/authentication token data is specified as empty the existing user record's settings are propagated down to the home directory storage. This is typically used after a user record is updated using UpdateHome() in order to propagate the - secrets/authentication tokens down to the storage. This method is equivalent to - ChangePassword() on the org.freedesktop.home1.Home - interface. + secrets/authentication tokens down to the storage. Background: depending on the backend the user's + authentication credentials are stored at multiple places: the user record kept on the host, the user + record kept in the home directory and the encrypted LUKS volume slot. If the home directory is used on + a different machined temporarily, and the password is changed there, and then is moved back to the + original host, the passwords of the three might get out of sync. By issuing + ChangePasswordHome() the three locations are updated to match the newest + information. This method is equivalent to ChangePassword() on the + org.freedesktop.home1.Home interface. LockHome() temporarily suspends access to a home directory, flushing out any cryptographic keys from memory. This is only supported on some back-ends, and usually done during system From 244101876ccd8dc28e8527d02e3a8ac822dc19ac Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 8 Nov 2023 11:21:53 +0100 Subject: [PATCH 5/9] man: explicitly document compat guarantees of cryptenroll vs. cryptsetup Fixes: #29743 --- man/systemd-cryptenroll.xml | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml index ad32bf68f2..b40d202233 100644 --- a/man/systemd-cryptenroll.xml +++ b/man/systemd-cryptenroll.xml @@ -235,6 +235,30 @@ limitation does not apply to PKCS#11 tokens. + + Compatibility + + Security technology both in systemd and in the general industry constantly evolves. In order to + provide best security guarantees, the way TPM2, FIDO2, PKCS#11 devices are enrolled is regularly updated + in newer versions of systemd. Whenever this happens the following compatibility guarantees are given: + + + Old enrollments continue to be supported and may be unlocked with newer versions of + systemd-cryptsetup@.service8. + + The opposite is not guaranteed however: it might not be possible to unlock volumes with + enrollments done with a newer version of systemd-cryptenroll with an older version + of systemd-cryptsetup. + + + That said, it is generally recommended to use matching versions of + systemd-cryptenroll and systemd-cryptsetup, since this is best + tested and supported. + + It might be advisable to re-enroll existing enrollments to take benefit of newer security features, + as they are added to systemd. + + Options From 28562194c49003b8f6af0df24c33b4f6d8a8df1e Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 8 Nov 2023 11:35:35 +0100 Subject: [PATCH 6/9] service: say explicitly that people should not use different NonBlocking= settings if they share socket units between multiple service units Fixes: #29600 --- man/systemd.service.xml | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 735c98d1d6..123f1db30d 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1064,14 +1064,25 @@ NonBlocking= - Set the O_NONBLOCK flag for all file descriptors passed via socket-based - activation. If true, all file descriptors >= 3 (i.e. all except stdin, stdout, stderr), excluding those passed - in via the file descriptor storage logic (see FileDescriptorStoreMax= for details), will - have the O_NONBLOCK flag set and hence are in non-blocking mode. This option is only + Set the O_NONBLOCK flag for all file descriptors passed via + socket-based activation. If true, all file descriptors >= 3 (i.e. all except stdin, stdout, stderr), + excluding those passed in via the file descriptor storage logic (see + FileDescriptorStoreMax= for details), will have the + O_NONBLOCK flag set and hence are in non-blocking mode. This option is only useful in conjunction with a socket unit, as described in - systemd.socket5 and has no - effect on file descriptors which were previously saved in the file-descriptor store for example. Defaults to - false. + systemd.socket5 + and has no effect on file descriptors which were previously saved in the file-descriptor store for + example. Defaults to false. + + Note that if the same socket unit is configured to be passed to multiple service units (via the + Sockets= setting, see below), and these services have different + NonBlocking= configurations, the precise state of O_NONBLOCK + depends on the order in which these services are invoked, and will possibly change after service code + already took possession of the socket file descriptor, simply because the + O_NONBLOCK state of a socket is shared by all file descriptors referencing + it. Hence it is essential that all services sharing the same socket use the same + NonBlocking= configuration, and do not change the flag in service code + either. From 28e3359fdcf5590014a3f36da385e6aa1459f7da Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 8 Nov 2023 11:52:53 +0100 Subject: [PATCH 7/9] man: document that Domains=local bind the domain to unicast DNS, not mDNS Fixes: #28983 --- man/resolved.conf.xml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml index 8edd6c94ef..d153865c6e 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -107,6 +107,13 @@ systemd-resolved.service8 for details of how search and route-only domains are used. + Note that configuring the MulticastDNS domain local as search or routing + domain has the effect of routing lookups for this domain to classic unicast DNS. This may be used to + provide compatibility with legacy installations that use this domain in a unicast DNS context, + against the IANA assignment of this domain to pure MulticastDNS purposes. Search and routing domains + are a unicast DNS concept, they cannot be used to resolve single-label lookups + via MulticastDNS. + From d33121d27d284ae558b576cc07fb8f9bb44b35cd Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 8 Nov 2023 11:57:44 +0100 Subject: [PATCH 8/9] man: document that changing --uid= doesn't work Fixes: #28982 --- man/homectl.xml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/man/homectl.xml b/man/homectl.xml index 1cfbdcd4f8..7fc7d5f012 100644 --- a/man/homectl.xml +++ b/man/homectl.xml @@ -269,6 +269,11 @@ owned by a different UID when logging in, the home directory and everything underneath it will have its ownership changed automatically before login completes. + Note that changing this option for existing home directories generally has no effect on home + directories that already have been registered locally (have a local binding), as + the UID used for an account on the local system is determined when the home directory is first + activated on it, and then remains in effect until the home directory is removed. + Note that users managed by systemd-homed always have a matching group associated with the same name as well as a GID matching the UID of the user. Thus, configuring the GID separately is not permitted. From cff559ec3aa5374890ceecc3660d635edf2ebb0f Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 8 Nov 2023 12:00:19 +0100 Subject: [PATCH 9/9] update TODO --- TODO | 2 ++ 1 file changed, 2 insertions(+) diff --git a/TODO b/TODO index 25165de973..8fee0eac7d 100644 --- a/TODO +++ b/TODO @@ -2243,6 +2243,8 @@ Features: avatar/photo or so. This data should be stored along with the user record, but probably shouldn't be part of the record itself, since it might be large. + - add "homectl unbind" command to remove local user record of an inactive + home dir * add a new switch --auto-definitions=yes/no or so to systemd-repart. If specified, synthesize a definition automatically if we can: enlarge last