diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2013-01-14 04:08:20 +0100 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2014-09-13 20:15:57 -0700 |
| commit | b81acb15047fda64470b9e7366cf78cb34353b01 (patch) | |
| tree | b10f65e0997bd0c7dcedabd92d36ca48276cae92 /man7/namespaces.7 | |
| parent | cf8bfe6d2af94138de65eb86023d4d34632d621b (diff) | |
| download | man-pages-b81acb15047fda64470b9e7366cf78cb34353b01.tar.gz | |
proc.5, namespaces.7: Move /proc/[pid]/{gid_map,uid_map} text from proc.5 to namespaces.7
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Diffstat (limited to 'man7/namespaces.7')
| -rw-r--r-- | man7/namespaces.7 | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/man7/namespaces.7 b/man7/namespaces.7 index 483c31c3e2..26ff98226e 100644 --- a/man7/namespaces.7 +++ b/man7/namespaces.7 @@ -281,6 +281,137 @@ but is unprivileged for operations outside the namespace. Starting in Linux 3.8, unprivileged processes can create user namespaces. +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 . +The description here explains the details for +.IR uid_map ; +.IR gid_map +is exactly the same, +but each instance of "user ID" is replaced by "group ID". + +The +.I uid_map +file exposes the mapping of user IDs from the user namespace +of the process +.IR pid +to the user namespace of the process that opened +.IR 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. + +Each line in the file specifies a 1-to-1 mapping of a range of contiguous +between two user namespaces. +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 user namespace. +The third number specifies the length of the mapped range. +In detail, the fields are interpreted as follows: +.IP (1) 4 +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 +.IR pid +are in the same user namespace, as follows: +.RS +.IP a) 3 +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 . +(The "parent user namespace" +is the user namespace of the process that created a user namespace +via a call to +.BR unshare (2) +or +.BR clone (2) +with the +.BR CLONE_NEWUSER +flag.) +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. +.PP +After the creation of a new user namespace, the +.I uid_map +file may be written to exactly once to specify +the mapping of user IDs in the new user namespace. +(An attempt to write more than once to the file fails with the error +.BR EPERM .) + +The lines written to +.IR uid_map +must conform to the following rules: +.IP * 3 +The three fields must be valid numbers, +and the last field must be greater than 0. +.IP * +Lines are terminated by newline characters. +.IP * +There is an (arbitrary) limit on the number of lines in the file. +As at Linux 3.8, the limit is five lines. +.IP * +The range of user IDs specified in each line cannot overlap with the ranges +in any other lines. +In the current implementation (Linux 3.8), this requirement is +satisfied by a simplistic implementation that imposes the further +requirement that +the values in both field 1 and field 2 of successive lines must be +in ascending numerical order. +.PP +Writes that violate the above rules fail with the error +.BR EINVAL . + +In order for a process to write to the +.I /proc/[pid]/uid_map +.RI ( /proc/[pid]/gid_map ) +file, the following requirements must be met: +.IP * 3 +The process must have the +.BR CAP_SETUID +.RB ( CAP_SETGID ) +capability in the user namespace of the process +.IR pid . +.IP * +The process must have the +.BR CAP_SETUID +.RB ( CAP_SETGID ) +capability in the parent user namespace. +.IP * +The process must be in either the user namespace of the process +.I pid +or inside the parent user namespace of the process +.IR pid . + .SS UTS namespaces (CLONE_NEWUTS) UTS namespaces provide isolation of two system identifiers: |