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 2 participants 16 messages Dec 30, 2019 – Dec 31, 2019

Subsystems (3)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

v2 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.

Changes in v2
-------------
Also convert pnfs-block-server.txt, pnfs-scsi-server.txt and fault_injection.txt

Daniel W. S. Almeida (8):
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: nfs: convert pnfs-block-server to ReST
Documentation: nfs: pnfs-scsi-server: convert to ReST
Documentation: nfs: fault_injection: convert to ReST

 Documentation/admin-guide/index.rst           |   1 +
 .../nfs/fault_injection.rst}                  |   5 +-
 Documentation/admin-guide/nfs/index.rst       |  16 +
 .../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 +++++----
 .../nfs/pnfs-block-server.rst}                |  25 +-
 .../nfs/pnfs-scsi-server.rst}                 |   1 +
 Documentation/filesystems/nfs/nfs-rdma.txt    | 274 -----------------
 11 files changed, 475 insertions(+), 418 deletions(-)
 rename Documentation/{filesystems/nfs/fault_injection.txt => admin-guide/nfs/fault_injection.rst} (98%)
 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%)
 rename Documentation/{filesystems/nfs/pnfs-block-server.txt => admin-guide/nfs/pnfs-block-server.rst} (80%)
 rename Documentation/{filesystems/nfs/pnfs-scsi-server.txt => admin-guide/nfs/pnfs-scsi-server.rst} (97%)
 delete mode 100644 Documentation/filesystems/nfs/nfs-rdma.txt
Signature · 1 line
2.24.1
#1 lore raw

PATCH v2 1/8 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
maintainer
#2 lore raw

Re: [PATCH v2 1/8] Documentation: convert nfs.txt to ReST

Quoted 11 lines · On Mon, 30 Dec 2019 01:55:55 -0300 "Daniel W. S. Almeida"…

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'.

This generally looks good, I just have one request...

Quoted 65 lines
 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 +8 -4
similarity index 72%
rename from Documentation/filesystems/nfs/nfs.txt
rename to Documentation/admin-guide/nfs/nfs-client.rst
index f2571c8bef74..f01bf6a6c207 100644
@@ -1,3 +1,6 @@
+==========
+NFS Client
+==========
 
 The NFS client
 ==============
@@ -59,10 +62,11 @@ The DNS resolver
 
 NFSv4 allows for one server to refer the NFS client to data that has been
 migrated onto another server by means of the special "fs_locations"
-attribute. See
-	http://tools.ietf.org/html/rfc3530#section-6
-and
-	http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
+attribute. See `RFC3530 Section 6: Filesystem Migration and Replication`_ and
+`Implementation Guide for Referrals in NFSv4`_.
+
+.. _RFC3530 Section 6\: Filesystem Migration and Replication: http://tools.ietf.org/html/rfc3530#section-6
+.. _Implementation Guide for Referrals in NFSv4: http://tools.ietf.org/html/draft-ietf-nfsv4-referrals-00
 
 The fs_locations information can take the form of either an ip address and
 a path, or a DNS hostname and a path. The latter requires the NFS client to

Documentation/admin-guide/nfs/nfs-client.rst upcall to allow userland to provide this service. · line 79

Quoted 5 lines
Documentation/admin-guide/nfs/nfs-client.rst renamed from Documentation/filesystems/nfs/nfs.txt +1 -1
@@ -72,16 +76,16 @@ upcall to allow userland to provide this service.
 Assuming that the user has the 'rpc_pipefs' filesystem mounted in the usual
 /var/lib/nfs/rpc_pipefs, the upcall consists of the following steps:
 
-   (1) The process checks the dns_resolve cache to see if it contains a
+   #.  The process checks the dns_resolve cache to see if it contains a

It really only occurs to me now that we probaby shouldn't use the "#" notation. If we truly need an *enumerated* list, meaning that the numbers are an important part of reading the list, then we should retain the numbers in the plain-text version, even if that means we occasionally have to change them if the list changes. If, instead, the numbers aren't important, we should just use bullets instead.

In this case, we have an explicit sequence of events, so the numbers should probably remain.

Thanks,

jon

#3 lore raw

