Skip to contentSkip to conversation

Documentation: nfs: Convert a few documents to RST and move them to admin-guide

PATCH Superseded Daniel W. S. Almeida 1 participant 6 messages Dec 26, 2019

Subsystems (3)

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

cover Documentation: nfs: Convert a few documents to RST and move them to admin-guide

From: "Daniel W. S. Almeida" <[email protected]>

This series converts a few docs in Documentation/filesystems/nfs to RST. The docs were also moved into admin-guide because they contain information that might be useful for system administrators

Most changes are related to aesthetics and presentation, i.e. the content itself remains mostly untouched. The use of markup was limited in order not to negatively impact the plain-text reading experience.

Daniel W. S. Almeida (5):
Documentation: convert nfs.txt to ReST
Documentation: nfsroot.txt: convert to ReST
Documentation: nfs-rdma: convert to ReST
Documentation: convert nfsd-admin-interfaces to ReST
Documentation: nfs: idmapper: convert to ReST

 Documentation/admin-guide/index.rst           |   1 +
 Documentation/admin-guide/nfs/index.rst       |  13 +
 .../nfs/nfs-client.rst}                       |  91 +++---
 .../nfs/nfs-idmapper.rst}                     |  31 +-
 Documentation/admin-guide/nfs/nfs-rdma.rst    | 290 ++++++++++++++++++
 .../nfs/nfsd-admin-interfaces.rst}            |  19 +-
 .../nfs/nfsroot.rst}                          | 140 +++++----
 Documentation/filesystems/nfs/nfs-rdma.txt    | 274 -----------------
 8 files changed, 453 insertions(+), 406 deletions(-)
 create mode 100644 Documentation/admin-guide/nfs/index.rst
 rename Documentation/{filesystems/nfs/nfs.txt => admin-guide/nfs/nfs-client.rst} (72%)
 rename Documentation/{filesystems/nfs/idmapper.txt => admin-guide/nfs/nfs-idmapper.rst} (81%)
 create mode 100644 Documentation/admin-guide/nfs/nfs-rdma.rst
 rename Documentation/{filesystems/nfs/nfsd-admin-interfaces.txt => admin-guide/nfs/nfsd-admin-interfaces.rst} (70%)
 rename Documentation/{filesystems/nfs/nfsroot.txt => admin-guide/nfs/nfsroot.rst} (83%)
 delete mode 100644 Documentation/filesystems/nfs/nfs-rdma.txt
Signature · 1 line
2.24.1
#1 lore raw

PATCH 1/5 Documentation: convert nfs.txt to ReST

From: "Daniel W. S. Almeida" <[email protected]>

This patch converts nfs.txt to RST. It also moves it to admin-guide. The reason for moving it is because this document contains information useful for system administrators, as noted on the following paragraph:

'The purpose of this document is to provide information on some of the special features of the NFS client that can be configured by system administrators'.

---
 Documentation/admin-guide/index.rst           |  1 +
 Documentation/admin-guide/nfs/index.rst       |  9 ++
 .../nfs/nfs-client.rst}                       | 91 ++++++++++---------
 3 files changed, 58 insertions(+), 43 deletions(-)
 create mode 100644 Documentation/admin-guide/nfs/index.rst
 rename Documentation/{filesystems/nfs/nfs.txt => admin-guide/nfs/nfs-client.rst} (72%)
Documentation/admin-guide/index.rst +1 -0
index 4405b7485312..4433f3929481 100644
@@ -76,6 +76,7 @@ configure specific aspects of kernel behavior to your liking.
    device-mapper/index
    efi-stub
    ext4
+   nfs/index
    gpio/index
    highuid
    hw_random
Documentation/admin-guide/nfs/index.rst new file +9 -0
new file mode 100644
index 000000000000..f5c0180f4e5e
@@ -0,0 +1,9 @@
+=============
+NFS
+=============
+
+.. toctree::
+    :maxdepth: 1
+
+    nfs-client
+
Documentation/admin-guide/nfs/nfs-client.rst renamed from Documentation/filesystems/nfs/nfs.txt +48 -43

120 lines not on this page · raw message

Signature · 1 line
2.24.1
#2 lore raw

