| blob | 53c1d44dca257d91ae987b8ded534a03a07222c0 |
1 '\" te
2 .\" Copyright 2008 Sun Microsystems, Inc. All Rights reserved. Use is subject to license terms.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH STMSBOOT 1M "Dec 15, 2008"
7 .SH NAME
8 stmsboot \- administration program for the Solaris I/O multipathing feature
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/sbin/stmsboot\fR [[\fB-d\fR | \fB-e\fR [\fB-D\fR (fp | mpt) ]]
13 | \fB-u\fR | \fB-L\fR | \fB-l\fR \fIcontroller_number\fR]
14 .fi
16 .SH DESCRIPTION
17 .sp
18 .LP
19 The Solaris I/O multipathing feature is a multipathing solution for storage
20 devices that is part of the Solaris operating environment. This feature was
21 formerly known as Sun StorEdge Traffic Manager (STMS) or MPxIO.
22 .sp
23 .LP
24 The \fBstmsboot\fR program is an administrative command to manage enumeration
25 of multipath-capable devices with Solaris I/O multipathing. Solaris I/O
26 multipathing-enabled devices are enumerated under \fBscsi_vhci\fR(7D),
27 providing multipathing capabilities. Solaris I/O multipathing-disabled devices
28 are enumerated under the physical controller.
29 .sp
30 .LP
31 In the \fB/dev\fR and \fB/devices\fR trees, Solaris I/O multipathing-enabled
32 devices receive new names that indicate that they are under Solaris I/O
33 multipathing control. This means a device will have a different name from its
34 original name (after enabling) when it is under Solaris I/O multipathing
35 control. The \fBstmsboot\fR command automatically updates \fB/etc/vfstab\fR and
36 dump configuration to reflect the device names changes when enabling or
37 disabling Solaris I/O multipathing. One reboot is required for changes to take
38 effect.
39 .SH OPTIONS
40 .sp
41 .LP
42 The following options are supported:
43 .sp
44 .ne 2
45 .na
46 \fB\fB-e\fR [ \fB-D\fR \fBfp | mpt\fR ]\fR
47 .ad
48 .sp .6
49 .RS 4n
50 Enables Solaris I/O multipathing on all supported multipath-capable controller
51 ports. Multipath-capable ports include fibre channel (\fBfp\fR(7D)) controller
52 ports and SAS (\fBmpt\fR(7D)) controller ports. Following this enabling, you
53 are prompted to reboot. During the reboot, \fBvfstab\fR and the dump
54 configuration will be updated to reflect the device name changes. Specifying
55 either \fB-D\fR \fBmpt\fR or \fB-D\fR \fBfp\fR limits the enabling operation to
56 ports attached using the specified driver.
57 .RE
59 .sp
60 .ne 2
61 .na
62 \fB\fB-d\fR [ \fB-D\fR \fBfp | mpt\fR ]\fR
63 .ad
64 .sp .6
65 .RS 4n
66 Disables Solaris I/O multipathing on all supported multipath-capable controller
67 ports. Multipath-capable ports include fibre channel (\fBfp\fR(7D)) controller
68 ports and SAS (\fBmpt\fR(7D)) controller ports. Following this disabling, you
69 are prompted to reboot. During the reboot, \fBvfstab\fR and the dump
70 configuration will be updated to reflect the device name changes. Specifying
71 either \fB-D\fR \fBmpt\fR or \fB-D\fR \fBfp\fR limits the disabling operation
72 to ports attached using the specified driver.
73 .RE
75 .sp
76 .ne 2
77 .na
78 \fB\fB-u\fR\fR
79 .ad
80 .sp .6
81 .RS 4n
82 Updates \fBvfstab\fR and the dump configuration after you have manually
83 modified the configuration to have Solaris I/O multipathing enabled or disabled
84 on specific multipath-capable controller ports. This option prompts you to
85 reboot. During the reboot, \fBvfstab\fR and the dump configuration will be
86 updated to reflect the device name changes.
87 .RE
89 .sp
90 .ne 2
91 .na
92 \fB\fB-L\fR\fR
93 .ad
94 .sp .6
95 .RS 4n
96 Display the device name changes from non-Solaris I/O multipathing device names
97 to Solaris I/O multipathing device names for multipath-enabled controller
98 ports. If Solaris I/O multipathing is not enabled, then no mappings are
99 displayed.
100 .RE
102 .sp
103 .ne 2
104 .na
105 \fB\fB-l\fR \fIcontroller_number\fR\fR
106 .ad
107 .sp .6
108 .RS 4n
109 Display the device name changes from non-Solaris I/O multipathing device names
110 to Solaris I/O multipathing device names for the specified controller. If
111 Solaris I/O multipathing is not enabled, then no mappings are displayed.
112 .RE
114 .SH USAGE
115 .sp
116 .LP
117 The primary function of \fBstmsboot\fR is to control the enabling and disabling
118 of Solaris I/O multipathing on the host. The utility automatically updates
119 \fBvfstab\fR(4) and \fBdumpadm\fR(1M) configuration to reflect device name
120 changes. The system administrator is responsible for modifying application
121 configuration (for example, backup software, DBMS, and so forth) to reflect
122 updated device names.
123 .sp
124 .LP
125 The \fB-L\fR and \fB-l\fR options display the mapping between multipathed and
126 non-multipathed device names. These options function only after changes to the
127 Solaris I/O multipathing configuration have taken effect, that is, following
128 the reboot after invoking \fBstmsboot\fR \fB-e\fR.
129 .sp
130 .LP
131 ZFS datasets, including ZFS root datasets, are correctly handled by
132 \fBstmsboot\fR.
133 .SH EXAMPLES
134 .LP
135 \fBExample 1 \fREnabling Solaris I/O Multipathing
136 .sp
137 .LP
138 To enable Solaris I/O multipathing for all multipath-capable controllers, run:
140 .sp
141 .in +2
142 .nf
143 # \fBstmsboot -e\fR
144 .fi
145 .in -2
146 .sp
148 .sp
149 .LP
150 To enable Solaris I/O multipathing on multipath-capable \fBmpt\fR(7D)
151 controller ports, enter:
153 .sp
154 .in +2
155 .nf
156 # \fBstmsboot -D mpt -e\fR
157 .fi
158 .in -2
159 .sp
161 .sp
162 .LP
163 To enable Solaris I/O Multipathing on multipath-capable fibre channel
164 controller ports, enter:
166 .sp
167 .in +2
168 .nf
169 # \fBstmsboot -D fp -e\fR
170 .fi
171 .in -2
172 .sp
174 .LP
175 \fBExample 2 \fRDisabling Solaris I/O Multipathing
176 .sp
177 .LP
178 To disable Solaris I/O multipathing on all multipath-capable controllers,
179 enter:
181 .sp
182 .in +2
183 .nf
184 # \fBstmsboot -d\fR
185 .fi
186 .in -2
187 .sp
189 .sp
190 .LP
191 To disable Solaris I/O multipathing on multipath-capable \fBmpt\fR(7D)
192 controller ports, enter:
194 .sp
195 .in +2
196 .nf
197 # \fBstmsboot -D mpt -d\fR
198 .fi
199 .in -2
200 .sp
202 .sp
203 .LP
204 To disable Solaris I/O multipathing on multipath-capable fibre channel
205 controller ports, enter:
207 .sp
208 .in +2
209 .nf
210 # \fBstmsboot -D fp -d\fR
211 .fi
212 .in -2
213 .sp
215 .LP
216 \fBExample 3 \fREnabling Solaris I/O Multipathing on Selected Ports
217 .sp
218 .LP
219 To enable Solaris I/O multipathing on specific fibre channel controller ports
220 and disable the feature on others, manually edit the \fB/kernel/drv/fp.conf\fR
221 file. (See\fBfp\fR(7D).) The following command will update \fBvfstab\fR(4) and
222 \fBdumpadm\fR(1M) configurations to reflect the changed device names:
224 .sp
225 .in +2
226 .nf
227 # \fBstmsboot -u\fR
228 .fi
229 .in -2
230 .sp
232 .sp
233 .LP
234 A similar procedure involving the \fB/kernel/drv/mpt.conf\fR file should be
235 followed for devices attached by means of the \fBmpt\fR(7D) driver.
237 .SH ATTRIBUTES
238 .sp
239 .LP
240 See \fBattributes\fR(5) for descriptions of the following attributes:
241 .sp
243 .sp
244 .TS
245 box;
246 c | c
247 l | l .
248 ATTRIBUTE TYPE ATTRIBUTE VALUE
249 _
250 Interface Stability Obsolete
251 .TE
253 .SH SEE ALSO
254 .sp
255 .LP
256 \fBdumpadm\fR(1M), \fBfsck\fR(1M), \fBmpathadm\fR(1M), \fBufsdump\fR(1M),
257 \fBzfs\fR(1M), \fBzpool\fR(1M), \fBdumpdates\fR(4), \fBvfstab\fR(4),
258 \fBemlxs\fR(7D), \fBfcp\fR(7D), \fBfp\fR(7D), \fBmpt\fR(7D), \fBqlc\fR(7D),
259 \fBscsi_vhci\fR(7D)
260 .sp
261 .LP
262 \fISolaris SAN Configuration and Multipathing Guide\fR (see
263 \fBhttp://docs.sun.com\fR)
264 .sp
265 .LP
266 Consult a particular storage product's system administrator's guide and release
267 notes for further information specific to that product.
268 .SH NOTES
269 .sp
270 .LP
271 Solaris I/O multipathing is not supported on all devices. After enabling
272 Solaris I/O multipathing, only supported devices are placed under Solaris I/O
273 multipathing control. Non-supported devices remain unchanged.
274 .sp
275 .LP
276 For Solaris releases prior to the current release, the \fB-e\fR and \fB-d\fR
277 options replace \fBmpxio-disable\fR property entries with a global
278 \fBmpxio-disable\fR entry in \fBfp.conf\fR.
279 .SS "Enabling Solaris I/O Multipathing on a Sun StorEdge Disk Array"
280 .sp
281 .LP
282 The following applies to Sun StoreEdge T3, 3910, 3960, 6120, and 6320 storage
283 subsystems.
284 .sp
285 .LP
286 To place your Sun StorEdge disk subsystem under Solaris I/O multipathing
287 control, in addition to enabling Solaris I/O multipathing, the \fBmp_support\fR
288 of the subsystem must be set to \fBmpxio\fR mode. The preferred sequence is to
289 change the subsystem's \fBmp_support\fR to \fBmpxio\fR mode, then run
290 \fBstmsboot\fR \fB-e\fR. If Solaris I/O multipathing is already enabled but the
291 subsystem's \fBmp_support\fR is not in \fBmpxio\fR mode, then change the
292 \fBmp_support\fR to \fBmpxio\fR mode and run \fBstmsboot\fR \fB-u\fR.
293 .sp
294 .LP
295 Refer to the \fISun StorEdge Administrator's Guide\fR for your subsystem for
296 more details.
297 .SS "Using \fBufsdump\fR"
298 .sp
299 .LP
300 The \fBufsdump\fR(1M) command records details of filesystem dumps in
301 \fB/etc/dumpdates\fR (see \fBdumpdates\fR(4)). Among other items, the entries
302 contain device names. An effect of the "active" \fBstmsboot\fR options
303 (\fB-e\fR, \fB-d\fR, and \fB-u\fR) is to change the device name of a storage
304 device.
305 .sp
306 .LP
307 Because \fBstmsboot\fR does not modify \fBdumpdates\fR, entries will refer to
308 obsolete device names, that is, device names that were in effect before Solaris
309 I/O multipathing configuration changes were performed. In this situation
310 \fBufsdump\fR will behave as if no previous dump of the filesystem had been
311 performed. A level 0 dump will be performed.
312 .SS "Procedure to Use \fBstmsboot\fR in Conjunction with Sun Cluster"
313 .sp
314 .LP
315 If possible, invoke \fBstmsboot\fR \fB-e\fR before installing Sun Cluster
316 software. After executing \fBstmsboot\fR, install Sun Cluster software
317 normally.
318 .sp
319 .LP
320 If Sun Cluster software is installed before executing \fBstmsboot\fR, follow
321 this procedure:
322 .sp
323 .LP
324 On each machine in the cluster where Solaris I/O multipathing is required,
325 execute:
326 .sp
327 .in +2
328 .nf
329 # \fBstmsboot -e\fR
330 .fi
331 .in -2
332 .sp
334 .sp
335 .LP
336 \&...and allow the system to reboot.
337 .sp
338 .LP
339 When the system comes up, enter the following two commands:
340 .RS +4
341 .TP
342 1.
343 # \fB/usr/cluster/bin/scdidadm -C\fR
344 .RE
345 .RS +4
346 .TP
347 2.
348 # \fB/usr/cluster/bin/scdidadm -r\fR
349 .sp
350 The preceding commands update \fBdid\fR mappings with new device names while
351 preserving \fBdid\fR instance numbers for disks that are connected to multiple
352 cluster nodes. \fBdid\fR instance numbers of the local disks might not be
353 preserved. For this reason, the \fBdid\fR disk names for local disks might
354 change.
355 .RE
356 .RS +4
357 .TP
358 3.
359 Update \fB/etc/vfstab\fR to reflect any new \fBdid\fR disk names for your
360 local disks.
361 .RE
362 .RS +4
363 .TP
364 4.
365 Reboot the system.
366 .RE
367 .sp
368 .LP
369 To disable the Solaris multipathing feature, use \fBstmsboot\fR \fB-d\fR
370 (instead of \fBstmsboot\fR \fB-e\fR), then follow the procedure above.
371 .sp
372 .LP
373 To view mappings between the old and new device names, run \fBstmsboot\fR
374 \fB-L\fR. To view \fBdid\fR device name mappings, run
375 \fB/usr/cluster/bin/scdidadm\fR \fB-L\fR.
376 .sp
377 .LP
378 With active-passive storage arrays, it is possible that while your host is
379 rebooting the array controller could failover the path that a particular target
380 is using. In this scenario, \fBfsck\fR(1M) will fail to open the physical path
381 listed in \fB/etc/vfstab\fR. The \fBsvc:/system/filesystem/local:default\fR SMF
382 service will transition to a maintenance state as a result. To rectify this,
383 consult the documentation for your storage array to failback the path. The
384 \fBmpathadm\fR(1M) can assist with determining the active and passive path(s).
385 .SH LIMITATIONS
386 .sp
387 .LP
388 On x86 platforms, the current Solaris release does not support disabling
389 Solaris I/O multipathing of boot devices attached by means of fibre channel.
390 Solaris I/O multipathing is always enabled for supported fibre channel-attached
391 boot devices. Disabling Solaris I/O multipathing in this situation must be
392 performed on a per-port basis. See \fBfp\fR(7D).
393 .sp
394 .LP
395 Executing \fBdevfsadm\fR \fB-C\fR removes obsolete device entries that
396 \fBstmsboot\fR relies on. This will prevent correct operation of the \fB-d\fR
397 option for boot devices (regardless of platform type) and the \fB-L\fR option.