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>
author: Michael Kerrisk <mtk.manpages@gmail.com> 2015-03-04 10:46:14 +0100
committer: Michael Kerrisk <mtk.manpages@gmail.com> 2015-03-04 15:11:02 +0100
commit: ab28dba9a0642c5446ada99bddefef5b16ad0ce1 (patch)
tree: d5022f2a8e9c50f347752bf108136912386dca78
parent: 4e2683f9a383e90807d99d461dcbe4aef88a9a9c (diff)
download: man-pages-ab28dba9a0642c5446ada99bddefef5b16ad0ce1.tar.gz
2 files changed, 94 insertions, 88 deletions
diff --git a/man5/proc.5 b/man5/proc.5
index 4ab196fa87..6969e3e74f 100644
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -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.
diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7
index bcb9d7252f..c4ff5d3515 100644
--- a/man7/user_namespaces.7
+++ b/man7/user_namespaces.7
@@ -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)
author	Michael Kerrisk <mtk.manpages@gmail.com>	2015-03-04 10:46:14 +0100
committer	Michael Kerrisk <mtk.manpages@gmail.com>	2015-03-04 15:11:02 +0100
commit	ab28dba9a0642c5446ada99bddefef5b16ad0ce1 (patch)
tree	d5022f2a8e9c50f347752bf108136912386dca78
parent	4e2683f9a383e90807d99d461dcbe4aef88a9a9c (diff)
download	man-pages-ab28dba9a0642c5446ada99bddefef5b16ad0ce1.tar.gz