PATCH 2/5 Documentation: nfsroot.txt: convert to ReST

In reply to Daniel W. S. Almeida

From: "Daniel W. S. Almeida" <[email protected]>

Convert nfsroot.txt to RST and move it to admin-guide. Content remains mostly the same.

---
 Documentation/admin-guide/nfs/index.rst       |   1 +
 .../nfs/nfsroot.rst}                          | 140 ++++++++++--------
 2 files changed, 76 insertions(+), 65 deletions(-)
 rename Documentation/{filesystems/nfs/nfsroot.txt => admin-guide/nfs/nfsroot.rst} (83%)
Documentation/admin-guide/nfs/index.rst +1 -0
index f5c0180f4e5e..c2b87e9f0fed 100644
@@ -6,4 +6,5 @@ NFS
     :maxdepth: 1
 
     nfs-client
+    nfsroot
 
Documentation/admin-guide/nfs/nfsroot.rst renamed from Documentation/filesystems/nfs/nfsroot.txt +75 -65

316 lines not on this page · raw message

Signature · 1 line
2.24.1
#3 lore raw

PATCH 3/5 Documentation: nfs-rdma: convert to ReST

In reply to Daniel W. S. Almeida

From: "Daniel W. S. Almeida" <[email protected]>

Convert nfs-rdma to ReST and move it to admin-guide. Content remais mostly untouched.

---
 Documentation/admin-guide/nfs/index.rst    |   1 +
 Documentation/admin-guide/nfs/nfs-rdma.rst | 290 +++++++++++++++++++++
 Documentation/filesystems/nfs/nfs-rdma.txt | 274 -------------------
 3 files changed, 291 insertions(+), 274 deletions(-)
 create mode 100644 Documentation/admin-guide/nfs/nfs-rdma.rst
 delete mode 100644 Documentation/filesystems/nfs/nfs-rdma.txt
Documentation/admin-guide/nfs/index.rst +1 -0
index c2b87e9f0fed..498652a8b955 100644
@@ -7,4 +7,5 @@ NFS
 
     nfs-client
     nfsroot
+    nfs-rdma
 
Documentation/admin-guide/nfs/nfs-rdma.rst new file +290 -0

290 lines not on this page · raw message

Documentation/filesystems/nfs/nfs-rdma.txt deleted +0 -274

274 lines not on this page · raw message

Signature · 1 line
2.24.1
#4 lore raw

PATCH 4/5 Documentation: convert nfsd-admin-interfaces to ReST

In reply to Daniel W. S. Almeida

From: "Daniel W. S. Almeida" <[email protected]>

Convert nfsd-admin-interfaces to ReST and move it into admin-guide. Content remains mostly untouched.

---
 Documentation/admin-guide/nfs/index.rst       |  1 +
 .../nfs/nfsd-admin-interfaces.rst}            | 19 +++++++++----------
 2 files changed, 10 insertions(+), 10 deletions(-)
 rename Documentation/{filesystems/nfs/nfsd-admin-interfaces.txt => admin-guide/nfs/nfsd-admin-interfaces.rst} (70%)
Documentation/admin-guide/nfs/index.rst +1 -0
index 498652a8b955..c73ba9c16b77 100644
@@ -8,4 +8,5 @@ NFS
     nfs-client
     nfsroot
     nfs-rdma
+    nfsd-admin-interfaces
 
Documentation/admin-guide/nfs/nfsd-admin-interfaces.rst renamed from Documentation/filesystems/nfs/nfsd-admin-interfaces.txt +9 -10
similarity index 70%
rename from Documentation/filesystems/nfs/nfsd-admin-interfaces.txt
rename to Documentation/admin-guide/nfs/nfsd-admin-interfaces.rst
index 56a96fb08a73..7f8c64ad7632 100644
@@ -1,5 +1,6 @@
+==================================
 Administrative interfaces for nfsd
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+==================================
 
 Note that normally these interfaces are used only by the utilities in
 nfs-utils.
@@ -13,18 +14,16 @@ nfsd/threads.
 Before doing that, NFSD can be told which sockets to listen on by
 writing to nfsd/portlist; that write may be:
 
