From 1e70fd534bc97ca15ab4a80eed3b420d69478ad1 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Feb 13 2025 17:15:51 +0000 Subject: [PATCH 1/2] Drop obsolete chunk of text explaining scriptlet usage The scriptlets were removed in 6d066acbb16452e1befc2f384d2f14bab9f54361: 'UsersAndGroups: Use %sysusers_create_compat macro', 2020-12-10. That explanation was left behind, but it doesn't make sense without the scriptlets, and the variables like USERNAME/GROUPNAME/HOMEDIR are not used anywhere either. --- diff --git a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc index 1ea737e..2461f54 100644 --- a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc +++ b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc @@ -192,51 +192,6 @@ To create users and groups in packages with an allocated UID/GID, add a sysusers that specifies the ID for the given user and/or group and follow the same steps as in the dynamic allocation section above. -=== Values given to useradd and groupadd - -* `+HOMEDIR+` should usually be a directory created and owned by the package, - with appropriately restrictive permissions. - One good choice for the location of the directory - is the package's data directory in case it has one. -* `+USERNAME+` and `+GROUPNAME+` are the symbolic names used by your package. - Be aware that all code in the package should use these names, - not the UID or GID. - If this is not possible, please mention it within the ticket - so that the FPC can see if this is a different type of problem than we usually encounter. -* `+ALLOCATED_UID+` and `+ALLOCATED_GID+` are the UID and GID - that FPC tells you has been allocated for use by your package. -* User accounts created by packages are rarely used for interactive logons, - and should thus generally use `+/sbin/nologin+` as the user's shell. - -=== Rationale for some of the implementation choices - -* We run `+getent+` before `+groupadd+` and `+useradd+` - to check whether the user/group we're about to create - already exists and skip the creation if they do. - This is what allows the local system administrators - to customize the users and groups beforehand - in case they wish to get a predefined static UID/GID mapping for those users. - Similarly, we verify whether the ID values - allocated in the "setup" package - aren't already allocated by the local system administrators. -* We want to invoke `+groupadd+` explicitly - instead of relying on `+useradd+` to create the group for us. - This is because `+useradd+` alone would fail - if the group it tries to create already existed. -* We run the `+groupadd+`/`+useradd+` always - -- both on initial installs and upgrades -- in `+%pre+`. - This is made possible by the `+getent+` checks above, - and should fix things up if the user/group has disappeared - after the package to be upgraded was initially installed - (just like file permissions get reset on upgrades etc). -* The `+exit 0+` at the end will result in the `+%pre+` scriptlet - passing through even if the user/group creation fails for some reason. - This is suboptimal but has less potential for system wide breakage - than allowing it to fail. - If the user/group aren't available - at the time the package's payload is unpacked, - rpm will fall back to setting those files owned by root. - === List of statically allocated UID/GID and corresponding package The list of statically allocated accounts is maintained in the `setup` package: From b85d6de4858b9a826c69ca531d1c2ec2813f141e Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Feb 13 2025 17:15:51 +0000 Subject: [PATCH 2/2] UsersAndGroups: switch to sysusers.d for F42+ https://fedoraproject.org/wiki/Changes/RPMSuportForSystemdSysusers simplifies the creation of system users and groups: the package only has to provide a sysusers.d config file as part of the payload and rpm will implement this configuration before the package is installed. Before this patch, %sysusers_create_compat was the only documented way to create users and groups. The traditional approach with getent/useradd/groupadd was dropped a few years ago (6d066acbb16452e1befc2f384d2f14bab9f54361: 'UsersAndGroups: Use %sysusers_create_compat macro', 2020-12-10). So what this patch effectively does is to drop the requirement for the sysusers file to be a separate Source and to call %sysusers_create_compat in F42+. Some packages still use the old old approach of manual getent/useradd/groupadd scriptlets. This hasn't been documented for the last four years. We generally do not require packages to update when packaging guidelines are changed, so those packages are "fine", but we want them to switch to provide sysusers files. The transition plan is: - spec files only for F42+ only need to provide a sysusers file - spec files for F42- or compatible with both are recommended to use the previously-described approach with %sysusers_create_compat. - spec files which use the old old approach can switch to %sysusers_create_compat (if a single spec file is to be used in multiple branches), or just switch to the new approach in the rawhide branch. While packages that create users via scriptlets will continue to work, we want to switch all packages to the new scheme. We have dependencies between packages that create and use system accounts. Rpm will automatically create dependencies on user and group accounts for files that are the package payload. Currently those dependencies are weak (Recommends), and the first attempt to switch to strong dependencies caused installability issues. But once we have sysusers.d definitions for all users/groups used by packages, we can switch those dependencies to strong (Requires). Thus we need to provide full sysusers.d coverage of users to allow robust sorting of packages during install. Once this is merged, I'll change the %sysusers_create_compat and %sysusers_requires_compat to be empty. --- diff --git a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc index 2461f54..6dc7b87 100644 --- a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc +++ b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc @@ -135,15 +135,35 @@ In these cases, apply only the `+groupadd+` parts of the below recipes. === Dynamic allocation -To create users and groups in packages using dynamic allocation, do the following: +To create system users and groups in packages using dynamic allocation, +the package shall install a `sysusers.d/.conf` file. +If it is not provided by the upstream, +the maintainer *should* provide one either as a separate `+Source+` +or otherwise create it during the package build. -Create a `.sysusers` file with the user definition and add it to the specfile as a source. -For example for the `munge` package, this file contains: +For example for the `munge` package, this file may contain: ``` #Type Name ID GECOS Home directory Shell -u munge - "Runs Uid 'N' Gid Emporium" /run/munge /sbin/nologin +u munge - "Runs Uid 'N' Gid Emporium" /run/munge - ``` +(The shell is not specified, so the default of `nologin` shall be used.) + +When a package with a sysusers.d file is built, +a virtual `Provides` for `+user(…)+` and `+group(…)+` is automatically generated. +When `rpm` installs a package with such `Provides`, +it shall create the users and groups according to those definitions. + +Use `+rpm -q --qf='[%{SYSUSERS}\n]' …+` to view the definitions of users and groups +decoded from the virtual `Provides`. + +=== Creation of users and groups with scriptlets + +For Fedora releases before 42, +manual creation of users and groups is required. + +The sysusers file must be a separate `Source` file. + In the specfile, add a BuildRequires for systemd-rpm-macros, install the sysusers file, use the `%sysusers_create_compat` macro to consume it in the `%pre` section (in this example the sysusers config file is `Source3` of the specfile), and the @@ -168,6 +188,11 @@ install -p -D -m 0644 %{SOURCE3} %{buildroot}%{_sysusersdir}/munge.conf [...] ``` +This form is compatible with Fedora 42+, +and the same spec file may be used for older and newer releases. +In F42+, the `%sysusers_requires_compat` and `%sysusers_create_compat` +macros will evaluate as empty. + === Soft static allocation To allocate a UID and/or GID, @@ -188,9 +213,22 @@ or the one used by other distributions). We will try to accommodate on a first-come-first serve basis if the UID/GID is available from within the Fedora system UID/GID range. -To create users and groups in packages with an allocated UID/GID, add a sysusers file -that specifies the ID for the given user and/or group and follow the same steps as in -the dynamic allocation section above. +To create users and groups in packages with an allocated UID/GID, +follow the steps in the dynamic allocation section above, +but add the UID or GID in the `ID` column. + +=== Sharing of users or groups between packages + +The package that provides the definition of the user or group account +has automatically-generated virtual `Provides`. +Other packages which want to ensure that users or groups exist, +*may* use `Requires` on the user or group names. + +For example, `+Requires: user(mock)+` or `+Requires: group(man)+`. + +`rpm` automatically creates weak dependencies (`Recommends`) +for packages which contain files owned by users and groups. +In the future, those depencencies will be changed to `Requires`. === List of statically allocated UID/GID and corresponding package