PATCH v2 2/8 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
maintainer
#4 lore raw

Re: [PATCH v2 2/8] Documentation: nfsroot.txt: convert to ReST

Quoted 6 lines · On Mon, 30 Dec 2019 01:55:56 -0300 "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.

This one, too, is almost there, but ...

Quoted 40 lines
 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 +9 -5
similarity index 83%
rename from Documentation/filesystems/nfs/nfsroot.txt
rename to Documentation/admin-guide/nfs/nfsroot.rst
index ae4332464560..85d834ad3d03 100644
@@ -1,18 +1,24 @@
+===============================================
 Mounting the root filesystem via NFS (nfsroot)
 ===============================================
 
-Written 1996 by Gero Kuhlmann <[email protected]>
-Updated 1997 by Martin Mares <[email protected]>
-Updated 2006 by Nico Schottelius <[email protected]>
-Updated 2006 by Horms <[email protected]>
-Updated 2018 by Chris Novakovic <[email protected]>
+:Authors:
+	Written 1996 by Gero Kuhlmann <[email protected]>
+
+	Updated 1997 by Martin Mares <[email protected]>
+
+	Updated 2006 by Nico Schottelius <[email protected]>
+
+	Updated 2006 by Horms <[email protected]>

Documentation/admin-guide/nfs/nfsroot.rst line 20

Quoted 10 lines
Documentation/admin-guide/nfs/nfsroot.rst renamed from Documentation/filesystems/nfs/nfsroot.txt +3 -2
+
+	Updated 2018 by Chris Novakovic <[email protected]>
 
 
 
 In order to use a diskless system, such as an X-terminal or printer server
 for example, it is necessary for the root filesystem to be present on a
-non-disk device. This may be an initramfs (see Documentation/filesystems/
-ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/admin-guide/initrd.rst) or a
+non-disk device. This may be an initramfs (see Documentation/filesystems/ramfs-rootfs-initramfs.txt`),

It's best in general to avoid refilling paragraphs so as to make it clear what is being changed. But we would also like to avoid creating such long lines. Perhaps an add-on patch refilling things would satisfy both criteria here.

Also, there seems to be a stray backtick (`) in there.

Quoted 49 lines
Documentation/admin-guide/nfs/nfsroot.rst renamed from Documentation/filesystems/nfs/nfsroot.txt +7 -8
+a ramdisk (see Documentation/admin-guide/initrd.rst) or a
 filesystem mounted via NFS. The following text describes on how to use NFS
 for the root filesystem. For the rest of this text 'client' means the
 diskless system, and 'server' means the NFS server.
@@ -20,8 +26,8 @@ diskless system, and 'server' means the NFS server.
 
 
 
-1.) Enabling nfsroot capabilities
-    -----------------------------
+Enabling nfsroot capabilities
+=============================
 
 In order to use nfsroot, NFS client support needs to be selected as
 built-in during configuration. Once this has been selected, the nfsroot
@@ -34,8 +40,8 @@ DHCP, BOOTP and RARP is safe.
 
 
 
-2.) Kernel command line
-    -------------------
+Kernel command line
+===================
 
 When the kernel has been loaded by a boot loader (see below) it needs to be
 told what root fs device to use. And in the case of nfsroot, where to find
@@ -44,19 +50,17 @@ This can be established using the following kernel command line parameters:
 
 
 root=/dev/nfs
-
   This is necessary to enable the pseudo-NFS-device. Note that it's not a
   real device but just a synonym to tell the kernel to use NFS instead of
   a real device.
 
 
 nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
-
   If the `nfsroot' parameter is NOT given on the command line,
-  the default "/tftpboot/%s" will be used.
+  the default ``"/tftpboot/%s"`` will be used.
 
   <server-ip>	Specifies the IP address of the NFS server.
-		The default address is determined by the `ip' parameter
+		The default address is determined by the ip parameter
 		(see below). This parameter allows the use of different
 		servers for IP autoconfiguration and NFS.
 

Documentation/admin-guide/nfs/nfsroot.rst nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>] · line 76