-	- an ascii-encoded file descriptor, which should refer to a
-	  bound (and listening, for tcp) socket, or
-	- "transportname port", where transportname is currently either
-	  "udp", "tcp", or "rdma".
+	#. an ascii-encoded file descriptor, which should refer to a
+	   bound (and listening, for tcp) socket, or
+	#. "transportname port", where transportname is currently either
+	   "udp", "tcp", or "rdma".
 
 If nfsd is started without doing any of these, then it will create one
 udp and one tcp listener at port 2049 (see nfsd_init_socks).
 
-On startup, nfsd and lockd grace periods start.
-
-nfsd is shut down by a write of 0 to nfsd/threads.  All locks and state
-are thrown away at that point.
+On startup, nfsd and lockd grace periods start. nfsd is shut down by a write of
+0 to nfsd/threads.  All locks and state are thrown away at that point.
 
 Between startup and shutdown, the number of threads may be adjusted up
 or down by additional writes to nfsd/threads or by writes to
@@ -34,7 +33,7 @@ For more detail about files under nfsd/ and what they control, see
 fs/nfsd/nfsctl.c; most of them have detailed comments.
 
 Implementation notes
-^^^^^^^^^^^^^^^^^^^^
+====================
 
 Note that the rpc server requires the caller to serialize addition and
 removal of listening sockets, and startup and shutdown of the server.
Signature · 6 lines
2.24.1

_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
#5 lore raw

PATCH 5/5 Documentation: nfs: idmapper: convert to ReST

In reply to Daniel W. S. Almeida

From: "Daniel W. S. Almeida" <[email protected]>

Convert idmapper.txt to ReST and move it to admin-guide. Content remains mostly unchanged otherwise.

---
 Documentation/admin-guide/nfs/index.rst       |  1 +
 .../nfs/nfs-idmapper.rst}                     | 31 ++++++++++---------
 2 files changed, 18 insertions(+), 14 deletions(-)
 rename Documentation/{filesystems/nfs/idmapper.txt => admin-guide/nfs/nfs-idmapper.rst} (81%)
Documentation/admin-guide/nfs/index.rst +1 -0
index c73ba9c16b77..c90fd5ebc640 100644
@@ -9,4 +9,5 @@ NFS
     nfsroot
     nfs-rdma
     nfsd-admin-interfaces
+    nfs-idmapper
 
Documentation/admin-guide/nfs/nfs-idmapper.rst renamed from Documentation/filesystems/nfs/idmapper.txt +17 -14
similarity index 81%
rename from Documentation/filesystems/nfs/idmapper.txt
rename to Documentation/admin-guide/nfs/nfs-idmapper.rst
index b86831acd583..58b8e63412d5 100644
@@ -1,7 +1,7 @@
+=============
+NFS ID Mapper
+=============
 
-=========
-ID Mapper
-=========
 Id mapper is used by NFS to translate user and group ids into names, and to
 translate user and group names into ids.  Part of this translation involves
 performing an upcall to userspace to request the information.  There are two
@@ -20,22 +20,24 @@ legacy rpc.idmap daemon for the id mapping.  This result will be stored
 in a custom NFS idmap cache.
 
 
-===========
 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:
 
-#OP	TYPE	DESCRIPTION	CALLOUT INFO	PROGRAM ARG1 ARG2 ARG3 ...
-#======	=======	===============	===============	===============================
-create	id_resolver	*	*		/usr/sbin/nfs.idmap %k %d 600
+``#OP	TYPE	DESCRIPTION	CALLOUT INFO	PROGRAM ARG1 ARG2 ARG3 ...``
+``#======	=======	===============	===============	===============================``
+``create	id_resolver	*	*		/usr/sbin/nfs.idmap %k %d 600``
+
 
 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.
 
-id mapper uses for key descriptions:
+id mapper uses for 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
@@ -45,23 +47,24 @@ 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:
 
-#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
+``#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``
+
 
 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.
 
-See <file:Documentation/security/keys/request-key.rst> for more information
+See Documentation/security/keys/request-key.rst for more information
 about the request-key function.
 
 
-=========
 nfs.idmap
 =========
+
 nfs.idmap 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
Signature · 1 line
2.24.1