lspath Command

Purpose

Displays information about paths to an MultiPath I/O (MPIO) capable device.

Syntax

lspath [ -F Format | –t ] [ -H ] [ -l Name ] [ -p Parent ] [ -s Status ] [ -w Connection ] [ -i PathID ]

lspath -A -l Name -p Parent [ -w Connection ] [ -i PathID ] {-D [ -O ] | -E [ -O ] | -F Format [ -Z character ] } [ -a Attribute ] ...[ -f File ] [ -H ]

lspath -A -l Name -p Parent [ -w Connection ] [ -i PathID ]-R -a Attribute [ -f File ] [ -H ]

lspath -h

Description

The lspath command displays one of two types of information about paths to an MPIO capable device. It either displays the operational status for one or more paths to a single device, or it displays one or more attributes for a single path to a single MPIO capable device. The first syntax shown above displays the operational status for one or more paths to a particular MPIO capable device. In this instance, the lspath command is similar to the lsdev command. The second syntax (keyed by the presence of the -A flag) displays one or more attributes for a single path to a particular MPIO capable device. In this instance, the lspath command is similar to the lsattr command. In fact, all of the flags for the lsattr command are supported on the lspath command when displaying path attributes.

Displaying Path Status with the lspath Command

When displaying path status, the set of paths to display is obtained by searching the device configuration database for paths that match the following criteria:

The target device name matches the device specified with the -l flag. If the -l flag is not present, then the target device is not used in the criteria.
The parent device name matches the device specified with the -p flag. If the -p flag is not present, then parent is not used in the criteria.
The connection matches the connection specified with the -w flag. If the -w flag is not present, then connection is not used in the criteria.
The path status matches status specified with the -s flag. If the -s flag is not present, the path status is not used in the criteria.

If none of the -l, -p, -w, -s flags are specified, then all paths known to the system are displayed.

By default, this command will display the information in columnar form. When no flags are specified that qualify the paths to display, the format of the output is:

status device  parent

The default display format can be overridden by using the -F Format flag. The -F Format flag displays the output in a user-specified format where the Format parameter is a quoted list of field names separated by, and possibly ended by, non-alphanumeric characters or white space. The field names are the fields defined in the CuPath class or one of the column heading defined above.

Note: The column names above are not translated into other languages (either when output as column headings or when input as part of the Format of the -F flag).

Possible values that can appear for the status column are:

enabled: Indicates that the path is configured and operational. It will be considered when paths are selected for IO.
Note: The AIX® MPIO does not fail the last path. Even though all paths to the storage are lost, the last path displays the status as enabled. In such a case, an IO error indicates the actual loss of the last path to the disk.
disabled: Indicates that the path is configured, but not currently operational. It has been manually disabled and will not be considered when paths are selected for IO.
failed: Indicates that the path is configured, but it has had IO failures that have rendered it unusable. It will not be considered when paths are selected for IO.
defined: Indicates that the path has not been configured into the device driver.
missing: Indicates that the path was defined in a previous boot, but it was not detected in the most recent boot of the system.
detected: Indicates that the path was detected in the most recent boot of the system, but for some reason it was not configured. A path should only have this status during boot and so this status should never appear as a result of the lspath command.

Displaying Path Attributes with the lspath Command

When displaying attributes for a path, the path must be fully qualified. Multiple attributes for a path can be displayed, but attributes belonging to multiple paths cannot be displayed in a single invocation of the lspath command. Therefore, in addition to the -A flag, the -l, -p, or-w flags are required to uniquely identify a single path. For example:

if only one path exists to a device, the -l flag is required
if only one path between a device and a specific parent, the -l and -p flags are required
if there are multiple paths between a device and a specific parent, the -l, -p, and -w flags are required

Furthermore, the -s flag is not allowed.

The same rules used by the lsattr command for displaying device attributes applies to the lspath command for displaying path attributes.

By default, this command will display the information in columnar form. The format of the output is the same as the lsattr command:

attribute   value    description         user_settable

All fields are shown by default. The default display format can be overridden by using the -F Format flag. The -F Format flag displays the output in a user-specified format where the Format parameter is a quoted list of column names separated by, and possibly ended by, non-alphanumeric characters or white space. The column names allowed are the field names from the CuPathAt, PdPathAt, and PdAtXtd object classes plus the columns listed above. The PdAtXtd based information is used by the Web-based System Manager.

Note: The column names above are not translated into other languages (either when output as column headings or when input as part of the Format of the -F flag).

Flags