Quoted 6 lines
Documentation/admin-guide/nfs/nfsroot.rst renamed from Documentation/filesystems/nfs/nfsroot.txt +3 -0
@@ -67,6 +71,9 @@ nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
 
   <nfs-options>	Standard NFS options. All options are separated by commas.
 		The following defaults are used:
+
+		::
+

Please don't use the standalone "::" like that. Just say "used::"

[...]

Quoted 11 lines
Documentation/admin-guide/nfs/nfsroot.rst renamed from Documentation/filesystems/nfs/nfsroot.txt +2 -2
-3.) Boot Loader
-    ----------
+Boot Loader
+===========
 

To get the kernel into memory different approaches can be used. They depend on various facilities being available:

-3.1) Booting from a floppy using syslinux
+#. Booting from a floppy using syslinux

Here, too, I wouldn't use "#". This is essentially an unordered list, so basic bullets should be fine.

Thanks,

jon

#5 lore raw

Re: [PATCH v2 2/8] Documentation: nfsroot.txt: convert to ReST

Hi Jon, thanks for the review.

Would you please rephrase this? My first language isn't English and I am not sure I understood that.

Quoted 4 lines

It's best in general to avoid refilling paragraphs so as to make it clear what is being changed. But we would also like to avoid creating such long lines. Perhaps an add-on patch refilling things would satisfy both criteria here.

maintainer
#6 lore raw

Re: [PATCH v2 2/8] Documentation: nfsroot.txt: convert to ReST

Quoted 7 lines · On Tue, 31 Dec 2019 01:08:11 -0300 "Daniel W. S. Almeida"…

Would you please rephrase this? My first language isn't English and I am not sure I understood that.

Quoted 4 lines

It's best in general to avoid refilling paragraphs so as to make it clear what is being changed. But we would also like to avoid creating such long lines. Perhaps an add-on patch refilling things would satisfy both criteria here.

Changing text in an existing paragraph can
result in line lengths that are inconsistent and ragged, leading to a less pleasant appearance
and the temptation to "refill" the paragraph so that the
lines are all approximately equal in length. The problem with yielding to that temptation is that it messes up
the diff output so that you can no longer easily see the actual text changes that were made.

Thus, when making such changes, it can be better to not refill the paragraphs - as, indeed, you did not. But if the result becomes too difficult to read (as in, it creates lines that are waaaay to long), it can be good to create a second patch that makes only the cosmetic changes without any associated text changes. I was suggesting doing that in this case.

Does that help?

Thanks,

jon

#7 lore raw

Re: [PATCH v2 2/8] Documentation: nfsroot.txt: convert to ReST

Quoted 9 lines

Changing text in an existing paragraph can
result in line lengths that are inconsistent and ragged, leading to a less pleasant appearance
and the temptation to "refill" the paragraph so that the
lines are all approximately equal in length. The problem with yielding to that temptation is that it messes up
the diff output so that you can no longer easily see the actual text changes that were made.

Quoted 8 lines

Thus, when making such changes, it can be better to not refill the paragraphs - as, indeed, you did not. But if the result becomes too difficult to read (as in, it creates lines that are waaaay to long), it can be good to create a second patch that makes only the cosmetic changes without any associated text changes. I was suggesting doing that in this case.

Does that help?

Yes, that's better!

Thank you.

#8 lore raw

PATCH v2 3/8 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
maintainer
#9 lore raw

Re: [PATCH v2 3/8] Documentation: nfs-rdma: convert to ReST

Quoted 6 lines · On Mon, 30 Dec 2019 01:55:57 -0300 "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.

With this one, my main concern is that this document looks *way* out of date, to the point that I wonder whether it is still useful or not. It would be good to find somebody who knows about this stuff to figure that out. Consider:

Documentation/admin-guide/nfs/nfs-rdma.rst line 16

Quoted 2 lines
Documentation/admin-guide/nfs/nfs-rdma.rst new file +2 -0
+The NFS/RDMA client was first included in Linux 2.6.24. The NFS/RDMA server
+was first included in the following release, Linux 2.6.25.

That was a while ago at this point.

Documentation/admin-guide/nfs/nfs-rdma.rst line 27

