en/glep/glep-0027.txt

GLEP: 27
Title: Portage Management of UIDs/GIDs
Version: $Revision: 1.4 $
Last-Modified: $Date: 2005/09/15 02:39:54 $
Author: Mike Frysinger <vapier@gentoo.org>
Status: Approved
Type: Standards Track
Content-Type: text/x-rst
Created: 29 May 2004
Post-History: 29-May-2004, 20-Jul-2004


Status
======

This GLEP was approved as-is on 14-Jun-2004.

Abstract
========

The current handling of users and groups in the portage system lacks 
policy and a decent API.  We need an API that is both simple for 
developers and end users.


Motivation
==========

Currently the policy is left up to respective ebuild maintainers to 
choose the username, id, shell settings, etc... and to have them added 
in the right place at the right time in the right way.  When the 
addition of users was found to often times have broken logic, the 
enewuser and enewgroup functions were designed to remove all the 
details.  However, these functions still suffer from some fundamental 
problems.  First, there is no local customization.  Second, maintainers 
still use the functions improperly (binary packages have suffered the 
most thus far).  Third, the functions are not portable across non-linux 
systems and not friendly to cross compiling or other exotic setups.  
There are other reasons, but these listed few are enough to warrant 
change.


Specification
=============


Portage Structure
-----------------


Defining Accounts
'''''''''''''''''


New directories will need to be added to the rsync tree to store the files 
that define the default values for new accounts.  They will be stored on a 
per-profile basis, that way sub-profiles may easily override parent profiles.  
The default location will be the base profile since all other profiles inherit 
from there.

::

        portage/profiles/base/accounts/
            user/<username>
            group/<groupname>
            accounts

The files are named with the respective user/group name since they need 
to be unique in their respective domains.  For example, the file 
detailing the ntp user would be located accounts/user/ntp.  Each 
username file will detail the required information about each user.  
Certain account features that exist on one class of systems (Linux) but 
not on others (\*BSD) can be redefined in their respective subprofiles.  Each 
groupname will follow similar guidelines.  The accounts file will be used to 
describe global account defaults such as the default range of 'valid system' 
ids.  For example, if the UID 123 is already used on a system, but the ntp 
user defaults to '123', we obviously cannot just duplicate it.  So we 
would select the next available UID on the system based upon the range 
defined here.


Local Overrides
'''''''''''''''

Following the tried and true style of custom local portage files being 
found in /etc/portage, this new system will follow the same.  Users can 
setup their own directory heirarchy in /etc/portage/profile/accounts/ that 
mimics the heirarchy found in the portage tree.  When portage attempts to add 
a new user, it will first check /etc/portage/profile/accounts/user/<username>.  
If it does not exist, it will simply use the default definition in the 
portage tree.


Developer Interface
-------------------


EUSERS + EGROUPS
''''''''''''''''

Ebuilds that wish to add users or groups to the system must set these 
variables.  They are both space delimited lists that tells portage what 
users/groups must be added to the system before emerging the ebuild.  The 
maintainer of the ebuild can assume the users/groups they have listed 
exist before the functions in the ebuild (pkg_setup, src_install, etc...) 
are ever run.


Defining Accounts
'''''''''''''''''

Any developer is free to add users/groups in their ebuilds provided they 
create the required account definition files.  


User Interface
--------------


users-update
''''''''''''

When this script is run, all the users/groups that have been added by 
portage to the system will be shown along with the packages that have 
added said users/groups.  Here they can delete accounts that are no longer 
required by the currently installed packages (and optionally run a 
script that will try to locate all files on the system that may still be 
owned by the account).


FEATURES=noautoaccts
''''''''''''''''''''

This is for the people who never want portage creating accounts for them.  
When portage needs to add an account to the system but "noautoaccts" is 
in FEATURES, portage will abort with a message instructing the user to 
add the accounts that are listed in EUSERS and EGROUPS.  This is 
obviously a required step before the package will be emerged.


Rationale
=========

Developers no longer have to worry about how to properly add users/groups 
to systems and worry about whether or not their code will work on all 
systems (LDAP vs local shadow vs cross compile vs etc...).  Users can 
easily override the defaults Gentoo has before dictated.  The default 
passwd and group database can once again be trimmed down to the barest of 
accounts.


Backwards Compatibility
=======================

Handled in similar fashion as other portage rollouts.  When using the new 
account system, add a DEPEND for the required version of portage to the 
ebuild.


References
==========