Item	Description
-a Attribute	Identifies the specific attribute to list. The 'Attribute' is the name of a path specific attribute. When this flag is provided, only the identified attribute is displayed. Multiple instances of this flag may be used to list multiple attributes. If this flag is not specified at all, all attributes associated with the identified path will be listed.
-A	Indicates that attributes for a specific path are to be displayed. When the -A flag is present, the -s Status flag is not allowed. However, the -l Name, -p Parent, and -w Connection flags must be present to fully qualify the path.
-D	Displays the attribute names, default values, descriptions, and user-settable flag values for a specific path when not used with the -O flag. The -D flag displays only the attribute name and default value in colon format when used with the -O flag. This flag is only valid when displaying path attributes and it cannot be used with the -E, -F, or -R flag.
-E	Displays the attribute names, current values, descriptions, and user-settable flag values for a specific path when not used with the -O flag. The -E flag displays only the attribute name and current value in colon format when used with the -O flag. This flag is only valid when displaying path attributes and it cannot be used with the -D, -F, or -R flag.
-f File	Reads the needed flags from the File parameter.
-F Format	Displays the output in a user-specified format, where the Format parameter is a quoted list of column names separated by non-alphanumeric characters or white space. Using white space as the separator, the lspath command displays the output in aligned columns. Valid column names depends upon the type of information requested. For path display, column names from the CuPath object class can be specified. For path attribute display (the -A flag is specified), column names from the PdPathAt and CuPathAt object classes can be specified. In addition to the column names, there are two special purpose names that can be used. The name description can be used to obtain a display of attribute descriptions and user-settable can be used to obtain an indication as to whether or not an attribute can be changed. This flag cannot be used with the -E, -D, -O or -R flag.
-h	Displays the command usage message.
-H	Displays headers above the column output. To use the -H flag with the -O flag is meaningless, the -O flag prevails. To use the -H flag with the -R flag is meaningless; the -R flag prevails.
-i PathID	Indicates the path ID associated with the path to be displayed.
-l Name	Specifies the logical device name of the target device whose path information is to be displayed. This flag is optional for displaying path status, but is required for displaying path attributes.
-O	Displays all attribute names separated by colons and, on the second line, displays all the corresponding attribute values separated by colons. The attribute values are current values when the -E flag is also specified and default values when the -D flag is specified. This flag is only valid when displaying path attributes and it cannot be used with the -F and -R flags.
-p Parent	Indicates the logical device name of the parent device of the path(s) to be displayed. This flag is optional for displaying path status, but is required for displaying path attributes.
-R	Displays the legal values for an attribute name. The -R flag cannot be used with the -D, -E, -F and -O flags. The -R flag displays the list attribute values in a vertical column as follows: `Value1 Value2 . . ValueN` The -R flag displays the range attribute values as x...n(+i) where x is the start of the range, n is the end of the range, and i is the increment.
-s Status	The -s Status flag indicates the status to use in qualifying the paths to be displayed. When displaying path information, the allowable values for this flag are: enabled Display paths that are enabled for MPIO path selection. disabled Display paths that are disabled from MPIO path selection. failed Display paths that are failed due to IO errors. available Display paths whose path_status is PATH_AVAILABLE (that is, paths that are configured in the system, includes enabled, disabled, and failed paths). defined Display paths whose path_status is PATH_DEFINED. missing Display paths whose path_status is PATH_MISSING. You can use alternative forms of the values. Strings beginning with 0, d, or D are treated in the same way as defined. The only exception is that strings starting with di, Di, dI, or DI are treated in the same way as disabled. Strings beginning with 1, a, or A are treated in the same way as available. Strings beginning with 3, m, or M are treated in the same way as missing. Strings beginning with e or E are treated in the same way as enabled. Strings beginning with f or F are treated in the same way as failed.
-t	Displays the path ID in addition to the current default output. The -t flag cannot be used with the -F or the -A flags.
-w Connection	Indicates the connection information to use in qualifying the paths to be displayed. This flag is optional for displaying path status, but is required for displaying path attributes.
-Z Character	The -Z Character flag is meant to be used for programs that need to deal with ODM fields that may have embedded new line characters. An example of such a program is the Web-based System Manager. The -Z Character flag is used to change the record separator character for each record (line) of output generated. The new record separator is the 'Character' argument to this flag. The -Z Character flag is only relevant when the -A and the -F Format flags are specified. The -Z Character flag cannot be used with the -D, -E, -O, or the -R flags.

Security

Privilege Control: All users can execute this command.

Auditing Events: None.

Examples

Examples of displaying path status:

To display the status of all paths to hdisk1 with column headers, enter:
```
lspath -H -l hdisk1
```
The system will display a message similar to the following:
```
status    device   parent
enabled   hdisk1   scsi0
disabled  hdisk1   scsi1
missing   hdisk1   scsi2
```
To display, without column headers, the set of paths whose operational status is disabled, enter:
```
lspath -s disabled
```
The system will display a message similar to the following:
```
disabled  hdisk1   scsi1
disabled  hdisk2   scsi1
disabled  hdisk23  scsi8
disabled  hdisk25  scsi8
```
To display the set of paths whose operational status is failed, enter:
```
lspath -s failed
```
The system will display a message similar to the following:
```
failed  hdisk1   scsi1
failed  hdisk2   scsi1
failed  hdisk23  scsi8
failed  hdisk25  scsi8
```
To display in a user-specified format, without column headers, the set of paths to hdisk1 whose path status is available enter:
```
lspath -l hdisk1 -s available -F"connection:parent:path_status:status"
```
The system will display a message similar to the following:
```
5,0:scsi0:available:enabled
6,0:scsi1:available:disabled
```
Note that this output shows both the path status and the operational status of the device. The path status simply indicates whether the path is configured or not. The operational status indicates how the path is being used with respect to path selection processing in the device driver. Only paths with a path status of available also have an operational status. If a path is not currently configured into the device driver, it does not have an operational status.

Examples of displaying path attributes:

If the target device is a SCSI disk, to display all attributes for the path to parent scsi0 at connection 5,0, use the command:
```
lspath -AHE -l hdisk10 -p scsi0 -w "5,0"
```
The system will display a message similar to the following:
```
attribute  value  description                       user_settable
weight     1      Order of path failover selection  true
```