1 .\" Copyright (c) 2007 Matthew Jacob
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd "disk multipath control utility"
54 utility is used for device multipath configuration.
56 Only automatic configuration is supported at the present time via the
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.
67 indicates an action to be performed:
68 .Bl -tag -width ".Cm destroy"
70 Label the given underlying device with the specified
74 will be loaded if it is not loaded already.
76 Clear metadata on the given device.
94 variable can be used to control the behavior of the
97 .Bl -tag -width indent
98 .It Va kern.geom.multipath.debug : No 0
102 This can be set to 0 (default) or 1 to disable or enable various
106 Exit status is 0 on success, and 1 if the command fails.
107 .Sh MULTIPATH ARCHITECTURE
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
118 identity, but in all respects such identity can rarely be considered
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
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.
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.
141 the active device is kicked out of the
143 GEOM class and the next in a list is selected, the failed I/O reissued
144 and the system proceeds.
146 When new devices are added to the system the
148 GEOM class is given an opportunity to taste these new devices.
152 label, the device is used to either create a new
154 GEOM, or to attach to the end of the list of devices for an existing
158 It is this mechanism that works reasonably with
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.
168 failure event just described.
170 When Fibre Channel events inform either
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.
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).
183 Automatic rescanning is not a requirement.
184 Nor is Fibre Channel.
186 same failover mechanisms work equally well for traditional "Parallel"
187 SCSI but require manual intervention with
189 to cause the reattachment of repaired device links.
191 The following example shows how to use
193 to find possible multiple path devices and to create a
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
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.
216 command to label and create a
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....
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
246 should allow for a manual method of pairing disks.
248 There is currently no way for
249 .Pa geom_multipath.ko
250 to distinguish between various label instances of the same provider.
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
263 .An Matthew Jacob Aq mjacob@FreeBSD.org