Manpage of EMC powermt-- PowerPath 4.x Management Utility

User Commands powermt(1)

NAME
powermt - PowerPath 4.x Management Utility

SYNOPSIS
powermt check [class={symm|clariion|hitachi|hpxp|ess|all}] [force]
[hba=hba#|all] [dev=path|device|all]

powermt check_registration

powermt config

powermt display|watch [paths|ports]
[class={symm|clariion|hitachi|hpxp|ess|all}] [every=seconds]
powermt display|watch [ports] [dev=device|all]
[class={symm|clariion|hitachi|hpxp|ess|all}] [every=seconds]

powermt display options

powermt display unmanaged

powermt load [class={symm|clariion|hitachi|hpxp|ess|all}]
[file=pathname]

powermt manage {dev=device|class={hitachi|hpxp|ess}}

powermt remove [class={symm|clariion|hitachi|hpxp|ess|all}] [force]
hba=hba#|all | dev=path|device|all
powermt remove [class={symm|clariion|hitachi|hpxp|ess|all}] [force]
hba=hba#|all dev=path|device|all

powermt restore [class={symm|clariion|hitachi|hpxp|ess|all}] [force]
[hba=hba#|all] [dev=path|device|all]

powermt save [file=pathname]

powermt set periodic_autorestore=on|off
[class={symm|clariion|hitachi|hpxp|ess|all}]

powermt set mode=active|standby
[class={symm|clariion|hitachi|hpxp|ess|all}]
[hba=hba#|all] [dev=path|device|all]

powermt set policy=policy [class={symm|clariion|hitachi|hpxp|ess|all}]
[dev=device|all]

powermt set priority=priority# [class={symm|clariion|hitachi|hpxp|ess|all}]
[dev=device|all]

powermt set transparent=on|off [dev=device|all]

powermt set write_throttle=on|off [class=symm] [dev=device|all]

SunOS 5.8 Last change: January, 2004 1

User Commands powermt(1)

powermt set write_throttle_queue=queue_depth#
[class=symm] [dev=path|device|all]

powermt unmanage {dev=device|class={hitachi|hpxp|ess}}

powermt update lun_names

powermt version

DESCRIPTION
The powermt utility is used to configure and restore paths
to logical devices, validate and check logical device serial
numbers, display information about HBAs and PowerPath
devices, and set load-balancing and failover policies.

A logical device is the smallest addressable storage unit.
An entity managed and presented by a storage system, a
logical device comprises one or more physical disks or
sections of physical disks.

A PowerPath device is created by PowerPath for each logical
device discovered by the PowerPath driver. There is a one-
to-one relationship between a PowerPath device and a logical
device. A PowerPath device is also referred to as a pseudo
device.

In contrast, a native device is created by the operating
system to represent and provide access to a logical device.
The device is "native" in that it is provided by the
operating system.

In PowerPath, an I/O path, or path, refers to the route
travelled by data between a host and a logical device. A
path comprises an HBA, one or more cables, a switch or hub
(Fibre Channel only), a storage system interface and port,
and a logical device. Typically, a native device represents
a single path to a logical device.

Prerequisites to Executing powermt
By default, the PowerPath installation process sets the file
permissions so that only the superuser (root) can run
powermt. You can allow other users to run powermt by
changing access permissions on the powermt command, by
setting the setuid/setgid bits.

Executing powermt
To run powermt, type any of the commands listed in
"SYNOPSIS" at the shell prompt.

dev Argument Specification
Several powermt commands have a dev argument. Depending on
the command, this argument can specify a logical device or a

SunOS 5.8 Last change: January, 2004 2

User Commands powermt(1)

path.

dev acts on paths in the following commands:

powermt check
powermt remove
powermt restore
powermt set mode
powermt set write_throttle_queue (acts on ports associated
with paths)

dev acts on logical devices in the following commands:

powermt display
powermt manage
powermt set policy
powermt set priority
powermt set transparent
powermt set write_throttle
powermt unmanage

You can specify either a PowerPath device or a native/path
device in the dev argument. The dev argument is context
specific. powermt interprets the meaning of the argument
based on the context of the command being executed:

For commands that act on paths, specifying a PowerPath
device causes the command to be applied to all paths
associated with the device; specifying an associated
native/path device causes the command to be applied
only to that path.

For commands that act on logical devices, you can
specify the logical device using either the PowerPath
device or any of the native/path devices associated
with that logical device.

Correct dev arguments are as follows:

AIX

To specify a device
hdiskpower# or #

To specify a path
hdisk#

Examples
hdiskpower3, 3, hdisk3

HP-UX

SunOS 5.8 Last change: January, 2004 3

User Commands powermt(1)

To specify a device
N/A

To specify a path
c#t#d#

Examples
c1t2d2

Solaris

To specify a device
emcpower#[a-h] or #

To specify a path
c#t#d#[s0-s7]

Examples
emcpower2a, 2, c1t1d1

COMMANDS
powermt check [class={symm|clariion|hitachi|hpxp|ess|all}] [force]
[hba=hba#|all] [dev=path|device|all]

powermt check checks specified paths and, if desired, removes from
the PowerPath configuration any paths marked dead.

If a path is marked dead or the serial numbers encoded
in the path configuration information do not match the
serial numbers on the logical device, powermt check
prompts you to remove the path:

Warning: storage_system I/O path path_name is dead.
Do you want to remove it (y/n/a/q)?

Valid responses are:

y Remove the dead path, and continue checking
remaining paths.

n Do not remove the path, but continue checking
remaining paths.

a Remove the dead path and any subsequent paths
marked dead.

q Do not remove the dead path, and exit the command.
Any paths that were already removed remain
removed.

If the PowerPath license is invalid, powermt check
issues a warning and continues its processing. Use

SunOS 5.8 Last change: January, 2004 4

User Commands powermt(1)

powermt check_registration to determine the problem
with the PowerPath license.

Arguments

class={symm|clariion|hitachi|hpxp|ess|all}
Limits the command to the specified type of
storage system. all specifies all storage-system
types. The default is all. (You can change the
default using the PP_DEFAULT_STORAGE_SYS
environment variable.)

If class is specified along with hba and/or dev,
the command is applied to paths that meet all
specified constraints.

force
Suppresses the confirmation prompt and silently
removes all paths marked dead.

hba=hba#|all
Limits the check to paths from the specified HBA.
hba# is a number in the Host Bus Adapters ###
column of powermt display output. all specifies
all HBAs under PowerPath control. The default is
all.

(adapter can be used instead of hba. adapter is
included only for compatibility with prior
PowerPath releases. Use hba instead.)

dev=path|device|all
Limits the check to the specified path or all
paths to the specified PowerPath device. all
specifies all paths to all devices. The default is
all.

powermt check_registration

powermt check_registration checks the state of the
PowerPath license on a host.

powermt check_registration determines whether the host
has:

- A valid permanent license or evaluation license
- An expired evaluation license
- An invalid or corrupt license
- No license

Evaluation licenses provide the same functionality as
permanent licenses, but an evaluation license expires

SunOS 5.8 Last change: January, 2004 5

User Commands powermt(1)

on the last day of a specified month.

powermt check_registration displays output like the
following:

Key number
Product: PowerPath
Capabilities: license - storage_systems

where number is your 24-digit registration key, license
is your license type and storage_systems is a list of
the storage systems on which this license is valid (for
example, CLARiiON).

For an evaluation license, powermt check_registration
also outputs a line like this:

Expires: month, year

For an expired license, powermt check_registration also
outputs a line like this:

Expired: month, year

If the license is expired or there is no license:

- No powermt set commands can be executed.

- powermt save cannot be executed.

At boot time, the load balancing and failover policy is
set as follows:

- Symmetrix optimization. Set for Symmetrix storage
systems on platforms with a valid PowerPath license.

- CLARiiON optimization. Set for CLARiiON storage
systems on platforms with a valid PowerPath license.

- Adaptive. Set for Hitachi Lightning, HP xp, and IBM
ESS storage systems on platforms with a valid PowerPath
license.

- no redirect. Set for Symmetrix, Hitachi Lightning, HP
xp, and IBM ESS storage systems on platforms without a
valid PowerPath license.

- basic failover. Set for CLARiiON storage systems on
platforms without a valid PowerPath license.

powermt config

SunOS 5.8 Last change: January, 2004 6

User Commands powermt(1)

powermt config configures all detected Symmetrix and
CLARiiON logical devices as PowerPath devices and adds
these devices to the PowerPath configuration.

powermt config also configures all detected third-party
array logical devices as PowerPath devices if their
storage array classes are set to managed.

powermt config creates devices as required on AIX and
Solaris platforms. (On HP-UX platforms, PowerPath uses
only existing, native devices.)

powermt config also configures all detected paths to
PowerPath devices and adds these paths to the PowerPath
configuration.

powermt config does not remove previously configured
paths when they become dead paths.

powermt config adds paths to logical devices based on
the storage-system frame serial number and the logical
device serial number. Together, these values (shown in
the output of powermt display dev) uniquely identify a
logical device. By default, powermt config adds
PowerPath devices with the Symmetrix optimization,
CLARiiON optimization, or Adaptive load balancing and
failover policy, a priority of 0, write throttling set
to off, and a write throttle queue depth of 256. It
adds paths with the mode set to active. It adds
storage systems with periodic autorestore set to on.

After powermt config completes, you can change the
configuration with several powermt commands: powermt
set policy, powermt set priority, powermt set
periodic_autorestore, powermt set mode, powermt set
write_throttle, powermt set write_throttle_queue, or
powermt load.

If the PowerPath license is invalid, powermt config
issues a warning and continues its processing. Use
powermt check_registration to determine the problem
with the PowerPath license.

Platform-Specific Notes

On AIX, if powermt config encounters an error, a
general AIX error message is displayed, indicating
there is a problem configuring a device. The text of
the message depends on the underlying error. For more
detailed PowerPath error information, we recommend AIX
users run cfgmgr -vl powerpath0 instead of powermt
config. The cfgmgr command performs the same function

SunOS 5.8 Last change: January, 2004 7

User Commands powermt(1)

as powermt config but generates more detailed error
messages (documented in the PowerPath Product Guide).

On HP-UX, powermt config runs at boot time from
/etc/inittab to configure PowerPath. On Solaris,
powermt config runs at boot time from startup scripts
under /etc/rcS.d. You need to run powermt config only
if more paths are added after boot time.

powermt display [paths|ports] [class={symm|clariion|hitachi|hpxp|ess|all}]
[every=seconds]
powermt display [ports] [dev=device|all]
[class={symm|clariion|hitachi|hpxp|ess|all}] [every=seconds]

powermt display displays information about HBAs and/or
devices configured for and managed by PowerPath.

powermt watch is equivalent to powermt display.
powermt watch is included only for compatibility with
prior PowerPath releases. Use powermt display instead.

Arguments

class={symm|clariion|hitachi|hpxp|ess|all}
Limits the command to the specified type of
storage system. all specifies all storage-system
types. The default is all. (You can change the
default using the PP_DEFAULT_STORAGE_SYS
environment variable.)

If class is specified along with hba and/or dev,
the command is applied to paths that meet all
specified constraints.

paths
Displays information one line per path.

ports
Displays information one line per port.

dev=device|all
Displays information about the specified device.
all specifies all PowerPath devices.

If paths, ports, or dev is not specified, a summary HBA
listing is displayed, with one line per HBA.

every=seconds
Integer in the range 1-86400 that specifies, in
seconds, how often the display is updated. By
default, the display is not updated.

SunOS 5.8 Last change: January, 2004 8

User Commands powermt(1)

The seconds value is the minimum time between
refreshes; the actual time is affected by the
overall system load. On busy systems, display
updates can be less frequent than specified.

Description of the Displays

The first form of the command (powermt display) yields
the HBA display. The second form of the command
(powermt display dev) yields the devices display. The
following sections explain the fields in each display.

Note: For a more detailed description of these
displays, including example displays and a discussion
of the effects of zoning on the displays, see the
PowerPath Product Guide.

Fields in the HBA Display

storage_system_type logical device count
Value: Non-negative integer

Total number of unique logical devices from all
storage devices of a given type that are
configured by PowerPath and that this host can
access.

Each powermt display table contains information
about one type of storage system, such as
Symmetrix.

Host Bus Adapters ###
Value: Non-negative integer

PowerPath number for the HBA.

When the dev option is used, the output of powermt
display identifies the HBA by this same HBA
number.

This number is preserved across boots but is not
preserved after configuration changes.

Host Bus Adapters HW Path
Value: Alphanumeric string

Operating-system-specific hardware descriptive
name for the bus:

- AIX: The name of the device that is the parent
of the hdisk; for example, scsi1.

SunOS 5.8 Last change: January, 2004 9

User Commands powermt(1)

- HP-UX: Hardware path as defined by the ioscan
command; for example, 10/4.2.0.

- Solaris: Modification of the /dev/rdsk symbolic
link target; for example, sbus@1f,0/fcaw@3,0.

I/O Paths Summary
Value: optimal, degraded, or failed

Status of the paths originating from this HBA:

- optimal means all paths are alive (usable).

- degraded means one or more, but not all, paths
from this HBA are dead (not usable).

- failed means all paths are dead and no data is
passing through this HBA.

I/O Paths Total
Value: Non-negative integer

Total number of paths that originate from this
HBA. The maximum number of logical devices
supported by one HBA is platform specific. The
total number of paths may exceed the number of
logical devices in a complex SAN topology, due to
zoning.

I/O Paths Dead
Value: Integer in the range 0 - I/O Paths Total

Total number of paths originating from this HBA
that are dead (not usable).

Stats IO/sec
Value: Non-negative integer

This field is blank for powermt display, unless it
is used with the every parameter. Subsequent
powermt display iterations display the average
number of I/Os sent across this bus each second.

Stats Q-IOs
Value: Non-negative integer

Total number of outstanding I/Os on this HBA now.

Stats Errors
Value: Non-negative integer

SunOS 5.8 Last change: January, 2004 10

User Commands powermt(1)

Total number of times any logical I/O paths on
this bus transitioned from alive to dead. This
always is equal to or less than the total number
of HBA I/O errors. It is cleared at boot time or
when powermt restore executes. The PowerPath
periodic autorestore feature does not clear this
number but may cause it to increase if the path
has intermittent failures (that is, some periodic
autorestore operations are successful and others
are not).

Storage System ID
Value: Hexadecimal value or alphanumeric string

Identification number for the storage system on
which the logical device is located.

Storage System Interface
Value: Alphanumeric string

Storage system-interface.

For Symmetrix systems, this has three parts:

- Interface type: Fibre Channel (FA) or SCSI (SA)

- Interface address: integer in the range 1-16

- Interface port: aA, aB, bA, bB

For CLARiiON systems, this has one part:

- Interface port: SP [A-B][0-3]

For Hitachi Lightning and HP xp systems, this is
the port name on the array.

For IBM ESS systems, this is a two-digit
hexadecimal port ID that can be decoded to a
Bay/Adaptor/Port on the ESS system. (IBM ESS
command-line interface documentation describes how
to decode the port ID.)

Storage System Wt_Q
Value: Non-negative integer

Maximum number of write I/O requests that will be
serviced before the I/O queue checks for any
outstanding read I/O.

Fields in the Devices Display

SunOS 5.8 Last change: January, 2004 11

User Commands powermt(1)

Pseudo name
Value: Alphanumeric string

Platform-specific value assigned by PowerPath to
the PowerPath device associated with the logical
device. See "dev Argument Specification" for
pseudo device naming formats for each platform.

storage_system_type ID
Value: Hexadecimal value or alphanumeric string

Identification number for the storage system on
which the logical device is located.

Each powermt display table contains information
about one type of storage system, such as
Symmetrix.

For CLARiiON systems only, the user-specified
storage group name, if available, is by default
displayed in brackets after this identification
number. To suppress display of the name, define
the environment variable PP_SHOW_CLAR_LUN_NAMES
and set it to "false" or "FALSE". (To re-enable
the default behavior, either remove the variable
or set it to "true" or "TRUE".)

Logical device ID
Value: Hexadecimal value or alphanumeric string

Identification number for the logical device. Each
logical device on each storage system has a unique
ID. Each storage system, however, uses the same
storage system ID. Together, storage system ID and
logical device ID create a unique ID for every
logical device in the world.

On a CLARiiON system, the logical device ID is a
32-digit number. This is not the same as the
standard device identifier used by Navisphere.

For CLARiiON systems only, the user-assignable LUN
name, if available, is by default displayed in
brackets after this identification number. To
suppress display of LUN names, define the
environment variable PP_SHOW_CLAR_LUN_NAMES and
set it to "false" or "FALSE". (To re-enable the
default behavior, either remove the variable or
set it to "true" or "TRUE".)

state
Value: alive or dead

SunOS 5.8 Last change: January, 2004 12

User Commands powermt(1)

State of the PowerPath device:

- PowerPath marks a PowerPath device dead if it
returns certain types of I/O errors and is judged
unusable. Once a PowerPath device is marked dead
(and until it is restored with powermt restore),
PowerPath returns subsequent I/O requests with a
failure status, without forwarding them to the
associated logical device. This prevents further,
unrecoverable corruption and allows you to perform
data recovery if needed.

- If a PowerPath device is alive, either PowerPath
never marked it dead, or it was marked dead but
restored with powermt restore or an automatic path
test.

Owner
Value: default=SP x, current=SP x

Default and current owners of the logical device
(CLARiiON systems only).

policy
Value: Adaptive, BasicFailover, CLAROpt,
LeastBlocks, LeastIos, NoRedirect, Request,
RoundRobin, or SymmOpt

Current load balancing and failover policy for the
PowerPath device.

Use powermt set policy to change the policy.

priority
Value: Integer in the range 0-10

Amount of scheduling favoritism shown to the
PowerPath device. Priority applies only to the
Adaptive, SymmOpt and CLAROpt load balancing
policies.

Use powermt set priority to change the priority.

queued-IOs
Value: Non-negative integer

Number of I/O requests queued to this PowerPath
device.

write-throttle
Value: on or off

SunOS 5.8 Last change: January, 2004 13

User Commands powermt(1)

Write-throttling setting for this logical device.

Host ###
Value: Non-negative integer

PowerPath number for the HBA.

When the dev option is used, the output of powermt
display identifies the HBA by this same HBA
number.

This number is preserved across boots but is not
preserved after configuration changes.

Host HW Path
Value: Alphanumeric string

The platform-specific hardware descriptive name
for the path:

- AIX: The name of the device that is the parent
of the hdisk; for example, fscsi1.

- HP-UX: Hardware path as defined by the ioscan
command; for example, 10/4.2.0.

- Solaris: Modification of the /dev/rdsk symbolic
link target; for example,
/pci@8,700000/QLGC,qla@3/sd@0,2.

Host I/O Path
Value: Alphanumeric string

The platform-specific device name for the path.
See "dev Argument Specification".

On HP-UX and Solaris, if new devices are added,
powermt display every=seconds may display unknown
in place of the actual device names due to the
creation of device-name mappings at startup. If
this occurs, restart powermt display
every=seconds.

Stor Interf.
Value: Alphanumeric string

Storage system interface. For Symmetrix systems,
this has three parts:

- Interface type: Fibre Channel (FA) or SCSI (SA)

SunOS 5.8 Last change: January, 2004 14

User Commands powermt(1)

- Interface address: integer in the range 1-16

- Interface port: [abcd][AB]

For CLARiiON systems, this has one part:

- Interface port: SP [A-B][0-3]

For Hitachi Lightning and HP xp systems, this is
the port name on the array.

For IBM ESS systems, this is a two-digit
hexadecimal port ID that can be decoded to a
Bay/Adaptor/Port on the ESS system. (IBM ESS
command-line interface documentation describes how
to decode the port ID.)

I/O Paths Mode
Value: active, standby, or unlic

Current path mode:

- active indicates this path can accept I/O. Load
balancing is performed for a PowerPath device with
more than one active path, based on the load
balancing and failover policy set for the
PowerPath device. On active-passive storage
systems, I/O is load-balanced across paths to a
single SP for each logical device.

- standby indicates this path is held in reserve.
Being set to standby does not mean a path will not
be used. It only means the weight of the path is
heavily adjusted to preclude its use in normal
operations. A standby path still can be selected
if it is the best path for the request.

- unlic indicates that unlicensed PowerPath is
running for a CLARiiON array (no license key has
been installed). In this scenario, all paths are
marked unlicensed except one path to each SP.
Unlicensed paths cannot become candidates for path
failover.

Use powermt set mode to change the mode.

I/O Paths State
Value: alive or dead

Current path state:

SunOS 5.8 Last change: January, 2004 15

User Commands powermt(1)

- alive indicates the path is usable: PowerPath
can direct I/O to this path.

- dead indicates the path is not usable: PowerPath
will not direct I/O to this path. After marking
the path dead and incrementing the Errors count,
PowerPath tests the path to see whether it is
usable. If the test succeeds, PowerPath marks the
path alive; the path is then available for I/O. If
the test fails, the path remains dead, and
PowerPath ignores it for subsequent I/O
operations. If all the paths to a logical device
are dead, PowerPath retests each path.

Stats Q-IOs
Value: Non-negative integer

Total number of I/O operations under way to this
path. This is the total number of I/O requests to
this device that have not completed. The sum of
in-progress I/Os for all paths should equal the
number of in-progress I/Os for the PowerPath
device.

Stats Errors
Value: Non-negative number

Total number of times this path transitioned from
alive to dead. This always is equal to or less
than the total number of HBA I/O errors. It is
cleared at boot time or when powermt restore
executes. The PowerPath periodic autorestore
feature does not clear this number but may cause
it to increase if the path has intermittent
failures (that is, some periodic autorestore
operations are successful and others are not).

If both the dev and ports options are specified, a
compressed version of the devices display is output.
The compressed display includes a column listing the
write throttle setting (on or off) of each storage-
system port and a column listing the write throttle
queue depth for each port. To accommodate the extra
information, the I/O Paths Mode and I/O Paths State
columns of the normal devices display are merged into a
Path Status column. Valid values for Path Status are as
follows:

Value Meaning Description

a active See the description of Path mode, above
s standby See the description of Path mode, above

SunOS 5.8 Last change: January, 2004 16

User Commands powermt(1)

u unlicensed See the description of Path mode, above
v alive See the description of Path state, above
d dead See the description of Path state, above

powermt display options

powermt display options displays the default storage
system class and the following options settings for
each storage system class:

- Status of the storage system class (managed,
unmanaged, manage_incomplete, or unmanage_incomplete)

- Whether CLARiiON user-assignable LUN names are
displayed

- Whether periodic autorestore is enabled

Use powermt set periodic_autorestore to change the
periodic autorestore setting. Use powermt manage to
place logical devices under PowerPath management and
powermt unmanage to exclude devices from PowerPath
management (third-party storage systems only).

Use the PP_DEFAULT_STORAGE_SYS environment variable to
change the default storage system class.

CLARiiON user-assignable LUN names are displayed by
default. To suppress display of LUN names, define the
environment variable PP_SHOW_CLAR_LUN_NAMES and set it
to "false" or "FALSE". (To re-enable the default
behavior, either remove the variable or set it to
"true" or "TRUE".) An example using Bourne shell syntax
to suppress the display of LUN names is:

PP_SHOW_CLAR_LUN_NAMES=false
export PP_SHOW_CLAR_LUN_NAMES

powermt display unmanaged

powermt display unmanaged displays information about
logical devices that have been excluded from PowerPath
management using powermt unmanage. You can use the
native device as the dev argument to the powermt manage
dev= command.

powermt load [class={symm|clariion|hitachi|hpxp|ess|all}]
[file=pathname]

powermt load applies to the current configuration the
following settings from a saved configuration file:
PowerPath device policies and priorities; write

SunOS 5.8 Last change: January, 2004 17

User Commands powermt(1)

throttle setting and write throttle queue depth;
periodic autorestore setting; and path modes. On all
platforms, the file is saved when powermt save is run
manually. On HP-UX and Solaris, the file is also saved
at boot time.

If a configuration is saved with powermt save under the
default filename, the configuration loads automatically
at boot time. (The exception is AIX, which always
loads default settings at boot time.) If the default
filename is not used, the configuration does not load
automatically at boot time; in this case, you must load
the configuration manually with powermt load.

Paths added since the last save remain as is. If the
configuration file has information about dead paths,
they are added in a failed state, allowing them to be
restored later. If the file has information about paths
that were removed since the last save, they are added.

If the PowerPath license is invalid, powermt load
issues a warning and continues its processing. Use
powermt check_registration to determine the problem
with the license.

powermt load behavior is undefined when invoked after
the host has booted and while paths are in a state
other than alive. Do not use powermt load to restore
dead paths online.

Arguments

class={symm|clariion|hitachi|hpxp|ess|all}
Limits the command to the specified type of
storage system. all specifies all storage-system
types. The default is all. (You can change the
default using the PP_DEFAULT_STORAGE_SYS
environment variable.)

file=pathname
Full pathname of the saved configuration file. For
the default filename, see powermt save.

powermt manage {dev=device|class={hitachi|hpxp|ess}}

powermt manage places a specified logical device, or a
specified storage system class, under PowerPath
management.

By default, all storage system classes are under
PowerPath management. You can use powermt unmanage to
exclude a storage system class from PowerPath

SunOS 5.8 Last change: January, 2004 18

User Commands powermt(1)

management. Use powermt manage class= to return that
storage system class to PowerPath control.

Likewise, by default, when a storage system class is
under PowerPath management, all logical devices of that
class are under PowerPath management. You can use
powermt unmanage to exclude an individual device from
PowerPath management. Use powermt manage dev= to return
that device to PowerPath control. powermt manage
returns a device to PowerPath control only if its
storage system class is currently managed by PowerPath.

A powermt manage class= operation is legal only if the
class's status is unmanaged or manage_incomplete. If
the class status is unmanage_incomplete, the unmanage
operation must be completed, or the host rebooted,
before powermt manage succeeds. The powermt display
options command displays the status of a class.

Arguments

dev=device
Specifies the pathname of a logical device to be
managed by PowerPath.

class={hitachi|hpxp|ess}
Specifies the storage system class to be managed
by PowerPath.

powermt remove [class={symm|clariion|hitachi|hpxp|ess|all}] [force]
hba=hba#|all | dev=path|device|all
powermt remove [class={symm|clariion|hitachi|hpxp|ess|all}] [force]
hba=hba#|all dev=path|device|all

powermt remove deletes the specified path (or paths)
from PowerPath's list of configured paths. It does not
delete the logical device that the paths refer to. As
long as the logical device remains visible on the
system, the logical device can be reconfigured via
powermt config.

CAUTION: Do not remove the last path to a logical
device unless you plan to remove the logical device
entirely, as data access will be interrupted.

On all platforms except AIX, powermt remove does not
remove a path if that native path is open--for example,
if a file system is mounted on the native path device
or an application has opened the native path device.
Instead, powermt remove removes all specified paths
that are not currently open, issues an error message,
and exits.

SunOS 5.8 Last change: January, 2004 19

User Commands powermt(1)

If a PowerPath device is open, powermt remove does not
remove that device or the last path to that device. If
a device is in a PPVM volume group, PowerPath does not
remove the last path to that device.

In addition, powermt remove operates on paths, so when
powermt remove is executed with an HBA or PowerPath
device argument, powermt remove iterates through all
the associated paths and attempts to remove them. The
HBA or PowerPath device is removed only if all the
associated paths are successfully removed.

To permanently remove a path from the PowerPath
configuration:

1. Run powermt check or powermt remove.

2. Physically remove the path.

3. Remove the operating system objects associated
with the path and/or device.

4. Run powermt save.

If the PowerPath license is invalid, powermt remove
issues a warning and continues its processing. Use
powermt check_registration to determine the problem
with the license.

On all platforms except AIX and Solaris, if you run
powermt remove on a live path with active I/O,
PowerPath returns the message

Cannot remove alive device device_name

and exits.

Arguments

class={symm|clariion|hitachi|hpxp|ess|all}
Limits the command to the specified type of
storage system. all specifies all storage-system
types. The default is all. (You can change the
default using the PP_DEFAULT_STORAGE_SYS
environment variable.)

If class is specified along with hba and/or dev,
the command is applied to paths that meet all
specified constraints.

force
Suppresses the confirmation prompt and silently

SunOS 5.8 Last change: January, 2004 20

User Commands powermt(1)

removes all specified paths, including the last
path to a logical device.

hba=hba#|all
Limits removal to paths from the specified HBA.
hba# is a number in the Host Bus Adapters ###
column of powermt display dev output. all
specifies all HBAs under PowerPath control. The
default is all.

(adapter can be used instead of hba. adapter is
included only for compatibility with prior
PowerPath releases. Use hba instead.)

dev=path|device|all
Limits removal to the specified path or all paths
to the specified PowerPath device. all specifies
all paths to all devices. The default is all.

powermt restore [class={symm|clariion|hitachi|hpxp|ess|all}] [force]
[hba=hba#|all] [dev=path|device|all]

powermt restore tests and restores specified paths. It
issues test I/Os and responds to the test results as
follows:

- If a live path passes the test, powermt restore does
nothing.

- If a dead path passes the test, powermt restore marks
it alive; PowerPath can now use it. In addition, other
dead paths on the same HBA and/or storage system port
may be tested.

- If a live path fails the test, powermt restore marks
it dead and prints a warning (every time the path fails
the test). In addition, other paths that share the
same HBA and port may be marked dead, and other paths
that share only the HBA or only the port may be tested.

- If a dead path fails the test, powermt restore prints
a warning (every time the path fails the test).

There may be a delay in accessing a recovered path. To
avoid this delay, run powermt restore after a path is
physically restored.

In addition to testing and restoring paths, powermt
restore attempts to resurrect dead volumes. A volume
may be marked dead if write errors occur that could
jeopardize the integrity of the data structures, and if
subsequent writes could aggravate the problem.

SunOS 5.8 Last change: January, 2004 21

User Commands powermt(1)

When applied to CLARiiON storage systems, powermt
restore also relocates LUNs to their default storage
processor.

If the PowerPath license is invalid, powermt restore
issues a warning and continues its processing. Use
powermt check_registration to determine the problem
with the PowerPath license.

Arguments

class={symm|clariion|hitachi|hpxp|ess|all}
Limits the command to the specified type of
storage system. all specifies all storage-system
types. The default is all. (You can change the
default using the PP_DEFAULT_STORAGE_SYS
environment variable.)

If class is specified along with hba and/or dev,
the command is applied to paths that meet all
specified constraints.

force
Attempts to restore dead volumes without prompting
for confirmation.

hba=hba#|all
Limits restoration to paths from the specified
HBA. hba# is a number in the Host Bus Adapters ###
column of the powermt display dev output. all
specifies all HBAs under PowerPath control. The
default is all.

(adapter can be used instead of hba. adapter is
included only for compatibility with prior
PowerPath releases. Use hba instead.)

dev=path|device|all
Limits restoration to the specified path or all
paths to the specified PowerPath device. all
specifies all paths to all devices. The default is
all.

powermt save [file=pathname]

By default, powermt save saves the PowerPath settings
in the file powermt.custom. You can specify an
alternate file. For each configured logical device,
powermt save records its serial numbers, policy,
priority, write throttle setting, write throttle queue
depth, and pseudo device name. For each configured path
(alive or dead), powermt save records its mode. For

SunOS 5.8 Last change: January, 2004 22

User Commands powermt(1)

each storage system class, powermt save records its
period autorestore setting.

For performance-tuning purposes, you can use powermt
save to save different configurations under different
filenames.

A saved configuration can be reloaded with powermt
load.

Arguments

file=pathname
Full pathname of the file in which to save the
configuration. PowerPath creates the file if it
does not exist. The default is
/etc/powermt.custom.

If a configuration is saved with powermt save
under the default filename, the configuration
loads automatically at boot time. (The exception
is AIX, which always loads default settings at
boot time.) If the default filename is not used,
the configuration does not load automatically at
boot time; in this case, you must load the
configuration manually with powermt load.

If a configuration is saved under the default
filename, any previously existing configuration
file is overwritten without notice.

The configuration file is saved with read-only
access for root and no access for others.

CAUTION: Do not modify the configuration file
manually.

powermt set periodic_autorestore=on|off
[class={symm|clariion|hitachi|hpxp|ess|all}]

powermt set periodic_autorestore enables or disables
PowerPath's periodic autorestore feature.

When periodic autorestore is on, PowerPath periodically
tests dead paths and, if they are no longer dead,
restores them to service. Even when periodic
autorestore is off, path testing continues under
certain conditions, and automatic path restoration
continues to occur based on the results of that
testing. For details about periodic autorestore, refer
to the PowerPath Product Guide.

SunOS 5.8 Last change: January, 2004 23

User Commands powermt(1)

To determine the periodic autorestore setting, use
powermt display options.

Arguments

on|off
on enables periodic autorestore. off disables it.
The default is on.

class={symm|clariion|hitachi|hpxp|ess|all}
Limits the command to the specified type of
storage system. all specifies all storage-system
types. The default is all. (You can change the
default using the PP_DEFAULT_STORAGE_SYS
environment variable.)

powermt set mode=active|standby
[class={symm|clariion|hitachi|hpxp|ess|all}]
[hba=hba#|all] [dev=path|device|all]

powermt set mode sets paths to active or standby mode.

For most applications, the best performance is achieved
by designating all paths to a PowerPath device as
active. By using this command selectively, however, the
path usage of PowerPath devices can be controlled. This
is helpful if you do not want I/O for one PowerPath
device to affect the performance of another PowerPath
device.

Arguments

mode=active|standby
Determines whether a path is available for I/O or
held in reserve. In active mode, user I/O is
delivered to a path. If you designate a path as
active, it is continuously scheduled for I/O
according to the load balancing and failover
policy in use. In standby mode, the path is held
in reserve.

Being set to standby does not mean a path will not
be used. It only means the weight of the path is
heavily adjusted to preclude its use in normal
operations.

class={symm|clariion|hitachi|hpxp|ess|all}
Limits the command to the specified type of
storage system. all specifies all storage-system
types. The default is all. (You can change the
default using the PP_DEFAULT_STORAGE_SYS
environment variable.)

SunOS 5.8 Last change: January, 2004 24

User Commands powermt(1)

If class is specified along with hba and/or dev,
the command is applied to paths that meet all
specified constraints.

hba=hba#|all
Sets the mode for paths from the specified HBA.
hba# is a number in the Host Bust Adapters ###
column of powermt display dev and powermt display
paths output. all specifies all HBAs under
PowerPath control. The default is all.

(adapter can be used instead of hba. adapter is
included only for compatibility with prior
PowerPath releases. Use hba instead.)

dev=path|device|all
Sets the mode for the specified path or all paths
to the specified PowerPath device. all specifies
all paths to all devices. The default is all.

powermt set policy=policy [class={symm|clariion|hitachi|hpxp|ess|all}]
[dev=device|all]

powermt set policy sets the load balancing and failover
policy for PowerPath devices.

Arguments

policy=policy
Sets the load balancing and failover policy to one
of the following values:

ad Adaptive. I/O requests are assigned to paths
based on an algorithm that takes into account
path load and logical device priority. This
policy is valid only for Hitachi Lightning,
HP xp, and IBM ESS storage systems and is the
default policy for them on platforms with a
valid PowerPath license.

bf Basic failover. Load balancing is not in
effect. I/O routing on failure is limited to
one HBA and one port on each storage
processor. When a host boots, it designates
one path (through one interface) for all I/O.
If an I/O is issued to a logical device that
cannot be reached via that path (that is, the
I/O cannot reach that logical device through
the device's assigned interface), a trespass
is performed: the logical device is assigned
to the other interface.

SunOS 5.8 Last change: January, 2004 25

User Commands powermt(1)

This policy protects against SP and back-end
failures and allows non-disruptive upgrades
to work when running PowerPath without a
license key. It does not protect against HBA
or host loop failures.

This policy is valid only for CLARiiON
storage systems and is the default policy for
them on platforms without a valid PowerPath
license.

co CLARiiON optimization (listed in powermt
display output as CLAROpt). I/O requests are
assigned to paths based on an algorithm that
takes into account path load and the priority
you set with powermt set policy.

This policy is valid only for CLARiiON
storage systems and is the default policy for
them on platforms with a valid PowerPath
license.

lb Least blocks. Load balance is based on the
number of blocks in the pending I/Os. I/O
requests are assigned to the path with the
smallest burden in terms of blocks,
regardless of the number of requests
involved.

li Least I/Os. Load balance is based on the
number of pending I/Os. I/O requests are
assigned to the path with the smallest number
of requests, regardless of total block
volume.

nr No redirect. Neither load balancing nor
failover is in effect. If nr is set on a
failed path and a native device is used, I/O
errors will occur when I/O is directed to
that path. If one or more paths is failed and
nr is set, data I/O errors can occur.

This policy is valid only for Symmetrix,
Hitachi Lightning, HP xp, and IBM ESS storage
systems and is the default policy for them on
platforms without a valid PowerPath license.

re Request. For native devices, uses the path
that would have been used if PowerPath were
not installed. For pseudo devices, uses one
arbitrary path for all I/O. For all devices,
failover is in effect, but load balancing is

SunOS 5.8 Last change: January, 2004 26

User Commands powermt(1)

not.

rr Round robin. I/O requests are assigned to
each available path in rotation.

so Symmetrix optimization (listed in powermt
display output as SymmOpt). I/O requests are
assigned to paths based on an algorithm that
takes into account path load and the priority
you set with powermt set policy.

This policy is valid only for Symmetrix
storage systems and is the default policy for
them on platforms with a valid PowerPath
license.

class={symm|clariion|hitachi|hpxp|ess|all}
Limits the command to the specified type of
storage system. all specifies all storage-system
types. The default is all. (You can change the
default using the PP_DEFAULT_STORAGE_SYS
environment variable.)

If class is specified along with hba and/or dev,
the command is applied to paths that meet all
specified constraints.

dev=device|all
Limits the policy change to the specified
PowerPath device. all specifies all PowerPath
devices. The default is all.

If neither class nor dev is specified, and the
specified policy does not apply to any storage system
in the environment (for example, if the bf policy is
specified, but there are no CLARiiON storage systems),
no policy setting occurs, and no error message appears.

powermt set priority=priority#
[class={symm|clariion|hitachi|hpxp|ess|all}] [dev=|device|all]

powermt set priority sets the I/O priority for
PowerPath devices. I/O to lower priority logical
devices tends to be delivered to paths not used by
higher priority logical devices.

This command is relevant only for those PowerPath
devices whose load balancing policy and failover is set
to Symmetrix optimization, CLARiiON optimization, or
Adaptive. Although it sets priorities for PowerPath
devices with other policies, it has no effect on load
balancing on those devices. If the policy for a given

SunOS 5.8 Last change: January, 2004 27

User Commands powermt(1)

device is anything other than Symmetrix optimization,
CLARiiON optimization, or Adaptive when a priority for
that device is set, the priority setting has no effect;
if, however, the policy for that device is later
changed to Symmetrix optimization, CLARiiON
optimization, or Adaptive, the previously set priority
becomes relevant when the policy change occurs.

Setting a high priority for several PowerPath devices
improves their I/O performance at the expense of the
remaining PowerPath devices, while otherwise
maintaining the best possible load balance across all
paths. For example, to favor certain applications over
others, assign a higher priority to the PowerPath
devices used by that application.

Arguments

priority#
Integer in the range 0 - 10. The default is 0. The
higher the number, the higher the priority.
Setting all PowerPath devices to the same priority
negates the effect of the command.

class={symm|clariion|hitachi|hpxp|ess|all}
Limits the command to the specified type of
storage system. all specifies all storage-system
types. The default is all. (You can change the
default using the PP_DEFAULT_STORAGE_SYS
environment variable.)

If class is specified along with hba and/or dev,
the command is applied to paths that meet all
specified constraints.

dev=device|all
Sets the priority for the specified PowerPath
device. all specifies all PowerPath devices. The
default is all.

powermt set transparent=on|off [dev=|device|all]

Note: This command works only on Symmetrix systems.

powermt set transparent enables or disables PowerPath's
load balancing and failover features on specified
devices.

powermt set transparent is included only for
compatibility with prior PowerPath releases. Use
powermt set policy instead, as indicated below:

SunOS 5.8 Last change: January, 2004 28

User Commands powermt(1)

- powermt set transparent=on is equivalent to
powermt set policy=nr

- powermt set transparent=off is equivalent to
powermt set policy=so.

Arguments

on|off
on disables load balancing and failover. off
enables these features. The default is off.

dev=device|all
Limits the change to the specified PowerPath
device. all specifies all PowerPath devices. The
default is all.

powermt set write_throttle=on|off [class=symm] [dev=device|all]

powermt set write_throttle enables or disables I/O
write throttling to the specified PowerPath device(s).

This command is available only with Symmetrix storage
systems.

Write throttling is enabled to limit the number of
queued writes to the common I/O queue in the HBA
driver; instead, the writes are queued in PowerPath. As
a result, read requests do not get delayed behind a
large number of write requests. Write throttling is
disabled by default.

Arguments

on|off
on enables write throttling to the specified
PowerPath device. off disables it. For new
PowerPath devices, write throttling is set to off
by default.

class=symm
Limits the command to the specified type of
storage system.

If class is specified along with hba and/or dev,
the command is applied to paths that meet all
specified constraints.

dev=device|all
Limits the change to the logical device associated
with the specified device. all specifies all
logical devices. The default is all.

SunOS 5.8 Last change: January, 2004 29

User Commands powermt(1)

(volume_dev can be used instead of dev. volume_dev
is included only for compatibility with prior
PowerPath releases. Use dev instead.)

powermt set write_throttle_queue=queue_depth#
[class=symm] [dev=path|device|all]

powermt set write_throttle_queue sets the write
throttling queue depths for a storage system port
connected to a specified device. The queue depth
setting limits the number of writes to all devices
enabled for write throttling which can be outstanding
(from PowerPath's perspective) on the storage system
port. The queues are allocated within PowerPath, one
per storage system port.

This command is available only for Symmetrix storage
systems.

Arguments

queue_depth#
Threshold value that limits the number of I/Os
sent/written to a port. The intent of setting this
value is to prevent write operations from delaying
the completion of read operations. The value of
queue_depth# must be in the range 1 - 2147483647.
For new ports, the queue depth is set to 256 by
default.

class=symm
Limits the command to the specified type of
storage system.

If class is specified along with hba and/or dev,
the command is applied to paths that meet all
specified constraints.

dev=path|device|all
Limits the change to the storage system port
associated with the specified path, or the port
connected to the specified device. all specifies
all storage-system ports to all devices. The
default is all.

(port_dev can be used instead of dev. port_dev is
included only for compatibility with prior
PowerPath releases. Use dev instead.)

powermt unmanage {dev=device|class={hitachi|hpxp|ess}}

SunOS 5.8 Last change: January, 2004 30

User Commands powermt(1)

powermt unmanage excludes a specified logical device or
storage system class from PowerPath management.

When applied to a storage system class, powermt
unmanage succeeds in completely removing the class from
PowerPath control only after you stop applications with
open devices of the specified class. If you cannot
stop applications, you may need to reboot the host.

When you remove a storage system class from PowerPath
control, custom configurations for that class (such as
policy or mode) are lost with the next reboot or
execution of powermt save.

A powermt unmanage class= operation is legal only if
the class's status is managed or unmanage_incomplete.
If the class status is manage_incomplete, the manage
operation must be completed, or the host rebooted,
before powermt unmanage succeeds. The powermt display
options command displays the status of a class.

When applied to a specific device, powermt unmanage
differs from powermt remove:

- powermt unmanage applies to the entire device, not
just the specified path.

- The effect of powermt unmanage is persistent:
powermt config does not restore the device to PowerPath
control.

Arguments

dev=device
Specifies the pathname of a logical device to be
excluded from PowerPath management.

class={hitachi|hpxp|ess}
Specifies the storage system class to be excluded
from PowerPath management.

powermt update lun_names

powermt update lun_names causes PowerPath to retrieve
the latest user-assignable CLARiiON LUN names. A user-
assignable LUN name is a character string that a user
or system manager associates with a LUN and assigns
through Navisphere.

powermt version

SunOS 5.8 Last change: January, 2004 31

User Commands powermt(1)

powermt version prints the number of the PowerPath
version for which powermt was created.

EXIT STATUS
All powermt commands return 0 to the user process on
success; 1 on error.

FILES
/etc/powermt.custom
Default pathname of the configuration file.

SEE ALSO
emcpminor(1),
emcpreg(1),
emcpupgrade(1),
powercf(1),
powerprotect(1),
PowerPath Product Guide

SunOS 5.8 Last change: January, 2004 32