1 .\" Copyright (c) 2013, 2014 by Michael Kerrisk <mtk.manpages@gmail.com>
2 .\" and Copyright (c) 2012, 2014 by Eric W. Biederman <ebiederm@xmission.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
27 .TH USER_NAMESPACES 7 2016-07-17 "Linux" "Linux Programmer's Manual"
29 user_namespaces \- overview of Linux user namespaces
31 For an overview of namespaces, see
34 User namespaces isolate security-related identifiers and attributes,
36 user IDs and group IDs (see
41 .\" FIXME: This page says very little about the interaction
42 .\" of user namespaces and keys. Add something on this topic.
44 .BR capabilities (7)).
45 A process's user and group IDs can be different
46 inside and outside a user namespace.
48 a process can have a normal unprivileged user ID outside a user namespace
49 while at the same time having a user ID of 0 inside the namespace;
51 the process has full privileges for operations inside the user namespace,
52 but is unprivileged for operations outside the namespace.
54 .\" ============================================================
56 .SS Nested namespaces, namespace membership
57 User namespaces can be nested;
58 that is, each user namespace\(emexcept the initial ("root")
59 namespace\(emhas a parent user namespace,
60 and can have zero or more child user namespaces.
61 The parent user namespace is the user namespace
62 of the process that creates the user namespace via a call to
70 The kernel imposes (since version 3.11) a limit of 32 nested levels of
71 .\" commit 8742f229b635bf1c1c84a3dfe5e47c814c20b5c8
73 .\" FIXME Explain the rationale for this limit. (What is the rationale?)
78 that would cause this limit to be exceeded fail with the error
81 Each process is a member of exactly one user namespace.
88 flag is a member of the same user namespace as its parent.
89 A single-threaded process can join another user namespace with
94 upon doing so, it gains a full set of capabilities in that namespace.
102 flag makes the new child process (for
106 a member of the new user namespace created by the call.
108 .\" ============================================================
111 The child process created by
115 flag starts out with a complete set
116 of capabilities in the new user namespace.
117 Likewise, a process that creates a new user namespace using
119 or joins an existing user namespace using
121 gains a full set of capabilities in that namespace.
123 that process has no capabilities in the parent (in the case of
125 or previous (in the case of
130 even if the new namespace is created or joined by the root user
131 (i.e., a process with user ID 0 in the root namespace).
135 will cause a process's capabilities to be recalculated in the usual way (see
136 .BR capabilities (7)).
138 unless the process has a user ID of 0 within the namespace,
139 or the executable file has a nonempty inheritable capabilities mask,
140 the process will lose all capabilities.
141 See the discussion of user and group ID mappings, below.
150 flag sets the "securebits" flags
152 .BR capabilities (7))
153 to their default values (all flags disabled) in the child (for
159 Note that because the caller no longer has capabilities
160 in its original user namespace after a call to
162 it is not possible for a process to reset its "securebits" flags while
163 retaining its user namespace membership by using a pair of
165 calls to move to another user namespace and then return to
166 its original user namespace.
168 The rules for determining whether or not a process has a capability
169 in a particular user namespace are as follows:
171 A process has a capability inside a user namespace
172 if it is a member of that namespace and
173 it has the capability in its effective capability set.
174 A process can gain capabilities in its effective capability
176 For example, it may execute a set-user-ID program or an
177 executable with associated file capabilities.
179 a process may gain capabilities via the effect of
184 as already described.
185 .\" In the 3.8 sources, see security/commoncap.c::cap_capable():
187 If a process has a capability in a user namespace,
188 then it has that capability in all child (and further removed descendant)
191 .\" * The owner of the user namespace in the parent of the
192 .\" * user namespace has all caps.
193 When a user namespace is created, the kernel records the effective
194 user ID of the creating process as being the "owner" of the namespace.
195 .\" (and likewise associates the effective group ID of the creating process
196 .\" with the namespace).
197 A process that resides
198 in the parent of the user namespace
199 .\" See kernel commit 520d9eabce18edfef76a60b7b839d54facafe1f9 for a fix
201 and whose effective user ID matches the owner of the namespace
202 has all capabilities in the namespace.
203 .\" This includes the case where the process executes a set-user-ID
204 .\" program that confers the effective UID of the creator of the namespace.
205 By virtue of the previous rule,
206 this means that the process has all capabilities in all
207 further removed descendant user namespaces as well.
209 .\" ============================================================
211 .SS Effect of capabilities within a user namespace
212 Having a capability inside a user namespace
213 permits a process to perform operations (that require privilege)
214 only on resources governed by that namespace.
215 In other words, having a capability in a user namespace permits a process
216 to perform privileged operations on resources that are governed by (nonuser)
217 namespaces associated with the user namespace (see the next subsection).
219 On the other hand, there are many privileged operations that affect
220 resources that are not associated with any namespace type,
221 for example, changing the system time (governed by
223 loading a kernel module (governed by
224 .BR CAP_SYS_MODULE ),
225 and creating a device (governed by
227 Only a process with privileges in the
229 user namespace can perform such operations.
233 within the user namespace associated with a process's mount namespace
234 allows that process to create bind mounts
235 and mount the following types of filesystems:
236 .\" fs_flags = FS_USERNS_MOUNT in kernel sources
260 .\" commit b2197755b2633e164a439682fb05a9b5ea48f706
267 within the user namespace associated with a process's cgroup namespace
268 allows (since Linux 4.6)
269 that process to the mount cgroup version 2 filesystem and
270 cgroup version 1 named hierarchies
271 (i.e., cgroup filesystems mounted with the
277 within the user namespace associated with a process's PID namespace
278 allows (since Linux 3.8)
279 that process to mount
283 Note however, that mounting block-based filesystems can be done
284 only by a process that holds
286 in the initial user namespace.
288 .\" ============================================================
290 .SS Interaction of user namespaces and other types of namespaces
291 Starting in Linux 3.8, unprivileged processes can create user namespaces,
292 and other the other types of namespaces can be created with just the
294 capability in the caller's user namespace.
296 When a non-user-namespace is created,
297 it is owned by the user namespace in which the creating process
298 was a member at the time of the creation of the namespace.
299 Actions on the non-user-namespace
300 require capabilities in the corresponding user namespace.
304 is specified along with other
310 call, the user namespace is guaranteed to be created first,
315 privileges over the remaining namespaces created by the call.
316 Thus, it is possible for an unprivileged caller to specify this combination
319 When a new namespace (other than a user namespace) is created via
323 the kernel records the user namespace of the creating process against
325 (This association can't be changed.)
326 When a process in the new namespace subsequently performs
327 privileged operations that operate on global
328 resources isolated by the namespace,
329 the permission checks are performed according to the process's capabilities
330 in the user namespace that the kernel associated with the new namespace.
331 For example, suppose that a process attempts to change the hostname
332 .RB ( sethostname (2)),
333 a resource governed by the UTS namespace.
335 the kernel will determine which user namespace is associated with
336 the process's UTS namespace, and check whether the process has the
338 .RB ( CAP_SYS_ADMIN )
339 in that user namespace.
341 .\" ============================================================
343 .SS Restrictions on mount namespaces
345 Note the following points with respect to mount namespaces:
347 A mount namespace has an owner user namespace.
348 A mount namespace whose owner user namespace is different from
349 the owner user namespace of its parent mount namespace is
350 considered a less privileged mount namespace.
352 When creating a less privileged mount namespace,
353 shared mounts are reduced to slave mounts.
354 This ensures that mappings performed in less
355 privileged mount namespaces will not propagate to more privileged
359 .\" What does "come as a single unit from more privileged mount" mean?
360 Mounts that come as a single unit from more privileged mount are
361 locked together and may not be separated in a less privileged mount
366 operation brings across all of the mounts from the original
367 mount namespace as a single unit,
368 and recursive mounts that propagate between
369 mount namespaces propagate as a single unit.)
377 and the "atime" flags
381 settings become locked
382 .\" commit 9566d6742852c527bf5af38af5cbb878dad75705
383 .\" Author: Eric W. Biederman <ebiederm@xmission.com>
384 .\" Date: Mon Jul 28 17:26:07 2014 -0700
386 .\" mnt: Correct permission checks in do_remount
388 when propagated from a more privileged to
389 a less privileged mount namespace,
390 and may not be changed in the less privileged mount namespace.
392 .\" (As of 3.18-rc1 (in Al Viro's 2014-08-30 vfs.git#for-next tree))
393 A file or directory that is a mount point in one namespace that is not
394 a mount point in another namespace, may be renamed, unlinked, or removed
396 in the mount namespace in which it is not a mount point
397 (subject to the usual permission checks).
399 Previously, attempting to unlink, rename, or remove a file or directory
400 that was a mount point in another mount namespace would result in the error
402 That behavior had technical problems of enforcement (e.g., for NFS)
403 and permitted denial-of-service attacks against more privileged users.
404 (i.e., preventing individual files from being updated
405 by bind mounting on top of them).
407 .\" ============================================================
409 .SS User and group ID mappings: uid_map and gid_map
410 When a user namespace is created,
411 it starts out without a mapping of user IDs (group IDs)
412 to the parent user namespace.
414 .IR /proc/[pid]/uid_map
416 .IR /proc/[pid]/gid_map
417 files (available since Linux 3.5)
418 .\" commit 22d917d80e842829d0ca0a561967d728eb1d6303
419 expose the mappings for user and group IDs
420 inside the user namespace for the process
422 These files can be read to view the mappings in a user namespace and
423 written to (once) to define the mappings.
425 The description in the following paragraphs explains the details for
429 but each instance of "user ID" is replaced by "group ID".
433 file exposes the mapping of user IDs from the user namespace
436 to the user namespace of the process that opened
438 (but see a qualification to this point below).
439 In other words, processes that are in different user namespaces
440 will potentially see different values when reading from a particular
442 file, depending on the user ID mappings for the user namespaces
443 of the reading processes.
447 file specifies a 1-to-1 mapping of a range of contiguous
448 user IDs between two user namespaces.
449 (When a user namespace is first created, this file is empty.)
450 The specification in each line takes the form of
451 three numbers delimited by white space.
452 The first two numbers specify the starting user ID in
453 each of the two user namespaces.
454 The third number specifies the length of the mapped range.
455 In detail, the fields are interpreted as follows:
457 The start of the range of user IDs in
458 the user namespace of the process
461 The start of the range of user
462 IDs to which the user IDs specified by field one map.
463 How field two is interpreted depends on whether the process that opened
467 are in the same user namespace, as follows:
470 If the two processes are in different user namespaces:
471 field two is the start of a range of
472 user IDs in the user namespace of the process that opened
475 If the two processes are in the same user namespace:
476 field two is the start of the range of
477 user IDs in the parent user namespace of the process
479 This case enables the opener of
481 (the common case here is opening
482 .IR /proc/self/uid_map )
483 to see the mapping of user IDs into the user namespace of the process
484 that created this user namespace.
487 The length of the range of user IDs that is mapped between the two
490 System calls that return user IDs (group IDs)\(emfor example,
493 and the credential fields in the structure returned by
494 .BR stat (2)\(emreturn
495 the user ID (group ID) mapped into the caller's user namespace.
497 When a process accesses a file, its user and group IDs
498 are mapped into the initial user namespace for the purpose of permission
499 checking and assigning IDs when creating a file.
500 When a process retrieves file user and group IDs via
502 the IDs are mapped in the opposite direction,
503 to produce values relative to the process user and group ID mappings.
505 The initial user namespace has no parent namespace,
506 but, for consistency, the kernel provides dummy user and group
507 ID mapping files for this namespace.
512 is the same) from a shell in the initial namespace shows:
516 $ \fBcat /proc/$$/uid_map\fP
521 This mapping tells us
522 that the range starting at user ID 0 in this namespace
523 maps to a range starting at 0 in the (nonexistent) parent namespace,
524 and the length of the range is the largest 32-bit unsigned integer.
525 This leaves 4294967295 (the 32-bit signed \-1 value) unmapped.
528 is used in several interfaces (e.g.,
530 as a way to specify "no user ID".
533 unmapped and unusable guarantees that there will be no
534 confusion when using these interfaces.
536 .\" ============================================================
538 .SS Defining user and group ID mappings: writing to uid_map and gid_map
540 After the creation of a new user namespace, the
544 of the processes in the namespace may be written to
546 to define the mapping of user IDs in the new user namespace.
547 An attempt to write more than once to a
549 file in a user namespace fails with the error
551 Similar rules apply for
558 must conform to the following rules:
560 The three fields must be valid numbers,
561 and the last field must be greater than 0.
563 Lines are terminated by newline characters.
565 There is an (arbitrary) limit on the number of lines in the file.
566 As at Linux 3.18, the limit is five lines.
567 In addition, the number of bytes written to
568 the file must be less than the system page size,
569 .\" FIXME(Eric): the restriction "less than" rather than "less than or equal"
570 .\" seems strangely arbitrary. Furthermore, the comment does not agree
571 .\" with the code in kernel/user_namespace.c. Which is correct?
572 and the write must be performed at the start of the file (i.e.,
576 can't be used to write to nonzero offsets in the file).
578 The range of user IDs (group IDs)
579 specified in each line cannot overlap with the ranges
581 In the initial implementation (Linux 3.8), this requirement was
582 satisfied by a simplistic implementation that imposed the further
584 the values in both field 1 and field 2 of successive lines must be
585 in ascending numerical order,
586 which prevented some otherwise valid maps from being created.
588 .\" commit 0bd14b4fd72afd5df41e9fd59f356740f22fceba
589 fix this limitation, allowing any valid set of nonoverlapping maps.
591 At least one line must be written to the file.
593 Writes that violate the above rules fail with the error
596 In order for a process to write to the
597 .I /proc/[pid]/uid_map
598 .RI ( /proc/[pid]/gid_map )
599 file, all of the following requirements must be met:
601 The writing process must have the
604 capability in the user namespace of the process
607 The writing process must either be in the user namespace of the process
609 or be in the parent user namespace of the process
612 The mapped user IDs (group IDs) must in turn have a mapping
613 in the parent user namespace.
615 One of the following two cases applies:
619 the writing process has the
627 No further restrictions apply:
628 the process can make mappings to arbitrary user IDs (group IDs)
629 in the parent user namespace.
633 otherwise all of the following restrictions apply:
639 must consist of a single line that maps
640 the writing process's effective user ID
641 (group ID) in the parent user namespace to a user ID (group ID)
642 in the user namespace.
644 The writing process must have the same effective user ID as the process
645 that created the user namespace.
651 system call must first be denied by writing
654 .I /proc/[pid]/setgroups
655 file (see below) before writing to
660 Writes that violate the above rules fail with the error
663 .\" ============================================================
665 .SS Interaction with system calls that change process UIDs or GIDs
666 In a user namespace where the
668 file has not been written, the system calls that change user IDs will fail.
671 file has not been written, the system calls that change group IDs will fail.
676 files have been written, only the mapped values may be used in
677 system calls that change user and group IDs.
679 For user IDs, the relevant system calls include
685 For group IDs, the relevant system calls include
696 .I /proc/[pid]/setgroups
697 file before writing to
698 .I /proc/[pid]/gid_map
699 .\" Things changed in Linux 3.19
700 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
701 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
702 .\" http://lwn.net/Articles/626665/
703 will permanently disable
705 in a user namespace and allow writing to
706 .I /proc/[pid]/gid_map
709 capability in the parent user namespace.
711 .\" ============================================================
713 .SS The /proc/[pid]/setgroups file
715 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
716 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
717 .\" http://lwn.net/Articles/626665/
718 .\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989
721 .I /proc/[pid]/setgroups
722 file displays the string
724 if processes in the user namespace that contains the process
726 are permitted to employ the
728 system call; it displays
732 is not permitted in that user namespace.
733 Note that regardless of the value in the
734 .I /proc/[pid]/setgroups
735 file (and regardless of the process's capabilities), calls to
737 are also not permitted if
738 .IR /proc/[pid]/gid_map
739 has not yet been set.
741 A privileged process (one with the
743 capability in the namespace) may write either of the strings
749 writing a group ID mapping
750 for this user namespace to the file
751 .IR /proc/[pid]/gid_map .
754 prevents any process in the user namespace from employing
757 The essence of the restrictions described in the preceding
758 paragraph is that it is permitted to write to
759 .I /proc/[pid]/setgroups
760 only so long as calling
762 is disallowed because
763 .I /proc/[pid]gid_map
765 This ensures that a process cannot transition from a state where
767 is allowed to a state where
770 a process can only transition from
776 The default value of this file in the initial user namespace is
780 .IR /proc/[pid]/gid_map
782 (which has the effect of enabling
784 in the user namespace),
785 it is no longer possible to disallow
790 .IR /proc/[pid]/setgroups
791 (the write fails with the error
794 A child user namespace inherits the
795 .IR /proc/[pid]/setgroups
796 setting from its parent.
804 system call can't subsequently be reenabled (by writing
806 to the file) in this user namespace.
807 (Attempts to do so will fail with the error
809 This restriction also propagates down to all child user namespaces of
813 .I /proc/[pid]/setgroups
814 file was added in Linux 3.19,
815 but was backported to many earlier stable kernel series,
816 because it addresses a security issue.
817 The issue concerned files with permissions such as "rwx\-\-\-rwx".
818 Such files give fewer permissions to "group" than they do to "other".
819 This means that dropping groups using
821 might allow a process file access that it did not formerly have.
822 Before the existence of user namespaces this was not a concern,
823 since only a privileged process (one with the
825 capability) could call
827 However, with the introduction of user namespaces,
828 it became possible for an unprivileged process to create
829 a new namespace in which the user had all privileges.
830 This then allowed formerly unprivileged
831 users to drop groups and thus gain file access
832 that they did not previously have.
834 .I /proc/[pid]/setgroups
835 file was added to address this security issue,
836 by denying any pathway for an unprivileged process to drop groups with
839 .\" /proc/PID/setgroups
840 .\" [allow == setgroups() is allowed, "deny" == setgroups() is disallowed]
841 .\" * Can write if have CAP_SYS_ADMIN in NS
842 .\" * Must write BEFORE writing to /proc/PID/gid_map
845 .\" * Must already have written to gid_maps
846 .\" * /proc/PID/setgroups must be "allow"
848 .\" /proc/PID/gid_map -- writing
849 .\" * Must already have written "deny" to /proc/PID/setgroups
851 .\" ============================================================
853 .SS Unmapped user and group IDs
855 There are various places where an unmapped user ID (group ID)
856 may be exposed to user space.
857 For example, the first process in a new user namespace may call
859 before a user ID mapping has been defined for the namespace.
860 In most such cases, an unmapped user ID is converted
861 .\" from_kuid_munged(), from_kgid_munged()
862 to the overflow user ID (group ID);
863 the default value for the overflow user ID (group ID) is 65534.
864 See the descriptions of
865 .IR /proc/sys/kernel/overflowuid
867 .IR /proc/sys/kernel/overflowgid
871 The cases where unmapped IDs are mapped in this fashion include
872 system calls that return user IDs
876 credentials passed over a UNIX domain socket,
878 credentials returned by
881 and the System V IPC "ctl"
884 credentials exposed by
887 .IR /proc/sysvipc/* ,
888 credentials returned via the
892 received with a signal (see
894 credentials written to the process accounting file (see
896 and credentials returned with POSIX message queue notifications (see
899 There is one notable case where unmapped user and group IDs are
901 .\" from_kuid(), from_kgid()
902 .\" Also F_GETOWNER_UIDS is an exception
903 converted to the corresponding overflow ID value.
908 file in which there is no mapping for the second field,
909 that field is displayed as 4294967295 (\-1 as an unsigned integer);
911 .\" ============================================================
913 .SS Set-user-ID and set-group-ID programs
915 When a process inside a user namespace executes
916 a set-user-ID (set-group-ID) program,
917 the process's effective user (group) ID inside the namespace is changed
918 to whatever value is mapped for the user (group) ID of the file.
919 However, if either the user
921 the group ID of the file has no mapping inside the namespace,
922 the set-user-ID (set-group-ID) bit is silently ignored:
923 the new program is executed,
924 but the process's effective user (group) ID is left unchanged.
925 (This mirrors the semantics of executing a set-user-ID or set-group-ID
926 program that resides on a filesystem that was mounted with the
928 flag, as described in
931 .\" ============================================================
935 When a process's user and group IDs are passed over a UNIX domain socket
936 to a process in a different user namespace (see the description of
940 they are translated into the corresponding values as per the
941 receiving process's user and group ID mappings.
944 Namespaces are a Linux-specific feature.
947 Over the years, there have been a lot of features that have been added
948 to the Linux kernel that have been made available only to privileged users
949 because of their potential to confuse set-user-ID-root applications.
950 In general, it becomes safe to allow the root user in a user namespace to
951 use those features because it is impossible, while in a user namespace,
952 to gain more privilege than the root user of a user namespace has.
954 .\" ============================================================
957 Use of user namespaces requires a kernel that is configured with the
960 User namespaces require support in a range of subsystems across
962 When an unsupported subsystem is configured into the kernel,
963 it is not possible to configure user namespaces support.
965 As at Linux 3.8, most relevant subsystems supported user namespaces,
966 but a number of filesystems did not have the infrastructure needed
967 to map user and group IDs between user namespaces.
968 Linux 3.9 added the required infrastructure support for many of
969 the remaining unsupported filesystems
970 (Plan 9 (9P), Andrew File System (AFS), Ceph, CIFS, CODA, NFS, and OCFS2).
971 Linux 3.12 added support the last of the unsupported major filesystems,
972 .\" commit d6970d4b726cea6d7a9bc4120814f95c09571fc3
976 The program below is designed to allow experimenting with
977 user namespaces, as well as other types of namespaces.
978 It creates namespaces as specified by command-line options and then executes
979 a command inside those namespaces.
982 function inside the program provide a full explanation of the program.
983 The following shell session demonstrates its use.
985 First, we look at the run-time environment:
989 $ \fBuname -rs\fP # Need Linux 3.8 or later
991 $ \fBid -u\fP # Running as unprivileged user
998 Now start a new shell in new user
1004 namespaces, with user ID
1008 1000 mapped to 0 inside the user namespace:
1012 $ \fB./userns_child_exec -p -m -U -M '0 1000 1' -G '0 1000 1' bash\fP
1016 The shell has PID 1, because it is the first process in the new
1026 Inside the user namespace, the shell has user and group ID 0,
1027 and a full set of permitted and effective capabilities:
1031 bash$ \fBcat /proc/$$/status | egrep '^[UG]id'\fP
1034 bash$ \fBcat /proc/$$/status | egrep '^Cap(Prm|Inh|Eff)'\fP
1035 CapInh: 0000000000000000
1036 CapPrm: 0000001fffffffff
1037 CapEff: 0000001fffffffff
1043 filesystem and listing all of the processes visible
1044 in the new PID namespace shows that the shell can't see
1045 any processes outside the PID namespace:
1049 bash$ \fBmount -t proc proc /proc\fP
1051 PID TTY STAT TIME COMMAND
1053 22 pts/3 R+ 0:00 ps ax
1059 /* userns_child_exec.c
1061 Licensed under GNU General Public License v2 or later
1063 Create a child process that executes a shell command in new
1064 namespace(s); allow UID and GID mappings to be specified when
1065 creating a user namespace.
1071 #include <sys/wait.h>
1079 /* A simple error\-handling function: print an error message based
1080 on the value in \(aqerrno\(aq and terminate the calling process */
1082 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
1086 char **argv; /* Command to be executed by child, with args */
1087 int pipe_fd[2]; /* Pipe used to synchronize parent and child */
1095 fprintf(stderr, "Usage: %s [options] cmd [arg...]\\n\\n", pname);
1096 fprintf(stderr, "Create a child process that executes a shell "
1097 "command in a new user namespace,\\n"
1098 "and possibly also other new namespace(s).\\n\\n");
1099 fprintf(stderr, "Options can be:\\n\\n");
1100 #define fpe(str) fprintf(stderr, " %s", str);
1101 fpe("\-i New IPC namespace\\n");
1102 fpe("\-m New mount namespace\\n");
1103 fpe("\-n New network namespace\\n");
1104 fpe("\-p New PID namespace\\n");
1105 fpe("\-u New UTS namespace\\n");
1106 fpe("\-U New user namespace\\n");
1107 fpe("\-M uid_map Specify UID map for user namespace\\n");
1108 fpe("\-G gid_map Specify GID map for user namespace\\n");
1109 fpe("\-z Map user\(aqs UID and GID to 0 in user namespace\\n");
1110 fpe(" (equivalent to: \-M \(aq0 <uid> 1\(aq \-G \(aq0 <gid> 1\(aq)\\n");
1111 fpe("\-v Display verbose messages\\n");
1113 fpe("If \-z, \-M, or \-G is specified, \-U is required.\\n");
1114 fpe("It is not permitted to specify both \-z and either \-M or \-G.\\n");
1116 fpe("Map strings for \-M and \-G consist of records of the form:\\n");
1118 fpe(" ID\-inside\-ns ID\-outside\-ns len\\n");
1120 fpe("A map string can contain multiple records, separated"
1122 fpe("the commas are replaced by newlines before writing"
1123 " to map files.\\n");
1128 /* Update the mapping file \(aqmap_file\(aq, with the value provided in
1129 \(aqmapping\(aq, a string that defines a UID or GID mapping. A UID or
1130 GID mapping consists of one or more newline\-delimited records
1133 ID_inside\-ns ID\-outside\-ns length
1135 Requiring the user to supply a string that contains newlines is
1136 of course inconvenient for command\-line use. Thus, we permit the
1137 use of commas to delimit records in this string, and replace them
1138 with newlines before writing the string to the file. */
1141 update_map(char *mapping, char *map_file)
1144 size_t map_len; /* Length of \(aqmapping\(aq */
1146 /* Replace commas in mapping string with newlines */
1148 map_len = strlen(mapping);
1149 for (j = 0; j < map_len; j++)
1150 if (mapping[j] == \(aq,\(aq)
1151 mapping[j] = \(aq\\n\(aq;
1153 fd = open(map_file, O_RDWR);
1155 fprintf(stderr, "ERROR: open %s: %s\\n", map_file,
1160 if (write(fd, mapping, map_len) != map_len) {
1161 fprintf(stderr, "ERROR: write %s: %s\\n", map_file,
1169 /* Linux 3.19 made a change in the handling of setgroups(2) and the
1170 \(aqgid_map\(aq file to address a security issue. The issue allowed
1171 *unprivileged* users to employ user namespaces in order to drop
1172 The upshot of the 3.19 changes is that in order to update the
1173 \(aqgid_maps\(aq file, use of the setgroups() system call in this
1174 user namespace must first be disabled by writing "deny" to one of
1175 the /proc/PID/setgroups files for this namespace. That is the
1176 purpose of the following function. */
1179 proc_setgroups_write(pid_t child_pid, char *str)
1181 char setgroups_path[PATH_MAX];
1184 snprintf(setgroups_path, PATH_MAX, "/proc/%ld/setgroups",
1187 fd = open(setgroups_path, O_RDWR);
1190 /* We may be on a system that doesn\(aqt support
1191 /proc/PID/setgroups. In that case, the file won\(aqt exist,
1192 and the system won\(aqt impose the restrictions that Linux 3.19
1193 added. That\(aqs fine: we don\(aqt need to do anything in order
1194 to permit \(aqgid_map\(aq to be updated.
1196 However, if the error from open() was something other than
1197 the ENOENT error that is expected for that case, let the
1200 if (errno != ENOENT)
1201 fprintf(stderr, "ERROR: open %s: %s\\n", setgroups_path,
1206 if (write(fd, str, strlen(str)) == \-1)
1207 fprintf(stderr, "ERROR: write %s: %s\\n", setgroups_path,
1213 static int /* Start function for cloned child */
1214 childFunc(void *arg)
1216 struct child_args *args = (struct child_args *) arg;
1219 /* Wait until the parent has updated the UID and GID mappings.
1220 See the comment in main(). We wait for end of file on a
1221 pipe that will be closed by the parent process once it has
1222 updated the mappings. */
1224 close(args\->pipe_fd[1]); /* Close our descriptor for the write
1225 end of the pipe so that we see EOF
1226 when parent closes its descriptor */
1227 if (read(args\->pipe_fd[0], &ch, 1) != 0) {
1229 "Failure in child: read from pipe returned != 0\\n");
1233 /* Execute a shell command */
1235 printf("About to exec %s\\n", args\->argv[0]);
1236 execvp(args\->argv[0], args\->argv);
1240 #define STACK_SIZE (1024 * 1024)
1242 static char child_stack[STACK_SIZE]; /* Space for child\(aqs stack */
1245 main(int argc, char *argv[])
1247 int flags, opt, map_zero;
1249 struct child_args args;
1250 char *uid_map, *gid_map;
1251 const int MAP_BUF_SIZE = 100;
1252 char map_buf[MAP_BUF_SIZE];
1253 char map_path[PATH_MAX];
1255 /* Parse command\-line options. The initial \(aq+\(aq character in
1256 the final getopt() argument prevents GNU\-style permutation
1257 of command\-line options. That\(aqs useful, since sometimes
1258 the \(aqcommand\(aq to be executed by this program itself
1259 has command\-line options. We don\(aqt want getopt() to treat
1260 those as options to this program. */
1267 while ((opt = getopt(argc, argv, "+imnpuUM:G:zv")) != \-1) {
1269 case \(aqi\(aq: flags |= CLONE_NEWIPC; break;
1270 case \(aqm\(aq: flags |= CLONE_NEWNS; break;
1271 case \(aqn\(aq: flags |= CLONE_NEWNET; break;
1272 case \(aqp\(aq: flags |= CLONE_NEWPID; break;
1273 case \(aqu\(aq: flags |= CLONE_NEWUTS; break;
1274 case \(aqv\(aq: verbose = 1; break;
1275 case \(aqz\(aq: map_zero = 1; break;
1276 case \(aqM\(aq: uid_map = optarg; break;
1277 case \(aqG\(aq: gid_map = optarg; break;
1278 case \(aqU\(aq: flags |= CLONE_NEWUSER; break;
1279 default: usage(argv[0]);
1283 /* \-M or \-G without \-U is nonsensical */
1285 if (((uid_map != NULL || gid_map != NULL || map_zero) &&
1286 !(flags & CLONE_NEWUSER)) ||
1287 (map_zero && (uid_map != NULL || gid_map != NULL)))
1290 args.argv = &argv[optind];
1292 /* We use a pipe to synchronize the parent and child, in order to
1293 ensure that the parent sets the UID and GID maps before the child
1294 calls execve(). This ensures that the child maintains its
1295 capabilities during the execve() in the common case where we
1296 want to map the child\(aqs effective user ID to 0 in the new user
1297 namespace. Without this synchronization, the child would lose
1298 its capabilities if it performed an execve() with nonzero
1299 user IDs (see the capabilities(7) man page for details of the
1300 transformation of a process\(aqs capabilities during execve()). */
1302 if (pipe(args.pipe_fd) == \-1)
1305 /* Create the child in new namespace(s) */
1307 child_pid = clone(childFunc, child_stack + STACK_SIZE,
1308 flags | SIGCHLD, &args);
1309 if (child_pid == \-1)
1312 /* Parent falls through to here */
1315 printf("%s: PID of child created by clone() is %ld\\n",
1316 argv[0], (long) child_pid);
1318 /* Update the UID and GID maps in the child */
1320 if (uid_map != NULL || map_zero) {
1321 snprintf(map_path, PATH_MAX, "/proc/%ld/uid_map",
1324 snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1", (long) getuid());
1327 update_map(uid_map, map_path);
1330 if (gid_map != NULL || map_zero) {
1331 proc_setgroups_write(child_pid, "deny");
1333 snprintf(map_path, PATH_MAX, "/proc/%ld/gid_map",
1336 snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1", (long) getgid());
1339 update_map(gid_map, map_path);
1342 /* Close the write end of the pipe, to signal to the child that we
1343 have updated the UID and GID maps */
1345 close(args.pipe_fd[1]);
1347 if (waitpid(child_pid, NULL, 0) == \-1) /* Wait for child */
1351 printf("%s: terminating\\n", argv[0]);
1357 .BR newgidmap (1), \" From the shadow package
1358 .BR newuidmap (1), \" From the shadow package
1364 .BR subgid (5), \" From the shadow package
1365 .BR subuid (5), \" From the shadow package
1366 .BR credentials (7),
1367 .BR capabilities (7),
1369 .BR cgroup_namespaces (7)
1370 .BR pid_namespaces (7)
1372 The kernel source file
1373 .IR Documentation/namespaces/resource-control.txt .