1 |
commit: fc00e95707919314996280083e61a929e2ad61a7 |
2 |
Author: Michał Górny <mgorny <AT> gentoo <DOT> org> |
3 |
AuthorDate: Mon Jul 22 16:42:58 2019 +0000 |
4 |
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org> |
5 |
CommitDate: Fri Aug 30 15:33:56 2019 +0000 |
6 |
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=fc00e957 |
7 |
|
8 |
ebuild-writing/users-and-groups: Update for GLEP 81 |
9 |
|
10 |
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org> |
11 |
|
12 |
ebuild-writing/users-and-groups/text.xml | 133 ++++++++++++++++++++++--------- |
13 |
1 file changed, 96 insertions(+), 37 deletions(-) |
14 |
|
15 |
diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml |
16 |
index 536be3b..190a099 100644 |
17 |
--- a/ebuild-writing/users-and-groups/text.xml |
18 |
+++ b/ebuild-writing/users-and-groups/text.xml |
19 |
@@ -5,82 +5,141 @@ |
20 |
|
21 |
<body> |
22 |
<p> |
23 |
-If your ebuild requires a user or group to be added for a daemon, for example, |
24 |
-this should be performed via the functions available in <c>user.eclass</c>. |
25 |
-Regardless of whether you are adding a group or a user, this should be performed |
26 |
-in the <c>pkg_setup</c> phase function. <c>pkg_setup</c> is called |
27 |
-before the compile process, with |
28 |
-<uri link="::general-concepts/sandbox">sandbox</uri> |
29 |
-disabled, so a build that requires the user to exist will |
30 |
-have it, and is also called for both binary and source packages. You may also |
31 |
-use the <c>pkg_preinst</c> or <c>pkg_postinst</c> functions for user creation, if |
32 |
-the user is not required during or before <c>src_install</c>. |
33 |
+Creating users and groups is governed by <uri |
34 |
+link="https://gentoo.org/glep/glep-0081.html">GLEP 81</uri>. It is implemented |
35 |
+via <c>acct-user</c> and <c>acct-group</c> eclasses. |
36 |
+</p> |
37 |
+ |
38 |
+<p> |
39 |
+New users and groups are created as packages respectively in <c>acct-user</c> |
40 |
+and <c>acct-group</c> categories. First, choose UIDs/GIDs that are not used by |
41 |
+any other package. You should consult the <uri |
42 |
+link="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/UID_GID_Assignment"> |
43 |
+UID/GID assignment list</uri> maintained by the QA project, and possibly the |
44 |
+UID/GID registries maintained by other distributions that are linked on the |
45 |
+same page. Afterwards, send the proposed ebuilds to the <c>gentoo-dev</c> |
46 |
+mailing list for review. The naming conventions for user and group ebuilds are |
47 |
+explained in the following sections. Finally, after getting positive reviews, |
48 |
+commit the new user and group packages. |
49 |
+</p> |
50 |
+ |
51 |
+<p> |
52 |
+The historical way of using <c>user.eclass</c> directly is now deprecated |
53 |
+and must not be used for new packages. |
54 |
</p> |
55 |
</body> |
56 |
|
57 |
<section> |
58 |
-<title>Adding Groups</title> |
59 |
+<title>Group ebuilds</title> |
60 |
<body> |
61 |
|
62 |
<p> |
63 |
-To add a group, use the <c>enewgroup</c> function: |
64 |
+Group ebuilds are placed in <c>acct-group</c> category, with the package name |
65 |
+matching the group name. The following can be used as a template for writing |
66 |
+group ebuilds: |
67 |
</p> |
68 |
|
69 |
<pre> |
70 |
-enewgroup <name> [gid] |
71 |
+# Copyright 2019 Gentoo Authors |
72 |
+# Distributed under the terms of the GNU General Public License v2 |
73 |
+ |
74 |
+EAPI=7 |
75 |
+ |
76 |
+inherit acct-group |
77 |
+ |
78 |
+DESCRIPTION="Meaningful description of the group" |
79 |
+ACCT_GROUP_ID=123 |
80 |
</pre> |
81 |
|
82 |
<p> |
83 |
-By default the next available group ID is selected. To set a specfic group ID, |
84 |
-pass it an extra argument to <c>enewgroup</c>. |
85 |
+<c>ACCT_GROUP_ID</c> must be set to the requested GID. |
86 |
</p> |
87 |
|
88 |
-<note> |
89 |
-Group IDs should rarely be hardcoded. If this is the case, you should |
90 |
-probably check first on gentoo-dev. |
91 |
-</note> |
92 |
- |
93 |
</body> |
94 |
</section> |
95 |
|
96 |
<section> |
97 |
-<title>Adding Users</title> |
98 |
+<title>User ebuilds</title> |
99 |
<body> |
100 |
|
101 |
<p> |
102 |
-To add a user, use the <c>enewuser</c> function: |
103 |
+User ebuilds are placed in <c>acct-user</c> category, with the package name |
104 |
+matching the user name. The following can be used as a template for writing |
105 |
+user ebuilds: |
106 |
</p> |
107 |
|
108 |
<pre> |
109 |
-enewuser <user> [uid] [shell] [homedir] [groups] |
110 |
+# Copyright 2019 Gentoo Authors |
111 |
+# Distributed under the terms of the GNU General Public License v2 |
112 |
+ |
113 |
+EAPI=7 |
114 |
+ |
115 |
+inherit acct-user |
116 |
+ |
117 |
+DESCRIPTION="Meaningful description of the user" |
118 |
+ACCT_USER_ID=123 |
119 |
+ACCT_USER_SHELL=/usr/bin/foo |
120 |
+ACCT_USER_HOME=/var/lib/foo |
121 |
+ACCT_USER_HOME_OWNER=foo:bar |
122 |
+ACCT_USER_HOME_PERMS=0775 |
123 |
+ACCT_USER_GROUPS=( foo bar baz ) |
124 |
+ |
125 |
+acct-user_add_deps |
126 |
</pre> |
127 |
|
128 |
<p> |
129 |
-By default, both <c>enewuser</c> and <c>enewgroup</c> allocate the next available user |
130 |
-ID or group ID to the new user or group - if not, you explicitly have to specify |
131 |
-one. |
132 |
+<c>ACCT_USER_ID</c> must be set to the requested GID. <c>ACCT_USER_GROUPS</c> |
133 |
+should list all the groups user belongs to, the primary group first. All |
134 |
+the other keys are optional. |
135 |
</p> |
136 |
|
137 |
<p> |
138 |
-Arguments for <c>enewuser</c> must be passed in the order as shown above: if you do |
139 |
-not want to specify a fixed user ID however but do want to set a specific shell, |
140 |
-for example, use <c>-1</c> for the <c>uid</c> parameter. The same applies for any other |
141 |
-parameter where you want to keep the default setting. |
142 |
+<c>ACCT_USER_SHELL</c> can be used to set the shell for the user. If unset, |
143 |
+the best system equivalent of nologin is used. <c>ACCT_USER_HOME</c> specifies |
144 |
+the home directory, with <c>/dev/null</c> being the default. |
145 |
+<c>ACCT_USER_HOME_OWNER</c> can be used to override the ownership of the home |
146 |
+directory, and <c>ACCT_USER_HOME_PERMS</c> to override the default permissions. |
147 |
+The defaults are the user and primary group for the owner, and 0755 for the |
148 |
+permissions. |
149 |
+</p> |
150 |
+ |
151 |
+</body> |
152 |
+</section> |
153 |
+ |
154 |
+<section> |
155 |
+<title>Utilizing users and groups in packages</title> |
156 |
+<body> |
157 |
+ |
158 |
+<p> |
159 |
+In order to make your package install specific users and groups, specify them |
160 |
+as dependencies. Accounts needed at build time must be included |
161 |
+in <c>DEPEND</c>, and accounts needed at runtime must be included |
162 |
+in <c>RDEPEND</c>. |
163 |
</p> |
164 |
|
165 |
<p> |
166 |
-Groups for the <c>groups</c> argument should be separated by a comma (<c>,</c>) and |
167 |
-wrapped correctly, for example: |
168 |
+For example, an ebuild requiring the user and group <c>foo</c> at runtime would |
169 |
+specify: |
170 |
</p> |
171 |
|
172 |
<pre> |
173 |
-enewuser frozd -1 -1 -1 "backup,frozd" |
174 |
+RDEPEND=" |
175 |
+ acct-user/foo |
176 |
+ acct-group/foo" |
177 |
</pre> |
178 |
|
179 |
-<note> |
180 |
-User IDs should rarely be hardcoded. If this is the case, you should |
181 |
-probably check first on gentoo-dev. |
182 |
-</note> |
183 |
+<p> |
184 |
+This would also be sufficient if ownership of installed files were set |
185 |
+in <c>pkg_preinst</c>. However, if the ebuild needs the user and group |
186 |
+to be present at build-time already, it would specify: |
187 |
+</p> |
188 |
+ |
189 |
+<pre> |
190 |
+RDEPEND=" |
191 |
+ acct-user/foo |
192 |
+ acct-group/foo" |
193 |
+DEPEND="${RDEPEND}" |
194 |
+</pre> |
195 |
|
196 |
</body> |
197 |
</section> |