Merge pull request #353 from ikerexxe/man_subid

man: improve subid documentation

man/newgidmap.1.xml

@@ -87,12 +87,11 @@
   <refsect1 id='description'>
     <title>DESCRIPTION</title>
     <para>
-      The <command>newgidmap</command> sets <filename>/proc/[pid]/gid_map</filename> based on its
+      The <command>newgidmap</command> sets <filename>/proc/[pid]/gid_map</filename>
-      command line arguments and the gids allowed. The subid delegation can come either from files
+      based on its command line arguments and the gids allowed. Subgid
-      (<filename>/etc/subgid</filename>) or from the configured NSS subid module. Only one of them
+      delegation can either be managed via <filename>/etc/subgid</filename>
-      can be chosen at a time. So, for example, if the subid source is configured as NSS and
+      or through the configured NSS subid module. These options are mutually
-      <command>groupadd</command> is executed, then the command will fail and the entry will not be
+      exclusive.
-      created in <filename>/etc/subgid</filename>.
     </para>
 
     <para>

man/newuidmap.1.xml

@@ -87,12 +87,11 @@
   <refsect1 id='description'>
     <title>DESCRIPTION</title>
     <para>
-      The <command>newuidmap</command> sets <filename>/proc/[pid]/uid_map</filename> based on its
+      The <command>newuidmap</command> sets <filename>/proc/[pid]/uid_map</filename>
-      command line arguments and the uids allowed. The subid delegation can come either from files
+      based on its command line arguments and the uids allowed. Subuid
-      (<filename>/etc/subuid</filename>) or from the configured NSS subid module. Only one of them
+      delegation can either be managed via <filename>/etc/subuid</filename> or
-      can be chosen at a time. So, for example, if the subid source is configured as NSS and
+      through the configured NSS subid module. These options are mutually
-      <command>useradd</command> is executed, then the command will fail and the entry will not be
+      exclusive.
-      created in <filename>/etc/subuid</filename>.
     </para>
 
     <para>

man/subgid.5.xml

@@ -38,6 +38,11 @@
       <surname>Biederman</surname>
       <contrib>Creation, 2013</contrib>
     </author>
+    <author>
+      <firstname>Iker</firstname>
+      <surname>Pedrosa</surname>
+      <contrib>Developer, 2021</contrib>
+    </author>
   </refentryinfo>
   <refmeta>
     <refentrytitle>subgid</refentrytitle>
@@ -48,11 +53,36 @@
   </refmeta>
   <refnamediv id='name'>
     <refname>subgid</refname>
-    <refpurpose>the subordinate gid file</refpurpose>
+    <refpurpose>the configuration for subordinate group ids</refpurpose>
   </refnamediv>
 
   <refsect1 id='description'>
     <title>DESCRIPTION</title>
+    <para>
+      Subgid authorizes a group id to map ranges of group ids from its namespace
+      into child namespaces.
+    </para>
+    <para>
+      The delegation of the subordinate gids can be configured via the
+      <replaceable>subid</replaceable> field in
+      <filename>/etc/nsswitch.conf</filename> file. Only one value can be set
+      as the delegation source. Setting this field to
+      <replaceable>files</replaceable> configures the delegation of gids to
+      <filename>/etc/subgid</filename>. Setting any other value treats
+      the delegation as a plugin following with a name of the form
+      <replaceable>libsubid_$value.so</replaceable>. If the value or plugin is
+      missing, then the subordinate gid delegation falls back to
+      <replaceable>files</replaceable>.
+    </para>
+    <para>
+      Note, that <command>groupadd</command> will only create entries in
+      <filename>/etc/subgid</filename> if subid delegation is managed via subid
+      files.
+    </para>
+  </refsect1>
+
+  <refsect1 id='local-subordinate-delegation'>
+    <title>LOCAL SUBORDINATE DELEGATION</title>
     <para>
       Each line in <filename>/etc/subgid</filename> contains
       a user name and a range of subordinate group ids that user

man/subuid.5.xml

@@ -38,6 +38,11 @@
       <surname>Biederman</surname>
       <contrib>Creation, 2013</contrib>
     </author>
+    <author>
+      <firstname>Iker</firstname>
+      <surname>Pedrosa</surname>
+      <contrib>Developer, 2021</contrib>
+    </author>
   </refentryinfo>
   <refmeta>
     <refentrytitle>subuid</refentrytitle>
@@ -48,11 +53,36 @@
   </refmeta>
   <refnamediv id='name'>
     <refname>subuid</refname>
-    <refpurpose>the subordinate uid file</refpurpose>
+    <refpurpose>the configuration for subordinate user ids</refpurpose>
   </refnamediv>
 
   <refsect1 id='description'>
     <title>DESCRIPTION</title>
+    <para>
+      Subuid authorizes a user id to map ranges of user ids from its namespace
+      into child namespaces.
+    </para>
+    <para>
+      The delegation of the subordinate uids can be configured via the
+      <replaceable>subid</replaceable> field in
+      <filename>/etc/nsswitch.conf</filename> file. Only one value can be set
+      as the delegation source. Setting this field to
+      <replaceable>files</replaceable> configures the delegation of uids to
+      <filename>/etc/subuid</filename>. Setting any other value treats
+      the delegation as a plugin following with a name of the form
+      <replaceable>libsubid_$value.so</replaceable>. If the value or plugin is
+      missing, then the subordinate uid delegation falls back to
+      <replaceable>files</replaceable>.
+    </para>
+    <para>
+      Note, that <command>useradd</command> will only create entries in
+      <filename>/etc/subuid</filename> if subid delegation is managed via subid
+      files.
+    </para>
+  </refsect1>
+
+  <refsect1 id='local-subordinate-delegation'>
+    <title>LOCAL SUBORDINATE DELEGATION</title>
     <para>
       Each line in <filename>/etc/subuid</filename> contains
       a user name and a range of subordinate user ids that user