User Creation

Disclaimer

This page is in the PackagingDrafts category only due to organisational reasons but not because it requires discussion. fedora-usermgmt is an existing technology which is used by many packages already. This page shall be understood as documentation about the features of fedora-usermgmt.

Documentation

Using 'fedora-usermgmt' is optional and not required by packaging guidelines. When you want it for your package, register a user in the User Registry and add something like the following to your package spec:

Requires(pre): fedora-usermgmt
Requires(postun): fedora-usermgmt

...

%pre
/usr/sbin/fedora-groupadd %uid -r %username &>/dev/null || :
/usr/sbin/fedora-useradd  %uid -r -s /sbin/nologin -d %homedir -M          \
-c '%gecos' -g %username %username &>/dev/null || :

%postun
test "$1" != 0 || /usr/sbin/fedora-userdel  %username &>/dev/null || :
test "$1" != 0 || /usr/sbin/fedora-groupdel %username &>/dev/null || :

The following values should be used:

%uid ... the uid from the User Registry
%username ... the username from the User Registry
%home ... the homedir (usually %_var/lib/%username)
%gecos ... the GECOS entry

Beginning with Fedora Core 6, the following format is possible/shall be used:

%bcond_without	fedora

BuildRequires:	fedora-usermgmt-devel
%{?FE_USERADD_REQ}
...
%pre
%__fe_groupadd %uid -r %username &>/dev/null || :
%__fe_useradd  %uid -r -s /sbin/nologin -d %homedir -M          \
-c '%gecos' -g %username %username &>/dev/null || :

%postun
%__fe_userdel  %username &>/dev/null || :
%__fe_groupdel %username &>/dev/null || :

It has the following advantages compared to the old format:

shorter and less error-prone commands/macros
allows to build the package for non-fedora environments which do not have 'fedora-usermgmt' at package installation-time. This can be done with a '--without fedora' rpmbuild-switch and the useradd/userdel macros expand to the ordinary shadow-utils commands

Administrators who want static uid/gid allocations can install the fedora-usermgmt-shadow-utils package and execute:

/usr/sbin/update-alternatives --set fedora-usermgmt /etc/fedora/usermgmt/scripts.shadow-utils

Instead of the default uid/gid base of 300, a free range for approximately 1000 ids should be chosen (e.g. 63000-63999) and those base-ids configured:

echo 63000 >/etc/fedora/usermgmt/baseuid
echo 63000 >/etc/fedora/usermgmt/basegid

NOTE: it is not possible to find base-ids which are free on every system. 63000 is an example only. You will probably have to select another value that fits in your environment.

Debugging

fedora-usermgmt works around some nscd caching bugs, so it should work more reliably than useradd. Nevertheless, failures can occur. To ease debugging, fedora-usermgmt supports logging of successful and failed actions. To enable this logging, you have to do something like this:

ln -s /var/log/usermgmt /etc/fedora/usermgmt/log
touch /etc/fedora/usermgmt/log

The /var/log/usermgmt file will then be filled with logging information.

Background

Additional discussions about fedora-usermgmt, which have not resulted in a final conclusion, can be found in these mailing list archives:

Alternatives

When the package is intented for other platforms that do not have a user registry for non-core packages, you can conditionalize the spec file:

%{?_with_fedorausrmgmt:%global   useradd    /usr/sbin/fedora-useradd %uid}
%{?_with_fedorausrmgmt:%global   groupadd   /usr/sbin/fedora-groupadd %uid}
%{?_with_fedorausrmgmt:%global   userdel    /usr/sbin/fedora-userdel}
%{?_with_fedorausrmgmt:%global   groupadd   /usr/sbin/fedora-groupdel}
%{!?_with_fedorausrmgmt:%global  useradd    useradd}
%{!?_with_fedorausrmgmt:%global  groupadd   groupadd}
%{!?_with_fedorausrmgmt:%global  useradel   userdel}
%{!?_with_fedorausrmgmt:%global  groupdel   groupdel}

...

%{?_with_fedorausrmgmt:Requires(pre):    fedora-usermgmt}
%{?_with_fedorausrmgmt:Requires(postun): fedora-usermgmt}

...

%pre
%groupadd -r %username &>/dev/null || :
%useradd  -r -s /sbin/nologin -d %homedir -M          \
-c '%gecos' -g %username %username &>/dev/null || :

%postun
test "$1" != 0 || %userdel  %username &>/dev/null || :
test "$1" != 0 || %groupdel %username &>/dev/null || :

By giving a '--with fedorausrmgmt' option to 'rpmbuild' or defining the %_with_fedorausrmgmt macro depending on the existence of the /etc/fedora-release file, usage of 'fedora-usermgmt' can be turned on or off easily.

Reasons

With the existing shadow-utils, there are two ways to create a user in general-purpose RPM packages.

The first is to register a fixed UID and call "/usr/sbin/useradd -r -u <uid> <user>" or assign a random UID by omitting the "-u <uid>" parameter. For fixed UIDs, there are only 100 free slots, which is not enough for the Fedora Project (79 are already used by Fedora Core), and dynamic or random UIDs have problems of their own, as demonstrated here .

Another solution might be semi-static UIDs, which are relative to a system-wide value and unique for the entire Fedora Project. The current (experimental) implementation uses the file /etc/fedora/usermgmt/baseuid to configure the value to which the relative UID would be added. As an example, when /etc/fedora/usermgmt/baseuid contains "30000", the user 'joe', with the semi-static UID 23, will get the final UID 30023 (30000+23).

Creating the User

There are two approaches for creating the user:

In-line RPM macros
Separate user-space programs

In-line RPM macros

For this approach, %pre scriptlets would contain something like this:

| %pre
| %fedora_useradd -u 32 -s /bin/false joe

It would expand to something like this:

| %pre
| /usr/sbin/useradd -u $[ $(cat /etc/fedora/usermgmt/baseuid) + 32 ]  -s /bin/false joe

Advantages:

Does not require additional packages

Drawbacks:

Only simple, one-line scripts would be sensible
Error-handling (e.g. non-existing or poorly-formatted baseuid file) difficultly)
Cannot be customized (e.g. for LDAP-usermanagement)

Separate user-space programs

When using separate user-space programs, like these , the %pre scriptlet would look like this:

| %pre
| /usr/sbin/fedora-useradd 32 -s /bin/false joe

To handle this, /usr/sbin/fedora-useradd would be a script or program evaluating the baseuid file.