sbin/geom/class/multipath/gmultipath.8

   1 .\" Copyright (c) 2007 Matthew Jacob
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd February 26, 2007
  28 .Dt GMULTIPATH 8
  29 .Os
  30 .Sh NAME
  31 .Nm gmultipath
  32 .Nd "disk multipath control utility"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Cm label
  36 .Op Fl hv
  37 .Ar name
  38 .Ar prov ...
  39 .Nm
  40 .Cm clear
  41 .Op Fl v
  42 .Ar prov ...
  43 .Nm
  44 .Cm list
  45 .Nm
  46 .Cm status
  47 .Nm
  48 .Cm load
  49 .Nm
  50 .Cm unload
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 utility is used for device multipath configuration.
  55 .Pp
  56 Only automatic configuration is supported at the present time via the
  57 .Cm label
  58 command.
  59 This operation writes a label on the last sector of the underlying
  60 disk device with a contained name and UUID.
  61 The UUID guarantees uniqueness
  62 in a shared storage environment but is in general too cumbersome to use.
  63 The name is what is exported via the device interface.
  64 .Pp
  65 The first argument to
  66 .Nm
  67 indicates an action to be performed:
  68 .Bl -tag -width ".Cm destroy"
  69 .It Cm label
  70 Label the given underlying device with the specified
  71 .Ar name .
  72 The kernel module
  73 .Pa geom_multipath.ko
  74 will be loaded if it is not loaded already.
  75 .It Cm clear
  76 Clear metadata on the given device.
  77 .It Cm list
  78 See
  79 .Xr geom 8 .
  80 .It Cm status
  81 See
  82 .Xr geom 8 .
  83 .It Cm load
  84 See
  85 .Xr geom 8 .
  86 .It Cm unload
  87 See
  88 .Xr geom 8 .
  89 .El
  90 .Pp
  91 .Sh SYSCTL VARIABLES
  92 The following
  93 .Xr sysctl 8
  94 variable can be used to control the behavior of the
  95 .Nm MULTIPATH
  96 GEOM class.
  97 .Bl -tag -width indent
  98 .It Va kern.geom.multipath.debug : No 0
  99 Debug level of the
 100 .Nm MULTIPATH
 101 GEOM class.
 102 This can be set to 0 (default) or 1 to disable or enable various
 103 forms of chattiness.
 104 .El
 105 .Sh EXIT STATUS
 106 Exit status is 0 on success, and 1 if the command fails.
 107 .Sh MULTIPATH ARCHITECTURE
 108 .Pp
 109 This is an active/passive
 110 multiple path architecture with no device knowledge or presumptions other
 111 than size matching built in.
 112 Therefore the user must exercise some care
 113 in selecting providers that do indeed represent multiple paths to the
 114 same underlying disk device.
 115 The reason for this is that there are several
 116 criteria across multiple underlying transport types that can
 117 .Ar indicate
 118 identity, but in all respects such identity can rarely be considered
 119 .Ar definitive .
 120 .Pp
 121 For example, if you use the World Word Port Name of a Fibre Channel
 122 disk object you might believe that two disks that have the same WWPN
 123 on different paths (or even disjoint fabrics) might be considered
 124 the same disk.
 125 Nearly always this would be a safe assumption, until
 126 you realize that a WWPN, like an Ethernet MAC address, is a soft
 127 programmable entity, and that a misconfigured Director Class switch
 128 could lead you to believe incorrectly that you have found multiple
 129 paths to the same device.
 130 This is an extreme and theoretical case, but
 131 it is possible enough to indicate that the policy for deciding which
 132 of multiple pathnames refer to the same device should be left to the
 133 system operator who will use tools and knowledge of their own storage
 134 subsystem to make the correct configuration selection.
 135 .Pp
 136 As an active/passive architecture, only one path has I/O moving on it
 137 at any point in time.
 138 This I/O continues until an I/O is returned with
 139 a generic I/O error or a "Nonexistent Device" error.
 140 When this occurs,
 141 the active device is kicked out of the
 142 .Nm MULTIPATH
 143 GEOM class and the next in a list is selected, the failed I/O reissued
 144 and the system proceeds.
 145 .Pp
 146 When new devices are added to the system the
 147 .Nm MULTIPATH
 148 GEOM class is given an opportunity to taste these new devices.
 149 If a new
 150 device has a
 151 .Nm MULTIPATH
 152 label, the device is used to either create a new
 153 .Nm MULTIPATH
 154 GEOM, or to attach to the end of the list of devices for an existing
 155 .Nm MULTIPATH
 156 GEOM.
 157 .Pp
 158 It is this mechanism that works reasonably with
 159 .Xr isp 4
 160 and
 161 .Xr mpt 4
 162 based Fibre Channel disk devices.
 163 For these devices, when a device disappears
 164 (due e.g., to a cable pull or power failure to a switch), the device is
 165 proactively marked as gone and I/O to it failed.
 166 This causes the
 167 .Nm MULTIPATH
 168 failure event just described.
 169 .Pp
 170 When Fibre Channel events inform either
 171 .Xr isp 4
 172 or
 173 .Xr mpt 4
 174 host bus adapters that new devices may have arrived (e.g., the arrival
 175 of an RSCN event from the Fabric Domain Controller), they can cause
 176 a rescan to occur and cause the attachment and configuration of any
 177 (now) new devices to occur, causing the taste event described above.
 178 .Pp
 179 This means that this active/passive architecture is not a one-shot path
 180 failover, but can be considered to be steady state as long as failed
 181 paths are repaired (automatically or otherwise).
 182 .Pp
 183 Automatic rescanning is not a requirement.
 184 Nor is Fibre Channel.
 185 The
 186 same failover mechanisms work equally well for traditional "Parallel"
 187 SCSI but require manual intervention with
 188 .Xr camcontrol 8
 189 to cause the reattachment of repaired device links.
 190 .Sh EXAMPLES
 191 The following example shows how to use
 192 .Xr camcontrol 8
 193 to find possible multiple path devices and to create a
 194 .Nm MULTIPATH
 195 GEOM class for them.
 196 .Bd -literal -offset indent
 197 mysys# camcontrol devlist
 198 <ECNCTX @WESTVILLE >   at scbus0 target 0 lun 0 (da0,pass0)
 199 <ECNCTX @WESTVILLE >   at scbus0 target 0 lun 1 (da1,pass1)
 200 <ECNCTX @WESTVILLE >   at scbus1 target 0 lun 0 (da2,pass2)
 201 <ECNCTX @WESTVILLE >   at scbus1 target 0 lun 1 (da3,pass3)
 202 mysys# camcontrol inquiry da0 -S
 203 ECNTX0LUN000000SER10ac0d01
 204 mysys# camcontrol inquiry da2 -S
 205 ECNTX0LUN000000SER10ac0d01
 206 .Ed
 207 .Pp
 208 Now that you have used the Serial Number to compare two disk paths
 209 it is not entirely unreasonable to conclude that these are multiple
 210 paths to the same device.
 211 However, only the user who is familiar
 212 with their storage is qualified to make this judgement.
 213 .Pp
 214 You can then use the
 215 .Nm
 216 command to label and create a
 217 .Nm MULTIPATH
 218 GEOM provider named
 219 .Ar FRED .
 220 .Bd -literal -offset indent
 221 gmultipath label -v FRED /dev/da0 /dev/da2
 222 disklabel -Brw /dev/multipath/FRED auto
 223 newfs /dev/multipath/FREDa
 224 mount /dev/multipath/FREDa /mnt....
 225 .Ed
 226 .Pp
 227 The resultant console output looks something like:
 228 .Bd -literal -offset indent
 229 GEOM_MULTIPATH: adding da0 to Fred/b631385f-c61c-11db-b884-0011116ae789
 230 GEOM_MULTIPATH: da0 now active path in Fred
 231 GEOM_MULTIPATH: adding da2 to Fred/b631385f-c61c-11db-b884-0011116ae789
 232 .Ed
 233 .Sh SEE ALSO
 234 .Xr geom 4 ,
 235 .Xr isp 4 ,
 236 .Xr mpt 4 ,
 237 .Xr loader.conf 5 ,
 238 .Xr camcontrol 8 ,
 239 .Xr geom 8 ,
 240 .Xr mount 8 ,
 241 .Xr newfs 8 ,
 242 .Xr sysctl 8
 243 .Sh BUGS
 244 The
 245 .Nm
 246 should allow for a manual method of pairing disks.
 247 .Pp
 248 There is currently no way for
 249 .Pa geom_multipath.ko
 250 to distinguish between various label instances of the same provider.
 251 That
 252 is devices such as
 253 .Ar da0
 254 and
 255 .Ar da0c
 256 can be tasted and instantiated as multiple paths for the same device.
 257 Technically, this is correct, but pretty useless.
 258 This will be fixed soon
 259 (I hope), but to avoid this it is a good idea to destroy any label on
 260 the disk object prior to labelling it with
 261 .Nm .
 262 .Sh AUTHOR
 263 .An Matthew Jacob Aq mjacob@FreeBSD.org