usr.sbin/nfsd/pnfsserver.4

   1 .\" Copyright (c) 2018 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 December 20, 2019
  27 .Dt PNFSSERVER 4
  28 .Os
  29 .Sh NAME
  30 .Nm pNFSserver
  31 .Nd NFS Version 4.1 and 4.2 Parallel NFS Protocol Server
  32 .Sh DESCRIPTION
  33 A set of FreeBSD servers may be configured to provide a
  34 .Xr pnfs 4
  35 service.
  36 One FreeBSD system needs to be configured as a MetaData Server (MDS) and
  37 at least one additional FreeBSD system needs to be configured as one or
  38 more Data Servers (DS)s.
  39 .Pp
  40 These FreeBSD systems are configured to be NFSv4.1 and NFSv4.2
  41 servers, see
  42 .Xr nfsd 8
  43 and
  44 .Xr exports 5
  45 if you are not familiar with configuring a NFSv4.n server.
  46 All DS(s) and the MDS should support NFSv4.2 as well as NFSv4.1.
  47 Mixing an MDS that supports NFSv4.2 with any DS(s) that do not support
  48 NFSv4.2 will not work correctly.
  49 As such, all DS(s) must be upgraded from
  50 .Fx 12
  51 to
  52 .Fx 13
  53 before upgrading the MDS.
  54 .Sh DS server configuration
  55 The DS(s) need to be configured as NFSv4.1 and NFSv4.2 server(s),
  56 with a top level exported
  57 directory used for storage of data files.
  58 This directory must be owned by
  59 .Dq root
  60 and would normally have a mode of
  61 .Dq 700 .
  62 Within this directory there needs to be additional directories named
  63 ds0,...,dsN (where N is 19 by default) also owned by
  64 .Dq root
  65 with mode
  66 .Dq 700 .
  67 These are the directories where the data files are stored.
  68 The following command can be run by root when in the top level exported
  69 directory to create these subdirectories.
  70 .Bd -literal -offset indent
  71 jot -w ds 20 0 | xargs mkdir -m 700
  72 .Ed
  73 .sp
  74 Note that
  75 .Dq 20
  76 is the default and can be set to a larger value on the MDS as shown below.
  77 .sp
  78 The top level exported directory used for storage of data files must be
  79 exported to the MDS with the
  80 .Dq maproot=root sec=sys
  81 export options so that the MDS can create entries in these subdirectories.
  82 It must also be exported to all pNFS aware clients, but these clients do
  83 not require the
  84 .Dq maproot=root
  85 export option and this directory should be exported to them with the same
  86 options as used by the MDS to export file system(s) to the clients.
  87 .Pp
  88 It is possible to have multiple DSs on the same FreeBSD system, but each
  89 of these DSs must have a separate top level exported directory used for storage
  90 of data files and each
  91 of these DSs must be mountable via a separate IP address.
  92 Alias addresses can be set on the DS server system for a network
  93 interface via
  94 .Xr ifconfig 8
  95 to create these different IP addresses.
  96 Multiple DSs on the same server may be useful when data for different file systems
  97 on the MDS are being stored on different file system volumes on the FreeBSD
  98 DS system.
  99 .Sh MDS server configuration
 100 The MDS must be a separate FreeBSD system from the FreeBSD DS system(s) and
 101 NFS clients.
 102 It is configured as a NFSv4.1 and NFSv4.2 server with
 103 file system(s) exported to clients.
 104 However, the
 105 .Dq -p
 106 command line argument for
 107 .Xr nfsd
 108 is used to indicate that it is running as the MDS for a pNFS server.
 109 .Pp
 110 The DS(s) must all be mounted on the MDS using the following mount options:
 111 .Bd -literal -offset indent
 112 nfsv4,minorversion=2,soft,retrans=2
 113 .Ed
 114 .sp
 115 so that they can be defined as DSs in the
 116 .Dq -p
 117 option.
 118 Normally these mounts would be entered in the
 119 .Xr fstab 5
 120 on the MDS.
 121 For example, if there are four DSs named nfsv4-data[0-3], the
 122 .Xr fstab 5
 123 lines might look like:
 124 .Bd -literal -offset
 125 nfsv4-data0:/ /data0 nfs rw,nfsv4,minorversion=2,soft,retrans=2 0 0
 126 nfsv4-data1:/ /data1 nfs rw,nfsv4,minorversion=2,soft,retrans=2 0 0
 127 nfsv4-data2:/ /data2 nfs rw,nfsv4,minorversion=2,soft,retrans=2 0 0
 128 nfsv4-data3:/ /data3 nfs rw,nfsv4,minorversion=2,soft,retrans=2 0 0
 129 .Ed
 130 .sp
 131 The
 132 .Xr nfsd 8
 133 command line option
 134 .Dq -p
 135 indicates that the NFS server is a pNFS MDS and specifies what
 136 DSs are to be used.
 137 .br
 138 For the above
 139 .Xr fstab 5
 140 example, the
 141 .Xr nfsd 8
 142 nfs_server_flags line in your
 143 .Xr rc.conf 5
 144 might look like:
 145 .Bd -literal -offset
 146 nfs_server_flags="-u -t -n 128 -p nfsv4-data0:/data0,nfsv4-data1:/data1,nfsv4-data2:/data2,nfsv4-data3:/data3"
 147 .Ed
 148 .sp
 149 This example specifies that the data files should be distributed over the
 150 four DSs and File layouts will be issued to pNFS enabled clients.
 151 If issuing Flexible File layouts is desired for this case, setting the sysctl
 152 .Dq vfs.nfsd.default_flexfile
 153 non-zero in your
 154 .Xr sysctl.conf 5
 155 file will make the
 156 .Nm
 157 do that.
 158 .br
 159 Alternately, this variant of
 160 .Dq nfs_server_flags
 161 will specify that two way mirroring is to be done, via the
 162 .Dq -m
 163 command line option.
 164 .Bd -literal -offset
 165 nfs_server_flags="-u -t -n 128 -p nfsv4-data0:/data0,nfsv4-data1:/data1,nfsv4-data2:/data2,nfsv4-data3:/data3 -m 2"
 166 .Ed
 167 .sp
 168 With two way mirroring, the data file for each exported file on the MDS
 169 will be stored on two of the DSs.
 170 When mirroring is enabled, the server will always issue Flexible File layouts.
 171 .Pp
 172 It is also possible to specify which DSs are to be used to store data files for
 173 specific exported file systems on the MDS.
 174 For example, if the MDS has exported two file systems
 175 .Dq /export1
 176 and
 177 .Dq /export2
 178 to clients, the following variant of
 179 .Dq nfs_server_flags
 180 will specify that data files for
 181 .Dq /export1
 182 will be stored on nfsv4-data0 and nfsv4-data1, whereas the data files for
 183 .Dq /export2
 184 will be store on nfsv4-data2 and nfsv4-data3.
 185 .Bd -literal -offset
 186 nfs_server_flags="-u -t -n 128 -p nfsv4-data0:/data0#/export1,nfsv4-data1:/data1#/export1,nfsv4-data2:/data2#/export2,nfsv4-data3:/data3#/export2"
 187 .Ed
 188 .sp
 189 This can be used by system administrators to control where data files are
 190 stored and might be useful for control of storage use.
 191 For this case, it may be convenient to co-locate more than one of the DSs
 192 on the same FreeBSD server, using separate file systems on the DS system
 193 for storage of the respective DS's data files.
 194 If mirroring is desired for this case, the
 195 .Dq -m
 196 option also needs to be specified.
 197 There must be enough DSs assigned to each exported file system on the MDS
 198 to support the level of mirroring.
 199 The above example would be fine for two way mirroring, but four way mirroring
 200 would not work, since there are only two DSs assigned to each exported file
 201 system on the MDS.
 202 .Pp
 203 The number of subdirectories in each DS is defined by the
 204 .Dq vfs.nfs.dsdirsize
 205 sysctl on the MDS.
 206 This value can be increased from the default of 20, but only when the
 207 .Xr nfsd 8
 208 is not running and after the additional ds20,... subdirectories have been
 209 created on all the DSs.
 210 For a service that will store a large number of files this sysctl should be
 211 set much larger, to avoid the number of entries in a subdirectory from
 212 getting too large.
 213 .Sh Client mounts
 214 Once operational, NFSv4.1 or NFSv4.2 FreeBSD client mounts
 215 done with the
 216 .Dq pnfs
 217 option should do I/O directly on the DSs.
 218 The clients mounting the MDS must be running the
 219 .Xr nfscbd
 220 daemon for pNFS to work.
 221 Set
 222 .Bd -literal -offset indent
 223 nfscbd_enable="YES"
 224 .Ed
 225 .sp
 226 in the
 227 .Xr rc.conf 5
 228 on these clients.
 229 Non-pNFS aware clients or NFSv3 mounts will do all I/O RPCs on the MDS,
 230 which acts as a proxy for the appropriate DS(s).
 231 .Sh Backing up a pNFS service
 232 Since the data is separated from the metadata, the simple way to back up
 233 a pNFS service is to do so from an NFS client that has the service mounted
 234 on it.
 235 If you back up the MDS exported file system(s) on the MDS, you must do it
 236 in such a way that the
 237 .Dq system
 238 namespace extended attributes get backed up.
 239 .Sh Handling of failed mirrored DSs
 240 When a mirrored DS fails, it can be disabled one of three ways:
 241 .sp
 242 1 - The MDS detects a problem when trying to do proxy
 243 operations on the DS.
 244 This can take a couple of minutes
 245 after the DS failure or network partitioning occurs.
 246 .sp
 247 2 - A pNFS client can report an I/O error that occurred for a DS to the MDS in
 248 the arguments for a LayoutReturn operation.
 249 .sp
 250 3 - The system administrator can perform the pnfsdskill(8) command on the MDS
 251 to disable it.
 252 If the system administrator does a pnfsdskill(8) and it fails with ENXIO
 253 (Device not configured) that normally means the DS was already
 254 disabled via #1 or #2.
 255 Since doing this is harmless, once a system administrator knows that
 256 there is a problem with a mirrored DS, doing the command is recommended.
 257 .sp
 258 Once a system administrator knows that a mirrored DS has malfunctioned
 259 or has been network partitioned, they should do the following as root/su
 260 on the MDS:
 261 .Bd -literal -offset indent
 262 # pnfsdskill <mounted-on-path-of-DS>
 263 # umount -N <mounted-on-path-of-DS>
 264 .Ed
 265 .sp
 266 Note that the <mounted-on-path-of-DS> must be the exact mounted-on path
 267 string used when the DS was mounted on the MDS.
 268 .Pp
 269 Once the mirrored DS has been disabled, the pNFS service should continue to
 270 function, but file updates will only happen on the DS(s) that have not been disabled.
 271 Assuming two way mirroring, that implies the one DS of the pair stored in the
 272 .Dq pnfsd.dsfile
 273 extended attribute for the file on the MDS, for files stored on the disabled DS.
 274 .Pp
 275 The next step is to clear the IP address in the
 276 .Dq pnfsd.dsfile
 277 extended attribute on all files on the MDS for the failed DS.
 278 This is done so that, when the disabled DS is repaired and brought back online,
 279 the data files on this DS will not be used, since they may be out of date.
 280 The command that clears the IP address is
 281 .Xr pnfsdsfile 8
 282 with the
 283 .Dq -r
 284 option.
 285 .Bd -literal -offset
 286 For example:
 287 # pnfsdsfile -r nfsv4-data3 yyy.c
 288 yyy.c:  nfsv4-data2.home.rick   ds0/207508569ff983350c000000ec7c0200e4c57b2e0000000000000000    0.0.0.0 ds0/207508569ff983350c000000ec7c0200e4c57b2e0000000000000000
 289 .Ed
 290 .sp
 291 replaces nfsv4-data3 with an IPv4 address of 0.0.0.0, so that nfsv4-data3
 292 will not get used.
 293 .Pp
 294 Normally this will be called within a
 295 .Xr find 1
 296 command for all regular
 297 files in the exported directory tree and must be done on the MDS.
 298 When used with
 299 .Xr find 1 ,
 300 you will probably also want the
 301 .Dq -q
 302 option so that it won't spit out the results for every file.
 303 If the disabled/repaired DS is nfsv4-data3, the commands done on the MDS
 304 would be:
 305 .Bd -literal -offset
 306 # cd <top-level-exported-dir>
 307 # find . -type f -exec pnfsdsfile -q -r nfsv4-data3 {} \;
 308 .Ed
 309 .sp
 310 There is a problem with the above command if the file found by
 311 .Xr find 1
 312 is renamed or unlinked before the
 313 .Xr pnfsdsfile 8
 314 command is done on it.
 315 This should normally generate an error message.
 316 A simple unlink is harmless
 317 but a link/unlink or rename might result in the file not having been processed
 318 under its new name.
 319 To check that all files have their IP addresses set to 0.0.0.0 these
 320 commands can be used (assuming the
 321 .Xr sh 1
 322 shell):
 323 .Bd -literal -offset
 324 # cd <top-level-exported-dir>
 325 # find . -type f -exec pnfsdsfile {} \; | sed "/nfsv4-data3/!d"
 326 .Ed
 327 .sp
 328 Any line(s) printed require the
 329 .Xr pnfsdsfile 8
 330 with
 331 .Dq -r
 332 to be done again.
 333 Once this is done, the replaced/repaired DS can be brought back online.
 334 It should have empty ds0,...,dsN directories under the top level exported
 335 directory for storage of data files just like it did when first set up.
 336 Mount it on the MDS exactly as you did before disabling it.
 337 For the nfsv4-data3 example, the command would be:
 338 .Bd -literal -offset
 339 # mount -t nfs -o nfsv4,minorversion=2,soft,retrans=2 nfsv4-data3:/ /data3
 340 .Ed
 341 .sp
 342 Then restart the nfsd to re-enable the DS.
 343 .Bd -literal -offset
 344 # /etc/rc.d/nfsd restart
 345 .Ed
 346 .sp
 347 Now, new files can be stored on nfsv4-data3,
 348 but files with the IP address zeroed out on the MDS will not yet use the
 349 repaired DS (nfsv4-data3).
 350 The next step is to go through the exported file tree on the MDS and,
 351 for each of the
 352 files with an IPv4 address of 0.0.0.0 in its extended attribute, copy the file
 353 data to the repaired DS and re-enable use of this mirror for it.
 354 This command for copying the file data for one MDS file is
 355 .Xr pnfsdscopymr 8
 356 and it will also normally be used in a
 357 .Xr find 1 .
 358 For the example case, the commands on the MDS would be:
 359 .Bd -literal -offset
 360 # cd <top-level-exported-dir>
 361 # find . -type f -exec pnfsdscopymr -r /data3 {} \;
 362 .Ed
 363 .sp
 364 When this completes, the recovery should be complete or at least nearly so.
 365 As noted above, if a link/unlink or rename occurs on a file name while the
 366 above
 367 .Xr find 1
 368 is in progress, it may not get copied.
 369 To check for any file(s) not yet copied, the commands are:
 370 .Bd -literal -offset
 371 # cd <top-level-exported-dir>
 372 # find . -type f -exec pnfsdsfile {} \; | sed "/0\.0\.0\.0/!d"
 373 .Ed
 374 .sp
 375 If this command prints out any file name(s), these files must
 376 have the
 377 .Xr pnfsdscopymr 8
 378 command done on them to complete the recovery.
 379 .Bd -literal -offset
 380 # pnfsdscopymr -r /data3 <file-path-reported>
 381 .Ed
 382 .sp
 383 If this commmand fails with the error
 384 .br
 385 .Dq pnfsdscopymr: Copymr failed for file <path>: Device not configured
 386 .br
 387 repeatedly, this may be caused by a Read/Write layout that has not
 388 been returned.
 389 The only way to get rid of such a layout is to restart the
 390 .Xr nfsd 8 .
 391 .sp
 392 All of these commands are designed to be
 393 done while the pNFS service is running and can be re-run safely.
 394 .Pp
 395 For a more detailed discussion of the setup and management of a pNFS service
 396 see:
 397 .Bd -literal -offset indent
 398 http://people.freebsd.org/~rmacklem/pnfs-planb-setup.txt
 399 .Ed
 400 .sp
 401 .Sh SEE ALSO
 402 .Xr nfsv4 4 ,
 403 .Xr pnfs 4 ,
 404 .Xr exports 5 ,
 405 .Xr fstab 5 ,
 406 .Xr rc.conf 5 ,
 407 .Xr sysctl.conf 5 ,
 408 .Xr nfscbd 8 ,
 409 .Xr nfsd 8 ,
 410 .Xr nfsuserd 8 ,
 411 .Xr pnfsdscopymr 8 ,
 412 .Xr pnfsdsfile 8 ,
 413 .Xr pnfsdskill 8
 414 .Sh HISTORY
 415 The
 416 .Nm
 417 service first appeared in
 418 .Fx 12.0 .
 419 .Sh BUGS
 420 Since the MDS cannot be mirrored, it is a single point of failure just
 421 as a non
 422 .Tn pNFS
 423 server is.
 424 For non-mirrored configurations, all FreeBSD systems used in the service
 425 are single points of failure.