Quoted 5 lines
Documentation/admin-guide/nfs/nfs-rdma.rst new file +5 -0
+Getting Help
+============
+
+If you get stuck, you can ask questions on the
[email protected] mailing list.

What are the chances that this list still works and has relevant people to it? It might be worth sending a copy of this patch there and seeing what results...

Documentation/admin-guide/nfs/nfs-rdma.rst line 46

Quoted 5 lines

+- Install a Linux distribution and tools

Documentation/admin-guide/nfs/nfs-rdma.rst new file +4 -0
+
+  The first kernel release to contain both the NFS/RDMA client and server was
+  Linux 2.6.25  Therefore, a distribution compatible with this and subsequent
+  Linux kernel release should be installed.

Hmmm..where might I find such a distribution...? :)

Documentation/admin-guide/nfs/nfs-rdma.rst line 51

Quoted 4 lines
Documentation/admin-guide/nfs/nfs-rdma.rst new file +4 -0
+  The procedures described in this document have been tested with
+  distributions from Red Hat's Fedora Project (http://fedora.redhat.com/).
+
+- Install nfs-utils-1.1.2 or greater on the client

I have nfs-utils 2.4.2 here. So probably nobody needs to do this installation at this point.

Quoted 1 line

+ Download the latest package from: http://www.kernel.org/pub/linux/utils/nfs

This directory, amusingly, has nothing after 1.0.7, so this advice is actively wrong.

I could go on, but I think you get the point. At a bare minimum we should put a big warning at the top saying that this document is obsolete. I should create a standard warning, I guess; for now anything that gets the point across should do.

Thanks,

jon

#10 lore raw

PATCH v2 4/8 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
maintainer
#11 lore raw

Re: [PATCH v2 4/8] Documentation: convert nfsd-admin-interfaces to ReST

Quoted 39 lines · On Mon, 30 Dec 2019 01:55:58 -0300 "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 +2 -1
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

Documentation/admin-guide/nfs/nfsd-admin-interfaces.rst nfsd/threads. · line 20

Quoted 10 lines
Documentation/admin-guide/nfs/nfsd-admin-interfaces.rst renamed from Documentation/filesystems/nfs/nfsd-admin-interfaces.txt +4 -4
 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".

So here we actually had bullets, I think it would be best to leave them that way.

Let's focus on getting the series up to this point ready, then we can look at the later patches.

Thanks,

jon

#12 lore raw

PATCH v2 5/8 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
#13 lore raw

PATCH v2 6/8 Documentation: nfs: convert pnfs-block-server to ReST

In reply to Daniel W. S. Almeida

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

Convert pnfs-block-server.txt to ReST and move it to admin-guide. Content remains mostly unchanged.

---
 Documentation/admin-guide/nfs/index.rst       |  1 +
 .../nfs/pnfs-block-server.rst}                | 25 +++++++++++--------
 2 files changed, 16 insertions(+), 10 deletions(-)
 rename Documentation/{filesystems/nfs/pnfs-block-server.txt => admin-guide/nfs/pnfs-block-server.rst} (80%)
Documentation/admin-guide/nfs/index.rst +1 -0
index c90fd5ebc640..f3bfd0f5a362 100644
@@ -10,4 +10,5 @@ NFS
     nfs-rdma
     nfsd-admin-interfaces
     nfs-idmapper
+    pnfs-block-server
 
Documentation/admin-guide/nfs/pnfs-block-server.rst renamed from Documentation/filesystems/nfs/pnfs-block-server.txt +15 -10
similarity index 80%
rename from Documentation/filesystems/nfs/pnfs-block-server.txt
rename to Documentation/admin-guide/nfs/pnfs-block-server.rst
index 2143673cf154..b00a2e705cc4 100644
@@ -1,4 +1,6 @@
+===================================
 pNFS block layout server user guide
+===================================
 
 The Linux NFS server now supports the pNFS block layout extension.  In this
 case the NFS server acts as Metadata Server (MDS) for pNFS, which in addition
@@ -22,16 +24,19 @@ If the nfsd server needs to fence a non-responding client it calls
 /sbin/nfsd-recall-failed with the first argument set to the IP address of
 the client, and the second argument set to the device node without the /dev
 prefix for the file system to be fenced. Below is an example file that shows
