| blob | aa1b0a88c594529d8d7b4c23eb0f7c7a48042afe |
1 '\" te
2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
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 MPATHADM 1M "May 4, 2009"
7 .SH NAME
8 mpathadm \- multipath discovery and administration
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBmpathadm\fR \fIsubcommand\fR \fIdirect-object\fR [\fIoptions\fR] [\fIoperand\fR]
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 The \fBmpathadm\fR command enables multipathing discovery and management. The
19 \fBmpathadm\fR command is implemented as a set of subcommands, many with their
20 own options, that are described in the section for that subcommand. Options not
21 associated with a particular subcommand are described under OPTIONS. The
22 \fBmpathadm\fR subcommands operate on a \fIdirect-object\fR. These are
23 described in this section for each subcommand. The \fIdirect-objects\fR,
24 \fIinitiator-port\fR, \fItarget-port\fR, and\fIlogical-unit\fR in the
25 subcommands are consistent with SCSI standard definitions.
26 .sp
27 .LP
28 The \fBmpathadm\fR command supports the following subcommands, which are
29 described in detail in subsections that follow.
30 .sp
31 .ne 2
32 .na
33 \fB\fBlist\fR\fR
34 .ad
35 .RS 12n
36 Display a list of discovered instances for a given object.
37 .RE
39 .sp
40 .ne 2
41 .na
42 \fB\fBshow\fR\fR
43 .ad
44 .RS 12n
45 Display information about a given object instance.
46 .RE
48 .sp
49 .ne 2
50 .na
51 \fB\fBmodify\fR\fR
52 .ad
53 .RS 12n
54 Modify properties of an object.
55 .RE
57 .sp
58 .ne 2
59 .na
60 \fB\fBenable\fR\fR
61 .ad
62 .RS 12n
63 Enable an object.
64 .RE
66 .sp
67 .ne 2
68 .na
69 \fB\fBdisable\fR\fR
70 .ad
71 .RS 12n
72 Disable an object.
73 .RE
75 .sp
76 .ne 2
77 .na
78 \fB\fBfailover\fR\fR
79 .ad
80 .RS 12n
81 Cause target port group failover for a logical-unit.
82 .RE
84 .sp
85 .ne 2
86 .na
87 \fB\fBoverride\fR\fR
88 .ad
89 .RS 12n
90 Set a path to be used over other paths on a logical-unit.
91 .RE
93 .sp
94 .LP
95 The \fBmpathadm\fR subcommands operate on a \fIdirect-object\fR. These are
96 described in this section for each subcommand.
97 .SS "list Subcommand"
98 .sp
99 .LP
100 The syntax for the \fBlist\fR subcommand is:
101 .sp
102 .in +2
103 .nf
104 # mpathadm list \fIdirect-object\fR [\fIoperands\fR...]
105 .fi
106 .in -2
108 .sp
109 .LP
110 The \fBlist\fR subcommand displays data for following direct-objects:
111 .sp
112 .ne 2
113 .na
114 \fB\fBmpath-support\fR [\fImpath-support-name\fR, ...]\fR
115 .ad
116 .sp .6
117 .RS 4n
118 List the multipathing support that can be administered by this CLI. This
119 presents itself in the form of a library name registered through the MPAPI
120 framework. If no mpath-support name \fImpath-support-name\fR is specified, all
121 registered multipathing support libraries will be displayed.
122 .RE
124 .sp
125 .ne 2
126 .na
127 \fB\fBinitiator-port\fR [\fIinitiator-port-name\fR, ...]\fR
128 .ad
129 .sp .6
130 .RS 4n
131 List the initiator ports that are discovered on this system. If no
132 \fIinitiator-port-name\fR is specified, all discovered initiator ports are
133 displayed.
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fB{\fBlogical-unit\fR | \fBlu\fR} [\fIoptions\fR]
140 [\fIlogical-unit-name\fR, ...]\fR
141 .ad
142 .sp .6
143 .RS 4n
144 List the information on multipath logical units. If no \fIlogical-unit-name\fR
145 is specified, all discovered logical-units will be displayed.
146 .sp
147 Options for \fBlist logical-unit\fR are as follows:
148 .sp
149 .ne 2
150 .na
151 \fB\fB-n\fR, \fB-\fR\fB-name\fR \fIname\fR\fR
152 .ad
153 .sp .6
154 .RS 4n
155 Return the logical unit name that is associated with the given name string.
156 This name can be extracted from the output of the \fBmpathadm\fR \fBshow lu\fR
157 command.
158 .RE
160 .sp
161 .ne 2
162 .na
163 \fB\fB-t\fR, \fB-\fR\fB-target-port\fR \fItarget-port-name\fR\fR
164 .ad
165 .sp .6
166 .RS 4n
167 Return the list of logical units names that are associated with the given
168 \fItarget-port-name\fR.
169 .RE
171 .RE
173 .SS "\fBshow\fR Subcommand"
174 .sp
175 .LP
176 The syntax for the \fBshow\fR subcommand is:
177 .sp
178 .in +2
179 .nf
180 # mpathadm show \fIdirect-object\fR [\fIoperands\fR...]
181 .fi
182 .in -2
184 .sp
185 .LP
186 The \fBshow\fR subcommand displays detailed information for following the
187 direct-objects:
188 .sp
189 .ne 2
190 .na
191 \fB\fBmpath-support\fR [\fImpath-support-name\fR, ...]\fR
192 .ad
193 .sp .6
194 .RS 4n
195 Show the detailed information on the given \fImpath-support-name\fR if the name
196 exists. If the given \fImpath-support-name\fR supports only a limited set of
197 device products, the list of device products will be listed as part of the
198 output.
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fBinitiator-port\fR
205 \fIinitiator-port-name\fR[,\fIinitiator-port-name\fR, ...]\fR
206 .ad
207 .sp .6
208 .RS 4n
209 Show the detailed information for the given \fIinitiator-port-name\fR.
210 .RE
212 .sp
213 .ne 2
214 .na
215 \fB{\fBlogical-unit\fR | \fBlu\fR} [\fIlogical-unit-name\fR, ...]\fR
216 .ad
217 .sp .6
218 .RS 4n
219 Display the detailed information on multipath logical unit(s), including path
220 and target port group information. Note that the name property in the logical
221 unit information represents the identifier for this LUN, derived from the
222 hardware, and used by this system. If the name is derived from SCSI Inquiry
223 Vital Product Data (VPD) page 83h, the name type property represents an
224 associated identifier type defined by the SCSI standards.
225 .RE
227 .SS "\fBmodify\fR Subcommand"
228 .sp
229 .LP
230 The syntax for the \fBmodify\fR subcommand is:
231 .sp
232 .in +2
233 .nf
234 # mpathadm modify \fIdirect-object\fR [\fIoptions\fR] [\fIoperands\fR...]
235 .fi
236 .in -2
238 .sp
239 .LP
240 The \fBmodify\fR subcommand modifies characteristics of the following
241 direct-objects:
242 .sp
243 .ne 2
244 .na
245 \fB\fBmpath-support\fR [\fIoptions\fR] \fImpath-support-name\fR, ...\fR
246 .ad
247 .sp .6
248 .RS 4n
249 Configuration management of an \fImpath-support\fR. Options to modify
250 mpath-support are as follows:
251 .sp
252 .ne 2
253 .na
254 \fB\fB-a\fR, \fB-\fR\fB-autofailback\fR on | off\fR
255 .ad
256 .sp .6
257 .RS 4n
258 Set \fBautofailback\fR. Applicable only when mpath-support provides auto
259 failback support.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fB-p\fR, \fB-\fR\fB-autoprobe\fR on | off\fR
266 .ad
267 .sp .6
268 .RS 4n
269 Set \fBautoprobing\fR. Applicable only when mpath-support provides auto probing
270 support.
271 .RE
273 .sp
274 .ne 2
275 .na
276 \fB\fB-b\fR, \fB-\fR\fB-loadbalance\fR loadbalance-type\fR
277 .ad
278 .sp .6
279 .RS 4n
280 Change the default load balance type. The \fBloadbalance\fR type is one of the
281 supported types listed in the \fBshow mpath-support\fR output.
282 .RE
284 .RE
286 .sp
287 .ne 2
288 .na
289 \fB{\fBlogical-unit\fR | \fBlu\fR} [\fIoptions\fR]
290 \fIlogical-unit-name\fR, ...\fR
291 .ad
292 .sp .6
293 .RS 4n
294 Configuration management of a logical unit. Options to modify
295 \fBlogical-unit\fR are as follows:
296 .sp
297 .ne 2
298 .na
299 \fB\fB-a\fR, \fB-\fR\fB-autofailback\fR on | off\fR
300 .ad
301 .sp .6
302 .RS 4n
303 Set \fBautofailback\fR. Applicable only when \fBmpath-support\fR provides auto
304 failback support
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fB\fB-p\fR, \fB-\fR\fB-autoprobe\fR on | off\fR
311 .ad
312 .sp .6
313 .RS 4n
314 Set \fBautoprobing\fR. Applicable only when \fBmpath-support\fR provides auto
315 probing support.
316 .RE
318 .sp
319 .ne 2
320 .na
321 \fB\fB-b\fR, \fB-\fR\fB-loadbalance\fR loadbalance-type\fR
322 .ad
323 .sp .6
324 .RS 4n
325 Set load balance type for the logical unit. Applicable only when load balance
326 configuration is supported at the logical unit level.
327 .RE
329 .RE
331 .SS "\fBenable\fR Subcommand"
332 .sp
333 .LP
334 The syntax for the \fBenable\fR subcommand is:
335 .sp
336 .in +2
337 .nf
338 # mpathadm disable [\fIoptions\fR]
339 .fi
340 .in -2
342 .sp
343 .LP
344 The \fBenable\fR subcommand supports the following direct-objects to be
345 enabled:
346 .sp
347 .ne 2
348 .na
349 \fB\fBpath\fR \fB-i\fR \fIinitiator-port-name\fR \fB-t\fR
350 \fItarget-port-name\fR\fR
351 .ad
352 .br
353 .na
354 \fB\fB-l\fR \fIlogical-unit-name\fR\fR
355 .ad
356 .sp .6
357 .RS 4n
358 The path that consists of the specified initiator port, target port, and
359 logical unit will be enabled.
360 .RE
362 .SS "\fBdisable\fR Subcommand"
363 .sp
364 .LP
365 The syntax for the \fBdisable\fR subcommand is:
366 .sp
367 .in +2
368 .nf
369 # mpathadm disable [\fIoptions\fR]
370 .fi
371 .in -2
373 .sp
374 .LP
375 The \fBdisable\fR subcommand supports the following direct-objects to be
376 disabled:
377 .sp
378 .ne 2
379 .na
380 \fB\fBpath\fR \fB-i\fR \fIinitiator-port-name\fR \fB-t\fR
381 \fItarget-port-name\fR\fR
382 .ad
383 .br
384 .na
385 \fB\fB-l\fR \fIlogical-unit-name\fR\fR
386 .ad
387 .sp .6
388 .RS 4n
389 The path that consists of the specified initiator port, target port, and
390 logical unit will be disabled.
391 .RE
393 .SS "\fBfailover\fR Subcommand"
394 .sp
395 .LP
396 The syntax for the \fBfailover\fR subcommand is:
397 .sp
398 .in +2
399 .nf
400 # mpathadm failover \fIdirect-object\fR [\fIoperand\fR]
401 .fi
402 .in -2
404 .sp
405 .LP
406 The \fBfailover\fR subcommand supports failover for the following
407 direct-objects:
408 .sp
409 .ne 2
410 .na
411 \fB{\fBlogical-unit\fR | \fBlu\fR} \fIlogical-unit-name\fR\fR
412 .ad
413 .sp .6
414 .RS 4n
415 The target port group will failover when the given logical-unit is asymmetric
416 and supports explicit state change. The currently active target port group will
417 be changed to the standby state and the standby target port group will be
418 active.
419 .RE
421 .SS "\fBoverride\fR Subcommand"
422 .sp
423 .LP
424 The syntax for the \fBoverride\fR subcommand is:
425 .sp
426 .in +2
427 .nf
428 # mpathadm override [\fIoptions\fR]
429 .fi
430 .in -2
432 .sp
433 .LP
434 The \fBoverride\fR subcommand controls whether or not the following
435 direct-objects override another:
436 .sp
437 .ne 2
438 .na
439 \fBpath {\fB-i\fR \fIinitiator-port-name\fR \fB-t\fR \fItarget-port-name\fR |
440 \fB-c\fR}\fR
441 .ad
442 .br
443 .na
444 \fB\fB-l\fR \fIlogical-unit-name\fR\fR
445 .ad
446 .sp .6
447 .RS 4n
448 Cause a path that consists of the specified initiator port, target port, and
449 logical unit to override other paths on the logical unit. Once a path overrides
450 other paths, the mpath-support uses only that path regardless of any other path
451 selection configuration. The \fB-c\fR option cancels the setting. The path that
452 consists of the specified initiator port, target port, and logical unit will be
453 disabled.
454 .sp
455 Options for override path are as follows:
456 .sp
457 .ne 2
458 .na
459 \fB\fB-i\fR, \fB-\fR\fB-initiator-port\fR \fIinitiator-port-name\fR\fR
460 .ad
461 .sp .6
462 .RS 4n
463 Represent the initiator port element of a path. Options \fB-t\fR and \fB-l\fR
464 must also be included.
465 .RE
467 .sp
468 .ne 2
469 .na
470 \fB\fB-t\fR, \fB-\fR\fB-target-port\fR \fItarget-port-name\fR\fR
471 .ad
472 .sp .6
473 .RS 4n
474 Represent the target port element of a path. Options \fB-i\fR and \fB-l\fR must
475 also be included.
476 .RE
478 .sp
479 .ne 2
480 .na
481 \fB\fB-l\fR, \fB-\fR\fB-logical-unit\fR \fIlogical-unit\fR\fR
482 .ad
483 .sp .6
484 .RS 4n
485 Represent the logical unit element of a path. Options \fB-i\fR and \fB-t\fR
486 must also be included.
487 .RE
489 .sp
490 .ne 2
491 .na
492 \fB\fB-c\fR, \fB-\fR\fB-cancel\fR\fR
493 .ad
494 .sp .6
495 .RS 4n
496 Cancels overriding setting for the given logical unit. Option \fB-l\fR must
497 also be included.
498 .RE
500 .RE
502 .SH OPTIONS
503 .sp
504 .LP
505 The following options are supported:
506 .sp
507 .ne 2
508 .na
509 \fB\fB-V\fR, \fB-\fR\fB-version\fR\fR
510 .ad
511 .RS 17n
512 Display the version information.
513 .RE
515 .sp
516 .ne 2
517 .na
518 \fB\fB-?\fR, \fB-\fR\fB-help\fR\fR
519 .ad
520 .RS 17n
521 Display context help. Can be used following an \fBmpathadm\fR command with no
522 arguments, following a subcommand, or following a subcommand direct-object
523 combination. Responds with help information appropriate for your entry. For
524 example, if you enter:
525 .sp
526 .in +2
527 .nf
528 # \fBmpathadm add mpath-support-help\fR
529 .fi
530 .in -2
531 .sp
533 \&... \fBmpathadm\fR responds with a display of the options available for that
534 combination of subcommand and direct-object.
535 .RE
537 .SH EXAMPLES
538 .LP
539 \fBExample 1 \fRObtaining a List of Multipathing Support
540 .sp
541 .LP
542 The following command uses the \fBlist\fR subcommand to list all currently
543 registered \fBmpath-support\fR libraries.
545 .sp
546 .in +2
547 .nf
548 # \fBmpathadm list mpath-support\fR
549 mpath-support: libmpscsi_vhci.so
550 .fi
551 .in -2
552 .sp
554 .LP
555 \fBExample 2 \fRDisplaying the Properties of a Particular Multipathing Support
556 .sp
557 .LP
558 The following command uses the \fBshow\fR subcommand to display the properties
559 for a currently registered \fBmpath-support\fR library.
561 .sp
562 .in +2
563 .nf
564 # \fBmpathadm show mpath-support libmpscsi_vhci.so\fR
565 mpath-support: libmpscsi_vhci.so
566 Vendor: Sun Microsystems
567 Driver Name: scsi_vhci
568 Default Load Balance: round-robin
569 Supported Load Balance Types:
570 round-robin
571 logical-block
572 Allows To Activate Target Port Group Access: yes
573 Allows Path Override: no
574 Supported Auto Failback Config: 1
575 Auto Failback: on
576 Failback Polling Rate (current/max): 0/0
577 Supported Auto Probing Config: 0
578 Auto Probing: NA
579 Probing Polling Rate (current/max): NA/NA
580 Supported Devices:
581 Vendor: SUN
582 Product: T300
583 Revision:
584 Supported Load Balance Types:
585 round-robin
586 Vendor: SUN
587 Product: T4
588 Revision:
589 Supported Load Balance Types:
590 round-robin
591 .fi
592 .in -2
593 .sp
595 .LP
596 \fBExample 3 \fRObtaining a List of Initiator Ports Discovered Through the
597 \fBmpath-support\fR Libraries
598 .sp
599 .LP
600 The following command uses the \fBlist initiator-port\fR subcommand to display
601 a list of initiator ports discovered by the currently registered
602 \fBmpath-support\fR libraries.
604 .sp
605 .in +2
606 .nf
607 # \fBmpathadm list initiator-port\fR
608 Initiator-Port: iqn.1986-03.com.sun:01:080020b7ac2b.437a3b3e,4000002a0000
609 Initiator-Port: 2000000173018713
610 Initiator-Port: 2000000173818713
611 .fi
612 .in -2
613 .sp
615 .LP
616 \fBExample 4 \fRDisplaying the Properties of a Particular Initiator Port
617 .sp
618 .LP
619 The following command uses the \fBshow initiator-port\fR subcommand to display
620 the properties of a particular initiator port discovered using the \fBlist
621 initiator-port\fR subcommand in an example above.
623 .sp
624 .in +2
625 .nf
626 # \fBmpathadm show initiator-port 2000000173018713\fR
627 initiator-port: 2000000173018713
628 Transport Type: Fibre Channel
629 OS device File: devices/pci@1f,4000/pci@2/SUNW,qlca@5/fp@0,0:fc
630 .fi
631 .in -2
632 .sp
634 .LP
635 \fBExample 5 \fRDisplaying the Properties of a Particular Logical Unit
636 .sp
637 .LP
638 The following command uses the \fBshow logical-unit\fR subcommand to display
639 the properties of the logical unit with the specified name.
641 .sp
642 .in +2
643 .nf
644 # \fBmpathadm show lu /dev/rdsk/c4t60003BA27D2120004204AC2B000DAB00d0s2\fR
645 Logical Unit: /dev/rdsk/c4t60003BA27D2120004204AC2B000DAB00d0s2
646 mpath-support libmpscsi_vhci.so
647 Vendor: SUN
648 Product: T4
649 Revision: 0301
650 Name Type: SCSI Inquiry VPD Page 83 type 3
651 Name: 60003ba27d2120004204ac2b000dab00
652 Asymmetric: yes
653 Current Load Balance: round-robin
654 Logical Unit Group ID: NA
655 Aauto Failback: on
656 Auto Probing: NA
658 Paths:
659 Initiator Port Name: 2000000173818713
660 Target Port Name: 20030003ba27d212
661 Override Path: NA
662 Path State: OK
663 Disabled: no
665 Initiator Port Name: 2000000173018713
666 Target Port Name: 20030003ba27d095
667 Override Path: NA
668 Path State: OK
669 Disabled: no
671 Target Port Group:
672 ID: 2
673 Explicit Failover: yes
674 Access State: standby
675 Target Ports:
676 Name: 20030003ba27d212
677 Relative ID: 0
679 ID: 5
680 Explicit Failover: yes
681 Access State: active
682 Target Ports
683 Name: 20030003ba27d095
684 Relative ID: 0
685 .fi
686 .in -2
687 .sp
689 .LP
690 \fBExample 6 \fREnabling a Path
691 .sp
692 .LP
693 The following command uses the \fBenable path\fR subcommand to enable the path
694 with the specified initiator port, target port, and logical unit.
696 .sp
697 .in +2
698 .nf
699 # \fBmpathadm enable path -i 2000000173018713 -t 20030003ba27d095 \e
700 -l /dev/rdsk/c4t60003BA27D2120004204AC2B000DAB00d0s2\fR
701 .fi
702 .in -2
703 .sp
705 .LP
706 \fBExample 7 \fRModifying \fBmpath-support\fR To Turn On \fBautofailback\fR
707 .sp
708 .in +2
709 .nf
710 # \fBmpathadm modify mpath-support -a on libmpscsi_vhci.so\fR
711 .fi
712 .in -2
713 .sp
715 .SH ATTRIBUTES
716 .sp
717 .LP
718 See \fBattributes\fR(5) for descriptions of the following attributes:
719 .sp
721 .sp
722 .TS
723 box;
724 c | c
725 l | l .
726 ATTRIBUTE TYPE ATTRIBUTE VALUE
727 _
728 Interface Stability Evolving
729 .TE
731 .SH SEE ALSO
732 .sp
733 .LP
734 \fBstmsboot\fR(1M), \fBlibMPAPI\fR(3LIB), \fBexec_attr\fR(4),
735 \fBattributes\fR(5)