diff options
Diffstat (limited to 'usr/src/man/man8/stmsboot.8')
| -rw-r--r-- | usr/src/man/man8/stmsboot.8 | 407 |
1 files changed, 407 insertions, 0 deletions
diff --git a/usr/src/man/man8/stmsboot.8 b/usr/src/man/man8/stmsboot.8 new file mode 100644 index 0000000000..ec0184040f --- /dev/null +++ b/usr/src/man/man8/stmsboot.8 @@ -0,0 +1,407 @@ +'\" te +.\" Copyright 2008 Sun Microsystems, Inc. All Rights reserved. Use is subject to license terms. +.\" 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. +.\" 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. +.\" 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] +.TH STMSBOOT 8 "Dec 15, 2008" +.SH NAME +stmsboot \- administration program for the Solaris I/O multipathing feature +.SH SYNOPSIS +.LP +.nf +\fB/usr/sbin/stmsboot\fR [[\fB-d\fR | \fB-e\fR [\fB-D\fR (fp | mpt) ]] + | \fB-u\fR | \fB-L\fR | \fB-l\fR \fIcontroller_number\fR] +.fi + +.SH DESCRIPTION +.sp +.LP +The Solaris I/O multipathing feature is a multipathing solution for storage +devices that is part of the Solaris operating environment. This feature was +formerly known as Sun StorEdge Traffic Manager (STMS) or MPxIO. +.sp +.LP +The \fBstmsboot\fR program is an administrative command to manage enumeration +of multipath-capable devices with Solaris I/O multipathing. Solaris I/O +multipathing-enabled devices are enumerated under \fBscsi_vhci\fR(4D), +providing multipathing capabilities. Solaris I/O multipathing-disabled devices +are enumerated under the physical controller. +.sp +.LP +In the \fB/dev\fR and \fB/devices\fR trees, Solaris I/O multipathing-enabled +devices receive new names that indicate that they are under Solaris I/O +multipathing control. This means a device will have a different name from its +original name (after enabling) when it is under Solaris I/O multipathing +control. The \fBstmsboot\fR command automatically updates \fB/etc/vfstab\fR and +dump configuration to reflect the device names changes when enabling or +disabling Solaris I/O multipathing. One reboot is required for changes to take +effect. +.SH OPTIONS +.sp +.LP +The following options are supported: +.sp +.ne 2 +.na +\fB\fB-e\fR [ \fB-D\fR \fBfp | mpt\fR ]\fR +.ad +.sp .6 +.RS 4n +Enables Solaris I/O multipathing on all supported multipath-capable controller +ports. Multipath-capable ports include fibre channel (\fBfp\fR(4D)) controller +ports and SAS (\fBmpt\fR(4D)) controller ports. Following this enabling, you +are prompted to reboot. During the reboot, \fBvfstab\fR and the dump +configuration will be updated to reflect the device name changes. Specifying +either \fB-D\fR \fBmpt\fR or \fB-D\fR \fBfp\fR limits the enabling operation to +ports attached using the specified driver. +.RE + +.sp +.ne 2 +.na +\fB\fB-d\fR [ \fB-D\fR \fBfp | mpt\fR ]\fR +.ad +.sp .6 +.RS 4n +Disables Solaris I/O multipathing on all supported multipath-capable controller +ports. Multipath-capable ports include fibre channel (\fBfp\fR(4D)) controller +ports and SAS (\fBmpt\fR(4D)) controller ports. Following this disabling, you +are prompted to reboot. During the reboot, \fBvfstab\fR and the dump +configuration will be updated to reflect the device name changes. Specifying +either \fB-D\fR \fBmpt\fR or \fB-D\fR \fBfp\fR limits the disabling operation +to ports attached using the specified driver. +.RE + +.sp +.ne 2 +.na +\fB\fB-u\fR\fR +.ad +.sp .6 +.RS 4n +Updates \fBvfstab\fR and the dump configuration after you have manually +modified the configuration to have Solaris I/O multipathing enabled or disabled +on specific multipath-capable controller ports. This option prompts you to +reboot. During the reboot, \fBvfstab\fR and the dump configuration will be +updated to reflect the device name changes. +.RE + +.sp +.ne 2 +.na +\fB\fB-L\fR\fR +.ad +.sp .6 +.RS 4n +Display the device name changes from non-Solaris I/O multipathing device names +to Solaris I/O multipathing device names for multipath-enabled controller +ports. If Solaris I/O multipathing is not enabled, then no mappings are +displayed. +.RE + +.sp +.ne 2 +.na +\fB\fB-l\fR \fIcontroller_number\fR\fR +.ad +.sp .6 +.RS 4n +Display the device name changes from non-Solaris I/O multipathing device names +to Solaris I/O multipathing device names for the specified controller. If +Solaris I/O multipathing is not enabled, then no mappings are displayed. +.RE + +.SH USAGE +.sp +.LP +The primary function of \fBstmsboot\fR is to control the enabling and disabling +of Solaris I/O multipathing on the host. The utility automatically updates +\fBvfstab\fR(5) and \fBdumpadm\fR(8) configuration to reflect device name +changes. The system administrator is responsible for modifying application +configuration (for example, backup software, DBMS, and so forth) to reflect +updated device names. +.sp +.LP +The \fB-L\fR and \fB-l\fR options display the mapping between multipathed and +non-multipathed device names. These options function only after changes to the +Solaris I/O multipathing configuration have taken effect, that is, following +the reboot after invoking \fBstmsboot\fR \fB-e\fR. +.sp +.LP +ZFS datasets, including ZFS root datasets, are correctly handled by +\fBstmsboot\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fREnabling Solaris I/O Multipathing +.sp +.LP +To enable Solaris I/O multipathing for all multipath-capable controllers, run: + +.sp +.in +2 +.nf +# \fBstmsboot -e\fR +.fi +.in -2 +.sp + +.sp +.LP +To enable Solaris I/O multipathing on multipath-capable \fBmpt\fR(4D) +controller ports, enter: + +.sp +.in +2 +.nf +# \fBstmsboot -D mpt -e\fR +.fi +.in -2 +.sp + +.sp +.LP +To enable Solaris I/O Multipathing on multipath-capable fibre channel +controller ports, enter: + +.sp +.in +2 +.nf +# \fBstmsboot -D fp -e\fR +.fi +.in -2 +.sp + +.LP +\fBExample 2 \fRDisabling Solaris I/O Multipathing +.sp +.LP +To disable Solaris I/O multipathing on all multipath-capable controllers, +enter: + +.sp +.in +2 +.nf +# \fBstmsboot -d\fR +.fi +.in -2 +.sp + +.sp +.LP +To disable Solaris I/O multipathing on multipath-capable \fBmpt\fR(4D) +controller ports, enter: + +.sp +.in +2 +.nf +# \fBstmsboot -D mpt -d\fR +.fi +.in -2 +.sp + +.sp +.LP +To disable Solaris I/O multipathing on multipath-capable fibre channel +controller ports, enter: + +.sp +.in +2 +.nf +# \fBstmsboot -D fp -d\fR +.fi +.in -2 +.sp + +.LP +\fBExample 3 \fREnabling Solaris I/O Multipathing on Selected Ports +.sp +.LP +To enable Solaris I/O multipathing on specific fibre channel controller ports +and disable the feature on others, manually edit the \fB/kernel/drv/fp.conf\fR +file. (See \fBfp\fR(4D).) The following command will update \fBvfstab\fR(5) and +\fBdumpadm\fR(8) configurations to reflect the changed device names: + +.sp +.in +2 +.nf +# \fBstmsboot -u\fR +.fi +.in -2 +.sp + +.sp +.LP +A similar procedure involving the \fB/kernel/drv/mpt.conf\fR file should be +followed for devices attached by means of the \fBmpt\fR(4D) driver. + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(7) for descriptions of the following attributes: +.sp + +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Obsolete +.TE + +.SH SEE ALSO +.sp +.LP +.BR emlxs (4D), +.BR fcp (4D), +.BR fp (4D), +.BR mpt (4D), +.BR qlc (4D), +.BR scsi_vhci (4D), +.BR dumpdates (5), +.BR vfstab (5), +.BR dumpadm (8), +.BR fsck (8), +.BR mpathadm (8), +.BR ufsdump (8), +.BR zfs (8), +.BR zpool (8) +.sp +.LP +\fISolaris SAN Configuration and Multipathing Guide\fR (see +\fBhttp://docs.sun.com\fR) +.sp +.LP +Consult a particular storage product's system administrator's guide and release +notes for further information specific to that product. +.SH NOTES +.sp +.LP +Solaris I/O multipathing is not supported on all devices. After enabling +Solaris I/O multipathing, only supported devices are placed under Solaris I/O +multipathing control. Non-supported devices remain unchanged. +.sp +.LP +For Solaris releases prior to the current release, the \fB-e\fR and \fB-d\fR +options replace \fBmpxio-disable\fR property entries with a global +\fBmpxio-disable\fR entry in \fBfp.conf\fR. +.SS "Enabling Solaris I/O Multipathing on a Sun StorEdge Disk Array" +.sp +.LP +The following applies to Sun StoreEdge T3, 3910, 3960, 6120, and 6320 storage +subsystems. +.sp +.LP +To place your Sun StorEdge disk subsystem under Solaris I/O multipathing +control, in addition to enabling Solaris I/O multipathing, the \fBmp_support\fR +of the subsystem must be set to \fBmpxio\fR mode. The preferred sequence is to +change the subsystem's \fBmp_support\fR to \fBmpxio\fR mode, then run +\fBstmsboot\fR \fB-e\fR. If Solaris I/O multipathing is already enabled but the +subsystem's \fBmp_support\fR is not in \fBmpxio\fR mode, then change the +\fBmp_support\fR to \fBmpxio\fR mode and run \fBstmsboot\fR \fB-u\fR. +.sp +.LP +Refer to the \fISun StorEdge Administrator's Guide\fR for your subsystem for +more details. +.SS "Using \fBufsdump\fR" +.sp +.LP +The \fBufsdump\fR(8) command records details of filesystem dumps in +\fB/etc/dumpdates\fR (see \fBdumpdates\fR(5)). Among other items, the entries +contain device names. An effect of the "active" \fBstmsboot\fR options +(\fB-e\fR, \fB-d\fR, and \fB-u\fR) is to change the device name of a storage +device. +.sp +.LP +Because \fBstmsboot\fR does not modify \fBdumpdates\fR, entries will refer to +obsolete device names, that is, device names that were in effect before Solaris +I/O multipathing configuration changes were performed. In this situation +\fBufsdump\fR will behave as if no previous dump of the filesystem had been +performed. A level 0 dump will be performed. +.SS "Procedure to Use \fBstmsboot\fR in Conjunction with Sun Cluster" +.sp +.LP +If possible, invoke \fBstmsboot\fR \fB-e\fR before installing Sun Cluster +software. After executing \fBstmsboot\fR, install Sun Cluster software +normally. +.sp +.LP +If Sun Cluster software is installed before executing \fBstmsboot\fR, follow +this procedure: +.sp +.LP +On each machine in the cluster where Solaris I/O multipathing is required, +execute: +.sp +.in +2 +.nf +# \fBstmsboot -e\fR +.fi +.in -2 +.sp + +.sp +.LP +\&...and allow the system to reboot. +.sp +.LP +When the system comes up, enter the following two commands: +.RS +4 +.TP +1. +# \fB/usr/cluster/bin/scdidadm -C\fR +.RE +.RS +4 +.TP +2. +# \fB/usr/cluster/bin/scdidadm -r\fR +.sp +The preceding commands update \fBdid\fR mappings with new device names while +preserving \fBdid\fR instance numbers for disks that are connected to multiple +cluster nodes. \fBdid\fR instance numbers of the local disks might not be +preserved. For this reason, the \fBdid\fR disk names for local disks might +change. +.RE +.RS +4 +.TP +3. +Update \fB/etc/vfstab\fR to reflect any new \fBdid\fR disk names for your +local disks. +.RE +.RS +4 +.TP +4. +Reboot the system. +.RE +.sp +.LP +To disable the Solaris multipathing feature, use \fBstmsboot\fR \fB-d\fR +(instead of \fBstmsboot\fR \fB-e\fR), then follow the procedure above. +.sp +.LP +To view mappings between the old and new device names, run \fBstmsboot\fR +\fB-L\fR. To view \fBdid\fR device name mappings, run +\fB/usr/cluster/bin/scdidadm\fR \fB-L\fR. +.sp +.LP +With active-passive storage arrays, it is possible that while your host is +rebooting the array controller could failover the path that a particular target +is using. In this scenario, \fBfsck\fR(8) will fail to open the physical path +listed in \fB/etc/vfstab\fR. The \fBsvc:/system/filesystem/local:default\fR SMF +service will transition to a maintenance state as a result. To rectify this, +consult the documentation for your storage array to failback the path. The +\fBmpathadm\fR(8) can assist with determining the active and passive path(s). +.SH LIMITATIONS +.sp +.LP +On x86 platforms, the current Solaris release does not support disabling +Solaris I/O multipathing of boot devices attached by means of fibre channel. +Solaris I/O multipathing is always enabled for supported fibre channel-attached +boot devices. Disabling Solaris I/O multipathing in this situation must be +performed on a per-port basis. See \fBfp\fR(4D). +.sp +.LP +Executing \fBdevfsadm\fR \fB-C\fR removes obsolete device entries that +\fBstmsboot\fR relies on. This will prevent correct operation of the \fB-d\fR +option for boot devices (regardless of platform type) and the \fB-L\fR option. |