Gentoo Archives: gentoo-commits

From: "Göktürk Yüksek" <gokturk@g.o>
To: gentoo-commits@l.g.o
Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/
Date: Fri, 30 Aug 2019 15:51:58
Message-Id: 1567179236.fc00e95707919314996280083e61a929e2ad61a7.gokturk@gentoo
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 &lt;name&gt; [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 &lt;user&gt; [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>