.. [#APIBUG] http://bugs.gentoo.org/show_bug.cgi?id=8634


Copyright
=========

This document has been placed in the public domain.
1	g2boojum	1.1	GLEP: 27
2	g2boojum	1.2	Title: Portage Management of UIDs/GIDs
3	vapier	1.5	Version: $Revision: 1.4 $
4			Last-Modified: $Date: 2005/09/15 02:39:54 $
5	g2boojum	1.1	Author: Mike Frysinger <vapier@gentoo.org>
6	vapier	1.5	Status: Approved
7	g2boojum	1.1	Type: Standards Track
8			Content-Type: text/x-rst
9			Created: 29 May 2004
10	g2boojum	1.3	Post-History: 29-May-2004, 20-Jul-2004
11	g2boojum	1.1
12
13	g2boojum	1.3	Status
14			======
15
16			This GLEP was approved as-is on 14-Jun-2004.
17
18	g2boojum	1.1	Abstract
19			========
20
21			The current handling of users and groups in the portage system lacks
22			policy and a decent API. We need an API that is both simple for
23			developers and end users.
24
25
26			Motivation
27			==========
28
29			Currently the policy is left up to respective ebuild maintainers to
30			choose the username, id, shell settings, etc... and to have them added
31			in the right place at the right time in the right way. When the
32			addition of users was found to often times have broken logic, the
33			enewuser and enewgroup functions were designed to remove all the
34			details. However, these functions still suffer from some fundamental
35			problems. First, there is no local customization. Second, maintainers
36			still use the functions improperly (binary packages have suffered the
37			most thus far). Third, the functions are not portable across non-linux
38			systems and not friendly to cross compiling or other exotic setups.
39			There are other reasons, but these listed few are enough to warrant
40			change.
41
42
43			Specification
44			=============
45
46
47			Portage Structure
48			-----------------
49
50
51			Defining Accounts
52			'''''''''''''''''
53
54
55	vapier	1.4	New directories will need to be added to the rsync tree to store the files
56			that define the default values for new accounts. They will be stored on a
57			per-profile basis, that way sub-profiles may easily override parent profiles.
58			The default location will be the base profile since all other profiles inherit
59			from there.
60	g2boojum	1.1
61			::
62
63	vapier	1.4	portage/profiles/base/accounts/
64			user/<username>
65			group/<groupname>
66			accounts
67	g2boojum	1.1
68			The files are named with the respective user/group name since they need
69			to be unique in their respective domains. For example, the file
70	vapier	1.4	detailing the ntp user would be located accounts/user/ntp. Each
71			username file will detail the required information about each user.
72	g2boojum	1.1	Certain account features that exist on one class of systems (Linux) but
73	vapier	1.4	not on others (\*BSD) can be redefined in their respective subprofiles. Each
74			groupname will follow similar guidelines. The accounts file will be used to
75			describe global account defaults such as the default range of 'valid system'
76			ids. For example, if the UID 123 is already used on a system, but the ntp
77	g2boojum	1.1	user defaults to '123', we obviously cannot just duplicate it. So we
78			would select the next available UID on the system based upon the range
79			defined here.
80
81
82			Local Overrides
83			'''''''''''''''
84
85			Following the tried and true style of custom local portage files being
86			found in /etc/portage, this new system will follow the same. Users can
87	vapier	1.4	setup their own directory heirarchy in /etc/portage/profile/accounts/ that
88			mimics the heirarchy found in the portage tree. When portage attempts to add
89			a new user, it will first check /etc/portage/profile/accounts/user/<username>.
90	g2boojum	1.1	If it does not exist, it will simply use the default definition in the
91			portage tree.
92
93
94			Developer Interface
95			-------------------
96
97
98			EUSERS + EGROUPS
99			''''''''''''''''
100
101			Ebuilds that wish to add users or groups to the system must set these
102			variables. They are both space delimited lists that tells portage what
103			users/groups must be added to the system before emerging the ebuild. The
104			maintainer of the ebuild can assume the users/groups they have listed
105			exist before the functions in the ebuild (pkg_setup, src_install, etc...)
106			are ever run.
107
108
109			Defining Accounts
110			'''''''''''''''''
111
112			Any developer is free to add users/groups in their ebuilds provided they
113			create the required account definition files.
114
115
116			User Interface
117			--------------
118
119
120			users-update
121			''''''''''''
122
123			When this script is run, all the users/groups that have been added by
124			portage to the system will be shown along with the packages that have
125			added said users/groups. Here they can delete accounts that are no longer
126			required by the currently installed packages (and optionally run a
127			script that will try to locate all files on the system that may still be
128			owned by the account).
129
130
131			FEATURES=noautoaccts
132			''''''''''''''''''''
133
134			This is for the people who never want portage creating accounts for them.
135			When portage needs to add an account to the system but "noautoaccts" is
136			in FEATURES, portage will abort with a message instructing the user to
137			add the accounts that are listed in EUSERS and EGROUPS. This is
138			obviously a required step before the package will be emerged.
139
140
141			Rationale
142			=========
143
144			Developers no longer have to worry about how to properly add users/groups
145			to systems and worry about whether or not their code will work on all
146			systems (LDAP vs local shadow vs cross compile vs etc...). Users can
147			easily override the defaults Gentoo has before dictated. The default
148			passwd and group database can once again be trimmed down to the barest of
149			accounts.
150
151
152			Backwards Compatibility
153			=======================
154
155			Handled in similar fashion as other portage rollouts. When using the new
156			account system, add a DEPEND for the required version of portage to the
157			ebuild.
158
159
160			References
161			==========
162
163			.. [#APIBUG] http://bugs.gentoo.org/show_bug.cgi?id=8634
164
165
166			Copyright
167			=========
168
169			This document has been placed in the public domain.