usr.sbin/nfsd/pnfs.4

   1 .\" Copyright (c) 2017 Rick Macklem
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd March 26, 2018
  27 .Dt PNFS 4
  28 .Os
  29 .Sh NAME
  30 .Nm pNFS
  31 .Nd NFS Version 4.1 Parallel NFS Protocol
  32 .Sh DESCRIPTION
  33 The NFSv4.1 client and server provides support for the
  34 .Tn pNFS
  35 specification; see
  36 .%T "Network File System (NFS) Version 4 Minor Version 1 Protocol RFC 5661" .
  37 A pNFS service separates Read/Write operations from all other NFSv4.1
  38 operations, which are referred to as Metadata operations.
  39 The Read/Write operations are performed directly on the Data Server (DS)
  40 where the file's data resides, bypassing the NFS server.
  41 All other file operations are performed on the NFS server, which is referred to
  42 as a Metadata Server (MDS).
  43 NFS clients that do not support
  44 .Tn pNFS
  45 perform Read/Write operations on the MDS, which acts as a proxy for the
  46 appropriate DS(s).
  47 .Pp
  48 The NFSv4.1 protocol provides two pieces of information to pNFS aware
  49 clients that allow them to perform Read/Write operations directly on
  50 the DS.
  51 .Pp
  52 The first is DeviceInfo, which is static information defining the DS
  53 server.
  54 The critical piece of information in DeviceInfo for the layout types
  55 supported by FreeBSD is the IP address that is used to perform RPCs on the DS.
  56 It also indicates which version of NFS the DS supports, I/O size and other
  57 layout specific information.
  58 In the DeviceInfo, there is a DeviceID which, for the FreeBSD server
  59 is unique to the DS configuration
  60 and changes whenever the
  61 .Xr nfsd
  62 daemon is restarted or the server is rebooted.
  63 .Pp
  64 The second is the layout, which is per file and references the DeviceInfo
  65 to use via the DeviceID.
  66 It is for a byte range of a file and is either Read or Read/Write.
  67 For the FreeBSD server, a layout covers all bytes of a file.
  68 A layout may be recalled by the MDS using a LayoutRecall callback.
  69 When a client returns a layout via the LayoutReturn operation it can
  70 indicate that error(s) were encountered while doing I/O on the DS.
  71 .Pp
  72 The FreeBSD client and server supports two layout types.
  73 .Pp
  74 The File Layout is described in RFC5661 and uses the NFSv4.1 protocol
  75 to perform I/O on the DS.
  76 It does not support client aware DS mirroring and, as such,
  77 the FreeBSD server only provides File Layout support for non-mirrored
  78 configurations.
  79 .Pp
  80 The Flexible File Layout allows the use of the NFSv3, NFSv4.0 or NFSv4.1
  81 protocol to perform I/O on the DS and does support client aware mirroring.
  82 As such, the FreeBSD server uses Flexible File Layout layouts for the
  83 mirrored DS configurations.
  84 The FreeBSD server supports the
  85 .Dq tightly coupled
  86 variant and all DSs use the
  87 NFSv4.1 protocol for I/O operations.
  88 Clients that support the Flexible File Layout will do writes and commits
  89 to all DS mirrors in the mirror set.
  90 .Pp
  91 A FreeBSD pNFS service consists of a single MDS server plus one or more
  92 DS servers, all of which are FreeBSD systems.
  93 For a non-mirrored configuration, the FreeBSD server will issue File Layout
  94 layouts by default.
  95 However that default can be set to the Flexible File Layout by setting the
  96 .Xr sysctl 1
  97 sysctl ``vfs.nfsd.default_flexfile'' to one.
  98 Mirrored server configurations will only issue Flexible File Layouts.
  99 .Tn pNFS
 100 clients mount the MDS as they would a single NFS server.
 101 .Pp
 102 A FreeBSD
 103 .Tn pNFS
 104 client must be running the
 105 .Xr nfscbd 8
 106 daemon and use the mount options
 107 .Dq nfsv4,minorversion=1,pnfs .
 108 .Pp
 109 When files are created, the MDS creates a file tree identical to what a
 110 single NFS server creates, except that all the regular (VREG) files will
 111 be empty.
 112 As such, if you look at the exported tree on the MDS directly
 113 on the MDS server (not via an NFS mount), the files will all be of size zero.
 114 Each of these files will also have two extended attributes in the system
 115 attribute name space:
 116 .Bd -literal -offset indent
 117 pnfsd.dsfile - This extended attrbute stores the information that the
 118     MDS needs to find the data file on a DS for this file.
 119 pnfsd.dsattr - This extended attribute stores the Size, AccessTime,
 120     ModifyTime and Change attributes for the file.
 121 .Ed
 122 .Pp
 123 For each regular (VREG) file, the MDS creates a data file on one
 124 (or on N of them for the mirrored case, where N is the mirror_level)
 125 of the DSs where the file's data will be stored.
 126 The name of this file is
 127 the file handle of the file on the MDS in hexadecimal at time of file creation.
 128 The data file will have the same file ownership, mode and NFSv4 ACL
 129 (if ACLs are enabled for the file system) as the file on the MDS, so that
 130 permission checking can be done on the DS.
 131 This is referred to as
 132 .Dq tightly coupled
 133 for the Flexible File Layout.
 134 .Pp
 135 For
 136 .Tn pNFS
 137 aware clients, the service generates File Layout
 138 or Flexible File Layout
 139 layouts and associated DeviceInfo.
 140 For non-pNFS aware NFS clients, the pNFS service appears just like a normal
 141 NFS service.
 142 For the non-pNFS aware client, the MDS will perform I/O operations on the appropriate DS(s), acting as
 143 a proxy for the non-pNFS aware client.
 144 This is also true for NFSv3 and NFSv4.0 mounts, since these are always non-pNFS
 145 aware.
 146 .Pp
 147 See
 148 .Bd -literal -offset indent
 149 http://people.freebsd.org/~rmacklem/pnfs-planb-setup.txt
 150 .Ed
 151 .sp
 152 for information on how to set up a FreeBSD pNFS service.
 153 .Sh SEE ALSO
 154 .Xr nfsv4 4 ,
 155 .Xr exports 5 ,
 156 .Xr fstab 5 ,
 157 .Xr rc.conf 5 ,
 158 .Xr nfscbd 8 ,
 159 .Xr nfsd 8 ,
 160 .Xr nfsuserd 8 ,
 161 .Xr pnfsdscopymr 8 ,
 162 .Xr pnfsdsfile 8 ,
 163 .Xr pnfsdskill 8
 164 .Sh BUGS
 165 Linux kernel versions prior to 4.12 only supports NFSv3 DSs in its client
 166 and will do all I/O through the MDS.
 167 For Linux 4.12 kernels, support for NFSv4.1 DSs was added, but I have seen
 168 Linux client crashes when testing this client.
 169 For Linux 4.17-rc2 kernels, I have not seen client crashes during testing,
 170 but it only supports the
 171 .Dq loosely coupled
 172 variant.
 173 To make it work correctly when mounting the FreeBSD server, you must either
 174 patch the Flexible File Layout client driver with a patch like:
 175 .Bd -literal -offset indent
 176 http://people.freebsd.org/~rmacklem/flexfile.patch
 177 .Ed
 178 .sp
 179 or set the sysctl
 180 .Dq vfs.nfsd.flexlinuxhack
 181 to one so that it works around
 182 the Linux client driver's limitations.
 183 .Pp
 184 Since the MDS cannot be mirrored, it is a single point of failure just
 185 as a non
 186 .Tn pNFS
 187 server is.