Users and Groups Guidelines

This guideline is for packaging cases that require creation of users and groups.

Basic premise for users

In designing these guidelines it was accepted that individual sites will have a need to customize the allocation of UIDs and GIDs to their particular systems. For instance, if they have both Debian and Fedora installs or if they’ve already allocated user accounts in the range that we use for system accounts and need to place system accounts elsewhere. Therefore, the methods that these guidelines advocate had to be adaptable so that local sysadmins could make our packages use the UIDs and GIDs that they desired at their site.

The guidelines provide two options: letting each individual system allocate UID and GID values individually or using a "soft static" allocation that attempts to allocate UIDs and GIDs consistently. In either case, if the username or groupname being created by the package already exists on the system the package will use that instead of creating a new one. This allows the local system administrator to pre-allocate the UIDs and GIDs for particular usernames and groupnames in order to set them to a particular value for their site.

Methods of pre-allocating

There are many ways to pre-allocate the UIDs and GIDs. Sites that only want to customize the UIDs and GIDs of a few nonessential services may write a script to create the entries with useradd and groupadd and install our package afterwards.

Sites that want to pre-allocate accounts that are needed during an unattended kickstart install have trickier problem. One way for them to accomplish their goals is to create a customized version of the “setup” package with the desired users and groups along with their chosen UID/GID mappings in the /etc/passwd, /etc/shadow, and /etc/group files. Then they make sure the install transaction uses that package instead of the vanilla distro one (by versioning their setup package higher than ours (for instance, with an epoch) and putting it in a local repo they include when installing or replacing our setup package with their own in a local mirror of the packages that they are installing from). Since setup is at the top of the dependency tree, it will be installed before any package which needs to use the UIDs and GIDs that are defined in it.

Using LDAP to preallocate: Sites with LDAP or other network authentication systems may want to use those for pre-allocating their system accounts sitewide. Such sites should make sure their infrastructure is robust and includes suitable local caching of the system accounts. Without suitable local caching, a computer that becomes disconnected from the network may not be able to start essential services because the computer is unable to resolve a username or groupname to a proper UID or GID.

Known caveat of the pre-allocation strategy

The practice of using existing users and groups if their symbolic names (usernames and groupnames) already exists on the system lets the system administrator customize the UIDs and GIDs as they please. However, it has one drawback that system admins should be aware of. If an unrelated account has already been created that uses those usernames and groupnames the package will make use of those accounts.

As an example, say that you are installing the mailman package which wants to create the mailman user and group so that the private mailing list archives can be owned by that user and group on disk. One of your local users already has the local username mailman. When the mailman package is installed, it will detect that there is already a mailman user and use that account for owning its private archives. The local user who owns the mailman account would then be able to read those private archives.

At the moment, there is no strategy for the packagers to counteract this. It is up to the site system administrators to keep track of and remove conflicts for the user and group names used by their users and those used by the packages they are using.

Allocation Strategies

We have two methods for creating users and groups: Dynamic and Soft Static.

Any package can use dynamic allocation; it is especially appropriate for packages that use separate identities only for privilege separation and don’t create any files owned by that group/user account. Because of the limited number of soft static UIDs and GIDs available, it is better to use dynamic allocation if in doubt.

Soft static allocation ensures that multiple independently installed systems use the same UID and GID values; either UID and GID values allocated by Fedora or values that were optionally pre-allocated by the system administrator. Don’t use soft static allocation unnecessarily as the number of available values is limited. Soft static allocation is only appropriate for packages where the UID or GID values are shared between computers. For instance, if the package creates files with the assigned UID or GID that are likely to be shared over NFS. Soft static allocation MUST be evaluated by the FPC. See the paragraph in the soft static section for details the FPC will want.

In some cases it is desirable to create only a group without a user account. Usually this is because there are some system resources to which we want to control access by using that group and a separate user account would add no value. Examples of common such cases include (but are not limited to) games whose executables are setgid for the purpose of sharing high score files or the like, and/or software that needs exceptional permissions to some hardware devices and it wouldn’t be appropriate to grant those to all system users nor even only those logged in on the console. 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:

Create a <package-name>.sysusers file with the user definition and add it to the specfile as a source. For example for the munge package, this file contains:

