svn commit: r334536 - projects/pnfs-planb-server/usr.sbin/nfsd

[Rick Macklem]

Author: rmacklem
Date: Sat Jun  2 20:11:28 2018
New Revision: 334536
URL: https://svnweb.freebsd.org/changeset/base/334536

Log:
  Update the nfsv4 man page to include a paragraph on pNFS.

Modified:
  projects/pnfs-planb-server/usr.sbin/nfsd/nfsv4.4

Modified: projects/pnfs-planb-server/usr.sbin/nfsd/nfsv4.4
==============================================================================
--- projects/pnfs-planb-server/usr.sbin/nfsd/nfsv4.4	Sat Jun  2 19:17:11 2018	(r334535)
+++ projects/pnfs-planb-server/usr.sbin/nfsd/nfsv4.4	Sat Jun  2 20:11:28 2018	(r334536)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 1, 2013
+.Dd June 2, 2018
 .Dt NFSV4 4
 .Os
 .Sh NAME
@@ -34,7 +34,8 @@
 The NFS client and server provides support for the
 .Tn NFSv4
 specification; see
-.%T "Network File System (NFS) Version 4 Protocol RFC 3530" .
+.%T "Network File System (NFS) Version 4 Protocol RFC 7530" and
+.%T "Network File System (NFS) Version 4 Minor Version 1 Protocol RFC 5661" .
 The protocol is somewhat similar to NFS Version 3, but differs in significant
 ways.
 It uses a single compound RPC that concatenates operations to-gether.
@@ -74,6 +75,7 @@ It provides several optional features not present in N
 - Referrals, which redirect subtrees to other servers
   (not yet implemented)
 - Delegations, which allow a client to operate on a file locally
+- pNFS, where I/O operations are separated from Metadata operations
 .Ed
 .Pp
 The
@@ -115,8 +117,8 @@ multiple server file systems, although not all clients
 this.
 .Pp
 .Nm
-uses names for users and groups instead of numbers.
-On the wire, they
+uses strings for users and groups instead of numbers.
+On the wire, these strings can either have the numbers in the string or
 take the form:
 .sp
 .Bd -literal -offset indent -compact
@@ -136,15 +138,37 @@ Under FreeBSD, the mapping daemon is called
 .Xr nfsuserd 8
 and has a command line option that overrides the domain component of the
 machine's hostname.
-For use of
+For use of this form of string on
 .Nm ,
 either client or server, this daemon must be running.
-If this ``<dns.domain>'' is not set correctly or the daemon is not running, ``ls -l'' will typically
+.Pp
+The form where the numbers are in the strings can only be used for AUTH_SYS.
+To configure your systems this way, the
+.Xr nfsuserd 8
+daemon does not need to be running on the server, but the following sysctls need to be
+set to 1 on the server.
+.sp
+.Bd -literal -offset indent -compact
+vfs.nfs.enable_uidtostring
+vfs.nfsd.enable_stringtouid
+.Ed
+.sp
+On the client, the sysctl
+.sp
+.Bd -literal -offset indent -compact
+vfs.nfs.enable_uidtostring
+.Ed
+.sp
+must be set to 1 and the
+.Xr nfsuserd 8
+daemon does not need to be running.
+.Pp
+If these strings are not configured correctly, ``ls -l'' will typically
 report a lot of ``nobody'' and ``nogroup'' ownerships.
 .Pp
 Although uid/gid numbers are no longer used in the
 .Nm
-protocol, they will still be in the RPC authentication fields when
+protocol except optionally in the above strings, they will still be in the RPC authentication fields when
 using AUTH_SYS (sec=sys), which is the default.
 As such, in this case both the user/group name and number spaces must
 be consistent between the client and server.
@@ -156,24 +180,24 @@ will go on the wire.
 .Sh SERVER SETUP
 To set up the NFS server that supports
 .Nm ,
