Revision as of 10:20, 27 October 2008

User Creation

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:

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.

Requires(pre):	    user(httpd)
...
%files
%attr(-,httpd,root) /var/www/foo

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

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.

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. File:PackageUserCreation fedora-usermgmt-my.spec must be added to the local repository. yum will see that both 'fedora-usermgmt-my' (created by the spec-file above) and 'fedora-usermgmt-default-fedora-setup' (part of fedora-usermgmt) are candidates to satisfy the 'Requires: setup(fedora-usermgmt)'. 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 '%__fe_useradd' 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

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.