Tribblix: manual page: stmsboot.8

STMSBOOT(8) Maintenance Commands and Procedures STMSBOOT(8)

NAME

stmsboot - administration program for the Solaris I/O multipathing
feature

SYNOPSIS

/usr/sbin/stmsboot [[-d | -e [-D (fp | mpt) ]]
| -u | -L | -l controller_number]

DESCRIPTION

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.

The stmsboot 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 scsi_vhci(4D), providing multipathing capabilities. Solaris I/O
multipathing-disabled devices are enumerated under the physical
controller.

In the /dev and /devices 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 stmsboot command automatically updates
/etc/vfstab 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.

OPTIONS

The following options are supported:

-e [ -D fp | mpt ]

Enables Solaris I/O multipathing on all supported multipath-
capable controller ports. Multipath-capable ports include fibre
channel (fp(4D)) controller ports and SAS (mpt(4D)) controller
ports. Following this enabling, you are prompted to reboot.
During the reboot, vfstab and the dump configuration will be
updated to reflect the device name changes. Specifying either -D
mpt or -D fp limits the enabling operation to ports attached
using the specified driver.

-d [ -D fp | mpt ]

Disables Solaris I/O multipathing on all supported multipath-
capable controller ports. Multipath-capable ports include fibre
channel (fp(4D)) controller ports and SAS (mpt(4D)) controller
ports. Following this disabling, you are prompted to reboot.
During the reboot, vfstab and the dump configuration will be
updated to reflect the device name changes. Specifying either -D
mpt or -D fp limits the disabling operation to ports attached
using the specified driver.

-u

Updates vfstab 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,
vfstab and the dump configuration will be updated to reflect the
device name changes.

-L

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.

-l controller_number

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.

USAGE

The primary function of stmsboot is to control the enabling and
disabling of Solaris I/O multipathing on the host. The utility
automatically updates vfstab(5) and dumpadm(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.

The -L and -l 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 stmsboot -e.

ZFS datasets, including ZFS root datasets, are correctly handled by
stmsboot.

EXAMPLES

Example 1: Enabling Solaris I/O Multipathing

To enable Solaris I/O multipathing for all multipath-capable
controllers, run:

# stmsboot -e

To enable Solaris I/O multipathing on multipath-capable mpt(4D)
controller ports, enter:

# stmsboot -D mpt -e

To enable Solaris I/O Multipathing on multipath-capable fibre channel
controller ports, enter:

# stmsboot -D fp -e

Example 2: Disabling Solaris I/O Multipathing

To disable Solaris I/O multipathing on all multipath-capable
controllers, enter:

# stmsboot -d

To disable Solaris I/O multipathing on multipath-capable mpt(4D)
controller ports, enter:

# stmsboot -D mpt -d

To disable Solaris I/O multipathing on multipath-capable fibre
channel controller ports, enter:

# stmsboot -D fp -d

Example 3: Enabling Solaris I/O Multipathing on Selected Ports

To enable Solaris I/O multipathing on specific fibre channel
controller ports and disable the feature on others, manually edit the
/kernel/drv/fp.conf file. (See fp(4D).) The following command will
update vfstab(5) and dumpadm(8) configurations to reflect the changed
device names:

# stmsboot -u

A similar procedure involving the /kernel/drv/mpt.conf file should be
followed for devices attached by means of the mpt(4D) driver.

ATTRIBUTES

NOTES

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.

For Solaris releases prior to the current release, the -e and -d
options replace mpxio-disable property entries with a global mpxio-
disable entry in fp.conf.

Enabling Solaris I/O Multipathing on a Sun StorEdge Disk Array
The following applies to Sun StoreEdge T3, 3910, 3960, 6120, and 6320
storage subsystems.

To place your Sun StorEdge disk subsystem under Solaris I/O
multipathing control, in addition to enabling Solaris I/O
multipathing, the mp_support of the subsystem must be set to mpxio
mode. The preferred sequence is to change the subsystem's mp_support
to mpxio mode, then run stmsboot -e. If Solaris I/O multipathing is
already enabled but the subsystem's mp_support is not in mpxio mode,
then change the mp_support to mpxio mode and run stmsboot -u.

Refer to the Sun StorEdge Administrator's Guide for your subsystem
for more details.

Using ufsdump

The ufsdump(8) command records details of filesystem dumps in
/etc/dumpdates (see dumpdates(5)). Among other items, the entries
contain device names. An effect of the "active" stmsboot options (-e,
-d, and -u) is to change the device name of a storage device.

Because stmsboot does not modify dumpdates, 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 ufsdump will behave as if no previous dump of the
filesystem had been performed. A level 0 dump will be performed.

Procedure to Use stmsboot in Conjunction with Sun Cluster
If possible, invoke stmsboot -e before installing Sun Cluster
software. After executing stmsboot, install Sun Cluster software
normally.

If Sun Cluster software is installed before executing stmsboot,
follow this procedure:

On each machine in the cluster where Solaris I/O multipathing is
required, execute:

# stmsboot -e

...and allow the system to reboot.

When the system comes up, enter the following two commands:

1. # /usr/cluster/bin/scdidadm -C

2. # /usr/cluster/bin/scdidadm -r

The preceding commands update did mappings with new device
names while preserving did instance numbers for disks that
are connected to multiple cluster nodes. did instance
numbers of the local disks might not be preserved. For
this reason, the did disk names for local disks might
change.

3. Update /etc/vfstab to reflect any new did disk names for
your local disks.

4. Reboot the system.

To disable the Solaris multipathing feature, use stmsboot -d (instead
of stmsboot -e), then follow the procedure above.

To view mappings between the old and new device names, run stmsboot
-L. To view did device name mappings, run /usr/cluster/bin/scdidadm
-L.

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, fsck(8) will fail to
open the physical path listed in /etc/vfstab. The
svc:/system/filesystem/local:default 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
mpathadm(8) can assist with determining the active and passive
path(s).

LIMITATIONS

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 fp(4D).

Executing devfsadm -C removes obsolete device entries that stmsboot
relies on. This will prevent correct operation of the -d option for
boot devices (regardless of platform type) and the -L option.

December 15, 2008 STMSBOOT(8)