| Current File : //usr/man/man1m/mpathadm.1m |
'\" te
.\" Copyright (c) 2006, 2014, Oracle and/or its affiliates. All rights reserved.
.TH mpathadm 1M "23 Apr 2014" "SunOS 5.11" "System Administration Commands"
.SH NAME
mpathadm \- multipath discovery and administration
.SH SYNOPSIS
.LP
.nf
\fBmpathadm\fR \fIsubcommand\fR \fIdirect-object\fR [\fIoptions\fR] [\fIoperand\fR]
.fi
.SH DESCRIPTION
.sp
.LP
The \fBmpathadm\fR command enables multipathing discovery and management. The \fBmpathadm\fR command is implemented as a set of subcommands, many with their own options, that are described in the section for that subcommand. Options not associated with a particular subcommand are described under OPTIONS. The \fBmpathadm\fR subcommands operate on a \fIdirect-object\fR. These are described in this section for each subcommand. The \fIdirect-objects\fR, \fIinitiator-port\fR, \fItarget-port\fR, and \fIlogical-unit\fR in the subcommands are consistent with SCSI standard definitions.
.sp
.LP
The \fBmpathadm\fR command supports the following subcommands, which are described in detail in subsections that follow.
.sp
.ne 2
.mk
.na
\fB\fBlist\fR\fR
.ad
.RS 12n
.rt
Display a list of discovered instances for a given object.
.RE
.sp
.ne 2
.mk
.na
\fB\fBshow\fR\fR
.ad
.RS 12n
.rt
Display information about a given object instance.
.RE
.sp
.ne 2
.mk
.na
\fB\fBmodify\fR\fR
.ad
.RS 12n
.rt
Modify properties of an object.
.RE
.sp
.ne 2
.mk
.na
\fB\fBenable\fR\fR
.ad
.RS 12n
.rt
Enable an object.
.RE
.sp
.ne 2
.mk
.na
\fB\fBdisable\fR\fR
.ad
.RS 12n
.rt
Disable an object.
.RE
.sp
.ne 2
.mk
.na
\fB\fBfailover\fR\fR
.ad
.RS 12n
.rt
Cause target port group failover for a logical-unit.
.RE
.sp
.ne 2
.mk
.na
\fB\fBoverride\fR\fR
.ad
.RS 12n
.rt
Set a path to be used over other paths on a logical-unit.
.RE
.sp
.LP
The \fBmpathadm\fR subcommands operate on a \fIdirect-object\fR. These are described in this section for each subcommand.
.SS "list Subcommand"
.sp
.LP
The syntax for the \fBlist\fR subcommand is:
.sp
.in +2
.nf
# mpathadm list \fIdirect-object\fR [\fIoperands\fR...]
.fi
.in -2
.sp
.LP
The \fBlist\fR subcommand displays data for following direct-objects:
.sp
.ne 2
.mk
.na
\fB\fBmpath-support\fR [\fImpath-support-name\fR, ...]\fR
.ad
.sp .6
.RS 4n
List the multipathing support that can be administered by this CLI. This presents itself in the form of a library name registered through the MPAPI framework. If no mpath-support name \fImpath-support-name\fR is specified, all registered multipathing support libraries will be displayed.
.RE
.sp
.ne 2
.mk
.na
\fB\fBinitiator-port\fR [\fIinitiator-port-name\fR, ...]\fR
.ad
.sp .6
.RS 4n
List the initiator ports that are discovered on this system. If no \fIinitiator-port-name\fR is specified, all discovered initiator ports are displayed.
.RE
.sp
.ne 2
.mk
.na
\fB{\fBlogical-unit\fR | \fBlu\fR} [\fIoptions\fR] [\fIlogical-unit-name\fR, \&...]\fR
.ad
.sp .6
.RS 4n
List the information on multipath logical units. If no \fIlogical-unit-name\fR is specified, all discovered logical-units will be displayed.
.sp
Options for \fBlist logical-unit\fR are as follows:
.sp
.ne 2
.mk
.na
\fB\fB-n\fR, \fB-\fR\fB-name\fR \fIname\fR\fR
.ad
.sp .6
.RS 4n
Return the logical unit name that is associated with the given name string. This name can be extracted from the output of the \fBmpathadm\fR \fBshow lu\fR command.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-t\fR, \fB-\fR\fB-target-port\fR \fItarget-port-name\fR\fR
.ad
.sp .6
.RS 4n
Return the list of logical units names that are associated with the given \fItarget-port-name\fR.
.RE
.RE
.SS "\fBshow\fR Subcommand"
.sp
.LP
The syntax for the \fBshow\fR subcommand is:
.sp
.in +2
.nf
# mpathadm show \fIdirect-object\fR [\fIoptions\fR] [\fIoperands\fR...]
.fi
.in -2
.sp
.LP
The \fBshow\fR subcommand displays detailed information for following the direct-objects:
.sp
.ne 2
.mk
.na
\fB\fBmpath-support\fR [\fImpath-support-name\fR, ...]\fR
.ad
.sp .6
.RS 4n
Show the detailed information on the given \fImpath-support-name\fR if the name exists. If the given \fImpath-support-name\fR supports only a limited set of device products, the list of device products will be listed as part of the output.
.RE
.sp
.ne 2
.mk
.na
\fB\fBinitiator-port\fR [\fIinitiator-port-name\fR, ...]\fR
.ad
.sp .6
.RS 4n
Show the detailed information for the given \fIinitiator-port-name\fR. If no \fIinitiator-port-name\fR is specified, all discovered initiator-ports will be displayed in detail.
.RE
.sp
.ne 2
.mk
.na
\fB{\fBlogical-unit\fR | \fBlu\fR} [\fIlogical-unit-name\fR, ...]\fR
.ad
.sp .6
.RS 4n
Display the detailed information on multipath logical unit(s), including path and target port group information. If no \fIlogical-unit-name\fR is specified, all discovered logical unit(s) will be displayed in detail. Note that the name property in the logical unit information represents the identifier for this LUN, derived from the hardware, and used by this system. If the name is derived from SCSI Inquiry Vital Product Data (VPD) page 83h, the name type property represents an associated identifier type defined by the SCSI standards.
.sp
Options for show logical-unit are as follows:
.sp
.ne 2
.mk
.na
\fB\fB-e\fR, \fB--path-missing\fR\fR
.ad
.RS 22n
.rt
Display overall discovered logical unit information with only missing paths.
.RE
.RE
.SS "\fBmodify\fR Subcommand"
.sp
.LP
The syntax for the \fBmodify\fR subcommand is:
.sp
.in +2
.nf
# mpathadm modify \fIdirect-object\fR [\fIoptions\fR] [\fIoperands\fR...]
.fi
.in -2
.sp
.LP
The \fBmodify\fR subcommand modifies characteristics of the following direct-objects:
.sp
.ne 2
.mk
.na
\fB\fBmpath-support\fR [\fIoptions\fR] \fImpath-support-name\fR, ...\fR
.ad
.sp .6
.RS 4n
Configuration management of an \fImpath-support\fR. Options to modify mpath-support are as follows:
.sp
.ne 2
.mk
.na
\fB\fB-a\fR, \fB-\fR\fB-autofailback\fR on | off\fR
.ad
.sp .6
.RS 4n
Set \fBautofailback\fR. Applicable only when mpath-support provides auto failback support.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-p\fR, \fB-\fR\fB-autoprobe\fR on | off\fR
.ad
.sp .6
.RS 4n
Set \fBautoprobing\fR. Applicable only when mpath-support provides auto probing support.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-b\fR, \fB-\fR\fB-loadbalance\fR loadbalance-type\fR
.ad
.sp .6
.RS 4n
Change the default load balance type. The \fBloadbalance\fR type is one of the supported types listed in the \fBshow mpath-support\fR output.
.RE
.RE
.sp
.ne 2
.mk
.na
\fB{\fBlogical-unit\fR | \fBlu\fR} [\fIoptions\fR] \fIlogical-unit-name\fR, \&...\fR
.ad
.sp .6
.RS 4n
Configuration management of a logical unit. Options to modify \fBlogical-unit\fR are as follows:
.sp
.ne 2
.mk
.na
\fB\fB-a\fR, \fB-\fR\fB-autofailback\fR on | off\fR
.ad
.sp .6
.RS 4n
Set \fBautofailback\fR. Applicable only when \fBmpath-support\fR provides auto failback support
.RE
.sp
.ne 2
.mk
.na
\fB\fB-p\fR, \fB-\fR\fB-autoprobe\fR on | off\fR
.ad
.sp .6
.RS 4n
Set \fBautoprobing\fR. Applicable only when \fBmpath-support\fR provides auto probing support.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-b\fR, \fB-\fR\fB-loadbalance\fR loadbalance-type\fR
.ad
.sp .6
.RS 4n
Set load balance type for the logical unit. Applicable only when load balance configuration is supported at the logical unit level.
.RE
.RE
.SS "\fBenable\fR Subcommand"
.sp
.LP
The syntax for the \fBenable\fR subcommand is:
.sp
.in +2
.nf
# mpathadm enable [\fIoptions\fR]
.fi
.in -2
.sp
.LP
The \fBenable\fR subcommand supports the following direct-objects to be enabled:
.sp
.ne 2
.mk
.na
\fB\fBpath\fR \fB-i\fR \fIinitiator-port-name\fR \fB-t\fR \fItarget-port-name\fR\fR
.ad
.br
.na
\fB\fB-l\fR \fIlogical-unit-name\fR\fR
.ad
.sp .6
.RS 4n
The path that consists of the specified initiator port, target port, and logical unit will be enabled.
.RE
.SS "\fBdisable\fR Subcommand"
.sp
.LP
The syntax for the \fBdisable\fR subcommand is:
.sp
.in +2
.nf
# mpathadm disable [\fIoptions\fR]
.fi
.in -2
.sp
.LP
The \fBdisable\fR subcommand supports the following direct-objects to be disabled:
.sp
.ne 2
.mk
.na
\fB\fBpath\fR \fB-i\fR \fIinitiator-port-name\fR \fB-t\fR \fItarget-port-name\fR\fR
.ad
.br
.na
\fB\fB-l\fR \fIlogical-unit-name\fR\fR
.ad
.sp .6
.RS 4n
The path that consists of the specified initiator port, target port, and logical unit will be disabled.
.RE
.SS "\fBfailover\fR Subcommand"
.sp
.LP
The syntax for the \fBfailover\fR subcommand is:
.sp
.in +2
.nf
# mpathadm failover \fIdirect-object\fR [\fIoperand\fR]
.fi
.in -2
.sp
.LP
The \fBfailover\fR subcommand supports failover for the following direct-objects:
.sp
.ne 2
.mk
.na
\fB{\fBlogical-unit\fR | \fBlu\fR} \fIlogical-unit-name\fR\fR
.ad
.sp .6
.RS 4n
The target port group will failover when the given logical-unit is asymmetric and supports explicit state change. The currently active target port group will be changed to the standby state and the standby target port group will be active. State of an unavailable target port group cannot be changed.
.RE
.SS "\fBoverride\fR Subcommand"
.sp
.LP
The syntax for the \fBoverride\fR subcommand is:
.sp
.in +2
.nf
# mpathadm override [\fIoptions\fR]
.fi
.in -2
.sp
.LP
The \fBoverride\fR subcommand controls whether or not the following direct-objects override another:
.sp
.ne 2
.mk
.na
\fBpath {\fB-i\fR \fIinitiator-port-name\fR \fB-t\fR \fItarget-port-name\fR | \fB-c\fR}\fR
.ad
.br
.na
\fB\fB-l\fR \fIlogical-unit-name\fR\fR
.ad
.sp .6
.RS 4n
Cause a path that consists of the specified initiator port, target port, and logical unit to override other paths on the logical unit. Once a path overrides other paths, the mpath-support uses only that path regardless of any other path selection configuration. The \fB-c\fR option cancels the setting. The path that consists of the specified initiator port, target port, and logical unit will be disabled.
.sp
Options for override path are as follows:
.sp
.ne 2
.mk
.na
\fB\fB-i\fR, \fB-\fR\fB-initiator-port\fR \fIinitiator-port-name\fR\fR
.ad
.sp .6
.RS 4n
Represent the initiator port element of a path. Options \fB-t\fR and \fB-l\fR must also be included.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-t\fR, \fB-\fR\fB-target-port\fR \fItarget-port-name\fR\fR
.ad
.sp .6
.RS 4n
Represent the target port element of a path. Options \fB-i\fR and \fB-l\fR must also be included.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-l\fR, \fB-\fR\fB-logical-unit\fR \fIlogical-unit\fR\fR
.ad
.sp .6
.RS 4n
Represent the logical unit element of a path. Options \fB-i\fR and \fB-t\fR must also be included.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-c\fR, \fB-\fR\fB-cancel\fR\fR
.ad
.sp .6
.RS 4n
Cancels overriding setting for the given logical unit. Option \fB-l\fR must also be included.
.RE
.RE
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-V\fR, \fB-\fR\fB-version\fR\fR
.ad
.RS 17n
.rt
Display the version information.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-?\fR, \fB-\fR\fB-help\fR\fR
.ad
.RS 17n
.rt
Display context help. Can be used following an \fBmpathadm\fR command with no arguments, following a subcommand, or following a subcommand direct-object combination. Responds with help information appropriate for your entry. For example, if you enter:
.sp
.in +2
.nf
# \fBmpathadm add mpath-support-help\fR
.fi
.in -2
.sp
\&... \fBmpathadm\fR responds with a display of the options available for that combination of subcommand and direct-object.
.RE
.SH EXAMPLES
.LP
\fBExample 1 \fRObtaining a List of Multipathing Support
.sp
.LP
The following command uses the \fBlist\fR subcommand to list all currently registered \fBmpath-support\fR libraries.
.sp
.in +2
.nf
# \fBmpathadm list mpath-support\fR
mpath-support: libmpscsi_vhci.so
.fi
.in -2
.sp
.LP
\fBExample 2 \fRDisplaying the Properties of a Particular Multipathing Support
.sp
.LP
The following command uses the \fBshow\fR subcommand to display the properties for a currently registered \fBmpath-support\fR library.
.sp
.in +2
.nf
# \fBmpathadm show mpath-support libmpscsi_vhci.so\fR
mpath-support: libmpscsi_vhci.so
Vendor: Sun Microsystems
Driver Name: scsi_vhci
Default Load Balance: round-robin
Supported Load Balance Types:
round-robin
logical-block
Allows To Activate Target Port Group Access: yes
Allows Path Override: no
Supported Auto Failback Config: 1
Auto Failback: on
Failback Polling Rate (current/max): 0/0
Supported Auto Probing Config: 0
Auto Probing: NA
Probing Polling Rate (current/max): NA/NA
Supported Devices:
Vendor: SUN
Product: T300
Revision:
Supported Load Balance Types:
round-robin
Vendor: SUN
Product: T4
Revision:
Supported Load Balance Types:
round-robin
.fi
.in -2
.sp
.LP
\fBExample 3 \fRObtaining a List of Initiator Ports Discovered Through the \fBmpath-support\fR Libraries
.sp
.LP
The following command uses the \fBlist initiator-port\fR subcommand to display a list of initiator ports discovered by the currently registered \fBmpath-support\fR libraries.
.sp
.in +2
.nf
# \fBmpathadm list initiator-port\fR
Initiator-Port: iqn.1986-03.com.sun:01:080020b7ac2b.437a3b3e,4000002a0000
Initiator-Port: 2000000173018713
Initiator-Port: 2000000173818713
.fi
.in -2
.sp
.LP
\fBExample 4 \fRDisplaying the Properties of a Particular Initiator Port
.sp
.LP
The following command uses the \fBshow initiator-port\fR subcommand to display the properties of a particular initiator port discovered using the \fBlist initiator-port\fR subcommand in an example above.
.sp
.in +2
.nf
# \fBmpathadm show initiator-port 2000000173018713\fR
initiator-port: 2000000173018713
Transport Type: Fibre Channel
OS device File: devices/pci@1f,4000/pci@2/SUNW,qlca@5/fp@0,0:fc
.fi
.in -2
.sp
.LP
\fBExample 5 \fRDisplaying the Properties of a Particular Logical Unit
.sp
.LP
The following command uses the \fBshow logical-unit\fR subcommand to display the properties of the logical unit with the specified name.
.sp
.in +2
.nf
# \fBmpathadm show lu /dev/rdsk/c4t60003BA27D2120004204AC2B000DAB00d0s2\fR
Logical Unit: /dev/rdsk/c4t60003BA27D2120004204AC2B000DAB00d0s2
mpath-support libmpscsi_vhci.so
Vendor: SUN
Product: T4
Revision: 0301
Name Type: SCSI Inquiry VPD Page 83 type 3
Name: 60003ba27d2120004204ac2b000dab00
Asymmetric: yes
Current Load Balance: round-robin
Logical Unit Group ID: NA
Aauto Failback: on
Auto Probing: NA
Paths:
Initiator Port Name: 2000000173818713
Target Port Name: 20030003ba27d212
Override Path: NA
Path State: OK
Disabled: no
Initiator Port Name: 2000000173018713
Target Port Name: 20030003ba27d095
Override Path: NA
Path State: OK
Disabled: no
Target Port Group:
ID: 2
Explicit Failover: yes
Access State: standby
Target Ports:
Name: 20030003ba27d212
Relative ID: 0
ID: 5
Explicit Failover: yes
Access State: active
Target Ports
Name: 20030003ba27d095
Relative ID: 0
.fi
.in -2
.sp
.LP
\fBExample 6 \fREnabling a Path
.sp
.LP
The following command uses the \fBenable path\fR subcommand to enable the path with the specified initiator port, target port, and logical unit.
.sp
.in +2
.nf
# \fBmpathadm enable path -i 2000000173018713 -t 20030003ba27d095 \e
-l /dev/rdsk/c4t60003BA27D2120004204AC2B000DAB00d0s2\fR
.fi
.in -2
.sp
.LP
\fBExample 7 \fRModifying \fBmpath-support\fR To Turn On \fBautofailback\fR
.sp
.in +2
.nf
# \fBmpathadm modify mpath-support -a on libmpscsi_vhci.so\fR
.fi
.in -2
.sp
.LP
\fBExample 8 \fRDisplaying the Overall Information About Host Initiator Port
.sp
.LP
The following command displays the overall information about host initiator port.
.sp
.in +2
.nf
# \fBmpathadm show initiator-port\fR
Initiator Port: 210100e08ba41feb
Transport Type: Fibre Channel
OS Device File: /devices/pci@1,0/pci1022,7450@1/pci1077,141@2,1/fp@0,0
Initiator Port: iqn.1986-03.com.sun:01:ffffffffffff.519c6677,4000002a00ff
Transport Type: iSCSI
OS Device File: /devices/iscsi
.fi
.in -2
.sp
.LP
\fBExample 9 \fRDisplaying the Overall Information About the Logical Unit With Only Missing Paths
.sp
.LP
The following command displays the overall information about the logical unit with only missing paths.
.sp
.in +2
.nf
# mpathadm show lu -e
Logical Unit: /dev/rdsk/c0t600A0B800026D63A000091344DBF39C4d0s2
mpath-support: libmpscsi_vhci.so
Vendor: SUN
Product: CSM200_R
Revision: 0660
Name Type: unknown type
Name: 600a0b800026d63a000091344dbf39c4
Asymmetric: yes
Current Load Balance: round-robin
Logical Unit Group ID: NA
Auto Failback: on
Auto Probing: NA
Paths:
Initiator Port Name: 210100e08ba41feb
Target Port Name: 200900a0b826d63b
Override Path: NA
Path State: OK
Disabled: no
Initiator Port Name: 210100e08ba41feb
Target Port Name: 200800a0b826d63c
Override Path: NA
Path State: unavailable
Disabled: no
Target Port Groups:
ID: 1
Explicit Failover: yes
Access State: active
Target Ports:
Name: 200900a0b826d63b
Relative ID: 0
ID: 3
Explicit Failover: yes
Access State: unavailable
Target Ports:
Name: 200800a0b826d63c
Relative ID: 0
.fi
.in -2
.sp
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i)
lw(2.75i) |lw(2.75i)
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/storage/multipath-utilities
_
T{
system/library/storage/libmpapi (\fBexec_attr\fR(4) entry)
T}
_
Interface StabilityCommitted
_
CLI OutputNot an interface
.TE
.SH SEE ALSO
.sp
.LP
\fBstmsboot\fR(1M), \fBlibMPAPI\fR(3LIB), \fBexec_attr\fR(4), \fBattributes\fR(5)