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(-)
--
2.39.2
Signed-off-by: Scott Mayhew <[email protected]>
---
utils/mount/nfs.man | 23 +++++++++++++++--------
1 file changed, 15 insertions(+), 8 deletions(-)
diff --git a/utils/mount/nfs.man b/utils/mount/nfs.man
index 7a410422..3cef2e23 100644
--- a/utils/mount/nfs.man
+++ b/utils/mount/nfs.man
@@ -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
--
2.39.2
Signed-off-by: Scott Mayhew <[email protected]>
---
utils/mount/nfs.man | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)
diff --git a/utils/mount/nfs.man b/utils/mount/nfs.man
index 3cef2e23..2ed898f8 100644
--- a/utils/mount/nfs.man
+++ b/utils/mount/nfs.man
@@ -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.
--
2.39.2
Also, move the documentation for max_connect to the section for
NFSv4-specific options.
Signed-off-by: Scott Mayhew <[email protected]>
---
utils/mount/nfs.man | 39 ++++++++++++++++++++++++++-------------
1 file changed, 26 insertions(+), 13 deletions(-)
diff --git a/utils/mount/nfs.man b/utils/mount/nfs.man
index 2ed898f8..0b976731 100644
--- a/utils/mount/nfs.man
+++ b/utils/mount/nfs.man
@@ -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
--
2.39.2
On 6/1/23 3:46 PM, Scott Mayhew wrote:
> 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.
> 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(-)
>
On Mon, 2023-06-05 at 10:23 -0400, Steve Dickson wrote:
>
>
> On 6/1/23 3:46 PM, Scott Mayhew wrote:
> > 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.
--
Trond Myklebust
Linux NFS client maintainer, Hammerspace
[email protected]
On 6/1/23 3:46 PM, Scott Mayhew wrote:
> 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.