Debian Codegraph @

upstream/fedora-44/man7/user_namespaces.7

raw
1 .\" Copyright (c) 2013, 2014 by Michael Kerrisk <[email protected]>
2 .\" and Copyright (c) 2012, 2014 by Eric W. Biederman <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\"
7 .TH user_namespaces 7 2025-01-11 "Linux man-pages 6.13"
8 .SH NAME
9 user_namespaces \- overview of Linux user namespaces
10 .SH DESCRIPTION
11 For an overview of namespaces, see
12 .BR namespaces (7).
13 .P
14 User namespaces isolate security-related identifiers and attributes,
15 in particular,
16 user IDs and group IDs (see
17 .BR credentials (7)),
18 the root directory,
19 keys (see
20 .BR keyrings (7)),
21 .\" FIXME: This page says very little about the interaction
22 .\" of user namespaces and keys. Add something on this topic.
23 and capabilities (see
24 .BR capabilities (7)).
25 A process's user and group IDs can be different
26 inside and outside a user namespace.
27 In particular,
28 a process can have a normal unprivileged user ID outside a user namespace
29 while at the same time having a user ID of 0 inside the namespace;
30 in other words,
31 the process has full privileges for operations inside the user namespace,
32 but is unprivileged for operations outside the namespace.
33 .\"
34 .\" ============================================================
35 .\"
36 .SS Nested namespaces, namespace membership
37 User namespaces can be nested;
38 that is, each user namespace\[em]except the initial ("root")
39 namespace\[em]has a parent user namespace,
40 and can have zero or more child user namespaces.
41 The parent user namespace is the user namespace
42 of the process that creates the user namespace via a call to
43 .BR unshare (2)
44 or
45 .BR clone (2)
46 with the
47 .B CLONE_NEWUSER
48 flag.
49 .P
50 The kernel imposes (since Linux 3.11) a limit of 32 nested levels of
51 .\" commit 8742f229b635bf1c1c84a3dfe5e47c814c20b5c8
52 user namespaces.
53 .\" FIXME Explain the rationale for this limit. (What is the rationale?)
54 Calls to
55 .BR unshare (2)
56 or
57 .BR clone (2)
58 that would cause this limit to be exceeded fail with the error
59 .BR EUSERS .
60 .P
61 Each process is a member of exactly one user namespace.
62 A process created via
63 .BR fork (2)
64 or
65 .BR clone (2)
66 without the
67 .B CLONE_NEWUSER
68 flag is a member of the same user namespace as its parent.
69 A single-threaded process can join another user namespace with
70 .BR setns (2)
71 if it has the
72 .B CAP_SYS_ADMIN
73 in that namespace;
74 upon doing so, it gains a full set of capabilities in that namespace.
75 .P
76 A call to
77 .BR clone (2)
78 or
79 .BR unshare (2)
80 with the
81 .B CLONE_NEWUSER
82 flag makes the new child process (for
83 .BR clone (2))
84 or the caller (for
85 .BR unshare (2))
86 a member of the new user namespace created by the call.
87 .P
88 The
89 .B NS_GET_PARENT
90 .BR ioctl (2)
91 operation can be used to discover the parental relationship
92 between user namespaces; see
93 .BR ioctl_nsfs (2).
94 .P
95 A task that changes one of its effective IDs
96 will have its dumpability reset to the value in
97 .IR /proc/sys/fs/suid_dumpable .
98 This may affect the ownership of proc files of child processes
99 and may thus cause the parent to lack the permissions
100 to write to mapping files of child processes running in a new user namespace.
101 In such cases making the parent process dumpable, using
102 .B PR_SET_DUMPABLE
103 in a call to
104 .BR prctl (2),
105 before creating a child process in a new user namespace
106 may rectify this problem.
107 See
108 .BR prctl (2)
109 and
110 .BR proc (5)
111 for details on how ownership is affected.
112 .\"
113 .\" ============================================================
114 .\"
115 .SS Capabilities
116 The child process created by
117 .BR clone (2)
118 with the
119 .B CLONE_NEWUSER
120 flag starts out with a complete set
121 of capabilities in the new user namespace.
122 Likewise, a process that creates a new user namespace using
123 .BR unshare (2)
124 or joins an existing user namespace using
125 .BR setns (2)
126 gains a full set of capabilities in that namespace.
127 On the other hand,
128 that process has no capabilities in the parent (in the case of
129 .BR clone (2))
130 or previous (in the case of
131 .BR unshare (2)
132 and
133 .BR setns (2))
134 user namespace,
135 even if the new namespace is created or joined by the root user
136 (i.e., a process with user ID 0 in the root namespace).
137 .P
138 Note that a call to
139 .BR execve (2)
140 will cause a process's capabilities to be recalculated in the usual way (see
141 .BR capabilities (7)).
142 Consequently,
143 unless the process has a user ID of 0 within the namespace,
144 or the executable file has a nonempty inheritable capabilities mask,
145 the process will lose all capabilities.
146 See the discussion of user and group ID mappings, below.
147 .P
148 A call to
149 .BR clone (2)
150 or
151 .BR unshare (2)
152 using the
153 .B CLONE_NEWUSER
154 flag
155 or a call to
156 .BR setns (2)
157 that moves the caller into another user namespace
158 sets the "securebits" flags
159 (see
160 .BR capabilities (7))
161 to their default values (all flags disabled) in the child (for
162 .BR clone (2))
163 or caller (for
164 .BR unshare (2)
165 or
166 .BR setns (2)).
167 Note that because the caller no longer has capabilities
168 in its original user namespace after a call to
169 .BR setns (2),
170 it is not possible for a process to reset its "securebits" flags while
171 retaining its user namespace membership by using a pair of
172 .BR setns (2)
173 calls to move to another user namespace and then return to
174 its original user namespace.
175 .P
176 The rules for determining whether or not a process has a capability
177 in a particular user namespace are as follows:
178 .IP \[bu] 3
179 A process has a capability inside a user namespace
180 if it is a member of that namespace and
181 it has the capability in its effective capability set.
182 A process can gain capabilities in its effective capability
183 set in various ways.
184 For example, it may execute a set-user-ID program or an
185 executable with associated file capabilities.
186 In addition,
187 a process may gain capabilities via the effect of
188 .BR clone (2),
189 .BR unshare (2),
190 or
191 .BR setns (2),
192 as already described.
193 .\" In the 3.8 sources, see security/commoncap.c::cap_capable():
194 .IP \[bu]
195 If a process has a capability in a user namespace,
196 then it has that capability in all child (and further removed descendant)
197 namespaces as well.
198 .IP \[bu]
199 .\" * The owner of the user namespace in the parent of the
200 .\" * user namespace has all caps.
201 When a user namespace is created, the kernel records the effective
202 user ID of the creating process as being the "owner" of the namespace.
203 .\" (and likewise associates the effective group ID of the creating process
204 .\" with the namespace).
205 A process that resides
206 in the parent of the user namespace
207 .\" See kernel commit 520d9eabce18edfef76a60b7b839d54facafe1f9 for a fix
208 .\" on this point
209 and whose effective user ID matches the owner of the namespace
210 has all capabilities in the namespace.
211 .\" This includes the case where the process executes a set-user-ID
212 .\" program that confers the effective UID of the creator of the namespace.
213 By virtue of the previous rule,
214 this means that the process has all capabilities in all
215 further removed descendant user namespaces as well.
216 The
217 .B NS_GET_OWNER_UID
218 .BR ioctl (2)
219 operation can be used to discover the user ID of the owner of the namespace;
220 see
221 .BR ioctl_nsfs (2).
222 .\"
223 .\" ============================================================
224 .\"
225 .SS Effect of capabilities within a user namespace
226 Having a capability inside a user namespace
227 permits a process to perform operations (that require privilege)
228 only on resources governed by that namespace.
229 In other words, having a capability in a user namespace permits a process
230 to perform privileged operations on resources that are governed by (nonuser)
231 namespaces owned by (associated with) the user namespace
232 (see the next subsection).
233 .P
234 On the other hand, there are many privileged operations that affect
235 resources that are not associated with any namespace type,
236 for example, changing the system (i.e., calendar) time (governed by
237 .BR CAP_SYS_TIME ),
238 loading a kernel module (governed by
239 .BR CAP_SYS_MODULE ),
240 and creating a device (governed by
241 .BR CAP_MKNOD ).
242 Only a process with privileges in the
243 .I initial
244 user namespace can perform such operations.
245 .P
246 Holding
247 .B CAP_SYS_ADMIN
248 within the user namespace that owns a process's mount namespace
249 allows that process to create bind mounts
250 and mount the following types of filesystems:
251 .\" fs_flags = FS_USERNS_MOUNT in kernel sources
252 .P
253 .RS 4
254 .PD 0
255 .IP \[bu] 3
256 .I /proc
257 (since Linux 3.8)
258 .IP \[bu]
259 .I /sys
260 (since Linux 3.8)
261 .IP \[bu]
262 .I devpts
263 (since Linux 3.9)
264 .IP \[bu]
265 .BR tmpfs (5)
266 (since Linux 3.9)
267 .IP \[bu]
268 .I ramfs
269 (since Linux 3.9)
270 .IP \[bu]
271 .I mqueue
272 (since Linux 3.9)
273 .IP \[bu]
274 .I bpf
275 .\" commit b2197755b2633e164a439682fb05a9b5ea48f706
276 (since Linux 4.4)
277 .IP \[bu]
278 .I overlayfs
279 .\" commit 92dbc9dedccb9759c7f9f2f0ae6242396376988f
280 .\" commit 4cb2c00c43b3fe88b32f29df4f76da1b92c33224
281 (since Linux 5.11)
282 .PD
283 .RE
284 .P
285 Holding
286 .B CAP_SYS_ADMIN
287 within the user namespace that owns a process's cgroup namespace
288 allows (since Linux 4.6)
289 that process to mount the cgroup version 2 filesystem and
290 cgroup version 1 named hierarchies
291 (i.e., cgroup filesystems mounted with the
292 .I \[dq]none,name=\[dq]
293 option).
294 .P
295 Holding
296 .B CAP_SYS_ADMIN
297 within the user namespace that owns a process's PID namespace
298 allows (since Linux 3.8)
299 that process to mount
300 .I /proc
301 filesystems.
302 .P
303 Note, however, that mounting block-based filesystems can be done
304 only by a process that holds
305 .B CAP_SYS_ADMIN
306 in the initial user namespace.
307 .\"
308 .\" ============================================================
309 .\"
310 .SS Interaction of user namespaces and other types of namespaces
311 Since Linux 3.8,
312 unprivileged processes can create user namespaces,
313 and the other types of namespaces can be created with just the
314 .B CAP_SYS_ADMIN
315 capability in the caller's user namespace.
316 .P
317 When a nonuser namespace is created,
318 it is owned by the user namespace in which the creating process
319 was a member at the time of the creation of the namespace.
320 Privileged operations on resources governed by the nonuser namespace
321 require that the process has the necessary capabilities
322 in the user namespace that owns the nonuser namespace.
323 .P
324 If
325 .B CLONE_NEWUSER
326 is specified along with other
327 .B CLONE_NEW*
328 flags in a single
329 .BR clone (2)
330 or
331 .BR unshare (2)
332 call, the user namespace is guaranteed to be created first,
333 giving the child
334 .RB ( clone (2))
335 or caller
336 .RB ( unshare (2))
337 privileges over the remaining namespaces created by the call.
338 Thus, it is possible for an unprivileged caller to specify this combination
339 of flags.
340 .P
341 When a new namespace (other than a user namespace) is created via
342 .BR clone (2)
343 or
344 .BR unshare (2),
345 the kernel records the user namespace of the creating process as the owner of
346 the new namespace.
347 (This association can't be changed.)
348 When a process in the new namespace subsequently performs
349 privileged operations that operate on global
350 resources isolated by the namespace,
351 the permission checks are performed according to the process's capabilities
352 in the user namespace that the kernel associated with the new namespace.
353 For example, suppose that a process attempts to change the hostname
354 .RB ( sethostname (2)),
355 a resource governed by the UTS namespace.
356 In this case,
357 the kernel will determine which user namespace owns
358 the process's UTS namespace, and check whether the process has the
359 required capability
360 .RB ( CAP_SYS_ADMIN )
361 in that user namespace.
362 .P
363 The
364 .B NS_GET_USERNS
365 .BR ioctl (2)
366 operation can be used to discover the user namespace
367 that owns a nonuser namespace; see
368 .BR ioctl_nsfs (2).
369 .\"
370 .\" ============================================================
371 .\"
372 .SS User and group ID mappings: uid_map and gid_map
373 When a user namespace is created,
374 it starts out without a mapping of user IDs (group IDs)
375 to the parent user namespace.
376 The
377 .IR /proc/ pid /uid_map
378 and
379 .IR /proc/ pid /gid_map
380 files (available since Linux 3.5)
381 .\" commit 22d917d80e842829d0ca0a561967d728eb1d6303
382 expose the mappings for user and group IDs
383 inside the user namespace for the process
384 .IR pid .
385 These files can be read to view the mappings in a user namespace and
386 written to (once) to define the mappings.
387 .P
388 The description in the following paragraphs explains the details for
389 .IR uid_map ;
390 .I gid_map
391 is exactly the same,
392 but each instance of "user ID" is replaced by "group ID".
393 .P
394 The
395 .I uid_map
396 file exposes the mapping of user IDs from the user namespace
397 of the process
398 .I pid
399 to the user namespace of the process that opened
400 .I uid_map
401 (but see a qualification to this point below).
402 In other words, processes that are in different user namespaces
403 will potentially see different values when reading from a particular
404 .I uid_map
405 file, depending on the user ID mappings for the user namespaces
406 of the reading processes.
407 .P
408 Each line in the
409 .I uid_map
410 file specifies a 1-to-1 mapping of a range of contiguous
411 user IDs between two user namespaces.
412 (When a user namespace is first created, this file is empty.)
413 The specification in each line takes the form of
414 three numbers delimited by white space.
415 The first two numbers specify the starting user ID in
416 each of the two user namespaces.
417 The third number specifies the size of the mapped range.
418 In detail, the fields are interpreted as follows:
419 .IP (1) 5
420 The start of the range of user IDs in
421 the user namespace of the process
422 .IR pid .
423 .IP (2)
424 The start of the range of user
425 IDs to which the user IDs specified by field one map.
426 How field two is interpreted depends on whether the process that opened
427 .I uid_map
428 and the process
429 .I pid
430 are in the same user namespace, as follows:
431 .RS
432 .IP (a) 5
433 If the two processes are in different user namespaces:
434 field two is the start of a range of
435 user IDs in the user namespace of the process that opened
436 .IR uid_map .
437 .IP (b)
438 If the two processes are in the same user namespace:
439 field two is the start of the range of
440 user IDs in the parent user namespace of the process
441 .IR pid .
442 This case enables the opener of
443 .I uid_map
444 (the common case here is opening
445 .IR /proc/self/uid_map )
446 to see the mapping of user IDs into the user namespace of the process
447 that created this user namespace.
448 .RE
449 .IP (3)
450 The size of the range of user IDs that is mapped between the two
451 user namespaces.
452 .P
453 System calls that return user IDs (group IDs)\[em]for example,
454 .BR getuid (2),
455 .BR getgid (2),
456 and the credential fields in the structure returned by
457 .BR stat (2)\[em]return
458 the user ID (group ID) mapped into the caller's user namespace.
459 .P
460 When a process accesses a file, its user and group IDs
461 are mapped into the initial user namespace for the purpose of permission
462 checking and assigning IDs when creating a file.
463 When a process retrieves file user and group IDs via
464 .BR stat (2),
465 the IDs are mapped in the opposite direction,
466 to produce values relative to the process user and group ID mappings.
467 .P
468 The initial user namespace has no parent namespace,
469 but, for consistency, the kernel provides dummy user and group
470 ID mapping files for this namespace.
471 Looking at the
472 .I uid_map
473 file
474 .RI ( gid_map
475 is the same) from a shell in the initial namespace shows:
476 .P
477 .in +4n
478 .EX
479 $ \fBcat /proc/$$/uid_map\fP
480 0 0 4294967295
481 .EE
482 .in
483 .P
484 This mapping tells us
485 that the range starting at user ID 0 in this namespace
486 maps to a range starting at 0 in the (nonexistent) parent namespace,
487 and the size of the range is the largest 32-bit unsigned integer.
488 This leaves 4294967295 (the 32-bit signed \-1 value) unmapped.
489 This is deliberate:
490 .I (uid_t)\~\-1
491 is used in several interfaces (e.g.,
492 .BR setreuid (2))
493 as a way to specify "no user ID".
494 Leaving
495 .I (uid_t)\~\-1
496 unmapped and unusable guarantees that there will be no
497 confusion when using these interfaces.
498 .\"
499 .\" ============================================================
500 .\"
501 .SS Defining user and group ID mappings: writing to uid_map and gid_map
502 After the creation of a new user namespace, the
503 .I uid_map
504 file of
505 .I one
506 of the processes in the namespace may be written to
507 .I once
508 to define the mapping of user IDs in the new user namespace.
509 An attempt to write more than once to a
510 .I uid_map
511 file in a user namespace fails with the error
512 .BR EPERM .
513 Similar rules apply for
514 .I gid_map
515 files.
516 .P
517 The lines written to
518 .I uid_map
519 .RI ( gid_map )
520 must conform to the following validity rules:
521 .IP \[bu] 3
522 The three fields must be valid numbers,
523 and the last field must be greater than 0.
524 .IP \[bu]
525 Lines are terminated by newline characters.
526 .IP \[bu]
527 There is a limit on the number of lines in the file.
528 In Linux 4.14 and earlier, this limit was (arbitrarily)
529 .\" 5*12-byte records could fit in a 64B cache line
530 set at 5 lines.
531 Since Linux 4.15,
532 .\" commit 6397fac4915ab3002dc15aae751455da1a852f25
533 the limit is 340 lines.
534 In addition, the number of bytes written to
535 the file must be less than the system page size,
536 and the write must be performed at the start of the file (i.e.,
537 .BR lseek (2)
538 and
539 .BR pwrite (2)
540 can't be used to write to nonzero offsets in the file).
541 .IP \[bu]
542 The range of user IDs (group IDs)
543 specified in each line cannot overlap with the ranges
544 in any other lines.
545 In the initial implementation (Linux 3.8), this requirement was
546 satisfied by a simplistic implementation that imposed the further
547 requirement that
548 the values in both field 1 and field 2 of successive lines must be
549 in ascending numerical order,
550 which prevented some otherwise valid maps from being created.
551 Linux 3.9 and later
552 .\" commit 0bd14b4fd72afd5df41e9fd59f356740f22fceba
553 fix this limitation, allowing any valid set of nonoverlapping maps.
554 .IP \[bu]
555 At least one line must be written to the file.
556 .P
557 Writes that violate the above rules fail with the error
558 .BR EINVAL .
559 .P
560 In order for a process to write to the
561 .IR /proc/ pid /uid_map
562 .RI ( /proc/ pid /gid_map )
563 file, all of the following permission requirements must be met:
564 .IP \[bu] 3
565 The writing process must have the
566 .B CAP_SETUID
567 .RB ( CAP_SETGID )
568 capability in the user namespace of the process
569 .IR pid .
570 .IP \[bu]
571 The writing process must either be in the user namespace of the process
572 .I pid
573 or be in the parent user namespace of the process
574 .IR pid .
575 .IP \[bu]
576 The mapped user IDs (group IDs) must in turn have a mapping
577 in the parent user namespace.
578 .IP \[bu]
579 If updating
580 .IR /proc/ pid /uid_map
581 to create a mapping that maps UID 0 in the parent namespace,
582 then one of the following must be true:
583 .RS
584 .IP (a) 5
585 if writing process is in the parent user namespace,
586 then it must have the
587 .B CAP_SETFCAP
588 capability in that user namespace; or
589 .IP (b)
590 if the writing process is in the child user namespace,
591 then the process that created the user namespace must have had the
592 .B CAP_SETFCAP
593 capability when the namespace was created.
594 .RE
595 .IP
596 This rule has been in place since
597 .\" commit db2e718a47984b9d71ed890eb2ea36ecf150de18
598 Linux 5.12.
599 It eliminates an earlier security bug whereby
600 a UID 0 process that lacks the
601 .B CAP_SETFCAP
602 capability,
603 which is needed to create a binary with namespaced file capabilities
604 (as described in
605 .BR capabilities (7)),
606 could nevertheless create such a binary,
607 by the following steps:
608 .RS
609 .IP (1) 5
610 Create a new user namespace with the identity mapping
611 (i.e., UID 0 in the new user namespace maps to UID 0 in the parent namespace),
612 so that UID 0 in both namespaces is equivalent to the same root user ID.
613 .IP (2)
614 Since the child process has the
615 .B CAP_SETFCAP
616 capability, it could create a binary with namespaced file capabilities
617 that would then be effective in the parent user namespace
618 (because the root user IDs are the same in the two namespaces).
619 .RE
620 .IP \[bu]
621 One of the following two cases applies:
622 .RS
623 .IP (a) 5
624 .I Either
625 the writing process has the
626 .B CAP_SETUID
627 .RB ( CAP_SETGID )
628 capability in the
629 .I parent
630 user namespace.
631 .RS
632 .IP \[bu] 3
633 No further restrictions apply:
634 the process can make mappings to arbitrary user IDs (group IDs)
635 in the parent user namespace.
636 .RE
637 .IP (b)
638 .I Or
639 otherwise all of the following restrictions apply:
640 .RS
641 .IP \[bu] 3
642 The data written to
643 .I uid_map
644 .RI ( gid_map )
645 must consist of a single line that maps
646 the writing process's effective user ID
647 (group ID) in the parent user namespace to a user ID (group ID)
648 in the user namespace.
649 .IP \[bu]
650 The writing process must have the same effective user ID as the process
651 that created the user namespace.
652 .IP \[bu]
653 In the case of
654 .IR gid_map ,
655 use of the
656 .BR setgroups (2)
657 system call must first be denied by writing
658 .RI \[dq] deny \[dq]
659 to the
660 .IR /proc/ pid /setgroups
661 file (see below) before writing to
662 .IR gid_map .
663 .RE
664 .RE
665 .P
666 Writes that violate the above rules fail with the error
667 .BR EPERM .
668 .\"
669 .\" ============================================================
670 .\"
671 .SS Project ID mappings: projid_map
672 Similarly to user and group ID mappings,
673 it is possible to create project ID mappings for a user namespace.
674 (Project IDs are used for disk quotas; see
675 .BR setquota (8)
676 and
677 .BR quotactl (2).)
678 .P
679 Project ID mappings are defined by writing to the
680 .IR /proc/ pid /projid_map
681 file (present since
682 .\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d
683 Linux 3.7).
684 .P
685 The validity rules for writing to the
686 .IR /proc/ pid /projid_map
687 file are as for writing to the
688 .I uid_map
689 file; violation of these rules causes
690 .BR write (2)
691 to fail with the error
692 .BR EINVAL .
693 .P
694 The permission rules for writing to the
695 .IR /proc/ pid /projid_map
696 file are as follows:
697 .IP \[bu] 3
698 The writing process must either be in the user namespace of the process
699 .I pid
700 or be in the parent user namespace of the process
701 .IR pid .
702 .IP \[bu]
703 The mapped project IDs must in turn have a mapping
704 in the parent user namespace.
705 .P
706 Violation of these rules causes
707 .BR write (2)
708 to fail with the error
709 .BR EPERM .
710 .\"
711 .\" ============================================================
712 .\"
713 .SS Interaction with system calls that change process UIDs or GIDs
714 In a user namespace where the
715 .I uid_map
716 file has not been written, the system calls that change user IDs will fail.
717 Similarly, if the
718 .I gid_map
719 file has not been written, the system calls that change group IDs will fail.
720 After the
721 .I uid_map
722 and
723 .I gid_map
724 files have been written, only the mapped values may be used in
725 system calls that change user and group IDs.
726 .P
727 For user IDs, the relevant system calls include
728 .BR setuid (2),
729 .BR setfsuid (2),
730 .BR setreuid (2),
731 and
732 .BR setresuid (2).
733 For group IDs, the relevant system calls include
734 .BR setgid (2),
735 .BR setfsgid (2),
736 .BR setregid (2),
737 .BR setresgid (2),
738 and
739 .BR setgroups (2).
740 .P
741 Writing
742 .RI \[dq] deny \[dq]
743 to the
744 .IR /proc/ pid /setgroups
745 file before writing to
746 .IR /proc/ pid /gid_map
747 .\" Things changed in Linux 3.19
748 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
749 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
750 .\" http://lwn.net/Articles/626665/
751 will permanently disable
752 .BR setgroups (2)
753 in a user namespace and allow writing to
754 .IR /proc/ pid /gid_map
755 without having the
756 .B CAP_SETGID
757 capability in the parent user namespace.
758 .\"
759 .\" ============================================================
760 .\"
761 .SS The \fI/proc/\fPpid\fI/setgroups\fP file
762 .\"
763 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
764 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
765 .\" http://lwn.net/Articles/626665/
766 .\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989
767 .\"
768 The
769 .IR /proc/ pid /setgroups
770 file displays the string
771 .RI \[dq] allow \[dq]
772 if processes in the user namespace that contains the process
773 .I pid
774 are permitted to employ the
775 .BR setgroups (2)
776 system call; it displays
777 .RI \[dq] deny \[dq]
778 if
779 .BR setgroups (2)
780 is not permitted in that user namespace.
781 Note that regardless of the value in the
782 .IR /proc/ pid /setgroups
783 file (and regardless of the process's capabilities), calls to
784 .BR setgroups (2)
785 are also not permitted if
786 .IR /proc/ pid /gid_map
787 has not yet been set.
788 .P
789 A privileged process (one with the
790 .B CAP_SYS_ADMIN
791 capability in the namespace) may write either of the strings
792 .RI \[dq] allow \[dq]
793 or
794 .RI \[dq] deny \[dq]
795 to this file
796 .I before
797 writing a group ID mapping
798 for this user namespace to the file
799 .IR /proc/ pid /gid_map .
800 Writing the string
801 .RI \[dq] deny \[dq]
802 prevents any process in the user namespace from employing
803 .BR setgroups (2).
804 .P
805 The essence of the restrictions described in the preceding
806 paragraph is that it is permitted to write to
807 .IR /proc/ pid /setgroups
808 only so long as calling
809 .BR setgroups (2)
810 is disallowed because
811 .IR /proc/ pid /gid_map
812 has not been set.
813 This ensures that a process cannot transition from a state where
814 .BR setgroups (2)
815 is allowed to a state where
816 .BR setgroups (2)
817 is denied;
818 a process can transition only from
819 .BR setgroups (2)
820 being disallowed to
821 .BR setgroups (2)
822 being allowed.
823 .P
824 The default value of this file in the initial user namespace is
825 .RI \[dq] allow \[dq].
826 .P
827 Once
828 .IR /proc/ pid /gid_map
829 has been written to
830 (which has the effect of enabling
831 .BR setgroups (2)
832 in the user namespace),
833 it is no longer possible to disallow
834 .BR setgroups (2)
835 by writing
836 .RI \[dq] deny \[dq]
837 to
838 .IR /proc/ pid /setgroups
839 (the write fails with the error
840 .BR EPERM ).
841 .P
842 A child user namespace inherits the
843 .IR /proc/ pid /setgroups
844 setting from its parent.
845 .P
846 If the
847 .I setgroups
848 file has the value
849 .RI \[dq] deny \[dq],
850 then the
851 .BR setgroups (2)
852 system call can't subsequently be reenabled (by writing
853 .RI \[dq] allow \[dq]
854 to the file) in this user namespace.
855 (Attempts to do so fail with the error
856 .BR EPERM .)
857 This restriction also propagates down to all child user namespaces of
858 this user namespace.
859 .P
860 The
861 .IR /proc/ pid /setgroups
862 file was added in Linux 3.19,
863 but was backported to many earlier stable kernel series,
864 because it addresses a security issue.
865 The issue concerned files with permissions such as "rwx\-\-\-rwx".
866 Such files give fewer permissions to "group" than they do to "other".
867 This means that dropping groups using
868 .BR setgroups (2)
869 might allow a process file access that it did not formerly have.
870 Before the existence of user namespaces this was not a concern,
871 since only a privileged process (one with the
872 .B CAP_SETGID
873 capability) could call
874 .BR setgroups (2).
875 However, with the introduction of user namespaces,
876 it became possible for an unprivileged process to create
877 a new namespace in which the user had all privileges.
878 This then allowed formerly unprivileged
879 users to drop groups and thus gain file access
880 that they did not previously have.
881 The
882 .IR /proc/ pid /setgroups
883 file was added to address this security issue,
884 by denying any pathway for an unprivileged process to drop groups with
885 .BR setgroups (2).
886 .\"
887 .\" /proc/PID/setgroups
888 .\" [allow == setgroups() is allowed, "deny" == setgroups() is disallowed]
889 .\" * Can write if have CAP_SYS_ADMIN in NS
890 .\" * Must write BEFORE writing to /proc/PID/gid_map
891 .\"
892 .\" setgroups()
893 .\" * Must already have written to gid_map
894 .\" * /proc/PID/setgroups must be "allow"
895 .\"
896 .\" /proc/PID/gid_map -- writing
897 .\" * Must already have written "deny" to /proc/PID/setgroups
898 .\"
899 .\" ============================================================
900 .\"
901 .SS Unmapped user and group IDs
902 There are various places where an unmapped user ID (group ID)
903 may be exposed to user space.
904 For example, the first process in a new user namespace may call
905 .BR getuid (2)
906 before a user ID mapping has been defined for the namespace.
907 In most such cases, an unmapped user ID is converted
908 .\" from_kuid_munged(), from_kgid_munged()
909 to the overflow user ID (group ID);
910 the default value for the overflow user ID (group ID) is 65534.
911 See the descriptions of
912 .I /proc/sys/kernel/overflowuid
913 and
914 .I /proc/sys/kernel/overflowgid
915 in
916 .BR proc (5).
917 .P
918 The cases where unmapped IDs are mapped in this fashion include
919 system calls that return user IDs
920 .RB ( getuid (2),
921 .BR getgid (2),
922 and similar),
923 credentials passed over a UNIX domain socket,
924 .\" also SO_PEERCRED
925 credentials returned by
926 .BR stat (2),
927 .BR waitid (2),
928 and the System V IPC "ctl"
929 .B IPC_STAT
930 operations,
931 credentials exposed by
932 .IR /proc/ pid /status
933 and the files in
934 .IR /proc/sysvipc/* ,
935 credentials returned via the
936 .I si_uid
937 field in the
938 .I siginfo_t
939 received with a signal (see
940 .BR sigaction (2)),
941 credentials written to the process accounting file (see
942 .BR acct (5)),
943 and credentials returned with POSIX message queue notifications (see
944 .BR mq_notify (3)).
945 .P
946 There is one notable case where unmapped user and group IDs are
947 .I not
948 .\" from_kuid(), from_kgid()
949 .\" Also F_GETOWNER_UIDS is an exception
950 converted to the corresponding overflow ID value.
951 When viewing a
952 .I uid_map
953 or
954 .I gid_map
955 file in which there is no mapping for the second field,
956 that field is displayed as 4294967295 (\-1 as an unsigned integer).
957 .\"
958 .\" ============================================================
959 .\"
960 .SS Accessing files
961 In order to determine permissions when an unprivileged process accesses a file,
962 the process credentials (UID, GID) and the file credentials
963 are in effect mapped back to what they would be in
964 the initial user namespace and then compared to determine
965 the permissions that the process has on the file.
966 The same is also true of other objects that employ the credentials plus
967 permissions mask accessibility model, such as System V IPC objects.
968 .\"
969 .\" ============================================================
970 .\"
971 .SS Operation of file-related capabilities
972 Certain capabilities allow a process to bypass various
973 kernel-enforced restrictions when performing operations on
974 files owned by other users or groups.
975 These capabilities are:
976 .BR CAP_CHOWN ,
977 .BR CAP_DAC_OVERRIDE ,
978 .BR CAP_DAC_READ_SEARCH ,
979 .BR CAP_FOWNER ,
980 and
981 .BR CAP_FSETID .
982 .P
983 Within a user namespace,
984 these capabilities allow a process to bypass the rules
985 if the process has the relevant capability over the file,
986 meaning that:
987 .IP \[bu] 3
988 the process has the relevant effective capability in its user namespace; and
989 .IP \[bu]
990 the file's user ID and group ID both have valid mappings
991 in the user namespace.
992 .P
993 The
994 .B CAP_FOWNER
995 capability is treated somewhat exceptionally:
996 .\" These are the checks performed by the kernel function
997 .\" inode_owner_or_capable(). There is one exception to the exception:
998 .\" overriding the directory sticky permission bit requires that
999 .\" the file has a valid mapping for both its UID and GID.
1000 it allows a process to bypass the corresponding rules so long as
1001 at least the file's user ID has a mapping in the user namespace
1002 (i.e., the file's group ID does not need to have a valid mapping).
1003 .\"
1004 .\" ============================================================
1005 .\"
1006 .SS Set-user-ID and set-group-ID programs
1007 When a process inside a user namespace executes
1008 a set-user-ID (set-group-ID) program,
1009 the process's effective user (group) ID inside the namespace is changed
1010 to whatever value is mapped for the user (group) ID of the file.
1011 However, if either the user
1012 .I or
1013 the group ID of the file has no mapping inside the namespace,
1014 the set-user-ID (set-group-ID) bit is silently ignored:
1015 the new program is executed,
1016 but the process's effective user (group) ID is left unchanged.
1017 (This mirrors the semantics of executing a set-user-ID or set-group-ID
1018 program that resides on a filesystem that was mounted with the
1019 .B MS_NOSUID
1020 flag, as described in
1021 .BR mount (2).)
1022 .\"
1023 .\" ============================================================
1024 .\"
1025 .SS Miscellaneous
1026 When a process's user and group IDs are passed over a UNIX domain socket
1027 to a process in a different user namespace (see the description of
1028 .B SCM_CREDENTIALS
1029 in
1030 .BR unix (7)),
1031 they are translated into the corresponding values as per the
1032 receiving process's user and group ID mappings.
1033 .\"
1034 .SH STANDARDS
1035 Linux.
1036 .\"
1037 .SH NOTES
1038 Over the years, there have been a lot of features that have been added
1039 to the Linux kernel that have been made available only to privileged users
1040 because of their potential to confuse set-user-ID-root applications.
1041 In general, it becomes safe to allow the root user in a user namespace to
1042 use those features because it is impossible, while in a user namespace,
1043 to gain more privilege than the root user of a user namespace has.
1044 .\"
1045 .\" ============================================================
1046 .\"
1047 .SS Global root
1048 The term "global root" is sometimes used as a shorthand for
1049 user ID 0 in the initial user namespace.
1050 .\"
1051 .\" ============================================================
1052 .\"
1053 .SS Availability
1054 Use of user namespaces requires a kernel that is configured with the
1055 .B CONFIG_USER_NS
1056 option.
1057 User namespaces require support in a range of subsystems across
1058 the kernel.
1059 When an unsupported subsystem is configured into the kernel,
1060 it is not possible to configure user namespaces support.
1061 .P
1062 As at Linux 3.8, most relevant subsystems supported user namespaces,
1063 but a number of filesystems did not have the infrastructure needed
1064 to map user and group IDs between user namespaces.
1065 Linux 3.9 added the required infrastructure support for many of
1066 the remaining unsupported filesystems
1067 (Plan 9 (9P), Andrew File System (AFS), Ceph, CIFS, CODA, NFS, and OCFS2).
1068 Linux 3.12 added support for the last of the unsupported major filesystems,
1069 .\" commit d6970d4b726cea6d7a9bc4120814f95c09571fc3
1070 XFS.
1071 .\"
1072 .SH EXAMPLES
1073 The program below is designed to allow experimenting with
1074 user namespaces, as well as other types of namespaces.
1075 It creates namespaces as specified by command-line options and then executes
1076 a command inside those namespaces.
1077 The comments and
1078 .IR usage ()
1079 function inside the program provide a full explanation of the program.
1080 The following shell session demonstrates its use.
1081 .P
1082 First, we look at the run-time environment:
1083 .P
1084 .in +4n
1085 .EX
1086 $ \fBuname \-rs\fP # Need Linux 3.8 or later
1087 Linux 3.8.0
1088 $ \fBid \-u\fP # Running as unprivileged user
1089 1000
1090 $ \fBid \-g\fP
1091 1000
1092 .EE
1093 .in
1094 .P
1095 Now start a new shell in new user
1096 .RI ( \-U ),
1097 mount
1098 .RI ( \-m ),
1099 and PID
1100 .RI ( \-p )
1101 namespaces, with user ID
1102 .RI ( \-M )
1103 and group ID
1104 .RI ( \-G )
1105 1000 mapped to 0 inside the user namespace:
1106 .P
1107 .in +4n
1108 .EX
1109 $ \fB./userns_child_exec \-p \-m \-U \-M \[aq]0 1000 1\[aq] \-G \[aq]0 1000 1\[aq] bash\fP
1110 .EE
1111 .in
1112 .P
1113 The shell has PID 1, because it is the first process in the new
1114 PID namespace:
1115 .P
1116 .in +4n
1117 .EX
1118 bash$ \fBecho $$\fP
1119 1
1120 .EE
1121 .in
1122 .P
1123 Mounting a new
1124 .I /proc
1125 filesystem and listing all of the processes visible
1126 in the new PID namespace shows that the shell can't see
1127 any processes outside the PID namespace:
1128 .P
1129 .in +4n
1130 .EX
1131 bash$ \fBmount \-t proc proc /proc\fP
1132 bash$ \fBps ax\fP
1133 PID TTY STAT TIME COMMAND
1134 1 pts/3 S 0:00 bash
1135 22 pts/3 R+ 0:00 ps ax
1136 .EE
1137 .in
1138 .P
1139 Inside the user namespace, the shell has user and group ID 0,
1140 and a full set of permitted and effective capabilities:
1141 .P
1142 .in +4n
1143 .EX
1144 bash$ \fBcat /proc/$$/status | egrep \[aq]\[ha][UG]id\[aq]\fP
1145 Uid: 0 0 0 0
1146 Gid: 0 0 0 0
1147 bash$ \fBcat /proc/$$/status | egrep \[aq]\[ha]Cap(Prm|Inh|Eff)\[aq]\fP
1148 CapInh: 0000000000000000
1149 CapPrm: 0000001fffffffff
1150 CapEff: 0000001fffffffff
1151 .EE
1152 .in
1153 .SS Program source
1154 \&
1155 .EX
1156 /* userns_child_exec.c
1157 \&
1158 Licensed under GNU General Public License v2 or later
1159 \&
1160 Create a child process that executes a shell command in new
1161 namespace(s); allow UID and GID mappings to be specified when
1162 creating a user namespace.
1163 */
1164 #define _GNU_SOURCE
1165 #include <err.h>
1166 #include <sched.h>
1167 #include <unistd.h>
1168 #include <stdint.h>
1169 #include <stdlib.h>
1170 #include <sys/wait.h>
1171 #include <signal.h>
1172 #include <fcntl.h>
1173 #include <stdio.h>
1174 #include <string.h>
1175 #include <limits.h>
1176 #include <errno.h>
1177 \&
1178 struct child_args {
1179 char **argv; /* Command to be executed by child, with args */
1180 int pipe_fd[2]; /* Pipe used to synchronize parent and child */
1181 };
1182 \&
1183 static int verbose;
1184 \&
1185 static void
1186 usage(char *pname)
1187 {
1188 fprintf(stderr, "Usage: %s [options] cmd [arg...]\[rs]n\[rs]n", pname);
1189 fprintf(stderr, "Create a child process that executes a shell "
1190 "command in a new user namespace,\[rs]n"
1191 "and possibly also other new namespace(s).\[rs]n\[rs]n");
1192 fprintf(stderr, "Options can be:\[rs]n\[rs]n");
1193 #define fpe(str) fprintf(stderr, " %s", str);
1194 fpe("\-i New IPC namespace\[rs]n");
1195 fpe("\-m New mount namespace\[rs]n");
1196 fpe("\-n New network namespace\[rs]n");
1197 fpe("\-p New PID namespace\[rs]n");
1198 fpe("\-u New UTS namespace\[rs]n");
1199 fpe("\-U New user namespace\[rs]n");
1200 fpe("\-M uid_map Specify UID map for user namespace\[rs]n");
1201 fpe("\-G gid_map Specify GID map for user namespace\[rs]n");
1202 fpe("\-z Map user\[aq]s UID and GID to 0 in user namespace\[rs]n");
1203 fpe(" (equivalent to: \-M \[aq]0 <uid> 1\[aq] \-G \[aq]0 <gid> 1\[aq])\[rs]n");
1204 fpe("\-v Display verbose messages\[rs]n");
1205 fpe("\[rs]n");
1206 fpe("If \-z, \-M, or \-G is specified, \-U is required.\[rs]n");
1207 fpe("It is not permitted to specify both \-z and either \-M or \-G.\[rs]n");
1208 fpe("\[rs]n");
1209 fpe("Map strings for \-M and \-G consist of records of the form:\[rs]n");
1210 fpe("\[rs]n");
1211 fpe(" ID\-inside\-ns ID\-outside\-ns size\[rs]n");
1212 fpe("\[rs]n");
1213 fpe("A map string can contain multiple records, separated"
1214 " by commas;\[rs]n");
1215 fpe("the commas are replaced by newlines before writing"
1216 " to map files.\[rs]n");
1217 \&
1218 exit(EXIT_FAILURE);
1219 }
1220 \&
1221 /* Update the mapping file \[aq]map_file\[aq], with the value provided in
1222 \[aq]mapping\[aq], a string that defines a UID or GID mapping. A UID or
1223 GID mapping consists of one or more newline\-delimited records
1224 of the form:
1225 \&
1226 ID_inside\-ns ID\-outside\-ns size
1227 \&
1228 Requiring the user to supply a string that contains newlines is
1229 of course inconvenient for command\-line use. Thus, we permit the
1230 use of commas to delimit records in this string, and replace them
1231 with newlines before writing the string to the file. */
1232 \&
1233 static void
1234 update_map(char *mapping, char *map_file)
1235 {
1236 int fd;
1237 size_t map_len; /* Length of \[aq]mapping\[aq] */
1238 \&
1239 /* Replace commas in mapping string with newlines. */
1240 \&
1241 map_len = strlen(mapping);
1242 for (size_t j = 0; j < map_len; j++)
1243 if (mapping[j] == \[aq],\[aq])
1244 mapping[j] = \[aq]\[rs]n\[aq];
1245 \&
1246 fd = open(map_file, O_RDWR);
1247 if (fd == \-1) {
1248 fprintf(stderr, "ERROR: open %s: %s\[rs]n", map_file,
1249 strerror(errno));
1250 exit(EXIT_FAILURE);
1251 }
1252 \&
1253 if (write(fd, mapping, map_len) != map_len) {
1254 fprintf(stderr, "ERROR: write %s: %s\[rs]n", map_file,
1255 strerror(errno));
1256 exit(EXIT_FAILURE);
1257 }
1258 \&
1259 close(fd);
1260 }
1261 \&
1262 /* Linux 3.19 made a change in the handling of setgroups(2) and
1263 the \[aq]gid_map\[aq] file to address a security issue. The issue
1264 allowed *unprivileged* users to employ user namespaces in
1265 order to drop groups. The upshot of the 3.19 changes is that
1266 in order to update the \[aq]gid_maps\[aq] file, use of the setgroups()
1267 system call in this user namespace must first be disabled by
1268 writing "deny" to one of the /proc/PID/setgroups files for
1269 this namespace. That is the purpose of the following function. */
1270 \&
1271 static void
1272 proc_setgroups_write(pid_t child_pid, char *str)
1273 {
1274 char setgroups_path[PATH_MAX];
1275 int fd;
1276 \&
1277 snprintf(setgroups_path, PATH_MAX, "/proc/%jd/setgroups",
1278 (intmax_t) child_pid);
1279 \&
1280 fd = open(setgroups_path, O_RDWR);
1281 if (fd == \-1) {
1282 \&
1283 /* We may be on a system that doesn\[aq]t support
1284 /proc/PID/setgroups. In that case, the file won\[aq]t exist,
1285 and the system won\[aq]t impose the restrictions that Linux 3.19
1286 added. That\[aq]s fine: we don\[aq]t need to do anything in order
1287 to permit \[aq]gid_map\[aq] to be updated.
1288 \&
1289 However, if the error from open() was something other than
1290 the ENOENT error that is expected for that case, let the
1291 user know. */
1292 \&
1293 if (errno != ENOENT)
1294 fprintf(stderr, "ERROR: open %s: %s\[rs]n", setgroups_path,
1295 strerror(errno));
1296 return;
1297 }
1298 \&
1299 if (write(fd, str, strlen(str)) == \-1)
1300 fprintf(stderr, "ERROR: write %s: %s\[rs]n", setgroups_path,
1301 strerror(errno));
1302 \&
1303 close(fd);
1304 }
1305 \&
1306 static int /* Start function for cloned child */
1307 childFunc(void *arg)
1308 {
1309 struct child_args *args = arg;
1310 char ch;
1311 \&
1312 /* Wait until the parent has updated the UID and GID mappings.
1313 See the comment in main(). We wait for end of file on a
1314 pipe that will be closed by the parent process once it has
1315 updated the mappings. */
1316 \&
1317 close(args\->pipe_fd[1]); /* Close our descriptor for the write
1318 end of the pipe so that we see EOF
1319 when parent closes its descriptor. */
1320 if (read(args\->pipe_fd[0], &ch, 1) != 0) {
1321 fprintf(stderr,
1322 "Failure in child: read from pipe returned != 0\[rs]n");
1323 exit(EXIT_FAILURE);
1324 }
1325 \&
1326 close(args\->pipe_fd[0]);
1327 \&
1328 /* Execute a shell command. */
1329 \&
1330 printf("About to exec %s\[rs]n", args\->argv[0]);
1331 execvp(args\->argv[0], args\->argv);
1332 err(EXIT_FAILURE, "execvp");
1333 }
1334 \&
1335 #define STACK_SIZE (1024 * 1024)
1336 \&
1337 static char child_stack[STACK_SIZE]; /* Space for child\[aq]s stack */
1338 \&
1339 int
1340 main(int argc, char *argv[])
1341 {
1342 int flags, opt, map_zero;
1343 pid_t child_pid;
1344 struct child_args args;
1345 char *uid_map, *gid_map;
1346 const int MAP_BUF_SIZE = 100;
1347 char map_buf[MAP_BUF_SIZE];
1348 char map_path[PATH_MAX];
1349 \&
1350 /* Parse command\-line options. The initial \[aq]+\[aq] character in
1351 the final getopt() argument prevents GNU\-style permutation
1352 of command\-line options. That\[aq]s useful, since sometimes
1353 the \[aq]command\[aq] to be executed by this program itself
1354 has command\-line options. We don\[aq]t want getopt() to treat
1355 those as options to this program. */
1356 \&
1357 flags = 0;
1358 verbose = 0;
1359 gid_map = NULL;
1360 uid_map = NULL;
1361 map_zero = 0;
1362 while ((opt = getopt(argc, argv, "+imnpuUM:G:zv")) != \-1) {
1363 switch (opt) {
1364 case \[aq]i\[aq]: flags |= CLONE_NEWIPC; break;
1365 case \[aq]m\[aq]: flags |= CLONE_NEWNS; break;
1366 case \[aq]n\[aq]: flags |= CLONE_NEWNET; break;
1367 case \[aq]p\[aq]: flags |= CLONE_NEWPID; break;
1368 case \[aq]u\[aq]: flags |= CLONE_NEWUTS; break;
1369 case \[aq]v\[aq]: verbose = 1; break;
1370 case \[aq]z\[aq]: map_zero = 1; break;
1371 case \[aq]M\[aq]: uid_map = optarg; break;
1372 case \[aq]G\[aq]: gid_map = optarg; break;
1373 case \[aq]U\[aq]: flags |= CLONE_NEWUSER; break;
1374 default: usage(argv[0]);
1375 }
1376 }
1377 \&
1378 /* \-M or \-G without \-U is nonsensical */
1379 \&
1380 if (((uid_map != NULL || gid_map != NULL || map_zero) &&
1381 !(flags & CLONE_NEWUSER)) ||
1382 (map_zero && (uid_map != NULL || gid_map != NULL)))
1383 usage(argv[0]);
1384 \&
1385 args.argv = &argv[optind];
1386 \&
1387 /* We use a pipe to synchronize the parent and child, in order to
1388 ensure that the parent sets the UID and GID maps before the child
1389 calls execve(). This ensures that the child maintains its
1390 capabilities during the execve() in the common case where we
1391 want to map the child\[aq]s effective user ID to 0 in the new user
1392 namespace. Without this synchronization, the child would lose
1393 its capabilities if it performed an execve() with nonzero
1394 user IDs (see the capabilities(7) man page for details of the
1395 transformation of a process\[aq]s capabilities during execve()). */
1396 \&
1397 if (pipe(args.pipe_fd) == \-1)
1398 err(EXIT_FAILURE, "pipe");
1399 \&
1400 /* Create the child in new namespace(s). */
1401 \&
1402 child_pid = clone(childFunc, child_stack + STACK_SIZE,
1403 flags | SIGCHLD, &args);
1404 if (child_pid == \-1)
1405 err(EXIT_FAILURE, "clone");
1406 \&
1407 /* Parent falls through to here. */
1408 \&
1409 if (verbose)
1410 printf("%s: PID of child created by clone() is %jd\[rs]n",
1411 argv[0], (intmax_t) child_pid);
1412 \&
1413 /* Update the UID and GID maps in the child. */
1414 \&
1415 if (uid_map != NULL || map_zero) {
1416 snprintf(map_path, PATH_MAX, "/proc/%jd/uid_map",
1417 (intmax_t) child_pid);
1418 if (map_zero) {
1419 snprintf(map_buf, MAP_BUF_SIZE, "0 %jd 1",
1420 (intmax_t) getuid());
1421 uid_map = map_buf;
1422 }
1423 update_map(uid_map, map_path);
1424 }
1425 \&
1426 if (gid_map != NULL || map_zero) {
1427 proc_setgroups_write(child_pid, "deny");
1428 \&
1429 snprintf(map_path, PATH_MAX, "/proc/%jd/gid_map",
1430 (intmax_t) child_pid);
1431 if (map_zero) {
1432 snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1",
1433 (intmax_t) getgid());
1434 gid_map = map_buf;
1435 }
1436 update_map(gid_map, map_path);
1437 }
1438 \&
1439 /* Close the write end of the pipe, to signal to the child that we
1440 have updated the UID and GID maps. */
1441 \&
1442 close(args.pipe_fd[1]);
1443 \&
1444 if (waitpid(child_pid, NULL, 0) == \-1) /* Wait for child */
1445 err(EXIT_FAILURE, "waitpid");
1446 \&
1447 if (verbose)
1448 printf("%s: terminating\[rs]n", argv[0]);
1449 \&
1450 exit(EXIT_SUCCESS);
1451 }
1452 .EE
1453 .SH SEE ALSO
1454 .BR newgidmap (1), \" From the shadow package
1455 .BR newuidmap (1), \" From the shadow package
1456 .BR clone (2),
1457 .BR ptrace (2),
1458 .BR setns (2),
1459 .BR unshare (2),
1460 .BR proc (5),
1461 .BR subgid (5), \" From the shadow package
1462 .BR subuid (5), \" From the shadow package
1463 .BR capabilities (7),
1464 .BR cgroup_namespaces (7),
1465 .BR credentials (7),
1466 .BR namespaces (7),
1467 .BR pid_namespaces (7)
1468 .P
1469 The kernel source file
1470 .IR Documentation/admin\-guide/namespaces/resource\-control.rst .