Add docs for some mount options missing from nfs(5)
Subsystems (2)
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
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
@@ -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
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
@@ -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
PATCH 3/3 nfs(5): Document the trunkdiscovery/notrunkdiscovery mount option.
In reply to Scott MayhewAlso, 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
@@ -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
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(-)
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]
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.