man: add documentation for new setgroups(2) semantics

Add documentation for allow_setgroups, deny_setgroups, the new option format of /etc/sub{uid,gid}, and fix some errors in the groupmod(8) man page that stopped it from building properly on my machine. Signed-off-by: Aleksa Sarai <asarai@suse.de>
shadow-maint · Feb 19, 2018 · 626af91 · 626af91
1 parent b1a1af3
commit 626af91
Show file tree

Hide file tree

Showing 4 changed files with 91 additions and 11 deletions.
diff --git a/man/groupmod.8.xml b/man/groupmod.8.xml
@@ -3,7 +3,7 @@
    Copyright (c) 1991       , Julianne Frances Haugh
    Copyright (c) 2007 - 2011, Nicolas François
    All rights reserved.
-  
+
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -15,7 +15,7 @@
    3. The name of the copyright holders or contributors may not be used to
       endorse or promote products derived from this software without
       specific prior written permission.
-  
+
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
@@ -136,7 +136,7 @@
 	  <option>-n</option>, <option>--new-name</option>&nbsp;<replaceable>NEW_GROUP</replaceable>
 	</term>
 	<listitem>
-	  <para> 
+	  <para>
 	    The name of the group will be changed from <replaceable>GROUP</replaceable>
 	    to <replaceable>NEW_GROUP</replaceable> name.
 	  </para>
@@ -278,16 +278,19 @@
 	    <para>E_GRP_UPDATE: can't update group file</para>
 	  </listitem>
 	</varlistentry>
+	<varlistentry>
 	  <term><replaceable>11</replaceable></term>
 	  <listitem>
 	    <para>E_CLEANUP_SERVICE: can't setup cleanup service</para>
 	  </listitem>
 	</varlistentry>
+	<varlistentry>
 	  <term><replaceable>12</replaceable></term>
 	  <listitem>
 	    <para>E_PAM_USERNAME: can't determine your username for use with pam</para>
 	  </listitem>
 	</varlistentry>
+	<varlistentry>
 	  <term><replaceable>13</replaceable></term>
 	  <listitem>
 	    <para>E_PAM_ERROR: pam returned an error, see syslog facility id groupmod for the PAM error message</para>

diff --git a/man/newgidmap.1.xml b/man/newgidmap.1.xml
@@ -2,7 +2,7 @@
 <!--
    Copyright (c) 2013 Eric W. Biederman
    All rights reserved.
-  
+
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -14,7 +14,7 @@
    3. The name of the copyright holders or contributors may not be used to
       endorse or promote products derived from this software without
       specific prior written permission.
-  
+
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
@@ -122,12 +122,29 @@
       of the above sets, each of the GIDs in the range [lowergid,
       lowergid+count] is allowed to the caller according to
       <filename>/etc/subgid</filename> before setting
+      <filename>/proc/[pid]/setgroups</filename> and
       <filename>/proc/[pid]/gid_map</filename>.
     </para>
+
     <para>
       Note that newgidmap may be used only once for a given process.
     </para>
 
+    <para>
+      <command>newgidmap</command> also allows you to map a user's own
+      effective group ID without it being specified in
+      <filename>/etc/subgid</filename> (in order to match the "unprivileged
+      user namespaces" feature in Linux 3.8). If this is the only mapping
+      requested (in order to match the security protections from Linux 3.19),
+      <command>newgidmap</command> will ensure that
+      <filename>/proc/[pid]/setgroups</filename> is set to "deny" (either by
+      writing "deny" itself or seeing that it is already set to "deny"), and
+      will fail if writing "deny" failed. This restriction is also applied if
+      any of the mappings given to <command>newgidmap</command> has the
+      <option>deny_setgroups</option> option set in
+      <filename>/etc/subgid</filename>.
+    </para>
+
   </refsect1>
 
   <refsect1 id='options'>

diff --git a/man/subgid.5.xml b/man/subgid.5.xml
@@ -2,7 +2,7 @@
 <!--
    Copyright (c) 2013 Eric W. Biederman
    All rights reserved.
-  
+
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -14,7 +14,7 @@
    3. The name of the copyright holders or contributors may not be used to
       endorse or promote products derived from this software without
       specific prior written permission.
-  
+
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
@@ -51,7 +51,7 @@
       a user name and a range of subordinate group ids that user
       is allowed to use.
 
-      This is specified with three fields delimited by colons
+      This is specified with four fields delimited by colons
       (<quote>:</quote>).
       These fields are:
     </para>
@@ -65,6 +65,9 @@
       <listitem>
 	<para>numerical subordinate group ID count</para>
       </listitem>
+      <listitem>
+	<para>comma-separated list of options (optional)</para>
+      </listitem>
     </itemizedlist>
 
     <para>
@@ -86,6 +89,42 @@
 
   </refsect1>
 
+  <refsect1 id='options'>
+    <title>OPTIONS</title>
+
+    <para>
+      Options are comma-separated. Empty options are ignored, and if the
+      field is missing entirely it is treated as an empty string. Attempting
+      to use an unknown option will cause <command>newgidmap</command> to emit
+      an error. Setting options from the same option-set multiple times in a
+      single entry will result in the last option specified taking precedence.
+    </para>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>allow_setgroups</option> (default),
+              <option>deny_setgroups</option></term>
+        <listitem>
+          <para>
+            Specify whether
+            <citerefentry>
+              <refentrytitle>setgroups</refentrytitle><manvolnum>2</manvolnum>
+            </citerefentry>
+            will be disabled by <command>newgidmap</command>. If more than one
+            mapping is given to <command>newgidmap</command>, and they have
+            different <option>*_setgroups</option> options set,
+            <option>deny_setgroups</option> always takes precedence. See
+            <citerefentry>
+              <refentrytitle>newgidmap</refentrytitle><manvolnum>1</manvolnum>
+            </citerefentry>
+            for more details.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1>
+
   <refsect1 id='files'>
     <title>FILES</title>
     <variablelist>

diff --git a/man/subuid.5.xml b/man/subuid.5.xml
@@ -2,7 +2,7 @@
 <!--
    Copyright (c) 2013 Eric W. Biederman
    All rights reserved.
-  
+
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -14,7 +14,7 @@
    3. The name of the copyright holders or contributors may not be used to
       endorse or promote products derived from this software without
       specific prior written permission.
-  
+
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
@@ -51,7 +51,7 @@
       a user name and a range of subordinate user ids that user
       is allowed to use.
 
-      This is specified with three fields delimited by colons
+      This is specified with four fields delimited by colons
       (<quote>:</quote>).
       These fields are:
     </para>
@@ -65,6 +65,9 @@
       <listitem>
 	<para>numerical subordinate user ID count</para>
       </listitem>
+      <listitem>
+	<para>comma-separated list of options (optional)</para>
+      </listitem>
     </itemizedlist>
 
     <para>
@@ -86,6 +89,24 @@
 
   </refsect1>
 
+  <refsect1 id='options'>
+    <title>OPTIONS</title>
+
+    <para>
+      Options are comma-separated. Empty options are ignored, and if the
+      field is missing entirely it is treated as an empty string. Attempting
+      to use an unknown option will cause <command>newuidmap</command> to emit
+      an error. Setting options from the same option-set multiple times in a
+      single entry will result in the last option specified taking precedence.
+    </para>
+
+    <para>
+      At the moment, no options are defined for
+      <filename>/etc/subuid</filename>.
+    </para>
+
+  </refsect1>
+
   <refsect1 id='files'>
     <title>FILES</title>
     <variablelist>