From Fedora Project Wiki

(Add a note that these are not part of the packaging guidelines)
(redirect to the up-to-date packaging guidelines pages)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{admon/warning||This page is not part of the Packaging Guidelines.  It documents fedora-usermgmt which is a package that attempts to solve some of the problems with creating users and groups in packages.  The [[Packaging:UsersAndGroups| official Fedora Guidelines]] have a simpler method that, however, may require more work on the part of the system admin.}}
#REDIRECT [[Packaging:UsersAndGroups]]
 
== Documentation ==
 
Using 'fedora-usermgmt' is optional and not required by packaging guidelines. When you want it for your package, register a user in the [[PackageUserRegistry|  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 [[FC5|  next section]] .<pre>
%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 || :
</pre>
 
 
The macros are having a meaning of:
* %uid ... the uid from the [[PackageUserRegistry|  User Registry]]
* %username ... the username from the  [[PackageUserRegistry|  User Registry]]  
* %homedir ... the homedir (usually %_var/lib/%username)
* %gecos ... the GECOS entry
 
Sniplett: <pre>
%global uid
%global username
%global homedir
%global gecos
</pre>
 
 
It is suggested to add the following headers: <pre>
Provides: group(%username) = %uid
Provides: user(%username)  = %uid</pre>
 
This allows:
* to query the repository which packages creates the user
* to add something like <pre>Requires(pre):     user(%username)</pre> to packages which are having files owned by the user. E.g.
  <pre>Requires(pre):     user(httpd)
...
%files
%attr(-,httpd,root) /var/www/foo</pre>
 
. The '<code>Requires(pre):</code>' is some kind of hack to enforce that the user exists before files will be extracted (<code>%pre</code> happens before extraction). <code>rpm</code> does not know a mechanism to express filesystem dependencies.
 
Administrators who want static uid/gid allocations can install the <code>fedora-usermgmt-shadow-utils</code> package and execute:
 
<pre>
/usr/sbin/update-alternatives --set fedora-usermgmt /etc/fedora/usermgmt/scripts.shadow-utils
</pre>
 
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:
 
<pre>
echo 63000 >/etc/fedora/usermgmt/baseuid
echo 63000 >/etc/fedora/usermgmt/basegid
</pre>
 
'''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. [[Image:PackageUserCreation_fedora-usermgmt-my.spec]] must be added to the local repository. <code>yum</code> will see that both '<code>fedora-usermgmt-my</code>' (created by the spec-file above) and '<code>fedora-usermgmt-default-fedora-setup</code>' (part of <code>fedora-usermgmt</code>) are candidates to satisfy the '<code>Requires: setup(fedora-usermgmt)</code>'. 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 '<code>%__fe_useradd</code>' will be installed.
 
 
{{Anchor|FC5}}
== FC5 and before ==
Formerly (FC5 and later), the suggested format was
 
<pre>
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 || :
</pre>
 
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 ==
 
<code>fedora-usermgmt</code> works around some nscd caching bugs, so it should work more reliably than <code>useradd</code>.  Nevertheless, failures can occur.  To ease debugging, <code>fedora-usermgmt</code> supports logging of successful and failed actions.  To enable this logging, you have to do something like this:
 
<pre>
ln -s /var/log/usermgmt /etc/fedora/usermgmt/log
touch /etc/fedora/usermgmt/log
</pre>
 
The <code>/var/log/usermgmt</code> file will then be filled with logging information.
 
== Background ==
 
* [https://www.redhat.com/archives/fedora-extras-list/2006-March/msg00688.html How fedora-usermgmt works]
* [https://www.redhat.com/archives/fedora-extras-list/2006-March/msg00793.html How to create custom packages for your environment]
* [https://www.redhat.com/archives/fedora-extras-list/2006-March/msg00690.html 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:
 
* [https://www.redhat.com/archives/fedora-packaging/2005-July/msg00000.html Packages which add user accounts: is fedora-usermgmt the way?]
* [https://www.redhat.com/archives/fedora-extras-list/2006-March/msg00584.html Non fedora-usermgmt user creation]
* [https://www.redhat.com/archives/fedora-extras-list/2006-March/msg00001.html 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:
 
<pre>
%{?_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 || :
</pre>
 
By giving a '--with fedorausrmgmt' option to 'rpmbuild' or defining the <code>%_with_fedorausrmgmt</code> macro depending on the existence of the <code>/etc/fedora-release</code> 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 "<code>/usr/sbin/useradd -r -u <uid> <user></code>" or assign a random UID by omitting the "<code>-u <uid></code>" 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 [[PackageDynamicUserCreationConsideredBad|  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) [https://bugzilla.fedora.us/show_bug.cgi?id=701 implementation]  uses the file <code>/etc/fedora/usermgmt/baseuid</code> to configure the value to which the relative UID would be added. As an example, when <code>/etc/fedora/usermgmt/baseuid</code> 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, <code>%pre</code> scriptlets would contain something like this:
 
<pre>
%pre
%fedora_useradd -u 32 -s /bin/false joe
</pre>
 
It would expand to something like this:
 
<pre>
%pre
/usr/sbin/useradd -u $[ $(cat /etc/fedora/usermgmt/baseuid) + 32 ]  -s /bin/false joe
</pre>
 
'''Advantages:'''
* Does not require additional packages
 
'''Drawbacks:'''
* Only simple, one-line scripts would be sensible
* Error-handling (e.g. non-existing or poorly-formatted <code>baseuid</code> file) difficultly)
* Cannot be customized (e.g. for LDAP-usermanagement)
 
=== Separate user-space programs ===
 
When using separate user-space programs, like [https://bugzilla.fedora.us/show_bug.cgi?id=701 these] , the <code>%pre</code> scriptlet would look like this:
 
<pre>
%pre
/usr/sbin/fedora-useradd 32 -s /bin/false joe
</pre>
 
To handle this, <code>/usr/sbin/fedora-useradd</code> would be a script or program evaluating the <code>baseuid</code> file.
 
'''Advantages:'''
* Customizable ([https://bugzilla.fedora.us/show_bug.cgi?id=701 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))
* <code>%pre</code> scriptlet is human-readable
 
'''Drawbacks:'''
* Requires additional package(s)

Latest revision as of 18:07, 15 January 2017