chpath Command

Purpose

Changes the operational status of paths to an MultiPath I/O (MPIO) capable device, or changes an attribute associated with a path to an MPIO capable device.

Syntax

chpath -l Name -s OpStatus [ -p Parent ] [ -w Connection ] [ -i PathID ]

chpath -l Name -p Parent [ -w Connection ] [ -P ] -a Attribute=Value [ -a Attribute=Value ... ] [ -g ]

chpath -l Name -i PathID [ -P ] -a Attribute=Value [ -a Attribute=Value ... ]

chpath -h

Description

The chpath command either changes the operational status of paths to the specified device (the -l Name flag) or it changes one, or more, attributes associated with a specific path to the specified device. The required syntax is slightly different depending upon the change being made.

The first syntax shown above changes the operational status of one or more paths to a specific device. The set of paths to change is obtained by taking the set of paths which match the following criteria:
  • The target device matches the specified device.
  • The parent device matches the specified parent (-p Parent), if a parent is specified.
  • The connection matches the specified connection (-w Connection), if a connection is specified.
  • The path status is PATH_AVAILABLE.

The operational status of a path refers to the usage of the path as part of MPIO path selection. The value of enable indicates that the path is to be used while disable indicates that the path is not to be used. It should be noted that setting a path to disable impacts future I/O, not I/O already in progress. As such, a path can be disabled, but still have outstanding I/O until such time that all of the I/O that was already in progress completes. As such, if -s disable is specified for a path and I/O is outstanding on the path, this fact will be output.

Disabling a path affects path selection at the device driver level. The path_status of the path is not changed in the device configuration database. The lspath command must be used to see current operational status of a path.

The second syntax shown above changes one or more path specific attributes associated with a particular path to a particular device. Note that multiple attributes can be changed in a single invocation of the chpath command; but all of the attributes must be associated with a single path. In other words, you cannot change attributes across multiple paths in a single invocation of the chpath command. To change attributes across multiple paths, separate invocations of chpath are required; one for each of the paths that are to be changed.

Flags

Item Description
-a Attribute=Value Identifies the attribute to change as well as the new value for the attribute. The Attribute is the name of a path specific attribute. The Value is the value which is to replace the current value for the Attribute. More than one instance of the -a Attribute=Value can be specified in order to change more than one attribute.
-g Forces the change path operation to take place on a locked device.
-h Displays the command usage message.
-i PathID Indicates the ID of the path that is affected by the change. This flag is used to uniquely identify a path.
-l Name Specifies the logical device name of the target device for the path(s) affected by the change. This flag is required in all cases.
-p Parent Indicates the logical device name of the parent device to use in qualifying the paths to be changed. This flag is required when changing attributes, but is optional when change operational status.
-P Changes the path's characteristics permanently in the ODM object class without actually changing the path. The change takes affect on the path the next time the path is unconfigured and then configured (possibly on the next boot).
-w Connection Indicates the connection information to use in qualifying the paths to be changed. This flag is optional when changing operational status. When changing attributes, it is optional if the device has only one path to the indicated parent. If there are multiple paths from the parent to the device, then this flag is required to identify the specific path being changed.
-s OpStatus Indicates the operational status to which the indicated paths should be changed. The operational status of a path is maintained at the device driver level. It determines if the path will be considered when performing path selection. The allowable values for this flag are:
enable
Mark the operational status as enabled for MPIO path selection. A path with this status will be considered for use when performing path selection. Note that enabling a path is the only way to recover a path from a failed condition.
disable
Mark the operational status as disabled for MPIO path selection. A path with this status will not be considered for use when performing path selection.
This flag is required when changing operational status. When used in conjunction with the -a Attribute=Value flag, a usage error is generated.

Security

Privilege Control: Only the root user and members of the system group have execute access to this command.

Auditing Events:
Event Information
DEV_Change The chpath command line.

Examples

  1. To disable the paths between scsi0 and the hdisk1 disk device, enter:
    chpath -l hdisk1 -p scsi0 -s disable
    The system displays a message similar to one of the following:
    paths disabled
    or
    some paths disabled
    The first message indicates that all PATH_AVAILABLE paths from scsi0 to hdisk1 have been successfully disabled. The second message indicates that only some of the PATH_AVAILABLE paths from scsi0 to hdisk1 have been successfully disabled.

Files

Item Description
/usr/sbin/chpath Contains the chpath command.

Related Information

The lspath command, mkpath command, rmpath command.