usr.sbin/pnfsdsfile/pnfsdsfile.8

   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 .Dd June 30, 2018
  25 .Dt PNFSDSFILE 8
  26 .Os
  27 .Sh NAME
  28 .Nm pnfsdsfile
  29 .Nd display
  30 a pNFS data storage file's location(s) and/or modify the
  31 .Dq pnfsd.dsfile
  32 extended attribute for them
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl qz
  36 .Op Fl s Ar dshostname
  37 .Op Fl c Ar old-dshostname,new-dshostname
  38 .Op Fl m Ar mirror_level
  39 .Op Fl r Ar dshostname
  40 .Ar mdsfile
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 command displays the data storage file's location(s) for a pNFS service and/or
  45 modifies the
  46 .Dq pnfsd.dsfile
  47 extended attribute on the
  48 .Ar mdsfile .
  49 A pNFS service maintains a data storage file for each regular file on
  50 the MetaData Server (MDS) on one or more of the Data Servers (DS).
  51 If mirroring is enabled, the data storage file will be on more that one of the DSs.
  52 Unless command options are specified, this command displays the location(s)
  53 of the data storage file for the MDS file
  54 .Ar mdsfile .
  55 It must be used on the MDS and the
  56 .Ar mdsfile
  57 must be a file on the exported local file system and not an NFSv4.1 mount.
  58 This information is stored in the
  59 .Dq pnfsd.dsfile
  60 extended attribute for this
  61 .Ar mdsfile .
  62 The command line options allow the information in the
  63 .Dq pnfsd.dsfile
  64 extended attribute to be changed.
  65 .Pp
  66 The following options are available:
  67 .Bl -tag -width Ds
  68 .It Fl q
  69 This option suppresses printing of the DS file's location(s).
  70 .It Fl z
  71 This option specifies that the file handle field of the pnfsd.dsfile
  72 extended attribute is to filled with all zero bits.
  73 This forces the pNFS MDS to do a Lookup RPC against the DS to acquire the file
  74 handle to update it.
  75 Normally this will only be necessary after the DS file has been recovered
  76 from a backup, causing the file handle to change.
  77 .It Fl s Ar dshostname
  78 This option can be used with
  79 .Fl z
  80 so that the zeroing out of the file handle is only done if the DS server
  81 is the one specified by this option.
  82 .It Fl c Ar old-dshostname,new-dshostname
  83 This option allows a sysadmin to replace the host IP# for the DS in the
  84 pnfsd.dsfile extended attribute.
  85 The old-hostname must resolve to the IP# already in the pnfsd.dsfile extended
  86 attribute or the replacement will not be done.
  87 If the old-dshostname matches, then the IP# is replaced by the first AF_INET
  88 or AF_INET6 address that
  89 .Xr getaddrinfo 3
  90 returns for the new-dshostname.
  91 Changing a DS server's host IP# should be avoided, but this option will
  92 allow it to be changed, if the change is unavoidable.
  93 .It Fl m Ar mirror_level
  94 This option adds entrie(s) to the extended attributes with IP address set
  95 to 0.0.0.0 to bring the number of entries up to
  96 .Dq mirror_level .
  97 It can be used by a system administrator to prepare a file for mirroring
  98 via the
  99 .Xr pnfsdscopymr
 100 command with
 101 .Fl r
 102 option.
 103 .It Fl r Ar dshostname
 104 This option sets the IP address of the extended attribute entry for the
 105 .Ar dshostname
 106 to 0.0.0.0 so that it will no longer be used.
 107 .Pp
 108 This is meant to be used when mirroring is enabled and the
 109 .Ar dshostname
 110 DS is disabled, so that it can be re-enabled once it is repaired.
 111 This needs to be done for all files in the exported MDS tree where
 112 the data may not be up-to-date on the repaired DS when it is re-enabled.
 113 After being re-enabled, the command
 114 .Xr pnfsdscopymr 1
 115 with the
 116 .Dq -r
 117 option
 118 will be used to copy the file's data to this repaired DS and then update the
 119 extended attribute to use it.
 120 .Pp
 121 A typical use of this will be within a
 122 .Xr find 1
 123 for all regular files in the MDS's exported tree.
 124 .sp
 125 For example, if the disabled DS is nfsv4-data3:
 126 .br
 127 # cd <top-level-exported-directory-on-MDS>
 128 .br
 129 # find . -type f -exec pnfsdsfile -q -r nfsv4-data3 {} \\;
 130 .El
 131 .Sh SEE ALSO
 132 .Xr find 1 ,
 133 .Xr getaddrinfo 3 ,
 134 .Xr nfsv4 4 ,
 135 .Xr pnfs 4 ,
 136 .Xr nfsd 8 ,
 137 .Xr pnfsdscopymr 8 ,
 138 .Xr pnfsdskill 8
 139 .Sh HISTORY
 140 The
 141 .Nm
 142 command first appeared in
 143 .Fx 12.0 .