admiopath(1M) DG/UX R4.11MU05 admiopath(1M)
NAME
admiopath - manage multi-path I/O
SYNOPSIS
admiopath -o add [ -sb ] -k backup-path primary-path
admiopath -o delete [ -k backup-path ] primary-path
admiopath -o modify [ -sb ] [ -k backup-path ] [ -n new-path ]
primary-path
admiopath -o list [ -dlqv ] [ primary-path ... ]
admiopath -o start [ primary-path ... ]
admiopath -o stop [ primary-path ... ]
admiopath -o switch -i inactive-path primary-path
admiopath -o repaired -r repaired-path primary-path
admiopath -o reset [ -dl ] [ primary-path ... ]
DESCRIPTION
The admiopath command is used to manage multi-path I/O. There are
operations provided for maintaining the iopath.params database, as
well as operations for starting and stopping the multi-path I/O
relationship between devices, and switching between I/O paths. Multi
path I/O can be set up whenever there are multiple I/O paths to the
same disk or LAN device. A multi-path I/O relationship consists of a
primary (initially active) path and at least one backup path.
Multi-path LAN I/O consists of two similar (ie., both cien)
controllers connected to the same network. The primary LAN controller
is active (ie., set up in /etc/tcpip.params) and the backup is not
active. Upon detecting failure of the primary, the system will
redirect I/O to the backup path.
Multi-path disk I/O configurations may vary. Using a system with two
disk controllers connected to a CLARiiON disk array that has two
Storage Processors (SP's), will protect against either controller or
SP failures. A disk primary I/O path can have up to three backup I/O
paths associated with it. Upon detecting failure of the primary, the
system will redirect I/O to one of the backup paths.
Once the primary and backup I/O paths have been added to the
iopath.params database, the system can start to use multi-path I/O
for those paths. In the event of a failure on the primary I/O path,
the operating system will automatically switch to a backup I/O path.
This change in I/O path will be transparent to the users of the
system.
The system administrator can manually switch I/O paths if desired, or
start and stop multi-path I/O relationships on a system.
Additionally, when a failed path is repaired, the administrator can
inform the system of this fact. The administrator can also reset all
of the I/O paths back to their primary paths (unless the primary has
failed and not yet been repaired).
In all operations the path that is specified as the primary is used
as a key for database searches. The database relationship is not
changed if a backup path is being used instead of the primary path.
The list operation will show which path in the relationship is
currently active.
Operations
add Add an iopath.params database entry. The add operation
creates an entry in the iopath.params(4M) database for the
specified primary and backup I/O paths. It can optionally
start the multi-path I/O relationship for these paths. The
add operation can also be used to add additional backup
paths to an existing disk entry.
delete Delete an iopath.params database entry. The delete
operation terminates the specified multi-path I/O
relationship and deletes the entry from the iopath.params
database. The delete operation can also be used to delete
backup paths. In this case if other backup paths exist,
then the entry is not deleted, only the specified backup
paths are deleted.
modify Modify an iopath.params database entry. The modify
operation allows the user to change either the primary-path
or any of the backup I/O paths for the specified
iopath.params database entry. This operations can
optionally stop and restart multi-path I/O for the modified
entry.
list List iopath.params database entries. The list operation
reports the following information to stdout:
name of the primary I/O path
flag indicating if relationship is started on system reboot
name of the currently active I/O path
list of backup paths
With the "verbose" format (-v), information is printed in
aligned columns with headers. With the "quiet" format (-q)
headers are suppressed and each iopath.params database
entry is printed on a separate line. If both -q and -v are
specified, the output will be in "quiet" format.
start Start multi-path I/O. This operation starts the multi-path
I/O relationship for the specified paths. If the paths are
LAN controllers and a failovermon(1M) monitor is not
running, this operation will start the failovermon(1M)
monitor to control the LAN redirection. If the primary disk
path cannot be registered, the admiopath command will
attempt to register one of the other paths in order to
build the multi-path I/O relationship.
stop Stop multi-path I/O. This operation stops the multi-path
I/O relationship for the specified paths. This operation
will attempt to switch the I/O back to the path on which
the relationship was started. For LAN, this means switching
back to the primary path. For disk, this means switching to
the path the disk was actually registered.
switch Switch to an inactive I/O path. The switch operation is
used to manually switch I/O from the currently active path
to an inactive one.
repaired Inform the appropriate driver that a path in a multi-path
I/O relationship has been repaired. This operation should
be used after the failed device has been replaced and
reconfigured into the system.
For disk I/O paths the repair of an I/O path may take
several seconds to a minute or more, depending on whether a
SCSI bus reset is required to complete the repair. During
these delays, all I/O to the multi-path disk I/O instance
will be pended. The I/O will be resumed after the operation
completes.
Disk I/O paths may also be repaired by the operating
system. If all paths have been marked as failed, the
vdmmpio(7) driver will attempt to repair all of the paths.
If all repairs fail, then an EIO error will be returned to
the user. If a failed path can be repaired by the system,
then the I/O will proceed on that path.
reset This operation will reset the specified I/O paths back to
the primary I/O path. This operation is useful in multi
channel I/O systems where a failure has forced all I/O onto
one channel. After the failed device has been repaired, the
reset operation can be used to move all of the switched I/O
paths back to their primary paths.
Options
The following option must be used with the add operation, and can be
used with the delete and modify operations:
-k backup-path
The name of the backup I/O path for the relationship. For
the add and delete operations, this can be a space
separated list of devices used as backups for the specified
primary I/O path. For the modify operation it is a single
backup path. A LAN primary I/O path can have only one
backup I/O path assigned to it. A disk primary I/O path can
have up to three backup I/O paths assigned to it.
The following option can be used with the modify operation:
-n new-path
The name of the new I/O path to assign to the iopath.params
database entry. If no backup-path argument is given to the
modify operation, this new-path will replace the specified
primary I/O path in the database entry. If a backup-path
name is given, this new-path will replace the backup-path
in the database entry.
The following option can be used with the add or modify operations:
-s Start now. If specified on an add operation the specified
multi-path I/O relationship will be started when the add
operation completes. If specified on a modify operation, a
multi-path I/O relationship currently in effect for the
modified iopath.params entry will be stopped and restarted
with the new information.
-b Start on reboot flag. When set to YES the multi-path I/O
relationship will be started when the system is rebooted.
This is controlled by the rc.failover script. When used
with the modify operation this option will cause the start
on reboot flag to toggle to the opposite of its current
setting.
The following options can be used with the list operation:
-d Disks. List iopath.params information about entries that
are for multi-path disk I/O.
-l LANs. List iopath.params information about entries that are
for multi-path LAN I/O.
-q Quiet. Produce an unformatted listing with no headers,
fields delimited by a single space.
-v Verbose. Produce a formatted listing with headers and
aligned columns. This option is the default.
The following options can be used with the reset operation:
-d Disks. Reset iopath.params entries that are for multi-path
disk I/O.
-l LANs. Reset iopath.params entries that are for multi-path
LAN I/O.
EXAMPLE
The following command line is used to add hken1 as a backup I/O path
to hken0 and start using multi-path I/O:
admiopath -o add -s -k hken1 hken0
The following command line is used to switch to the backup I/O path:
admiopath -o switch -i hken1 hken0
The following command line is used to add sd(dgsc(1,7),1,1) as a
backup I/O path to sd(dgsc(0,7),0,1) and start using multi-path I/O:
admiopath -o add -s -k "sd(dgsc(1,7),1,1)" "sd(dgsc(0,7),0,1)"
The following command line is used to switch to the backup I/O path:
admiopath -o switch -i "sd(dgsc(1,7),1,1)" "sd(dgsc(0,7),0,1)"
The following command line is used to add sd(dgsc(1,7),1,1) and
sd(dgsc(0,7),1,1) as backup I/O paths to sd(dgsc(0,7),0,1) and start
using multi-path I/O:
admiopath -o add -k "sd(dgsc(1,7),1,1) sd(dgsc(0,7),1,1)" "sd(dgsc(0,7),0,1)"
The following command line is used to stop multi-path I/O and delete
the iopath.params database entry:
admiopath -o delete hken0
FILES
/etc/iopath.params
DIAGNOSTICS
Warnings
- An attempt was made to start multi-path I/O when it has
already been started.
Errors
- An attempt was made to add or modify a backup I/O path that is
not of the same type as the primary I/O path.
- An attempt was made to switch to a currently active I/O path.
- An attempt was made to add a backup I/O path that is already
assigned to a primary I/O path.
- An attempt was made to add, delete, modify, list, or switch a
backup I/O path that does not exist.
- An attempt was made to add a backup I/O path to a primary I/O
path that does not exist.
- An attempt was made to add a backup I/O path to a primary I/O
path that already has the maximum number of backup I/O paths
assigned to it.
- An attempt was made to start a multi-path relationship on two
currently active I/O paths.
- An attempt was made to set up a multi-path disk I/O
relationship with disk specifications that do not resolve to
the same physical disk.
Exit Codes
0 The operation was successful.
1 The operation was unsuccessful.
2 The operation failed due to access restrictions.
3 There was an error in the command line.
SEE ALSO
failovermon(1M), iopath.params(4M), appropriate_privilege(5).
cap_defaults(5).
NOTE
You must have appropriate privilege to use this command. For systems
supporting the DG/UX Capability Option, appropriate privilege is
defined as having one or more specific capabilities enabled in the
effective capability set of the user. See cap_defaults(5) for the
default capabilities for this command.
On systems without the DG/UX Capability Option, appropriate privilege
means that your process has an effective UID of root. See the
appropriate_privilege(5) man page for more information.
Licensed material--property of copyright holder(s)