PackageUserCreation

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:

Beginning with Fedora Core 6, the following format is possible/shall be used. For Fedora Core 5 and before see  next section. %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 || :

The macros are having a meaning of:
 * %uid ... the uid from the  User Registry
 * %username ... the username from the   User Registry
 * %homedir ... the homedir (usually %_var/lib/%username)
 * %gecos ... the GECOS entry

Sniplett: %global uid %global username %global homedir %global gecos

It is suggested to add the following headers: Provides:	group(%username) = %uid Provides:	user(%username) = %uid

This allows: Requires(pre):	   user(httpd) ... %files %attr(-,httpd,root) /var/www/foo
 * to query the repository which packages creates the user
 * to add something like Requires(pre):	   user(%username) to packages which are having files owned by the user. E.g.

. The ' ' is some kind of hack to enforce that the user exists before files will be extracted ( happens before extraction). does not know a mechanism to express filesystem dependencies.

Administrators who want static uid/gid allocations can install the  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.

It is also possible to setup fedora-usermgmt during the initial installation resp. in the rpm transaction which adds 'fedora-usermgmt' to the system. To do this, a package created by e.g. must be added to the local repository. will see that both ' ' (created by the spec-file above) and ' ' (part of ) are candidates to satisfy the ' '. But the custom package will win due its shorter name and the system will be preconfigured to use the predictable uid mechanism. This happens before the first package using the ' ' will be installed.

FC5 and before
Formerly (FC5 and later), the suggested format was

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 || :

But the new one has the following advantages:
 * 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 building the package with a '--without fedora' rpmbuild-switch. Then the useradd/userdel macros expand to the ordinary shadow-utils commands

Debugging
works around some nscd caching bugs, so it should work more reliably than. Nevertheless, failures can occur. To ease debugging,  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  file will then be filled with logging information.

Background

 * How fedora-usermgmt works
 * How to create custom packages for your environment
 * How fedora-usermgmt helps to create users in LDAP/NIS environments

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


 * Packages which add user accounts: is fedora-usermgmt the way?
 * Non fedora-usermgmt user creation
 * User id allocation and fedora-usermgmt

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  macro depending on the existence of the   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 " " or assign a random UID by omitting the " " 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   to configure the value to which the relative UID would be added. As an example, when  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,  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  file) difficultly)
 * Cannot be customized (e.g. for LDAP-usermanagement)

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

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

To handle this,  would be a script or program evaluating the   file.

Advantages:
 * Customizable (fedora-usermgmt uses alternatives concept to switch between possible methods (old, legacy which ignores the semi-static UID, shadow-utils based, relative UIDs or calling LDAP-aware useradd scripts))
 * scriptlet is human-readable

Drawbacks:
 * Requires additional package(s)