#Type Name   ID  GECOS                        Home directory  Shell
u     munge  -   "Runs Uid 'N' Gid Emporium"  /run/munge      /sbin/nologin

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 %sysusers_requires_compat macro to specify the runtime dependencies for the %pre section:

[...]
BuildRequires: systemd-rpm-macros %{?sysusers_requires_compat}

[...]
%install install -p -D -m 0644 %{SOURCE3} %{buildroot}%{_sysusersdir}/munge.conf

[...]
%pre %sysusers_create_compat %{SOURCE3}

[...]
%files %{_sysusersdir}/munge.conf
[...]

Soft static allocation

To allocate a UID and/or GID, file a ticket here for the FPC to evaluate. If the FPC finds that your package needs a soft static UID or GID, they will approve your request and pass it on to the maintainers of the setup package for implementation. Because the number of UIDs and GIDs is limited, you need to justify your package’s need for a soft static uid in the FPC ticket. Explain how the uids and gids are being shared between computers. If applicable, also explain why the program can’t be adapted to use symbolic names (username and groupname) instead. If a specific UID or GID should be used, please mention it and why (for instance, it is the one used by upstream 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.

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

,=== User name,UID,Package,Comments

,=== Group name,GID,Package,Comments

root,0,https://src.fedoraproject.org/rpms/setup[setup], bin,1,https://src.fedoraproject.org/rpms/setup[setup], daemon,2,https://src.fedoraproject.org/rpms/setup[setup], sys,3,https://src.fedoraproject.org/rpms/setup[setup], adm,4,https://src.fedoraproject.org/rpms/setup[setup], tty,5,https://src.fedoraproject.org/rpms/setup[setup], disk,6,https://src.fedoraproject.org/rpms/setup[setup], lp,7,https://src.fedoraproject.org/rpms/setup[setup], mem,8,https://src.fedoraproject.org/rpms/setup[setup], kmem,9,https://src.fedoraproject.org/rpms/setup[setup], wheel,10,https://src.fedoraproject.org/rpms/setup[setup], cdrom,11,https://src.fedoraproject.org/rpms/setup[setup], mail,12,https://src.fedoraproject.org/rpms/setup[setup], man,15,https://src.fedoraproject.org/rpms/setup[setup], dialout,18,https://src.fedoraproject.org/rpms/setup[setup], floppy,19,https://src.fedoraproject.org/rpms/setup[setup], games,20,https://src.fedoraproject.org/rpms/setup[setup], utmp,22,https://src.fedoraproject.org/rpms/libutempter[libutempter], postgres,26,https://src.fedoraproject.org/rpms/postgresql[postgresql], rpc,32,https://src.fedoraproject.org/rpms/rpcbind[rpcbind], tape,33,https://src.fedoraproject.org/rpms/setup[setup], utempter,35,https://src.fedoraproject.org/rpms/libutempter[libutempter], kvm,36,https://src.fedoraproject.org/rpms/libvirt[libvirt], video,39,https://src.fedoraproject.org/rpms/setup[setup], gdm,42,https://src.fedoraproject.org/rpms/gdm[gdm], ftp,50,https://src.fedoraproject.org/rpms/setup[setup], lock,54,https://src.fedoraproject.org/rpms/setup[setup], tss,59,https://src.fedoraproject.org/rpms/tpm2-tss[tpm2-tss], audio,63,https://src.fedoraproject.org/rpms/setup[setup], tcpdump,72,https://src.fedoraproject.org/rpms/tcpdump[tcpdump], sshd,74,https://src.fedoraproject.org/rpms/openssh[openssh-server], dbus,81,https://src.fedoraproject.org/rpms/dbus[dbus-daemon], users,100,https://src.fedoraproject.org/rpms/setup[setup], qemu,107,https://src.fedoraproject.org/rpms/libvirt[libvirt], mock,135,https://src.fedoraproject.org/rpms/mock[mock], ceph,167,https://src.fedoraproject.org/rpms/ceph[ceph-common], nobody,65534,https://src.fedoraproject.org/rpms/setup[setup], ,===

Want to help? Learn how to contribute to Fedora Docs ›