Debian Codegraph @

upstream/debian-unstable/man7/user_namespaces.7

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