[PATCH 0/3] Documentation: update nfs idmapper doc and fix compile issues

[PATCH 0/3] Documentation: update nfs idmapper doc and fix compile issues

[chenxiaosong]

From: ChenXiaoSong <chenxiaosong@kylinos.cn>

Keep usage of `nfsidmap` consistent with nfsidmap manual.

Additionally, fix compile error and warning when running `make htmldocs`.

ChenXiaoSong (3):
  Documentation: nfs: idmapper: keep consistent with nfsidmap manual
  docs: filesystems: fix compile error in netfs_library.rst
  tracing/Documentation: fix compile warning in debugging.rst

 Documentation/admin-guide/nfs/nfs-idmapper.rst | 59 ++++++++++++++++++++++++++++++++---------------------------
 Documentation/filesystems/netfs_library.rst    |  1 -
 Documentation/trace/index.rst                  |  1 +
 3 files changed, 33 insertions(+), 28 deletions(-)

-- 
2.34.1

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

[chenxiaosong]

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

[PATCH 2/3] docs: filesystems: fix compile error in netfs_library.rst

[chenxiaosong]

From: ChenXiaoSong <chenxiaosong@kylinos.cn>

`make htmldocs` reports the following error:

  Error: Cannot open file fs/netfs/io.c

Fix it by removing the unused kernel-doc reference.

Fixes: 86b374d061ee ("netfs: Remove fs/netfs/io.c")
Signed-off-by: ChenXiaoSong <chenxiaosong@kylinos.cn>
---
 Documentation/filesystems/netfs_library.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst
index f0d2cb257bb8..73f0bfd7e903 100644
--- a/Documentation/filesystems/netfs_library.rst
+++ b/Documentation/filesystems/netfs_library.rst
@@ -592,4 +592,3 @@ API Function Reference
 
 .. kernel-doc:: include/linux/netfs.h
 .. kernel-doc:: fs/netfs/buffered_read.c
-.. kernel-doc:: fs/netfs/io.c
-- 
2.34.1

[PATCH 3/3] tracing/Documentation: fix compile warning in debugging.rst

[chenxiaosong]

From: ChenXiaoSong <chenxiaosong@kylinos.cn>

`make htmldocs` reports the following warning:

  Documentation/trace/debugging.rst: WARNING: document isn't included \
    in any toctree

Fix it by adding debugging.rst to toctree.

Signed-off-by: ChenXiaoSong <chenxiaosong@kylinos.cn>
---
 Documentation/trace/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 0b300901fd75..2827292f8f34 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -36,3 +36,4 @@ Linux Tracing Technologies
    user_events
    rv/index
    hisi-ptt
+   debugging
-- 
2.34.1

Re: [PATCH 0/3] Documentation: update nfs idmapper doc and fix compile issues

[Jonathan Corbet]

chenxiaosong@chenxiaosong.com writes:

> From: ChenXiaoSong <chenxiaosong@kylinos.cn>
>
> Keep usage of `nfsidmap` consistent with nfsidmap manual.
>
> Additionally, fix compile error and warning when running `make htmldocs`.

These are logically separate patches and do not need to be grouped
together. Additionally...

> ChenXiaoSong (3):
>   Documentation: nfs: idmapper: keep consistent with nfsidmap manual
>   docs: filesystems: fix compile error in netfs_library.rst
>   tracing/Documentation: fix compile warning in debugging.rst
>
>  Documentation/admin-guide/nfs/nfs-idmapper.rst | 59 ++++++++++++++++++++++++++++++++---------------------------
>  Documentation/filesystems/netfs_library.rst    |  1 -

This is already fixed in linux-next

>  Documentation/trace/index.rst                  |  1 +

...as is this one.

Thanks,

jon