Skip to contentSkip to conversation

Add docs for some mount options missing from nfs(5)

PATCH In review Scott Mayhew 3 participants 7 messages Jun 1, 2023 – Jun 12, 2023

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover Add docs for some mount options missing from nfs(5)

Scott Mayhew (3):
nfs(5): Document the softerr mount option.
nfs(5): Document the write=lazy|eager|wait mount option. nfs(5): Document the trunkdiscovery/notrunkdiscovery mount option.

 utils/mount/nfs.man | 84 +++++++++++++++++++++++++++++++++------------
 1 file changed, 63 insertions(+), 21 deletions(-)
Signature · 1 line
2.39.2
#1 lore raw

PATCH 1/3 nfs(5): Document the softerr mount option.

---
 utils/mount/nfs.man | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)
utils/mount/nfs.man +15 -8
index 7a410422..3cef2e23 100644
@@ -94,31 +94,38 @@ This option is an alternative to the
 option.
 It is included for compatibility with other operating systems
 .TP 1.5i
-.BR soft " / " hard
+.BR soft " / " softerr " / " hard
 Determines the recovery behavior of the NFS client
 after an NFS request times out.
-If neither option is specified (or if the
+If no option is specified (or if the
 .B hard
 option is specified), NFS requests are retried indefinitely.
-If the
-.B soft
+If either the
+.BR soft " or " softerr
 option is specified, then the NFS client fails an NFS request
 after
 .B retrans
 retransmissions have been sent,
-causing the NFS client to return an error
-to the calling application.
+causing the NFS client to return either the error
+.B EIO
+(for the
+.B soft
+option) or
+.B ETIMEDOUT
+(for the
+.B softerr
+option) to the calling application.
 .IP
 .I NB:
 A so-called "soft" timeout can cause
 silent data corruption in certain cases. As such, use the
-.B soft
+.BR soft " or " softerr
 option only when client responsiveness
 is more important than data integrity.
 Using NFS over TCP or increasing the value of the
 .B retrans
 option may mitigate some of the risks of using the
-.B soft
+.BR soft " or " softerr
 option.
 .TP 1.5i
 .BR softreval " / " nosoftreval
Signature · 1 line
2.39.2
#2 lore raw

PATCH 2/3 nfs(5): Document the write=lazy|eager|wait mount option.

In reply to Scott Mayhew
---
 utils/mount/nfs.man | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
utils/mount/nfs.man +22 -0
index 3cef2e23..2ed898f8 100644
@@ -614,6 +614,28 @@ option is not specified,
 the default behavior depends on the kernel,
 but is usually equivalent to
 .BR "xprtsec=none" .
+.TP 1.5i
+.BI write= behavior
+Controls how the NFS client handles the
+.BR write (2)
+system call.
+.I behavior
+can be one of
+.BR lazy ,
+.BR eager ,
+or
+.BR wait .
+If
+.B lazy
+(the default) is specified, then the NFS client delays sending application
+writes to the NFS server as described in the DATA AND METADATA COHERENCE
+section.  If
+.B eager
+is specified, then the NFS client sends off the write immediately as an
+unstable WRITE to the NFS server.  If
+.B wait
+is specified, then the NFS client sends off the write immediately as an
+unstable WRITE to the NFS server and then waits for the reply.
 .SS "Options for NFS versions 2 and 3 only"
 Use these options, along with the options in the above subsection,
 for NFS versions 2 and 3 only.
Signature · 1 line
2.39.2
#3 lore raw

PATCH 3/3 nfs(5): Document the trunkdiscovery/notrunkdiscovery mount option.

In reply to Scott Mayhew

Also, move the documentation for max_connect to the section for NFSv4-specific options.

---
 utils/mount/nfs.man | 39 ++++++++++++++++++++++++++-------------
 1 file changed, 26 insertions(+), 13 deletions(-)
utils/mount/nfs.man +26 -13
index 2ed898f8..0b976731 100644
@@ -423,19 +423,6 @@ Note that the
 option may also be used by some pNFS drivers to decide how many
 connections to set up to the data servers.
 .TP 1.5i
-.BR max_connect= n
-While
-.BR nconnect
-option sets a limit on the number of connections that can be established
-to a given server IP,
-.BR max_connect
-option allows the user to specify maximum number of connections to different
-server IPs that belong to the same NFSv4.1+ server (session trunkable
-connections) up to a limit of 16. When client discovers that it established
-a client ID to an already existing server, instead of dropping the newly
-created network transport, the client will add this new connection to the
-list of available transports for that RPC client.
-.TP 1.5i
 .BR rdirplus " / " nordirplus
 Selects whether to use NFS v3 or v4 READDIRPLUS requests.
 If this option is not specified, the NFS client uses READDIRPLUS requests
@@ -1000,6 +987,32 @@ when it identifies itself via a traditional identification string.
 .IP
 This mount option has no effect with NFSv4 minor versions newer than zero,
 which always use TSM-compatible client identification strings.
+.TP 1.5i
+.BR max_connect= n
+While
+.BR nconnect
+option sets a limit on the number of connections that can be established
+to a given server IP,
+.BR max_connect
+option allows the user to specify maximum number of connections to different
+server IPs that belong to the same NFSv4.1+ server (session trunkable
+connections) up to a limit of 16. When client discovers that it established
+a client ID to an already existing server, instead of dropping the newly
+created network transport, the client will add this new connection to the
+list of available transports for that RPC client.
+.TP 1.5i
+.BR trunkdiscovery " / " notrunkdiscovery
+When the client discovers a new filesystem on a NFSv4.1+ server, the
+.BR trunkdiscovery
+mount option will cause it to send a GETATTR for the fs_locations attribute.
+If is receives a non-zero length reply, it will iterate through the response,
+and for each server location it will establish a connection, send an
+EXCHANGE_ID, and test for session trunking.  If the trunking test succeeds,
+the connection will be added to the existing set of transports for the server,
+subject to the limit specified by the
+.BR max_connect
+option.  The default is
+.BR notrunkdiscovery .
 .SH nfs4 FILE SYSTEM TYPE
 The
 .BR nfs4
Signature · 1 line
2.39.2
#4 lore raw
In reply to Scott Mayhew
Quoted 2 lines · Scott Mayhew

Scott Mayhew (3):
nfs(5): Document the softerr mount option.

My only thought about this one, is do we want document an option we do people using since it will cause data corruption?

Personally I would be for ripping out all of the soft doc from the man page.

steved.

Quoted 6 lines

nfs(5): Document the write=lazy|eager|wait mount option. nfs(5): Document the trunkdiscovery/notrunkdiscovery mount option.

  utils/mount/nfs.man | 84 +++++++++++++++++++++++++++++++++------------
  1 file changed, 63 insertions(+), 21 deletions(-)
#5 lore raw
Quoted 12 lines · Steve Dickson
Quoted 2 lines · Scott Mayhew

Scott Mayhew (3):
   nfs(5): Document the softerr mount option.

My only thought about this one, is do we want document an option we do people using since it will cause data corruption?

Personally I would be for ripping out all of the soft doc from the man page.

Softerr was explicitly designed for use when re-exporting NFS. If you use a hard mount, you will find that if one of the NFS servers being re-exported goes down, eventually all your knfsd threads lock up. By timing out, and returning an error, 'softerr' prevents that scenario.

The difference between using 'soft' and 'softerr' here lies in the fact that knfsd will convert the ETIMEOUT into NFS3ERR_JUKEBOX / NFS4ERR_DELAY for the NFS clients, causing it to retry the operation. OTOH, 'soft' returns EIO, which gets converted to NFS3ERR_IO / NFS4ERR_IO, which does cause the client to error out and lose data.

IOW: this is an option that has a definite use case.

Signature · 3 lines
Trond Myklebust
Linux NFS client maintainer, Hammerspace
[email protected]
#6 lore raw
In reply to Scott Mayhew
Quoted 8 lines · Scott Mayhew

Scott Mayhew (3):
nfs(5): Document the softerr mount option.
nfs(5): Document the write=lazy|eager|wait mount option. nfs(5): Document the trunkdiscovery/notrunkdiscovery mount option.

  utils/mount/nfs.man | 84 +++++++++++++++++++++++++++++++++------------
  1 file changed, 63 insertions(+), 21 deletions(-)

Committed... (tag: nfs-utils-2-6-4-rc2)

steved.