summaryrefslogtreecommitdiffstats
path: root/man7/user_namespaces.7
diff options
context:
space:
mode:
Diffstat (limited to 'man7/user_namespaces.7')
-rw-r--r--man7/user_namespaces.71469
1 files changed, 0 insertions, 1469 deletions
diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7
deleted file mode 100644
index 94e0785..0000000
--- a/man7/user_namespaces.7
+++ /dev/null
@@ -1,1469 +0,0 @@
-.\" Copyright (c) 2013, 2014 by Michael Kerrisk <mtk.manpages@gmail.com>
-.\" and Copyright (c) 2012, 2014 by Eric W. Biederman <ebiederm@xmission.com>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.\"
-.TH user_namespaces 7 2024-02-25 "Linux man-pages 6.7"
-.SH NAME
-user_namespaces \- overview of Linux user namespaces
-.SH DESCRIPTION
-For an overview of namespaces, see
-.BR namespaces (7).
-.P
-User namespaces isolate security-related identifiers and attributes,
-in particular,
-user IDs and group IDs (see
-.BR credentials (7)),
-the root directory,
-keys (see
-.BR keyrings (7)),
-.\" FIXME: This page says very little about the interaction
-.\" of user namespaces and keys. Add something on this topic.
-and capabilities (see
-.BR capabilities (7)).
-A process's user and group IDs can be different
-inside and outside a user namespace.
-In particular,
-a process can have a normal unprivileged user ID outside a user namespace
-while at the same time having a user ID of 0 inside the namespace;
-in other words,
-the process has full privileges for operations inside the user namespace,
-but is unprivileged for operations outside the namespace.
-.\"
-.\" ============================================================
-.\"
-.SS Nested namespaces, namespace membership
-User namespaces can be nested;
-that is, each user namespace\[em]except the initial ("root")
-namespace\[em]has a parent user namespace,
-and can have zero or more child user namespaces.
-The parent user namespace is the user namespace
-of the process that creates the user namespace via a call to
-.BR unshare (2)
-or
-.BR clone (2)
-with the
-.B CLONE_NEWUSER
-flag.
-.P
-The kernel imposes (since Linux 3.11) a limit of 32 nested levels of
-.\" commit 8742f229b635bf1c1c84a3dfe5e47c814c20b5c8
-user namespaces.
-.\" FIXME Explain the rationale for this limit. (What is the rationale?)
-Calls to
-.BR unshare (2)
-or
-.BR clone (2)
-that would cause this limit to be exceeded fail with the error
-.BR EUSERS .
-.P
-Each process is a member of exactly one user namespace.
-A process created via
-.BR fork (2)
-or
-.BR clone (2)
-without the
-.B CLONE_NEWUSER
-flag is a member of the same user namespace as its parent.
-A single-threaded process can join another user namespace with
-.BR setns (2)
-if it has the
-.B CAP_SYS_ADMIN
-in that namespace;
-upon doing so, it gains a full set of capabilities in that namespace.
-.P
-A call to
-.BR clone (2)
-or
-.BR unshare (2)
-with the
-.B CLONE_NEWUSER
-flag makes the new child process (for
-.BR clone (2))
-or the caller (for
-.BR unshare (2))
-a member of the new user namespace created by the call.
-.P
-The
-.B NS_GET_PARENT
-.BR ioctl (2)
-operation can be used to discover the parental relationship
-between user namespaces; see
-.BR ioctl_ns (2).
-.P
-A task that changes one of its effective IDs
-will have its dumpability reset to the value in
-.IR /proc/sys/fs/suid_dumpable .
-This may affect the ownership of proc files of child processes
-and may thus cause the parent to lack the permissions
-to write to mapping files of child processes running in a new user namespace.
-In such cases making the parent process dumpable, using
-.B PR_SET_DUMPABLE
-in a call to
-.BR prctl (2),
-before creating a child process in a new user namespace
-may rectify this problem.
-See
-.BR prctl (2)
-and
-.BR proc (5)
-for details on how ownership is affected.
-.\"
-.\" ============================================================
-.\"
-.SS Capabilities
-The child process created by
-.BR clone (2)
-with the
-.B CLONE_NEWUSER
-flag starts out with a complete set
-of capabilities in the new user namespace.
-Likewise, a process that creates a new user namespace using
-.BR unshare (2)
-or joins an existing user namespace using
-.BR setns (2)
-gains a full set of capabilities in that namespace.
-On the other hand,
-that process has no capabilities in the parent (in the case of
-.BR clone (2))
-or previous (in the case of
-.BR unshare (2)
-and
-.BR setns (2))
-user namespace,
-even if the new namespace is created or joined by the root user
-(i.e., a process with user ID 0 in the root namespace).
-.P
-Note that a call to
-.BR execve (2)
-will cause a process's capabilities to be recalculated in the usual way (see
-.BR capabilities (7)).
-Consequently,
-unless the process has a user ID of 0 within the namespace,
-or the executable file has a nonempty inheritable capabilities mask,
-the process will lose all capabilities.
-See the discussion of user and group ID mappings, below.
-.P
-A call to
-.BR clone (2)
-or
-.BR unshare (2)
-using the
-.B CLONE_NEWUSER
-flag
-or a call to
-.BR setns (2)
-that moves the caller into another user namespace
-sets the "securebits" flags
-(see
-.BR capabilities (7))
-to their default values (all flags disabled) in the child (for
-.BR clone (2))
-or caller (for
-.BR unshare (2)
-or
-.BR setns (2)).
-Note that because the caller no longer has capabilities
-in its original user namespace after a call to
-.BR setns (2),
-it is not possible for a process to reset its "securebits" flags while
-retaining its user namespace membership by using a pair of
-.BR setns (2)
-calls to move to another user namespace and then return to
-its original user namespace.
-.P
-The rules for determining whether or not a process has a capability
-in a particular user namespace are as follows:
-.IP \[bu] 3
-A process has a capability inside a user namespace
-if it is a member of that namespace and
-it has the capability in its effective capability set.
-A process can gain capabilities in its effective capability
-set in various ways.
-For example, it may execute a set-user-ID program or an
-executable with associated file capabilities.
-In addition,
-a process may gain capabilities via the effect of
-.BR clone (2),
-.BR unshare (2),
-or
-.BR setns (2),
-as already described.
-.\" In the 3.8 sources, see security/commoncap.c::cap_capable():
-.IP \[bu]
-If a process has a capability in a user namespace,
-then it has that capability in all child (and further removed descendant)
-namespaces as well.
-.IP \[bu]
-.\" * The owner of the user namespace in the parent of the
-.\" * user namespace has all caps.
-When a user namespace is created, the kernel records the effective
-user ID of the creating process as being the "owner" of the namespace.
-.\" (and likewise associates the effective group ID of the creating process
-.\" with the namespace).
-A process that resides
-in the parent of the user namespace
-.\" See kernel commit 520d9eabce18edfef76a60b7b839d54facafe1f9 for a fix
-.\" on this point
-and whose effective user ID matches the owner of the namespace
-has all capabilities in the namespace.
-.\" This includes the case where the process executes a set-user-ID
-.\" program that confers the effective UID of the creator of the namespace.
-By virtue of the previous rule,
-this means that the process has all capabilities in all
-further removed descendant user namespaces as well.
-The
-.B NS_GET_OWNER_UID
-.BR ioctl (2)
-operation can be used to discover the user ID of the owner of the namespace;
-see
-.BR ioctl_ns (2).
-.\"
-.\" ============================================================
-.\"
-.SS Effect of capabilities within a user namespace
-Having a capability inside a user namespace
-permits a process to perform operations (that require privilege)
-only on resources governed by that namespace.
-In other words, having a capability in a user namespace permits a process
-to perform privileged operations on resources that are governed by (nonuser)
-namespaces owned by (associated with) the user namespace
-(see the next subsection).
-.P
-On the other hand, there are many privileged operations that affect
-resources that are not associated with any namespace type,
-for example, changing the system (i.e., calendar) time (governed by
-.BR CAP_SYS_TIME ),
-loading a kernel module (governed by
-.BR CAP_SYS_MODULE ),
-and creating a device (governed by
-.BR CAP_MKNOD ).
-Only a process with privileges in the
-.I initial
-user namespace can perform such operations.
-.P
-Holding
-.B CAP_SYS_ADMIN
-within the user namespace that owns a process's mount namespace
-allows that process to create bind mounts
-and mount the following types of filesystems:
-.\" fs_flags = FS_USERNS_MOUNT in kernel sources
-.P
-.RS 4
-.PD 0
-.IP \[bu] 3
-.I /proc
-(since Linux 3.8)
-.IP \[bu]
-.I /sys
-(since Linux 3.8)
-.IP \[bu]
-.I devpts
-(since Linux 3.9)
-.IP \[bu]
-.BR tmpfs (5)
-(since Linux 3.9)
-.IP \[bu]
-.I ramfs
-(since Linux 3.9)
-.IP \[bu]
-.I mqueue
-(since Linux 3.9)
-.IP \[bu]
-.I bpf
-.\" commit b2197755b2633e164a439682fb05a9b5ea48f706
-(since Linux 4.4)
-.IP \[bu]
-.I overlayfs
-.\" commit 92dbc9dedccb9759c7f9f2f0ae6242396376988f
-.\" commit 4cb2c00c43b3fe88b32f29df4f76da1b92c33224
-(since Linux 5.11)
-.PD
-.RE
-.P
-Holding
-.B CAP_SYS_ADMIN
-within the user namespace that owns a process's cgroup namespace
-allows (since Linux 4.6)
-that process to the mount the cgroup version 2 filesystem and
-cgroup version 1 named hierarchies
-(i.e., cgroup filesystems mounted with the
-.I \[dq]none,name=\[dq]
-option).
-.P
-Holding
-.B CAP_SYS_ADMIN
-within the user namespace that owns a process's PID namespace
-allows (since Linux 3.8)
-that process to mount
-.I /proc
-filesystems.
-.P
-Note, however, that mounting block-based filesystems can be done
-only by a process that holds
-.B CAP_SYS_ADMIN
-in the initial user namespace.
-.\"
-.\" ============================================================
-.\"
-.SS Interaction of user namespaces and other types of namespaces
-Starting in Linux 3.8, unprivileged processes can create user namespaces,
-and the other types of namespaces can be created with just the
-.B CAP_SYS_ADMIN
-capability in the caller's user namespace.
-.P
-When a nonuser namespace is created,
-it is owned by the user namespace in which the creating process
-was a member at the time of the creation of the namespace.
-Privileged operations on resources governed by the nonuser namespace
-require that the process has the necessary capabilities
-in the user namespace that owns the nonuser namespace.
-.P
-If
-.B CLONE_NEWUSER
-is specified along with other
-.B CLONE_NEW*
-flags in a single
-.BR clone (2)
-or
-.BR unshare (2)
-call, the user namespace is guaranteed to be created first,
-giving the child
-.RB ( clone (2))
-or caller
-.RB ( unshare (2))
-privileges over the remaining namespaces created by the call.
-Thus, it is possible for an unprivileged caller to specify this combination
-of flags.
-.P
-When a new namespace (other than a user namespace) is created via
-.BR clone (2)
-or
-.BR unshare (2),
-the kernel records the user namespace of the creating process as the owner of
-the new namespace.
-(This association can't be changed.)
-When a process in the new namespace subsequently performs
-privileged operations that operate on global
-resources isolated by the namespace,
-the permission checks are performed according to the process's capabilities
-in the user namespace that the kernel associated with the new namespace.
-For example, suppose that a process attempts to change the hostname
-.RB ( sethostname (2)),
-a resource governed by the UTS namespace.
-In this case,
-the kernel will determine which user namespace owns
-the process's UTS namespace, and check whether the process has the
-required capability
-.RB ( CAP_SYS_ADMIN )
-in that user namespace.
-.P
-The
-.B NS_GET_USERNS
-.BR ioctl (2)
-operation can be used to discover the user namespace
-that owns a nonuser namespace; see
-.BR ioctl_ns (2).
-.\"
-.\" ============================================================
-.\"
-.SS User and group ID mappings: uid_map and gid_map
-When a user namespace is created,
-it starts out without a mapping of user IDs (group IDs)
-to the parent user namespace.
-The
-.IR /proc/ pid /uid_map
-and
-.IR /proc/ pid /gid_map
-files (available since Linux 3.5)
-.\" commit 22d917d80e842829d0ca0a561967d728eb1d6303
-expose the mappings for user and group IDs
-inside the user namespace for the process
-.IR pid .
-These files can be read to view the mappings in a user namespace and
-written to (once) to define the mappings.
-.P
-The description in the following paragraphs explains the details for
-.IR uid_map ;
-.I gid_map
-is exactly the same,
-but each instance of "user ID" is replaced by "group ID".
-.P
-The
-.I uid_map
-file exposes the mapping of user IDs from the user namespace
-of the process
-.I pid
-to the user namespace of the process that opened
-.I uid_map
-(but see a qualification to this point below).
-In other words, processes that are in different user namespaces
-will potentially see different values when reading from a particular
-.I uid_map
-file, depending on the user ID mappings for the user namespaces
-of the reading processes.
-.P
-Each line in the
-.I uid_map
-file specifies a 1-to-1 mapping of a range of contiguous
-user IDs between two user namespaces.
-(When a user namespace is first created, this file is empty.)
-The specification in each line takes the form of
-three numbers delimited by white space.
-The first two numbers specify the starting user ID in
-each of the two user namespaces.
-The third number specifies the length of the mapped range.
-In detail, the fields are interpreted as follows:
-.IP (1) 5
-The start of the range of user IDs in
-the user namespace of the process
-.IR pid .
-.IP (2)
-The start of the range of user
-IDs to which the user IDs specified by field one map.
-How field two is interpreted depends on whether the process that opened
-.I uid_map
-and the process
-.I pid
-are in the same user namespace, as follows:
-.RS
-.IP (a) 5
-If the two processes are in different user namespaces:
-field two is the start of a range of
-user IDs in the user namespace of the process that opened
-.IR uid_map .
-.IP (b)
-If the two processes are in the same user namespace:
-field two is the start of the range of
-user IDs in the parent user namespace of the process
-.IR pid .
-This case enables the opener of
-.I uid_map
-(the common case here is opening
-.IR /proc/self/uid_map )
-to see the mapping of user IDs into the user namespace of the process
-that created this user namespace.
-.RE
-.IP (3)
-The length of the range of user IDs that is mapped between the two
-user namespaces.
-.P
-System calls that return user IDs (group IDs)\[em]for example,
-.BR getuid (2),
-.BR getgid (2),
-and the credential fields in the structure returned by
-.BR stat (2)\[em]return
-the user ID (group ID) mapped into the caller's user namespace.
-.P
-When a process accesses a file, its user and group IDs
-are mapped into the initial user namespace for the purpose of permission
-checking and assigning IDs when creating a file.
-When a process retrieves file user and group IDs via
-.BR stat (2),
-the IDs are mapped in the opposite direction,
-to produce values relative to the process user and group ID mappings.
-.P
-The initial user namespace has no parent namespace,
-but, for consistency, the kernel provides dummy user and group
-ID mapping files for this namespace.
-Looking at the
-.I uid_map
-file
-.RI ( gid_map
-is the same) from a shell in the initial namespace shows:
-.P
-.in +4n
-.EX
-$ \fBcat /proc/$$/uid_map\fP
- 0 0 4294967295
-.EE
-.in
-.P
-This mapping tells us
-that the range starting at user ID 0 in this namespace
-maps to a range starting at 0 in the (nonexistent) parent namespace,
-and the length of the range is the largest 32-bit unsigned integer.
-This leaves 4294967295 (the 32-bit signed \-1 value) unmapped.
-This is deliberate:
-.I (uid_t)\~\-1
-is used in several interfaces (e.g.,
-.BR setreuid (2))
-as a way to specify "no user ID".
-Leaving
-.I (uid_t)\~\-1
-unmapped and unusable guarantees that there will be no
-confusion when using these interfaces.
-.\"
-.\" ============================================================
-.\"
-.SS Defining user and group ID mappings: writing to uid_map and gid_map
-After the creation of a new user namespace, the
-.I uid_map
-file of
-.I one
-of the processes in the namespace may be written to
-.I once
-to define the mapping of user IDs in the new user namespace.
-An attempt to write more than once to a
-.I uid_map
-file in a user namespace fails with the error
-.BR EPERM .
-Similar rules apply for
-.I gid_map
-files.
-.P
-The lines written to
-.I uid_map
-.RI ( gid_map )
-must conform to the following validity rules:
-.IP \[bu] 3
-The three fields must be valid numbers,
-and the last field must be greater than 0.
-.IP \[bu]
-Lines are terminated by newline characters.
-.IP \[bu]
-There is a limit on the number of lines in the file.
-In Linux 4.14 and earlier, this limit was (arbitrarily)
-.\" 5*12-byte records could fit in a 64B cache line
-set at 5 lines.
-Since Linux 4.15,
-.\" commit 6397fac4915ab3002dc15aae751455da1a852f25
-the limit is 340 lines.
-In addition, the number of bytes written to
-the file must be less than the system page size,
-and the write must be performed at the start of the file (i.e.,
-.BR lseek (2)
-and
-.BR pwrite (2)
-can't be used to write to nonzero offsets in the file).
-.IP \[bu]
-The range of user IDs (group IDs)
-specified in each line cannot overlap with the ranges
-in any other lines.
-In the initial implementation (Linux 3.8), this requirement was
-satisfied by a simplistic implementation that imposed the further
-requirement that
-the values in both field 1 and field 2 of successive lines must be
-in ascending numerical order,
-which prevented some otherwise valid maps from being created.
-Linux 3.9 and later
-.\" commit 0bd14b4fd72afd5df41e9fd59f356740f22fceba
-fix this limitation, allowing any valid set of nonoverlapping maps.
-.IP \[bu]
-At least one line must be written to the file.
-.P
-Writes that violate the above rules fail with the error
-.BR EINVAL .
-.P
-In order for a process to write to the
-.IR /proc/ pid /uid_map
-.RI ( /proc/ pid /gid_map )
-file, all of the following permission requirements must be met:
-.IP \[bu] 3
-The writing process must have the
-.B CAP_SETUID
-.RB ( CAP_SETGID )
-capability in the user namespace of the process
-.IR pid .
-.IP \[bu]
-The writing process must either be in the user namespace of the process
-.I pid
-or be in the parent user namespace of the process
-.IR pid .
-.IP \[bu]
-The mapped user IDs (group IDs) must in turn have a mapping
-in the parent user namespace.
-.IP \[bu]
-If updating
-.IR /proc/ pid /uid_map
-to create a mapping that maps UID 0 in the parent namespace,
-then one of the following must be true:
-.RS
-.IP (a) 5
-if writing process is in the parent user namespace,
-then it must have the
-.B CAP_SETFCAP
-capability in that user namespace; or
-.IP (b)
-if the writing process is in the child user namespace,
-then the process that created the user namespace must have had the
-.B CAP_SETFCAP
-capability when the namespace was created.
-.RE
-.IP
-This rule has been in place since
-.\" commit db2e718a47984b9d71ed890eb2ea36ecf150de18
-Linux 5.12.
-It eliminates an earlier security bug whereby
-a UID 0 process that lacks the
-.B CAP_SETFCAP
-capability,
-which is needed to create a binary with namespaced file capabilities
-(as described in
-.BR capabilities (7)),
-could nevertheless create such a binary,
-by the following steps:
-.RS
-.IP (1) 5
-Create a new user namespace with the identity mapping
-(i.e., UID 0 in the new user namespace maps to UID 0 in the parent namespace),
-so that UID 0 in both namespaces is equivalent to the same root user ID.
-.IP (2)
-Since the child process has the
-.B CAP_SETFCAP
-capability, it could create a binary with namespaced file capabilities
-that would then be effective in the parent user namespace
-(because the root user IDs are the same in the two namespaces).
-.RE
-.IP \[bu]
-One of the following two cases applies:
-.RS
-.IP (a) 5
-.I Either
-the writing process has the
-.B CAP_SETUID
-.RB ( CAP_SETGID )
-capability in the
-.I parent
-user namespace.
-.RS
-.IP \[bu] 3
-No further restrictions apply:
-the process can make mappings to arbitrary user IDs (group IDs)
-in the parent user namespace.
-.RE
-.IP (b)
-.I Or
-otherwise all of the following restrictions apply:
-.RS
-.IP \[bu] 3
-The data written to
-.I uid_map
-.RI ( gid_map )
-must consist of a single line that maps
-the writing process's effective user ID
-(group ID) in the parent user namespace to a user ID (group ID)
-in the user namespace.
-.IP \[bu]
-The writing process must have the same effective user ID as the process
-that created the user namespace.
-.IP \[bu]
-In the case of
-.IR gid_map ,
-use of the
-.BR setgroups (2)
-system call must first be denied by writing
-.RI \[dq] deny \[dq]
-to the
-.IR /proc/ pid /setgroups
-file (see below) before writing to
-.IR gid_map .
-.RE
-.RE
-.P
-Writes that violate the above rules fail with the error
-.BR EPERM .
-.\"
-.\" ============================================================
-.\"
-.SS Project ID mappings: projid_map
-Similarly to user and group ID mappings,
-it is possible to create project ID mappings for a user namespace.
-(Project IDs are used for disk quotas; see
-.BR setquota (8)
-and
-.BR quotactl (2).)
-.P
-Project ID mappings are defined by writing to the
-.IR /proc/ pid /projid_map
-file (present since
-.\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d
-Linux 3.7).
-.P
-The validity rules for writing to the
-.IR /proc/ pid /projid_map
-file are as for writing to the
-.I uid_map
-file; violation of these rules causes
-.BR write (2)
-to fail with the error
-.BR EINVAL .
-.P
-The permission rules for writing to the
-.IR /proc/ pid /projid_map
-file are as follows:
-.IP \[bu] 3
-The writing process must either be in the user namespace of the process
-.I pid
-or be in the parent user namespace of the process
-.IR pid .
-.IP \[bu]
-The mapped project IDs must in turn have a mapping
-in the parent user namespace.
-.P
-Violation of these rules causes
-.BR write (2)
-to fail with the error
-.BR EPERM .
-.\"
-.\" ============================================================
-.\"
-.SS Interaction with system calls that change process UIDs or GIDs
-In a user namespace where the
-.I uid_map
-file has not been written, the system calls that change user IDs will fail.
-Similarly, if the
-.I gid_map
-file has not been written, the system calls that change group IDs will fail.
-After the
-.I uid_map
-and
-.I gid_map
-files have been written, only the mapped values may be used in
-system calls that change user and group IDs.
-.P
-For user IDs, the relevant system calls include
-.BR setuid (2),
-.BR setfsuid (2),
-.BR setreuid (2),
-and
-.BR setresuid (2).
-For group IDs, the relevant system calls include
-.BR setgid (2),
-.BR setfsgid (2),
-.BR setregid (2),
-.BR setresgid (2),
-and
-.BR setgroups (2).
-.P
-Writing
-.RI \[dq] deny \[dq]
-to the
-.IR /proc/ pid /setgroups
-file before writing to
-.IR /proc/ pid /gid_map
-.\" Things changed in Linux 3.19
-.\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
-.\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
-.\" http://lwn.net/Articles/626665/
-will permanently disable
-.BR setgroups (2)
-in a user namespace and allow writing to
-.IR /proc/ pid /gid_map
-without having the
-.B CAP_SETGID
-capability in the parent user namespace.
-.\"
-.\" ============================================================
-.\"
-.SS The \fI/proc/\fPpid\fI/setgroups\fP file
-.\"
-.\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
-.\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
-.\" http://lwn.net/Articles/626665/
-.\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989
-.\"
-The
-.IR /proc/ pid /setgroups
-file displays the string
-.RI \[dq] allow \[dq]
-if processes in the user namespace that contains the process
-.I pid
-are permitted to employ the
-.BR setgroups (2)
-system call; it displays
-.RI \[dq] deny \[dq]
-if
-.BR setgroups (2)
-is not permitted in that user namespace.
-Note that regardless of the value in the
-.IR /proc/ pid /setgroups
-file (and regardless of the process's capabilities), calls to
-.BR setgroups (2)
-are also not permitted if
-.IR /proc/ pid /gid_map
-has not yet been set.
-.P
-A privileged process (one with the
-.B CAP_SYS_ADMIN
-capability in the namespace) may write either of the strings
-.RI \[dq] allow \[dq]
-or
-.RI \[dq] deny \[dq]
-to this file
-.I before
-writing a group ID mapping
-for this user namespace to the file
-.IR /proc/ pid /gid_map .
-Writing the string
-.RI \[dq] deny \[dq]
-prevents any process in the user namespace from employing
-.BR setgroups (2).
-.P
-The essence of the restrictions described in the preceding
-paragraph is that it is permitted to write to
-.IR /proc/ pid /setgroups
-only so long as calling
-.BR setgroups (2)
-is disallowed because
-.IR /proc/ pid /gid_map
-has not been set.
-This ensures that a process cannot transition from a state where
-.BR setgroups (2)
-is allowed to a state where
-.BR setgroups (2)
-is denied;
-a process can transition only from
-.BR setgroups (2)
-being disallowed to
-.BR setgroups (2)
-being allowed.
-.P
-The default value of this file in the initial user namespace is
-.RI \[dq] allow \[dq].
-.P
-Once
-.IR /proc/ pid /gid_map
-has been written to
-(which has the effect of enabling
-.BR setgroups (2)
-in the user namespace),
-it is no longer possible to disallow
-.BR setgroups (2)
-by writing
-.RI \[dq] deny \[dq]
-to
-.IR /proc/ pid /setgroups
-(the write fails with the error
-.BR EPERM ).
-.P
-A child user namespace inherits the
-.IR /proc/ pid /setgroups
-setting from its parent.
-.P
-If the
-.I setgroups
-file has the value
-.RI \[dq] deny \[dq],
-then the
-.BR setgroups (2)
-system call can't subsequently be reenabled (by writing
-.RI \[dq] allow \[dq]
-to the file) in this user namespace.
-(Attempts to do so fail with the error
-.BR EPERM .)
-This restriction also propagates down to all child user namespaces of
-this user namespace.
-.P
-The
-.IR /proc/ pid /setgroups
-file was added in Linux 3.19,
-but was backported to many earlier stable kernel series,
-because it addresses a security issue.
-The issue concerned files with permissions such as "rwx\-\-\-rwx".
-Such files give fewer permissions to "group" than they do to "other".
-This means that dropping groups using
-.BR setgroups (2)
-might allow a process file access that it did not formerly have.
-Before the existence of user namespaces this was not a concern,
-since only a privileged process (one with the
-.B CAP_SETGID
-capability) could call
-.BR setgroups (2).
-However, with the introduction of user namespaces,
-it became possible for an unprivileged process to create
-a new namespace in which the user had all privileges.
-This then allowed formerly unprivileged
-users to drop groups and thus gain file access
-that they did not previously have.
-The
-.IR /proc/ pid /setgroups
-file was added to address this security issue,
-by denying any pathway for an unprivileged process to drop groups with
-.BR setgroups (2).
-.\"
-.\" /proc/PID/setgroups
-.\" [allow == setgroups() is allowed, "deny" == setgroups() is disallowed]
-.\" * Can write if have CAP_SYS_ADMIN in NS
-.\" * Must write BEFORE writing to /proc/PID/gid_map
-.\"
-.\" setgroups()
-.\" * Must already have written to gid_map
-.\" * /proc/PID/setgroups must be "allow"
-.\"
-.\" /proc/PID/gid_map -- writing
-.\" * Must already have written "deny" to /proc/PID/setgroups
-.\"
-.\" ============================================================
-.\"
-.SS Unmapped user and group IDs
-There are various places where an unmapped user ID (group ID)
-may be exposed to user space.
-For example, the first process in a new user namespace may call
-.BR getuid (2)
-before a user ID mapping has been defined for the namespace.
-In most such cases, an unmapped user ID is converted
-.\" from_kuid_munged(), from_kgid_munged()
-to the overflow user ID (group ID);
-the default value for the overflow user ID (group ID) is 65534.
-See the descriptions of
-.I /proc/sys/kernel/overflowuid
-and
-.I /proc/sys/kernel/overflowgid
-in
-.BR proc (5).
-.P
-The cases where unmapped IDs are mapped in this fashion include
-system calls that return user IDs
-.RB ( getuid (2),
-.BR getgid (2),
-and similar),
-credentials passed over a UNIX domain socket,
-.\" also SO_PEERCRED
-credentials returned by
-.BR stat (2),
-.BR waitid (2),
-and the System V IPC "ctl"
-.B IPC_STAT
-operations,
-credentials exposed by
-.IR /proc/ pid /status
-and the files in
-.IR /proc/sysvipc/* ,
-credentials returned via the
-.I si_uid
-field in the
-.I siginfo_t
-received with a signal (see
-.BR sigaction (2)),
-credentials written to the process accounting file (see
-.BR acct (5)),
-and credentials returned with POSIX message queue notifications (see
-.BR mq_notify (3)).
-.P
-There is one notable case where unmapped user and group IDs are
-.I not
-.\" from_kuid(), from_kgid()
-.\" Also F_GETOWNER_UIDS is an exception
-converted to the corresponding overflow ID value.
-When viewing a
-.I uid_map
-or
-.I gid_map
-file in which there is no mapping for the second field,
-that field is displayed as 4294967295 (\-1 as an unsigned integer).
-.\"
-.\" ============================================================
-.\"
-.SS Accessing files
-In order to determine permissions when an unprivileged process accesses a file,
-the process credentials (UID, GID) and the file credentials
-are in effect mapped back to what they would be in
-the initial user namespace and then compared to determine
-the permissions that the process has on the file.
-The same is also true of other objects that employ the credentials plus
-permissions mask accessibility model, such as System V IPC objects.
-.\"
-.\" ============================================================
-.\"
-.SS Operation of file-related capabilities
-Certain capabilities allow a process to bypass various
-kernel-enforced restrictions when performing operations on
-files owned by other users or groups.
-These capabilities are:
-.BR CAP_CHOWN ,
-.BR CAP_DAC_OVERRIDE ,
-.BR CAP_DAC_READ_SEARCH ,
-.BR CAP_FOWNER ,
-and
-.BR CAP_FSETID .
-.P
-Within a user namespace,
-these capabilities allow a process to bypass the rules
-if the process has the relevant capability over the file,
-meaning that:
-.IP \[bu] 3
-the process has the relevant effective capability in its user namespace; and
-.IP \[bu]
-the file's user ID and group ID both have valid mappings
-in the user namespace.
-.P
-The
-.B CAP_FOWNER
-capability is treated somewhat exceptionally:
-.\" These are the checks performed by the kernel function
-.\" inode_owner_or_capable(). There is one exception to the exception:
-.\" overriding the directory sticky permission bit requires that
-.\" the file has a valid mapping for both its UID and GID.
-it allows a process to bypass the corresponding rules so long as
-at least the file's user ID has a mapping in the user namespace
-(i.e., the file's group ID does not need to have a valid mapping).
-.\"
-.\" ============================================================
-.\"
-.SS Set-user-ID and set-group-ID programs
-When a process inside a user namespace executes
-a set-user-ID (set-group-ID) program,
-the process's effective user (group) ID inside the namespace is changed
-to whatever value is mapped for the user (group) ID of the file.
-However, if either the user
-.I or
-the group ID of the file has no mapping inside the namespace,
-the set-user-ID (set-group-ID) bit is silently ignored:
-the new program is executed,
-but the process's effective user (group) ID is left unchanged.
-(This mirrors the semantics of executing a set-user-ID or set-group-ID
-program that resides on a filesystem that was mounted with the
-.B MS_NOSUID
-flag, as described in
-.BR mount (2).)
-.\"
-.\" ============================================================
-.\"
-.SS Miscellaneous
-When a process's user and group IDs are passed over a UNIX domain socket
-to a process in a different user namespace (see the description of
-.B SCM_CREDENTIALS
-in
-.BR unix (7)),
-they are translated into the corresponding values as per the
-receiving process's user and group ID mappings.
-.\"
-.SH STANDARDS
-Linux.
-.\"
-.SH NOTES
-Over the years, there have been a lot of features that have been added
-to the Linux kernel that have been made available only to privileged users
-because of their potential to confuse set-user-ID-root applications.
-In general, it becomes safe to allow the root user in a user namespace to
-use those features because it is impossible, while in a user namespace,
-to gain more privilege than the root user of a user namespace has.
-.\"
-.\" ============================================================
-.\"
-.SS Global root
-The term "global root" is sometimes used as a shorthand for
-user ID 0 in the initial user namespace.
-.\"
-.\" ============================================================
-.\"
-.SS Availability
-Use of user namespaces requires a kernel that is configured with the
-.B CONFIG_USER_NS
-option.
-User namespaces require support in a range of subsystems across
-the kernel.
-When an unsupported subsystem is configured into the kernel,
-it is not possible to configure user namespaces support.
-.P
-As at Linux 3.8, most relevant subsystems supported user namespaces,
-but a number of filesystems did not have the infrastructure needed
-to map user and group IDs between user namespaces.
-Linux 3.9 added the required infrastructure support for many of
-the remaining unsupported filesystems
-(Plan 9 (9P), Andrew File System (AFS), Ceph, CIFS, CODA, NFS, and OCFS2).
-Linux 3.12 added support for the last of the unsupported major filesystems,
-.\" commit d6970d4b726cea6d7a9bc4120814f95c09571fc3
-XFS.
-.\"
-.SH EXAMPLES
-The program below is designed to allow experimenting with
-user namespaces, as well as other types of namespaces.
-It creates namespaces as specified by command-line options and then executes
-a command inside those namespaces.
-The comments and
-.IR usage ()
-function inside the program provide a full explanation of the program.
-The following shell session demonstrates its use.
-.P
-First, we look at the run-time environment:
-.P
-.in +4n
-.EX
-$ \fBuname \-rs\fP # Need Linux 3.8 or later
-Linux 3.8.0
-$ \fBid \-u\fP # Running as unprivileged user
-1000
-$ \fBid \-g\fP
-1000
-.EE
-.in
-.P
-Now start a new shell in new user
-.RI ( \-U ),
-mount
-.RI ( \-m ),
-and PID
-.RI ( \-p )
-namespaces, with user ID
-.RI ( \-M )
-and group ID
-.RI ( \-G )
-1000 mapped to 0 inside the user namespace:
-.P
-.in +4n
-.EX
-$ \fB./userns_child_exec \-p \-m \-U \-M \[aq]0 1000 1\[aq] \-G \[aq]0 1000 1\[aq] bash\fP
-.EE
-.in
-.P
-The shell has PID 1, because it is the first process in the new
-PID namespace:
-.P
-.in +4n
-.EX
-bash$ \fBecho $$\fP
-1
-.EE
-.in
-.P
-Mounting a new
-.I /proc
-filesystem and listing all of the processes visible
-in the new PID namespace shows that the shell can't see
-any processes outside the PID namespace:
-.P
-.in +4n
-.EX
-bash$ \fBmount \-t proc proc /proc\fP
-bash$ \fBps ax\fP
- PID TTY STAT TIME COMMAND
- 1 pts/3 S 0:00 bash
- 22 pts/3 R+ 0:00 ps ax
-.EE
-.in
-.P
-Inside the user namespace, the shell has user and group ID 0,
-and a full set of permitted and effective capabilities:
-.P
-.in +4n
-.EX
-bash$ \fBcat /proc/$$/status | egrep \[aq]\[ha][UG]id\[aq]\fP
-Uid: 0 0 0 0
-Gid: 0 0 0 0
-bash$ \fBcat /proc/$$/status | egrep \[aq]\[ha]Cap(Prm|Inh|Eff)\[aq]\fP
-CapInh: 0000000000000000
-CapPrm: 0000001fffffffff
-CapEff: 0000001fffffffff
-.EE
-.in
-.SS Program source
-\&
-.EX
-/* userns_child_exec.c
-\&
- Licensed under GNU General Public License v2 or later
-\&
- Create a child process that executes a shell command in new
- namespace(s); allow UID and GID mappings to be specified when
- creating a user namespace.
-*/
-#define _GNU_SOURCE
-#include <err.h>
-#include <sched.h>
-#include <unistd.h>
-#include <stdint.h>
-#include <stdlib.h>
-#include <sys/wait.h>
-#include <signal.h>
-#include <fcntl.h>
-#include <stdio.h>
-#include <string.h>
-#include <limits.h>
-#include <errno.h>
-\&
-struct child_args {
- char **argv; /* Command to be executed by child, with args */
- int pipe_fd[2]; /* Pipe used to synchronize parent and child */
-};
-\&
-static int verbose;
-\&
-static void
-usage(char *pname)
-{
- fprintf(stderr, "Usage: %s [options] cmd [arg...]\en\en", pname);
- fprintf(stderr, "Create a child process that executes a shell "
- "command in a new user namespace,\en"
- "and possibly also other new namespace(s).\en\en");
- fprintf(stderr, "Options can be:\en\en");
-#define fpe(str) fprintf(stderr, " %s", str);
- fpe("\-i New IPC namespace\en");
- fpe("\-m New mount namespace\en");
- fpe("\-n New network namespace\en");
- fpe("\-p New PID namespace\en");
- fpe("\-u New UTS namespace\en");
- fpe("\-U New user namespace\en");
- fpe("\-M uid_map Specify UID map for user namespace\en");
- fpe("\-G gid_map Specify GID map for user namespace\en");
- fpe("\-z Map user\[aq]s UID and GID to 0 in user namespace\en");
- fpe(" (equivalent to: \-M \[aq]0 <uid> 1\[aq] \-G \[aq]0 <gid> 1\[aq])\en");
- fpe("\-v Display verbose messages\en");
- fpe("\en");
- fpe("If \-z, \-M, or \-G is specified, \-U is required.\en");
- fpe("It is not permitted to specify both \-z and either \-M or \-G.\en");
- fpe("\en");
- fpe("Map strings for \-M and \-G consist of records of the form:\en");
- fpe("\en");
- fpe(" ID\-inside\-ns ID\-outside\-ns len\en");
- fpe("\en");
- fpe("A map string can contain multiple records, separated"
- " by commas;\en");
- fpe("the commas are replaced by newlines before writing"
- " to map files.\en");
-\&
- exit(EXIT_FAILURE);
-}
-\&
-/* Update the mapping file \[aq]map_file\[aq], with the value provided in
- \[aq]mapping\[aq], a string that defines a UID or GID mapping. A UID or
- GID mapping consists of one or more newline\-delimited records
- of the form:
-\&
- ID_inside\-ns ID\-outside\-ns length
-\&
- Requiring the user to supply a string that contains newlines is
- of course inconvenient for command\-line use. Thus, we permit the
- use of commas to delimit records in this string, and replace them
- with newlines before writing the string to the file. */
-\&
-static void
-update_map(char *mapping, char *map_file)
-{
- int fd;
- size_t map_len; /* Length of \[aq]mapping\[aq] */
-\&
- /* Replace commas in mapping string with newlines. */
-\&
- map_len = strlen(mapping);
- for (size_t j = 0; j < map_len; j++)
- if (mapping[j] == \[aq],\[aq])
- mapping[j] = \[aq]\en\[aq];
-\&
- fd = open(map_file, O_RDWR);
- if (fd == \-1) {
- fprintf(stderr, "ERROR: open %s: %s\en", map_file,
- strerror(errno));
- exit(EXIT_FAILURE);
- }
-\&
- if (write(fd, mapping, map_len) != map_len) {
- fprintf(stderr, "ERROR: write %s: %s\en", map_file,
- strerror(errno));
- exit(EXIT_FAILURE);
- }
-\&
- close(fd);
-}
-\&
-/* Linux 3.19 made a change in the handling of setgroups(2) and
- the \[aq]gid_map\[aq] file to address a security issue. The issue
- allowed *unprivileged* users to employ user namespaces in
- order to drop groups. The upshot of the 3.19 changes is that
- in order to update the \[aq]gid_maps\[aq] file, use of the setgroups()
- system call in this user namespace must first be disabled by
- writing "deny" to one of the /proc/PID/setgroups files for
- this namespace. That is the purpose of the following function. */
-\&
-static void
-proc_setgroups_write(pid_t child_pid, char *str)
-{
- char setgroups_path[PATH_MAX];
- int fd;
-\&
- snprintf(setgroups_path, PATH_MAX, "/proc/%jd/setgroups",
- (intmax_t) child_pid);
-\&
- fd = open(setgroups_path, O_RDWR);
- if (fd == \-1) {
-\&
- /* We may be on a system that doesn\[aq]t support
- /proc/PID/setgroups. In that case, the file won\[aq]t exist,
- and the system won\[aq]t impose the restrictions that Linux 3.19
- added. That\[aq]s fine: we don\[aq]t need to do anything in order
- to permit \[aq]gid_map\[aq] to be updated.
-\&
- However, if the error from open() was something other than
- the ENOENT error that is expected for that case, let the
- user know. */
-\&
- if (errno != ENOENT)
- fprintf(stderr, "ERROR: open %s: %s\en", setgroups_path,
- strerror(errno));
- return;
- }
-\&
- if (write(fd, str, strlen(str)) == \-1)
- fprintf(stderr, "ERROR: write %s: %s\en", setgroups_path,
- strerror(errno));
-\&
- close(fd);
-}
-\&
-static int /* Start function for cloned child */
-childFunc(void *arg)
-{
- struct child_args *args = arg;
- char ch;
-\&
- /* Wait until the parent has updated the UID and GID mappings.
- See the comment in main(). We wait for end of file on a
- pipe that will be closed by the parent process once it has
- updated the mappings. */
-\&
- close(args\->pipe_fd[1]); /* Close our descriptor for the write
- end of the pipe so that we see EOF
- when parent closes its descriptor. */
- if (read(args\->pipe_fd[0], &ch, 1) != 0) {
- fprintf(stderr,
- "Failure in child: read from pipe returned != 0\en");
- exit(EXIT_FAILURE);
- }
-\&
- close(args\->pipe_fd[0]);
-\&
- /* Execute a shell command. */
-\&
- printf("About to exec %s\en", args\->argv[0]);
- execvp(args\->argv[0], args\->argv);
- err(EXIT_FAILURE, "execvp");
-}
-\&
-#define STACK_SIZE (1024 * 1024)
-\&
-static char child_stack[STACK_SIZE]; /* Space for child\[aq]s stack */
-\&
-int
-main(int argc, char *argv[])
-{
- int flags, opt, map_zero;
- pid_t child_pid;
- struct child_args args;
- char *uid_map, *gid_map;
- const int MAP_BUF_SIZE = 100;
- char map_buf[MAP_BUF_SIZE];
- char map_path[PATH_MAX];
-\&
- /* Parse command\-line options. The initial \[aq]+\[aq] character in
- the final getopt() argument prevents GNU\-style permutation
- of command\-line options. That\[aq]s useful, since sometimes
- the \[aq]command\[aq] to be executed by this program itself
- has command\-line options. We don\[aq]t want getopt() to treat
- those as options to this program. */
-\&
- flags = 0;
- verbose = 0;
- gid_map = NULL;
- uid_map = NULL;
- map_zero = 0;
- while ((opt = getopt(argc, argv, "+imnpuUM:G:zv")) != \-1) {
- switch (opt) {
- case \[aq]i\[aq]: flags |= CLONE_NEWIPC; break;
- case \[aq]m\[aq]: flags |= CLONE_NEWNS; break;
- case \[aq]n\[aq]: flags |= CLONE_NEWNET; break;
- case \[aq]p\[aq]: flags |= CLONE_NEWPID; break;
- case \[aq]u\[aq]: flags |= CLONE_NEWUTS; break;
- case \[aq]v\[aq]: verbose = 1; break;
- case \[aq]z\[aq]: map_zero = 1; break;
- case \[aq]M\[aq]: uid_map = optarg; break;
- case \[aq]G\[aq]: gid_map = optarg; break;
- case \[aq]U\[aq]: flags |= CLONE_NEWUSER; break;
- default: usage(argv[0]);
- }
- }
-\&
- /* \-M or \-G without \-U is nonsensical */
-\&
- if (((uid_map != NULL || gid_map != NULL || map_zero) &&
- !(flags & CLONE_NEWUSER)) ||
- (map_zero && (uid_map != NULL || gid_map != NULL)))
- usage(argv[0]);
-\&
- args.argv = &argv[optind];
-\&
- /* We use a pipe to synchronize the parent and child, in order to
- ensure that the parent sets the UID and GID maps before the child
- calls execve(). This ensures that the child maintains its
- capabilities during the execve() in the common case where we
- want to map the child\[aq]s effective user ID to 0 in the new user
- namespace. Without this synchronization, the child would lose
- its capabilities if it performed an execve() with nonzero
- user IDs (see the capabilities(7) man page for details of the
- transformation of a process\[aq]s capabilities during execve()). */
-\&
- if (pipe(args.pipe_fd) == \-1)
- err(EXIT_FAILURE, "pipe");
-\&
- /* Create the child in new namespace(s). */
-\&
- child_pid = clone(childFunc, child_stack + STACK_SIZE,
- flags | SIGCHLD, &args);
- if (child_pid == \-1)
- err(EXIT_FAILURE, "clone");
-\&
- /* Parent falls through to here. */
-\&
- if (verbose)
- printf("%s: PID of child created by clone() is %jd\en",
- argv[0], (intmax_t) child_pid);
-\&
- /* Update the UID and GID maps in the child. */
-\&
- if (uid_map != NULL || map_zero) {
- snprintf(map_path, PATH_MAX, "/proc/%jd/uid_map",
- (intmax_t) child_pid);
- if (map_zero) {
- snprintf(map_buf, MAP_BUF_SIZE, "0 %jd 1",
- (intmax_t) getuid());
- uid_map = map_buf;
- }
- update_map(uid_map, map_path);
- }
-\&
- if (gid_map != NULL || map_zero) {
- proc_setgroups_write(child_pid, "deny");
-\&
- snprintf(map_path, PATH_MAX, "/proc/%jd/gid_map",
- (intmax_t) child_pid);
- if (map_zero) {
- snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1",
- (intmax_t) getgid());
- gid_map = map_buf;
- }
- update_map(gid_map, map_path);
- }
-\&
- /* Close the write end of the pipe, to signal to the child that we
- have updated the UID and GID maps. */
-\&
- close(args.pipe_fd[1]);
-\&
- if (waitpid(child_pid, NULL, 0) == \-1) /* Wait for child */
- err(EXIT_FAILURE, "waitpid");
-\&
- if (verbose)
- printf("%s: terminating\en", argv[0]);
-\&
- exit(EXIT_SUCCESS);
-}
-.EE
-.SH SEE ALSO
-.BR newgidmap (1), \" From the shadow package
-.BR newuidmap (1), \" From the shadow package
-.BR clone (2),
-.BR ptrace (2),
-.BR setns (2),
-.BR unshare (2),
-.BR proc (5),
-.BR subgid (5), \" From the shadow package
-.BR subuid (5), \" From the shadow package
-.BR capabilities (7),
-.BR cgroup_namespaces (7),
-.BR credentials (7),
-.BR namespaces (7),
-.BR pid_namespaces (7)
-.P
-The kernel source file
-.IR Documentation/admin\-guide/namespaces/resource\-control.rst .