proc.5, user_namespaces.7: Migrate description of /proc/PID/setgroups to user_namespaces(7)

It makes sense to have the description of this file
in the general discussion of user namespaces.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2015-03-04 10:46:14 +01:00
parent 4e2683f9a3
commit ab28dba9a0
2 changed files with 94 additions and 88 deletions

View File

@ -1208,91 +1208,8 @@ are not available if the main thread has already terminated
.\" CONFIG_SCHEDSTATS
.TP
.IR /proc/[pid]/setgroups " (since Linux 3.19)"
.\"
.\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
.\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
.\" http://lwn.net/Articles/626665/
.\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989
.\"
This 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, however, that calls to
.BR setgroups (2)
are also not permitted if
.IR /proc/[pid]/gid_map
has not yet been set.)
A privileged process (one with the
.BR 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).
In other words, it is permitted to write to
.I /proc/[pid]/setgroups
so long as calling
.BR setgroups (2)
is not allowed because
.I /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 only transition from
.BR setgroups (2)
being disallowed to
.BR setgroups (2)
being allowed.
The default value of this file in the initial user namespace is
.RI \(dq allow \(dq.
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 deny
.BR setgroups (2)
by writing to
.IR /proc/[pid]/setgroups .
A child user namespace inherits the
.IR /proc/[pid]/gid_map
setting from its parent.
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.
This restriction also propagates down to all child user namespaces of
this user namespace.
See
.BR user_namespaces (7).
.TP
.IR /proc/[pid]/smaps " (since Linux 2.6.14)"
This file shows memory consumption for each of the process's mappings.

View File

@ -542,9 +542,7 @@ In the case of
.IR gid_map ,
the
.I /proc/[pid]/setgroups
file (see
.BR proc (5))
must have been written to earlier and disabled the
file (see below) must have been written to earlier and disabled the
.BR setgroups (2)
system call.
.IP * 3
@ -609,6 +607,97 @@ capability in the parent user namespace.
.\"
.\" ============================================================
.\"
.SS The /proc/[pid]/setgroups file
.\"
.\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
.\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
.\" http://lwn.net/Articles/626665/
.\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989
.\"
The
.I /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, however, that calls to
.BR setgroups (2)
are also not permitted if
.IR /proc/[pid]/gid_map
has not yet been set.)
A privileged process (one with the
.BR 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).
In other words, it is permitted to write to
.I /proc/[pid]/setgroups
so long as calling
.BR setgroups (2)
is not allowed because
.I /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 only transition from
.BR setgroups (2)
being disallowed to
.BR setgroups (2)
being allowed.
The default value of this file in the initial user namespace is
.RI \(dq allow \(dq.
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 deny
.BR setgroups (2)
by writing to
.IR /proc/[pid]/setgroups .
A child user namespace inherits the
.IR /proc/[pid]/gid_map
setting from its parent.
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.
This restriction also propagates down to all child user namespaces of
this user namespace.
.\"
.\" ============================================================
.\"
.SS Unmapped user and group IDs
.PP
There are various places where an unmapped user ID (group ID)