-you will need to either set the variables in
+you will need to set the variables in
 .Xr rc.conf 5
 as follows:
 .sp
 .Bd -literal -offset indent -compact
 nfs_server_enable="YES"
 nfsv4_server_enable="YES"
+.Ed
+.sp
+plus
+.sp
+.Bd -literal -offset indent -compact
 nfsuserd_enable="YES"
 .Ed
 .sp
-or start
-.Xr mountd 8
-and
-.Xr nfsd 8
-without the ``-o'' option, which would force use of the old server.
-The
-.Xr nfsuserd 8
-daemon must also be running.
+if the server is using the ``<user>@<domain>'' form of user/group strings or
+is using the ``-manage-gids'' option for
+.Xr nfsuserd 8 .
 .Pp
 You will also need to add at least one ``V4:'' line to the
 .Xr exports 5
@@ -232,7 +256,7 @@ plus set ``tcp'' and
 .Pp
 The
 .Xr nfsuserd 8
-must be running, as above.
+must be running if name<->uid/gid mapping is being used, as above.
 Also, since an
 .Nm
 mount uses the host uuid to identify the client uniquely to the server,
@@ -255,7 +279,7 @@ daemon to handle client side callbacks.
 This will occur if
 .sp
 .Bd -literal -offset indent -compact
-nfsuserd_enable="YES"
+nfsuserd_enable="YES"	<-- If name<->uid/gid mapping is being used.
 nfscbd_enable="YES"
 .Ed
 .sp
@@ -265,7 +289,7 @@ are set in
 Without a functioning callback path, a server will never issue Delegations
 to a client.
 .sp
-By default, the callback address will be set to the IP address acquired via
+For NFSv4.0, by default, the callback address will be set to the IP address acquired via
 rtalloc() in the kernel and port# 7745.
 To override the default port#, a command line option for
 .Xr nfscbd 8
@@ -282,6 +306,10 @@ N.N.N.N.N.N
 where the first 4 Ns are the host IP address and the last two are the
 port# in network byte order (all decimal #s in the range 0-255).
 .Pp
+For NFSv4.1, the callback path (called a backchannel) uses the same TCP connection as the mount,
+so none of the above applies and should work through gateways without
+any issues.
+.Pp
 To build a kernel with the client that supports
 .Nm
 linked into it, the option
@@ -308,6 +336,23 @@ It occurs when an nfsd thread tries to do an NFSv4 VOP
 as part of acquiring a new vnode.
 If all other nfsd threads are blocked waiting for lock(s) held by this nfsd
 thread, then there isn't an nfsd thread to service the Close RPC.
+.Pp
+The NFSv4.1 protocol includes an optional feature referred to as pNFS,
+that permits Read/Write operations to be done directly to Data Servers (DS)
+bypassing the NFSv4.1 server.
+For this case, the NFSv4.1 server only performs metadata operations for
+pNFS aware NFSv4.1 clients.
+For other NFS clients, the NFSv4.1 server, referred to as a Metadata Server (MDS)
+acts as a proxy for the appropriate DS(s) for Read/Write operations.
+The FreeBSD implementation of pNFS supports the File and Flexible File Layouts.
+For the Flexible File Layout, it is possible to configure mirroring on the DSs
+so that data files are stored on multiple DSs (usually two), providing
+redundant storage of file data.
+However, the MDS remains a single point of failure, similar to a non-pNFS
+NFS server.
+See
+.Xr pnfs 4
+for more information.
 .Sh FILES
 .Bl -tag -width /var/db/nfs-stablerestart.bak -compact
 .It Pa /var/db/nfs-stablerestart
@@ -316,6 +361,7 @@ NFS V4 stable restart file
 backup copy of the file
 .El
 .Sh SEE ALSO
+.Xr pnfs 4 ,
 .Xr stablerestart 5 ,
 .Xr mountd 8 ,
 .Xr nfscbd 8 ,