[PATCH 1/3] Documentation: nfs: idmapper: keep consistent with nfsidmap manual

[chenxiaosong@chenxiaosong.com]

From: ChenXiaoSong <chenxiaosong@kylinos.cn>

The usage of `nfsidmap` has been updated(e.g., use `-t 600` set the
expiration timer), keep it consistent with nfsidmap manual (Link[1]).

Link[1]: https://git.kernel.org/pub/scm/linux/kernel/git/rw/nfs-utils.git/tree/utils/nfsidmap/nfsidmap.man
Signed-off-by: ChenXiaoSong <chenxiaosong@kylinos.cn>
---
 Documentation/admin-guide/nfs/nfs-idmapper.rst | 59 ++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 32 insertions(+), 27 deletions(-)

diff --git a/Documentation/admin-guide/nfs/nfs-idmapper.rst b/Documentation/admin-guide/nfs/nfs-idmapper.rst
index 58b8e63412d5..0b72fd3a38af 100644
--- a/Documentation/admin-guide/nfs/nfs-idmapper.rst
+++ b/Documentation/admin-guide/nfs/nfs-idmapper.rst
@@ -24,55 +24,60 @@ Configuring
 ===========
 
 The file /etc/request-key.conf will need to be modified so /sbin/request-key can
-direct the upcall.  The following line should be added:
+properly direct the upcall. The following line should be added before a call to
+keyctl negate:
 
-``#OP	TYPE	DESCRIPTION	CALLOUT INFO	PROGRAM ARG1 ARG2 ARG3 ...``
-``#======	=======	===============	===============	===============================``
-``create	id_resolver	*	*		/usr/sbin/nfs.idmap %k %d 600``
+.. code-block:: none
 
+	#OP	TYPE		DESCRIPTION	CALLOUT INFO	PROGRAM ARG1 ARG2 ARG3 ...
+	#======	===============	===============	===============	===============================
+	create	id_resolver	*		*		/usr/sbin/nfsidmap -t 600 %k %d
 
-This will direct all id_resolver requests to the program /usr/sbin/nfs.idmap.
-The last parameter, 600, defines how many seconds into the future the key will
-expire.  This parameter is optional for /usr/sbin/nfs.idmap.  When the timeout
-is not specified, nfs.idmap will default to 600 seconds.
+This will direct all id_resolver requests to the program /usr/sbin/nfsidmap.
+The -t 600 defines how many seconds into the future the key will expire.
+This is an optional parameter for  /usr/sbin/nfsidmap  and  will default to 600
+seconds when not specified.
 
-id mapper uses for key descriptions::
+The idmapper system uses four key descriptions:
 
-	  uid:  Find the UID for the given user
-	  gid:  Find the GID for the given group
-	 user:  Find the user  name for the given UID
-	group:  Find the group name for the given GID
+.. code-block:: none
 
-You can handle any of these individually, rather than using the generic upcall
-program.  If you would like to use your own program for a uid lookup then you
-would edit your request-key.conf so it look similar to this:
+	  uid: Find the UID for the given user
+	  gid: Find the GID for the given group
+	 user: Find the user name for the given UID
+	group: Find the group name for the given GID
 
-``#OP	TYPE	DESCRIPTION	CALLOUT INFO	PROGRAM ARG1 ARG2 ARG3 ...``
-``#======	=======	===============	===============	===============================``
-``create	id_resolver	uid:*	*		/some/other/program %k %d 600``
-``create	id_resolver	*	*		/usr/sbin/nfs.idmap %k %d 600``
+You can choose to handle any of these individually, rather than using the
+generic upcall program.  If you would like to use your own program for a uid
+lookup then you would edit your request-key.conf so it looks similar to this:
 
+.. code-block:: none
+
+	#OP	TYPE		DESCRIPTION	CALLOUT INFO	PROGRAM ARG1 ARG2 ARG3 ...
+	#======	===============	===============	===============	==========================
+	create	id_resolver	uid:*		*		/some/other/program %k %d
+	create	id_resolver	*		*		/usr/sbin/nfsidmap %k %d
 
 Notice that the new line was added above the line for the generic program.
-request-key will find the first matching line and corresponding program.  In
-this case, /some/other/program will handle all uid lookups and
-/usr/sbin/nfs.idmap will handle gid, user, and group lookups.
+request-key will find the first matching line and run the corresponding program.
+In this case,  /some/other/program  will  handle  all  uid lookups,
+and /usr/sbin/nfsidmap will handle gid, user, and group lookups.
 
 See Documentation/security/keys/request-key.rst for more information
 about the request-key function.
 
 
-nfs.idmap
+nfsidmap
 =========
 
-nfs.idmap is designed to be called by request-key, and should not be run "by
+nfsidmap is designed to be called by request-key, and should not be run "by
 hand".  This program takes two arguments, a serialized key and a key
 description.  The serialized key is first converted into a key_serial_t, and
 then passed as an argument to keyctl_instantiate (both are part of keyutils.h).
 
-The actual lookups are performed by functions found in nfsidmap.h.  nfs.idmap
+The actual lookups are performed by functions found in nfsidmap.h.  nfsidmap
 determines the correct function to call by looking at the first part of the
 description string.  For example, a uid lookup description will appear as
 "uid:user@domain".
 
-nfs.idmap will return 0 if the key was instantiated, and non-zero otherwise.
+nfsidmap will return 0 if the key was instantiated, and non-zero otherwise.
-- 
2.34.1