'\" 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 1M "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(7D),
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(7D)) controller
ports and SAS (\fBmpt\fR(7D)) 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(7D)) controller
ports and SAS (\fBmpt\fR(7D)) 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(4) and \fBdumpadm\fR(1M) 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(7D)
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(7D)
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(7D).) The following command will update \fBvfstab\fR(4) and
\fBdumpadm\fR(1M) 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(7D) driver.

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) 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
\fBdumpadm\fR(1M), \fBfsck\fR(1M), \fBmpathadm\fR(1M), \fBufsdump\fR(1M),
\fBzfs\fR(1M), \fBzpool\fR(1M), \fBdumpdates\fR(4), \fBvfstab\fR(4),
\fBemlxs\fR(7D), \fBfcp\fR(7D), \fBfp\fR(7D), \fBmpt\fR(7D), \fBqlc\fR(7D),
\fBscsi_vhci\fR(7D)
.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(1M) command records details of filesystem dumps in
\fB/etc/dumpdates\fR (see \fBdumpdates\fR(4)). 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(1M) 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(1M) 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(7D).
.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.