1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
|
<?xml version="1.0"?>
<guide self="ebuild-writing/users-and-groups/">
<chapter>
<title>Users and Groups</title>
<body>
<p>
Creating users and groups is governed by <uri
link="https://gentoo.org/glep/glep-0081.html">GLEP 81</uri>. It is implemented
via <c>acct-user</c> and <c>acct-group</c> eclasses. New users and groups
are created as packages respectively in <c>acct-user</c> and <c>acct-group</c>
categories.
</p>
<p>
First, check the <uri link="https://api.gentoo.org/uid-gid.txt">UID/GID
assignment list</uri> and choose a free UID/GID in the range between
101 and 499. If you are adding a user and a group with the same name,
use the same number for their UID and GID, respectively. When in
doubt,
take the next free number from 499 downwards.
</p>
<p>
Add your new user(s) and group(s) to the <c>uid-gid.txt</c> file
located in the
<uri link="https://gitweb.gentoo.org/data/api.git">data/api.git</uri>
repository and push them before adding the actual packages.
This counts as reserving the identifiers and will prevent collisions.
Afterwards, you can push the new ebuilds.
</p>
<p>
The historical way of using <c>user.eclass</c> directly is now deprecated
and must not be used for new packages.
</p>
</body>
<section>
<title>Group ebuilds</title>
<body>
<p>
Group ebuilds are placed in <c>acct-group</c> category, with the package name
matching the group name. The following ebuild for <c>acct-group/suricata</c>
can be used as a template for writing group ebuilds:
</p>
<pre>
# Copyright 2019-2020 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=7
inherit acct-group
DESCRIPTION="Group for Suricata IDS"
ACCT_GROUP_ID=477
</pre>
<p>
<c>ACCT_GROUP_ID</c> must be set to the requested GID.
</p>
</body>
</section>
<section>
<title>User ebuilds</title>
<body>
<p>
User ebuilds are placed in <c>acct-user</c> category, with the package name
matching the user name. The following ebuild for <c>acct-user/suricata</c>
can be used as a template for writing user ebuilds:
</p>
<pre>
# Copyright 2019-2020 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=7
inherit acct-user
DESCRIPTION="User for Suricata IDS"
ACCT_USER_ID=477
ACCT_USER_GROUPS=( ${PN} )
acct-user_add_deps
</pre>
<p>
<c>ACCT_USER_ID</c> must be set to the requested GID. <c>ACCT_USER_GROUPS</c>
should list all the groups user belongs to, the primary group first. All
the other keys are optional.
</p>
<p>
<c>ACCT_USER_SHELL</c> can be used to set the shell for the user. If unset,
the best system equivalent of nologin is used. <c>ACCT_USER_HOME</c> specifies
the home directory, with <c>/dev/null</c> being the default.
<c>ACCT_USER_HOME_OWNER</c> can be used to override the ownership of the home
directory, and <c>ACCT_USER_HOME_PERMS</c> to override the default permissions.
The defaults are the user and primary group for the owner, and 0755 for the
permissions.
</p>
<important>
Whenever possible, the default shell and home directory should be
used. The rationale for this is explained below.
</important>
<p>
You should embark upon a GLEP81 migration like an EAPI
update. Rather than simply copy your user's settings into an
<c>acct-user</c> package, you should take the opportunity to
re-evaluate your user's name, shell, home directory, and its
permissions. Our GLEP 81 implementation will reveal many user
management issues that were allowed to fester in the past.
</p>
</body>
<subsection>
<title>Choosing a shell</title>
<body>
<p>
In most cases, the default shell (that is, no shell) should be
used. Services can still be started as a user who has no shell, and
daemons are able to drop privileges to a user who has no shell. If
necessary, the administrator can override a user's default shell with
<c>su -s <shell> <username></c>. This is sufficient for
testing, management of SSH credentials, and for initial configuration
in an ebuild's <c>pkg_config</c> phase.
</p>
<p>
An obvious exception to this rule is if a human being will need to log
into the account interactively, as is the case with the <c>root</c>
user. Other exceptions certainly exist, but should be evaluated
case-by-case. In other words, if you haven't checked, don't set your
user's shell to <c>/bin/bash</c> because you think he <e>might</e>
need it.
</p>
<p>
The goal here is twofold. First, the principle of least privilege says
that if a user doesn't need a real shell, he shouldn't have one. And
along those same lines, not having a shell gives the system
administrator some peace of mind: he doesn't have to be as concerned
with whether or not that user has a password (and how strong it is),
or whether or not its filesystem permissions are all set correctly, or
whether or not it can log in via SSH, et cetera.
</p>
</body>
</subsection>
<subsection>
<title>Choosing a home directory</title>
<body>
<p>
In most cases, the default home directory (that is, no home directory)
should be used. GLEP81 changed two aspects of user management with
respect to home directories:
</p>
<ol>
<li>
Creating a user can now modify the permissions on an existing
directory. Should the need arise, this is necessary for a new
version of an <c>acct-user</c> package to be able to fix the
ownership and permissions of its home directory.
</li>
<li>
All user data aside from the username became non-local to ebuilds
that depend on that user. This is merely a side-effect of moving
the user creation out of the client package, and into a separate
<c>acct-user</c> package.
</li>
</ol>
<p>
The first item means that you should be conservative when choosing a
home directory. If at all possible, avoid choosing a home directory
that is used by another package. In particular, no two
<c>acct-user</c> packages should use the same home directory. At best,
the ownership and permissions on a shared home directory would need to
be kept synchronized between all packages that share it. At worst, one
package goes out-of-sync and introduces a security hole for the others
who no longer have the expected permissions.
</p>
<p>
The second item means that if your package requires a user, you can
no longer be sure of that user's home directory or its ownership and
permissions. If your package requires a directory to be owned and
writable by some user, then your package's ebuild should create that
directory and ensure that it is writable by the user. In other
words, you should not rely on the directory being created
"transitively" by a dependency, even if that dependency is an
<c>acct-user</c> package.
</p>
<p>
In summary,
</p>
<ul>
<li>
Avoid using an <c>ACCT_USER_HOME</c> that belongs to another
package.
</li>
<li>
No two acct-user packages should define the same
<c>ACCT_USER_HOME</c>.
</li>
<li>
If for example your package's configuration needs <username>
to be able to write to <c>/var/lib/<username></c>, then your
package's ebuild should create that directory and set its
ownership and permissions. Barring any other considerations, the
corresponding <c>acct-user</c> package should leave
<c>ACCT_USER_HOME</c> at its default (empty) value; setting
<c>ACCT_USER_HOME=/var/lib/<username></c> creates
unnecessary duplication and risks desynchronizing the permissions.
</li>
</ul>
</body>
</subsection>
<subsection>
<title>Choosing home directory ownership</title>
<body>
<p>
In most cases, the default home directory ownership is correct. If a
non-default home directory is needed at all, then it should be
writable by its user and giving ownership of it to someone else would
prevent that. Being unwritable indicates that a shared and potentially
sensitive location was chosen. Moreover, the fact that the home
directory is not writable suggests that the default home directory
(which is also not writable) would suffice instead; the home directory
guidelines explain why the default is preferable in that case. For
example, setting <c>ACCT_USER_HOME_OWNER="root:root"</c> is suspicious
because it appears intended to "undo" the ownership changed by your
user package, and that would only be necessary if the path in question
is used by some other package.
</p>
</body>
</subsection>
<subsection>
<title>Choosing home directory permissions</title>
<body>
<p>
In many cases, the default home directory permissions (0755) will
suffice. But, if your package will work with mode 0700 or 0750, then
those are preferable. This is the principle of least privilege
again. If your package works with a non-writable home directory, then
you should probably be using the default of <e>no</e> home directory!
</p>
<warning>
The world-writable bit should never be set in
<c>ACCT_USER_HOME_PERMS</c>. This should never be necessary, and is
usually exploitable.
</warning>
</body>
</subsection>
<subsection>
<title>Epilogue</title>
<body>
<p>
These suggestions are not rules and are not written in stone, except
perhaps for the world-writable warning. There are packages in the tree
that <c>chroot()</c> to <c>$HOME</c>, and require that directory to be
owned by <c>root:root</c> for security reasons. In cases like that,
it's impossible to avoid implicitly tying the user to the package that
needs it via the home directory, and the best you can do is attempt to
ensure that the users and paths are unique so that no conflicts arise.
</p>
<p>
Unless your package is exceptional, though, following these guidelines
will minimize the potential for problems down the road.
</p>
</body>
</subsection>
</section>
<section>
<title>Utilizing users and groups in packages</title>
<body>
<p>
In order to make your package install specific users and groups, specify them
as dependencies. Accounts needed at build time must be included
in <c>DEPEND</c>, and accounts needed at runtime must be included
in <c>RDEPEND</c>.
</p>
<p>
For example, an ebuild requiring the user and group <c>foo</c> at runtime would
specify:
</p>
<pre>
RDEPEND="
acct-user/foo
acct-group/foo"
</pre>
<p>
This would also be sufficient if ownership of installed files were set
in <c>pkg_preinst</c>. However, if the ebuild needs the user and group
to be present at build-time already, it would specify:
</p>
<pre>
RDEPEND="
acct-user/foo
acct-group/foo"
DEPEND="${RDEPEND}"
</pre>
</body>
</section>
</chapter>
</guide>
|
GitWeb