From d5b15f8633d0eabed885cd16feda224ec2d59072 Mon Sep 17 00:00:00 2001
From: Iker Pedrosa <ipedrosa@redhat.com>
Date: Mon, 24 May 2021 12:14:43 +0200
Subject: [PATCH] man: clarify subid delegation

Clarify that the subid delegation can only come from one source.
Moreover, add an example of what might happen if the subid source is NSS
and useradd is executed.

Related: https://github.com/shadow-maint/shadow/issues/331
---
 man/newgidmap.1.xml | 12 +++++++++---
 man/newuidmap.1.xml | 10 ++++++++--
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/man/newgidmap.1.xml b/man/newgidmap.1.xml
index 76fc1e30..7aaf34bf 100644
--- a/man/newgidmap.1.xml
+++ b/man/newgidmap.1.xml
@@ -88,9 +88,15 @@
     <title>DESCRIPTION</title>
     <para>
       The <command>newgidmap</command> sets <filename>/proc/[pid]/gid_map</filename> based on its
-      command line arguments and the gids allowed (either in <filename>/etc/subgid</filename> or
-      through the configured NSS subid module).
-      Note that the root user is not exempted from the requirement for a valid
+      command line arguments and the gids allowed. The subid delegation can come either from files
+      (<filename>/etc/subgid</filename>) or from the configured NSS subid module. Only one of them
+      can be chosen at a time. So, for example, if the subid source is configured as NSS and
+      <command>groupadd</command> is executed, then the command will fail and the entry will not be
+      created in <filename>/etc/subgid</filename>.
+    </para>
+
+    <para>
+      Note that the root group is not exempted from the requirement for a valid
       <filename>/etc/subgid</filename> entry.
     </para>
 
diff --git a/man/newuidmap.1.xml b/man/newuidmap.1.xml
index 44eca50a..4bc1ef7a 100644
--- a/man/newuidmap.1.xml
+++ b/man/newuidmap.1.xml
@@ -88,8 +88,14 @@
     <title>DESCRIPTION</title>
     <para>
       The <command>newuidmap</command> sets <filename>/proc/[pid]/uid_map</filename> based on its
-      command line arguments and the uids allowed (either in <filename>/etc/subuid</filename> or
-      through the configured NSS subid module).
+      command line arguments and the uids allowed. The subid delegation can come either from files
+      (<filename>/etc/subuid</filename>) or from the configured NSS subid module. Only one of them
+      can be chosen at a time. So, for example, if the subid source is configured as NSS and
+      <command>useradd</command> is executed, then the command will fail and the entry will not be
+      created in <filename>/etc/subuid</filename>.
+    </para>
+
+    <para>
       Note that the root user is not exempted from the requirement for a valid
       <filename>/etc/subuid</filename> entry.
     </para>