-how to translate the device into a serial number from SCSI EVPD 0x80:
+how to translate the device into a serial number from SCSI EVPD 0x80::
 
-cat > /sbin/nfsd-recall-failed << EOF
-#!/bin/sh
+	cat > /sbin/nfsd-recall-failed << EOF
 
-CLIENT="$1"
-DEV="/dev/$2"
-EVPD=`sg_inq --page=0x80 ${DEV} | \
-	grep "Unit serial number:" | \
-	awk -F ': ' '{print $2}'`
+.. code-block:: sh
 
-echo "fencing client ${CLIENT} serial ${EVPD}" >> /var/log/pnfsd-fence.log
-EOF
+	#!/bin/sh
+
+	CLIENT="$1"
+	DEV="/dev/$2"
+	EVPD=`sg_inq --page=0x80 ${DEV} | \
+		grep "Unit serial number:" | \
+		awk -F ': ' '{print $2}'`
+
+	echo "fencing client ${CLIENT} serial ${EVPD}" >> /var/log/pnfsd-fence.log
+	EOF
Signature · 1 line
2.24.1
#14 lore raw

PATCH v2 7/8 Documentation: nfs: pnfs-scsi-server: convert to ReST

In reply to Daniel W. S. Almeida

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

Convert pnfs-scsi-server to ReST and move it to admin-guide. Content remains mostly unchanged.

---
 Documentation/admin-guide/nfs/index.rst                          | 1 +
 .../nfs/pnfs-scsi-server.rst}                                    | 1 +
 2 files changed, 2 insertions(+)
 rename Documentation/{filesystems/nfs/pnfs-scsi-server.txt => admin-guide/nfs/pnfs-scsi-server.rst} (97%)
Documentation/admin-guide/nfs/index.rst +1 -0
index f3bfd0f5a362..c96e93b61744 100644
@@ -11,4 +11,5 @@ NFS
     nfsd-admin-interfaces
     nfs-idmapper
     pnfs-block-server
+    pnfs-scsi-server
 
Documentation/admin-guide/nfs/pnfs-scsi-server.rst renamed from Documentation/filesystems/nfs/pnfs-scsi-server.txt +1 -0
similarity index 97%
rename from Documentation/filesystems/nfs/pnfs-scsi-server.txt
rename to Documentation/admin-guide/nfs/pnfs-scsi-server.rst
index 5bef7268bd9f..d2f6ee558071 100644
@@ -1,4 +1,5 @@
 
+==================================
 pNFS SCSI layout server user guide
 ==================================
 
Signature · 1 line
2.24.1
#15 lore raw

PATCH v2 8/8 Documentation: nfs: fault_injection: convert to ReST

In reply to Daniel W. S. Almeida

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

Convert fault_injection.txt to ReST and move it to admin-guide.

---
 .../nfs/fault_injection.rst}                                 | 5 +++--
 Documentation/admin-guide/nfs/index.rst                      | 1 +
 2 files changed, 4 insertions(+), 2 deletions(-)
 rename Documentation/{filesystems/nfs/fault_injection.txt => admin-guide/nfs/fault_injection.rst} (98%)
Documentation/admin-guide/nfs/fault_injection.rst renamed from Documentation/filesystems/nfs/fault_injection.txt +3 -2
similarity index 98%
rename from Documentation/filesystems/nfs/fault_injection.txt
rename to Documentation/admin-guide/nfs/fault_injection.rst
index f3a5b0a8ac05..eb029c0c15ce 100644
@@ -1,6 +1,7 @@
+===================
+NFS Fault Injection
+===================
 
-Fault Injection
-===============
 Fault injection is a method for forcing errors that may not normally occur, or
 may be difficult to reproduce.  Forcing these errors in a controlled environment
 can help the developer find and fix bugs before their code is shipped in a
Documentation/admin-guide/nfs/index.rst +1 -0
index c96e93b61744..410b8ccad11b 100644
@@ -12,4 +12,5 @@ NFS
     nfs-idmapper
     pnfs-block-server
     pnfs-scsi-server
+    fault_injection
 
Signature · 1 line
2.24.1