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 2014-09-21 "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 it has a user ID of 0 within the namespace or the executable file
139 has a nonempty inheritable capabilities mask,
140 it 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 Having a capability inside a user namespace
169 permits a process to perform operations (that require privilege)
170 only on resources governed by that namespace.
171 The rules for determining whether or not a process has a capability
172 in a particular user namespace are as follows:
174 A process has a capability inside a user namespace
175 if it is a member of that namespace and
176 it has the capability in its effective capability set.
177 A process can gain capabilities in its effective capability
179 For example, it may execute a set-user-ID program or an
180 executable with associated file capabilities.
182 a process may gain capabilities via the effect of
187 as already described.
188 .\" In the 3.8 sources, see security/commoncap.c::cap_capable():
190 If a process has a capability in a user namespace,
191 then it has that capability in all child (and further removed descendant)
194 .\" * The owner of the user namespace in the parent of the
195 .\" * user namespace has all caps.
196 When a user namespace is created, the kernel records the effective
197 user ID of the creating process as being the "owner" of the namespace.
198 .\" (and likewise associates the effective group ID of the creating process
199 .\" with the namespace).
200 A process that resides
201 in the parent of the user namespace
202 .\" See kernel commit 520d9eabce18edfef76a60b7b839d54facafe1f9 for a fix
204 and whose effective user ID matches the owner of the namespace
205 has all capabilities in the namespace.
206 .\" This includes the case where the process executes a set-user-ID
207 .\" program that confers the effective UID of the creator of the namespace.
208 By virtue of the previous rule,
209 this means that the process has all capabilities in all
210 further removed descendant user namespaces as well.
212 .\" ============================================================
214 .SS Interaction of user namespaces and other types of namespaces
215 Starting in Linux 3.8, unprivileged processes can create user namespaces,
216 and mount, PID, IPC, network, and UTS namespaces can be created with just the
218 capability in the caller's user namespace.
220 When a non-user-namespace is created,
221 it is owned by the user namespace in which the creating process
222 was a member at the time of the creation of the namespace.
223 Actions on the non-user-namespace
224 require capabilities in the corresponding user namespace.
228 is specified along with other
234 call, the user namespace is guaranteed to be created first,
239 privileges over the remaining namespaces created by the call.
240 Thus, it is possible for an unprivileged caller to specify this combination
243 When a new IPC, mount, network, PID, or UTS namespace is created via
247 the kernel records the user namespace of the creating process against
249 (This association can't be changed.)
250 When a process in the new namespace subsequently performs
251 privileged operations that operate on global
252 resources isolated by the namespace,
253 the permission checks are performed according to the process's capabilities
254 in the user namespace that the kernel associated with the new namespace.
256 .\" ============================================================
258 .SS Restrictions on mount namespaces
260 Note the following points with respect to mount namespaces:
262 A mount namespace has an owner user namespace.
263 A mount namespace whose owner user namespace is different from
264 the owner user namespace of its parent mount namespace is
265 considered a less privileged mount namespace.
267 When creating a less privileged mount namespace,
268 shared mounts are reduced to slave mounts.
269 This ensures that mappings performed in less
270 privileged mount namespaces will not propagate to more privileged
274 .\" What does "come as a single unit from more privileged mount" mean?
275 Mounts that come as a single unit from more privileged mount are
276 locked together and may not be separated in a less privileged mount
281 operation brings across all of the mounts from the original
282 mount namespace as a single unit,
283 and recursive mounts that propagate between
284 mount namespaces propagate as a single unit.)
292 and the "atime" flags
296 settings become locked
297 .\" commit 9566d6742852c527bf5af38af5cbb878dad75705
298 .\" Author: Eric W. Biederman <ebiederm@xmission.com>
299 .\" Date: Mon Jul 28 17:26:07 2014 -0700
301 .\" mnt: Correct permission checks in do_remount
303 when propagated from a more privileged to
304 a less privileged mount namespace,
305 and may not be changed in the less privileged mount namespace.
307 .\" (As of 3.18-rc1 (in Al Viro's 2014-08-30 vfs.git#for-next tree))
308 A file or directory that is a mount point in one namespace that is not
309 a mount point in another namespace, may be renamed, unlinked, or removed
311 in the mount namespace in which it is not a mount point
312 (subject to the usual permission checks).
314 Previously, attempting to unlink, rename, or remove a file or directory
315 that was a mount point in another mount namespace would result in the error
317 That behavior had technical problems of enforcement (e.g., for NFS)
318 and permitted denial-of-service attacks against more privileged users.
319 (i.e., preventing individual files from being updated
320 by bind mounting on top of them).
322 .\" ============================================================
324 .SS User and group ID mappings: uid_map and gid_map
325 When a user namespace is created,
326 it starts out without a mapping of user IDs (group IDs)
327 to the parent user namespace.
329 .IR /proc/[pid]/uid_map
331 .IR /proc/[pid]/gid_map
332 files (available since Linux 3.5)
333 .\" commit 22d917d80e842829d0ca0a561967d728eb1d6303
334 expose the mappings for user and group IDs
335 inside the user namespace for the process
337 These files can be read to view the mappings in a user namespace and
338 written to (once) to define the mappings.
340 The description in the following paragraphs explains the details for
344 but each instance of "user ID" is replaced by "group ID".
348 file exposes the mapping of user IDs from the user namespace
351 to the user namespace of the process that opened
353 (but see a qualification to this point below).
354 In other words, processes that are in different user namespaces
355 will potentially see different values when reading from a particular
357 file, depending on the user ID mappings for the user namespaces
358 of the reading processes.
362 file specifies a 1-to-1 mapping of a range of contiguous
363 user IDs between two user namespaces.
364 (When a user namespace is first created, this file is empty.)
365 The specification in each line takes the form of
366 three numbers delimited by white space.
367 The first two numbers specify the starting user ID in
368 each of the two user namespaces.
369 The third number specifies the length of the mapped range.
370 In detail, the fields are interpreted as follows:
372 The start of the range of user IDs in
373 the user namespace of the process
376 The start of the range of user
377 IDs to which the user IDs specified by field one map.
378 How field two is interpreted depends on whether the process that opened
382 are in the same user namespace, as follows:
385 If the two processes are in different user namespaces:
386 field two is the start of a range of
387 user IDs in the user namespace of the process that opened
390 If the two processes are in the same user namespace:
391 field two is the start of the range of
392 user IDs in the parent user namespace of the process
394 This case enables the opener of
396 (the common case here is opening
397 .IR /proc/self/uid_map )
398 to see the mapping of user IDs into the user namespace of the process
399 that created this user namespace.
402 The length of the range of user IDs that is mapped between the two
405 System calls that return user IDs (group IDs)\(emfor example,
408 and the credential fields in the structure returned by
409 .BR stat (2)\(emreturn
410 the user ID (group ID) mapped into the caller's user namespace.
412 When a process accesses a file, its user and group IDs
413 are mapped into the initial user namespace for the purpose of permission
414 checking and assigning IDs when creating a file.
415 When a process retrieves file user and group IDs via
417 the IDs are mapped in the opposite direction,
418 to produce values relative to the process user and group ID mappings.
420 The initial user namespace has no parent namespace,
421 but, for consistency, the kernel provides dummy user and group
422 ID mapping files for this namespace.
427 is the same) from a shell in the initial namespace shows:
431 $ \fBcat /proc/$$/uid_map\fP
436 This mapping tells us
437 that the range starting at user ID 0 in this namespace
438 maps to a range starting at 0 in the (nonexistent) parent namespace,
439 and the length of the range is the largest 32-bit unsigned integer.
440 This leaves 4294967295 (the 32-bit signed \-1 value) unmapped.
443 is used in several interfaces (e.g.,
445 as a way to specify "no user ID".
448 unmapped and unusable guarantees that there will be no
449 confusion when using these interfaces.
451 .\" ============================================================
453 .SS Defining user and group ID mappings: writing to uid_map and gid_map
455 After the creation of a new user namespace, the
459 of the processes in the namespace may be written to
461 to define the mapping of user IDs in the new user namespace.
462 An attempt to write more than once to a
464 file in a user namespace fails with the error
466 Similar rules apply for
473 must conform to the following rules:
475 The three fields must be valid numbers,
476 and the last field must be greater than 0.
478 Lines are terminated by newline characters.
480 There is an (arbitrary) limit on the number of lines in the file.
481 As at Linux 3.18, the limit is five lines.
482 In addition, the number of bytes written to
483 the file must be less than the system page size,
484 .\" FIXME(Eric): the restriction "less than" rather than "less than or equal"
485 .\" seems strangely arbitrary. Furthermore, the comment does not agree
486 .\" with the code in kernel/user_namespace.c. Which is correct?
487 and the write must be performed at the start of the file (i.e.,
491 can't be used to write to nonzero offsets in the file).
493 The range of user IDs (group IDs)
494 specified in each line cannot overlap with the ranges
496 In the initial implementation (Linux 3.8), this requirement was
497 satisfied by a simplistic implementation that imposed the further
499 the values in both field 1 and field 2 of successive lines must be
500 in ascending numerical order,
501 which prevented some otherwise valid maps from being created.
503 .\" commit 0bd14b4fd72afd5df41e9fd59f356740f22fceba
504 fix this limitation, allowing any valid set of nonoverlapping maps.
506 At least one line must be written to the file.
508 Writes that violate the above rules fail with the error
511 In order for a process to write to the
512 .I /proc/[pid]/uid_map
513 .RI ( /proc/[pid]/gid_map )
514 file, all of the following requirements must be met:
516 The writing process must have the
519 capability in the user namespace of the process
522 The writing process must be in either the user namespace of the process
524 or inside the parent user namespace of the process
527 The mapped user IDs (group IDs) must in turn have a mapping
528 in the parent user namespace.
530 One of the following two cases applies:
534 the writing process has the
537 capability in the parent user namespace.
540 No further restrictions apply:
541 a privileged process can make mappings to arbitrary user IDs (group IDs)
542 in the parent user namespace.
546 otherwise all of the following restrictions apply:
552 consists of a single line that maps the writing process's effective user ID
553 (group ID) in the parent user namespace to a user ID (group ID)
554 in the user namespace.
556 The writing process must have the same effective user ID as the process
557 that created the user namespace.
563 system call must first be denied by writing
566 .I /proc/[pid]/setgroups
567 file (see below) before writing to
572 Writes that violate the above rules fail with the error
575 .\" ============================================================
577 .SS Interaction with system calls that change process UIDs or GIDs
578 In a user namespace where the
580 file has not been written, the system calls that change user IDs will fail.
583 file has not been written, the system calls that change group IDs will fail.
588 files have been written, only the mapped values may be used in
589 system calls that change user and group IDs.
591 For user IDs, the relevant system calls include
597 For group IDs, the relevant system calls include
608 .I /proc/[pid]/setgroups
609 file before writing to
610 .I /proc/[pid]/gid_map
611 .\" Things changed in Linux 3.19
612 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
613 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
614 .\" http://lwn.net/Articles/626665/
615 will permanently disable
617 in a user namespace and allow writing to
618 .I /proc/[pid]/gid_map
621 capability in the parent user namespace.
623 .\" ============================================================
625 .SS The /proc/[pid]/setgroups file
627 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
628 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
629 .\" http://lwn.net/Articles/626665/
630 .\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989
633 .I /proc/[pid]/setgroups
634 file displays the string
636 if processes in the user namespace that contains the process
638 are permitted to employ the
640 system call; it displays
644 is not permitted in that user namespace.
646 A privileged process (one with the
648 capability in the namespace) may write either of the strings
654 writing a group ID mapping
655 for this user namespace to the file
656 .IR /proc/[pid]/gid_map .
659 prevents any process in the user namespace from employing
661 Note that regardless of the value in the
662 .I /proc/[pid]/setgroups
665 are also not permitted if
666 .IR /proc/[pid]/gid_map
667 has not yet been set.
669 The essence of the restrictions described in the preceding
670 paragraph is that it is permitted to write to
671 .I /proc/[pid]/setgroups
672 only so long as calling
674 is disallowed because
675 .I /proc/[pid]gid_map
677 This ensures that a process cannot transition from a state where
679 is allowed to a state where
682 a process can only transition from
688 The default value of this file in the initial user namespace is
692 .IR /proc/[pid]/gid_map
694 (which has the effect of enabling
696 in the user namespace),
697 it is no longer possible to deny
700 .IR /proc/[pid]/setgroups .
702 A child user namespace inherits the
703 .IR /proc/[pid]/gid_map
704 setting from its parent.
712 system call can't subsequently be reenabled (by writing
714 to the file) in this user namespace.
715 (Attempts to do so will fail with the error
717 This restriction also propagates down to all child user namespaces of
721 .I /proc/[pid]/setgroups
722 file was added in Linux 3.19,
723 but was backported to many earlier stable kernel series,
724 because it addresses a security issue.
725 The issue concerned files with permissions such as "rwx\-\-\-rwx".
726 Such files give fewer permissions to "group" than they do to "other".
727 This means that dropping groups using
729 might allow a process file access that it did not formerly have.
730 Before the existence of user namespaces this was not a concern,
731 since only a privileged process (one with the
733 capability) could call
735 However, with the introduction of user namespaces,
736 it became possible for an unprivileged process to create
737 a new namespace in which the user had all privileges.
738 This then allowed formerly unprivileged
739 users to drop groups and thus gain file access
740 that they did not previously have.
742 .I /proc/[pid]/setgroups
743 file was added to address this security issue,
744 by denying any pathway for an unprivleged process to drop groups with
747 .\" /proc/PID/setgroups
748 .\" [allow == setgroups() is allowed, "deny" == setgroups() is disallowed]
749 .\" * Can write if have CAP_SYS_ADMIN in NS
750 .\" * Must write BEFORE writing to /proc/PID/gid_map
753 .\" * Must already have written to gid_maps
754 .\" * /proc/PID/setgroups must be "allow"
756 .\" /proc/PID/gid_map -- writing
757 .\" * Must already have written "deny" to /proc/PID/setgroups
759 .\" ============================================================
761 .SS Unmapped user and group IDs
763 There are various places where an unmapped user ID (group ID)
764 may be exposed to user space.
765 For example, the first process in a new user namespace may call
767 before a user ID mapping has been defined for the namespace.
768 In most such cases, an unmapped user ID is converted
769 .\" from_kuid_munged(), from_kgid_munged()
770 to the overflow user ID (group ID);
771 the default value for the overflow user ID (group ID) is 65534.
772 See the descriptions of
773 .IR /proc/sys/kernel/overflowuid
775 .IR /proc/sys/kernel/overflowgid
779 The cases where unmapped IDs are mapped in this fashion include
780 system calls that return user IDs
784 credentials passed over a UNIX domain socket,
786 credentials returned by
789 and the System V IPC "ctl"
792 credentials exposed by
795 .IR /proc/sysvipc/* ,
796 credentials returned via the
800 received with a signal (see
802 credentials written to the process accounting file (see
804 and credentials returned with POSIX message queue notifications (see
807 There is one notable case where unmapped user and group IDs are
809 .\" from_kuid(), from_kgid()
810 .\" Also F_GETOWNER_UIDS is an exception
811 converted to the corresponding overflow ID value.
816 file in which there is no mapping for the second field,
817 that field is displayed as 4294967295 (\-1 as an unsigned integer);
819 .\" ============================================================
821 .SS Set-user-ID and set-group-ID programs
823 When a process inside a user namespace executes
824 a set-user-ID (set-group-ID) program,
825 the process's effective user (group) ID inside the namespace is changed
826 to whatever value is mapped for the user (group) ID of the file.
827 However, if either the user
829 the group ID of the file has no mapping inside the namespace,
830 the set-user-ID (set-group-ID) bit is silently ignored:
831 the new program is executed,
832 but the process's effective user (group) ID is left unchanged.
833 (This mirrors the semantics of executing a set-user-ID or set-group-ID
834 program that resides on a filesystem that was mounted with the
836 flag, as described in
839 .\" ============================================================
843 When a process's user and group IDs are passed over a UNIX domain socket
844 to a process in a different user namespace (see the description of
848 they are translated into the corresponding values as per the
849 receiving process's user and group ID mappings.
852 Namespaces are a Linux-specific feature.
855 Over the years, there have been a lot of features that have been added
856 to the Linux kernel that have been made available only to privileged users
857 because of their potential to confuse set-user-ID-root applications.
858 In general, it becomes safe to allow the root user in a user namespace to
859 use those features because it is impossible, while in a user namespace,
860 to gain more privilege than the root user of a user namespace has.
862 .\" ============================================================
865 Use of user namespaces requires a kernel that is configured with the
868 User namespaces require support in a range of subsystems across
870 When an unsupported subsystem is configured into the kernel,
871 it is not possible to configure user namespaces support.
873 As at Linux 3.8, most relevant subsystems supported user namespaces,
874 but a number of filesystems did not have the infrastructure needed
875 to map user and group IDs between user namespaces.
876 Linux 3.9 added the required infrastructure support for many of
877 the remaining unsupported filesystems
878 (Plan 9 (9P), Andrew File System (AFS), Ceph, CIFS, CODA, NFS, and OCFS2).
879 Linux 3.11 added support the last of the unsupported major filesystems,
880 .\" commit d6970d4b726cea6d7a9bc4120814f95c09571fc3
884 The program below is designed to allow experimenting with
885 user namespaces, as well as other types of namespaces.
886 It creates namespaces as specified by command-line options and then executes
887 a command inside those namespaces.
890 function inside the program provide a full explanation of the program.
891 The following shell session demonstrates its use.
893 First, we look at the run-time environment:
897 $ \fBuname -rs\fP # Need Linux 3.8 or later
899 $ \fBid -u\fP # Running as unprivileged user
906 Now start a new shell in new user
912 namespaces, with user ID
916 1000 mapped to 0 inside the user namespace:
920 $ \fB./userns_child_exec -p -m -U -M '0 1000 1' -G '0 1000 1' bash\fP
924 The shell has PID 1, because it is the first process in the new
934 Inside the user namespace, the shell has user and group ID 0,
935 and a full set of permitted and effective capabilities:
939 bash$ \fBcat /proc/$$/status | egrep '^[UG]id'\fP
942 bash$ \fBcat /proc/$$/status | egrep '^Cap(Prm|Inh|Eff)'\fP
943 CapInh: 0000000000000000
944 CapPrm: 0000001fffffffff
945 CapEff: 0000001fffffffff
951 filesystem and listing all of the processes visible
952 in the new PID namespace shows that the shell can't see
953 any processes outside the PID namespace:
957 bash$ \fBmount -t proc proc /proc\fP
959 PID TTY STAT TIME COMMAND
961 22 pts/3 R+ 0:00 ps ax
967 /* userns_child_exec.c
969 Licensed under GNU General Public License v2 or later
971 Create a child process that executes a shell command in new
972 namespace(s); allow UID and GID mappings to be specified when
973 creating a user namespace.
979 #include <sys/wait.h>
987 /* A simple error\-handling function: print an error message based
988 on the value in \(aqerrno\(aq and terminate the calling process */
990 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
994 char **argv; /* Command to be executed by child, with args */
995 int pipe_fd[2]; /* Pipe used to synchronize parent and child */
1003 fprintf(stderr, "Usage: %s [options] cmd [arg...]\\n\\n", pname);
1004 fprintf(stderr, "Create a child process that executes a shell "
1005 "command in a new user namespace,\\n"
1006 "and possibly also other new namespace(s).\\n\\n");
1007 fprintf(stderr, "Options can be:\\n\\n");
1008 #define fpe(str) fprintf(stderr, " %s", str);
1009 fpe("\-i New IPC namespace\\n");
1010 fpe("\-m New mount namespace\\n");
1011 fpe("\-n New network namespace\\n");
1012 fpe("\-p New PID namespace\\n");
1013 fpe("\-u New UTS namespace\\n");
1014 fpe("\-U New user namespace\\n");
1015 fpe("\-M uid_map Specify UID map for user namespace\\n");
1016 fpe("\-G gid_map Specify GID map for user namespace\\n");
1017 fpe("\-z Map user\(aqs UID and GID to 0 in user namespace\\n");
1018 fpe(" (equivalent to: \-M \(aq0 <uid> 1\(aq \-G \(aq0 <gid> 1\(aq)\\n");
1019 fpe("\-v Display verbose messages\\n");
1021 fpe("If \-z, \-M, or \-G is specified, \-U is required.\\n");
1022 fpe("It is not permitted to specify both \-z and either \-M or \-G.\\n");
1024 fpe("Map strings for \-M and \-G consist of records of the form:\\n");
1026 fpe(" ID\-inside\-ns ID\-outside\-ns len\\n");
1028 fpe("A map string can contain multiple records, separated"
1030 fpe("the commas are replaced by newlines before writing"
1031 " to map files.\\n");
1036 /* Update the mapping file \(aqmap_file\(aq, with the value provided in
1037 \(aqmapping\(aq, a string that defines a UID or GID mapping. A UID or
1038 GID mapping consists of one or more newline\-delimited records
1041 ID_inside\-ns ID\-outside\-ns length
1043 Requiring the user to supply a string that contains newlines is
1044 of course inconvenient for command\-line use. Thus, we permit the
1045 use of commas to delimit records in this string, and replace them
1046 with newlines before writing the string to the file. */
1049 update_map(char *mapping, char *map_file)
1052 size_t map_len; /* Length of \(aqmapping\(aq */
1054 /* Replace commas in mapping string with newlines */
1056 map_len = strlen(mapping);
1057 for (j = 0; j < map_len; j++)
1058 if (mapping[j] == \(aq,\(aq)
1059 mapping[j] = \(aq\\n\(aq;
1061 fd = open(map_file, O_RDWR);
1063 fprintf(stderr, "ERROR: open %s: %s\\n", map_file,
1068 if (write(fd, mapping, map_len) != map_len) {
1069 fprintf(stderr, "ERROR: write %s: %s\\n", map_file,
1077 /* Linux 3.19 made a change in the handling of setgroups(2) and the
1078 \(aqgid_map\(aq file to address a security issue. The issue allowed
1079 *unprivileged* users to employ user namespaces in order to drop
1080 The upshot of the 3.19 changes is that in order to update the
1081 \(aqgid_maps\(aq file, use of the setgroups() system call in this
1082 user namespace must first be disabled by writing "deny" to one of
1083 the /proc/PID/setgroups files for this namespace. That is the
1084 purpose of the following function. */
1087 proc_setgroups_write(pid_t child_pid, char *str)
1089 char setgroups_path[PATH_MAX];
1092 snprintf(setgroups_path, PATH_MAX, "/proc/%ld/setgroups",
1095 fd = open(setgroups_path, O_RDWR);
1098 /* We may be on a system that doesn\(aqt support
1099 /proc/PID/setgroups. In that case, the file won\(aqt exist,
1100 and the system won\(aqt impose the restrictions that Linux 3.19
1101 added. That\(aqs fine: we don\(aqt need to do anything in order
1102 to permit \(aqgid_map\(aq to be updated.
1104 However, if the error from open() was something other than
1105 the ENOENT error that is expected for that case, let the
1108 if (errno != ENOENT)
1109 fprintf(stderr, "ERROR: open %s: %s\\n", setgroups_path,
1114 if (write(fd, str, strlen(str)) == \-1)
1115 fprintf(stderr, "ERROR: write %s: %s\\n", setgroups_path,
1121 static int /* Start function for cloned child */
1122 childFunc(void *arg)
1124 struct child_args *args = (struct child_args *) arg;
1127 /* Wait until the parent has updated the UID and GID mappings.
1128 See the comment in main(). We wait for end of file on a
1129 pipe that will be closed by the parent process once it has
1130 updated the mappings. */
1132 close(args\->pipe_fd[1]); /* Close our descriptor for the write
1133 end of the pipe so that we see EOF
1134 when parent closes its descriptor */
1135 if (read(args\->pipe_fd[0], &ch, 1) != 0) {
1137 "Failure in child: read from pipe returned != 0\\n");
1141 /* Execute a shell command */
1143 printf("About to exec %s\\n", args\->argv[0]);
1144 execvp(args\->argv[0], args\->argv);
1148 #define STACK_SIZE (1024 * 1024)
1150 static char child_stack[STACK_SIZE]; /* Space for child\(aqs stack */
1153 main(int argc, char *argv[])
1155 int flags, opt, map_zero;
1157 struct child_args args;
1158 char *uid_map, *gid_map;
1159 const int MAP_BUF_SIZE = 100;
1160 char map_buf[MAP_BUF_SIZE];
1161 char map_path[PATH_MAX];
1163 /* Parse command\-line options. The initial \(aq+\(aq character in
1164 the final getopt() argument prevents GNU\-style permutation
1165 of command\-line options. That\(aqs useful, since sometimes
1166 the \(aqcommand\(aq to be executed by this program itself
1167 has command\-line options. We don\(aqt want getopt() to treat
1168 those as options to this program. */
1175 while ((opt = getopt(argc, argv, "+imnpuUM:G:zv")) != \-1) {
1177 case \(aqi\(aq: flags |= CLONE_NEWIPC; break;
1178 case \(aqm\(aq: flags |= CLONE_NEWNS; break;
1179 case \(aqn\(aq: flags |= CLONE_NEWNET; break;
1180 case \(aqp\(aq: flags |= CLONE_NEWPID; break;
1181 case \(aqu\(aq: flags |= CLONE_NEWUTS; break;
1182 case \(aqv\(aq: verbose = 1; break;
1183 case \(aqz\(aq: map_zero = 1; break;
1184 case \(aqM\(aq: uid_map = optarg; break;
1185 case \(aqG\(aq: gid_map = optarg; break;
1186 case \(aqU\(aq: flags |= CLONE_NEWUSER; break;
1187 default: usage(argv[0]);
1191 /* \-M or \-G without \-U is nonsensical */
1193 if (((uid_map != NULL || gid_map != NULL || map_zero) &&
1194 !(flags & CLONE_NEWUSER)) ||
1195 (map_zero && (uid_map != NULL || gid_map != NULL)))
1198 args.argv = &argv[optind];
1200 /* We use a pipe to synchronize the parent and child, in order to
1201 ensure that the parent sets the UID and GID maps before the child
1202 calls execve(). This ensures that the child maintains its
1203 capabilities during the execve() in the common case where we
1204 want to map the child\(aqs effective user ID to 0 in the new user
1205 namespace. Without this synchronization, the child would lose
1206 its capabilities if it performed an execve() with nonzero
1207 user IDs (see the capabilities(7) man page for details of the
1208 transformation of a process\(aqs capabilities during execve()). */
1210 if (pipe(args.pipe_fd) == \-1)
1213 /* Create the child in new namespace(s) */
1215 child_pid = clone(childFunc, child_stack + STACK_SIZE,
1216 flags | SIGCHLD, &args);
1217 if (child_pid == \-1)
1220 /* Parent falls through to here */
1223 printf("%s: PID of child created by clone() is %ld\\n",
1224 argv[0], (long) child_pid);
1226 /* Update the UID and GID maps in the child */
1228 if (uid_map != NULL || map_zero) {
1229 snprintf(map_path, PATH_MAX, "/proc/%ld/uid_map",
1232 snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1", (long) getuid());
1235 update_map(uid_map, map_path);
1237 if (gid_map != NULL || map_zero) {
1238 proc_setgroups_write(child_pid, "deny");
1240 snprintf(map_path, PATH_MAX, "/proc/%ld/gid_map",
1243 snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1", (long) getgid());
1246 update_map(gid_map, map_path);
1249 /* Close the write end of the pipe, to signal to the child that we
1250 have updated the UID and GID maps */
1252 close(args.pipe_fd[1]);
1254 if (waitpid(child_pid, NULL, 0) == \-1) /* Wait for child */
1258 printf("%s: terminating\\n", argv[0]);
1264 .BR newgidmap (1), \" From the shadow package
1265 .BR newuidmap (1), \" From the shadow package
1270 .BR subgid (5), \" From the shadow package
1271 .BR subuid (5), \" From the shadow package
1272 .BR credentials (7),
1273 .BR capabilities (7),
1275 .BR pid_namespaces (7)
1277 The kernel source file
1278 .IR Documentation/namespaces/resource-control.txt .