Documentation: nfs: Convert a few documents to RST and move them to admin-guide
Subsystems (3)
v4 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 v4
-------------
Add missing commit [Documentation: convert nfs.txt to ReST]
Fix the following errors:
Applying: Documentation: convert nfs.txt to ReST .git/rebase-apply/patch:35: new blank line at EOF.
+
warning: 1 line adds whitespace errors.
Applying: Documentation: nfsroot.txt: convert to ReST .git/rebase-apply/patch:163: space before tab in indent.
If unspecified the netmask is derived from the client IP address
.git/rebase-apply/patch:170: space before tab in indent.
If a '.' character is present, anything
.git/rebase-apply/patch:193: space before tab in indent.
In the case of options
warning: 3 lines add whitespace errors.
Changes in v3
-------------
Documentation: convert nfs.txt to ReST
- Remove "#." syntax
Documentation: nfsroot.txt: convert to ReST
- Remove stray backtick
- Remove standalone "::"
- Remove "#." syntax
- Refill paragraph in a new commit to remove long lines
Documentation: nfs-rdma: convert to ReST
- Add warning for obsolete content
- CC [email protected]
Documentation: convert nfsd-admin-interfaces to ReST
- Remove "#." syntax
Changes in v2
-------------
Also convert pnfs-block-server.txt, pnfs-scsi-server.txt and fault_injection.txt
Daniel W. S. Almeida (9):
Documentation: convert nfs.txt to ReST
Documentation: nfsroot.txt: convert to ReST
Documentation: nfsroot.rst: COSMETIC: refill a paragraph
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 | 15 +
.../nfs/nfs-client.rst} | 85 ++---
.../nfs/nfs-idmapper.rst} | 31 +-
Documentation/admin-guide/nfs/nfs-rdma.rst | 292 ++++++++++++++++++
.../nfs/nfsd-admin-interfaces.rst} | 19 +-
.../nfs/nfsroot.rst} | 151 ++++-----
.../nfs/pnfs-block-server.rst} | 25 +-
.../nfs/pnfs-scsi-server.rst} | 1 +
Documentation/filesystems/nfs/nfs-rdma.txt | 274 ----------------
11 files changed, 478 insertions(+), 421 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} (75%)
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} (80%)
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.txtSignature · 1 line
2.24.1
PATCH v4 1/9 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 | 8 ++
.../nfs/nfs-client.rst} | 85 ++++++++++---------
3 files changed, 54 insertions(+), 40 deletions(-)
create mode 100644 Documentation/admin-guide/nfs/index.rst
rename Documentation/{filesystems/nfs/nfs.txt => admin-guide/nfs/nfs-client.rst} (75%)Documentation/admin-guide/index.rst +1 -0
@@ -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 +8 -0
@@ -0,0 +1,8 @@ +============= +NFS +============= + +.. toctree:: + :maxdepth: 1 + + nfs-client
Documentation/admin-guide/nfs/nfs-client.rst renamed from Documentation/filesystems/nfs/nfs.txt +45 -40
109 lines not on this page · raw message
Signature · 1 line
2.24.1
PATCH v4 2/9 Documentation: nfsroot.txt: convert to ReST
In reply to Daniel W. S. AlmeidaFrom: "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, 75 insertions(+), 66 deletions(-)
rename Documentation/{filesystems/nfs/nfsroot.txt => admin-guide/nfs/nfsroot.rst} (83%)Documentation/admin-guide/nfs/index.rst +1 -0
@@ -6,3 +6,4 @@ NFS :maxdepth: 1 nfs-client + nfsroot
Documentation/admin-guide/nfs/nfsroot.rst renamed from Documentation/filesystems/nfs/nfsroot.txt +74 -66
316 lines not on this page · raw message
Signature · 1 line
2.24.1
PATCH v4 3/9 Documentation: nfsroot.rst: COSMETIC: refill a paragraph
In reply to Daniel W. S. AlmeidaFrom: "Daniel W. S. Almeida" <[email protected]>
Refill a paragraph to eliminate long lines.
--- Documentation/admin-guide/nfs/nfsroot.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-)
Documentation/admin-guide/nfs/nfsroot.rst +8 -7
@@ -15,13 +15,14 @@ Mounting the root filesystem via NFS (nfsroot) -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 -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. +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 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.
Signature · 6 lines
2.24.1 _______________________________________________ Linux-kernel-mentees mailing list [email protected] https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
PATCH v4 4/9 Documentation: nfs-rdma: convert to ReST
In reply to Daniel W. S. AlmeidaFrom: "Daniel W. S. Almeida" <[email protected]>
Convert nfs-rdma to ReST and move it to admin-guide. Content remais mostly untouched. Also, mark the doc as obsolete.
--- Documentation/admin-guide/nfs/index.rst | 1 + Documentation/admin-guide/nfs/nfs-rdma.rst | 292 +++++++++++++++++++++ Documentation/filesystems/nfs/nfs-rdma.txt | 274 ------------------- 3 files changed, 293 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
@@ -7,3 +7,4 @@ NFS nfs-client nfsroot + nfs-rdma
Documentation/admin-guide/nfs/nfs-rdma.rst new file +292 -0
292 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
PATCH v4 5/9 Documentation: convert nfsd-admin-interfaces to ReST
In reply to Daniel W. S. AlmeidaFrom: "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
@@ -8,3 +8,4 @@ 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
@@ -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
PATCH v4 6/9 Documentation: nfs: idmapper: convert to ReST
In reply to Daniel W. S. AlmeidaFrom: "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
@@ -9,3 +9,4 @@ 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
@@ -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 · 6 lines
2.24.1 _______________________________________________ Linux-kernel-mentees mailing list [email protected] https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
PATCH v4 7/9 Documentation: nfs: convert pnfs-block-server to ReST
In reply to Daniel W. S. AlmeidaFrom: "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
@@ -10,3 +10,4 @@ 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
@@ -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
PATCH v4 8/9 Documentation: nfs: pnfs-scsi-server: convert to ReST
In reply to Daniel W. S. AlmeidaFrom: "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
@@ -11,3 +11,4 @@ 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
@@ -1,4 +1,5 @@ +================================== pNFS SCSI layout server user guide ==================================
Signature · 6 lines
2.24.1 _______________________________________________ Linux-kernel-mentees mailing list [email protected] https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
PATCH v4 9/9 Documentation: nfs: fault_injection: convert to ReST
In reply to Daniel W. S. AlmeidaFrom: "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
@@ -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
@@ -12,3 +12,4 @@ NFS nfs-idmapper pnfs-block-server pnfs-scsi-server + fault_injection
Signature · 6 lines
2.24.1 _______________________________________________ Linux-kernel-mentees mailing list [email protected] https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
Jonathan Corbet
maintainerQuoted 7 lines · On Fri, 10 Jan 2020 20:24:22 -0300 "Daniel W. S. Almeida"…
This series converts a few docs in
Documentation/filesystems/nfsto RST. The docs were also moved into admin-guide because they contain information that might be useful for system administratorsMost 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.
OK, I've applied the full set to docs-next. Many thanks for doing this work and for your patience in getting it ready to apply!
jon