AIX, HACMP, PowerVM: AIX

Thanks to IBM,

Name

devscan

Purpose

Diagnostic tool for Storage Area Networks

Syntax

devscan [ options ]

Description

The devscan tool facilitates the debugging of storage problems by rapidly gathering a great deal of information about the SAN. It then displays the information in an easy-to-understand manner. . The information devscan displays is gathered from the SAN itself or the device driver, not from ODM, with exceptions described below inFurther Details. The data is therefore current and correct.

Devscan scans a set of SCSI adapters, and then issues a set of commands to a set of targets and LUNs on those adapters. In the default case, devscan finds every Fibre Channel, SAS, iSCSI, and VSCSI adapter in the system and traverses each one. It issues SCSI Report LUNs and Inquiry commands to every target and LUN it finds. The set of adapters to be scanned, targets and LUNs to be traversed, and commands to be issued may be controlled with several of the optional flags.

You can run devscan from any AIX host, including VIO clients, or from a VIOS.

In the default case, devscan is unable to change any state on the SAN or on the host, making it safe to run even in production environments. In all cases, devscan is safer to run than cfgmgr, because it cannot change the ODM. Some of the optional commands devscan can use are able to cause a state change on the SAN. Details are provided in the Flags section.

Flags

-t, --types=

Specify which adapter types to scan. Valid subflags are v, s, i, and f, for VSCSI, SAS, iSCSI, and FCP, respectively.

-c, --commands=

Commands may be specified as a level from 0 to 9, defaulting to 3, or as a series of subflags naming specific commands that are desired.

The levels have the following meanings

0

No commands issued, devscan will only report on the adapters it finds.
1

The special LUN 0 is Started and Report LUNs is issued, but no commands are sent to the other LUNs. The list of LUNs is printed.
3

Normal behavior. Every reported LUN is Started and an Inquiry is sent.
5

Normal behavior, plus PVID checking.
7

Everything except performance testing.
9

Everything.

The available commands are

l

Report LUNs
i

Inquiry
t

Test Unit Ready
a

ALUA commands (RTPG)
c

Read Capacity
r

Reservation commands (PR In & Read)
p

Performance testing (Read)
v

Check PVID (Read)

Some SCSI commands require others to be done. Specifying a command that requires others will cause the prerequisite commands to be performed as well.

Inquiry

-> Start
Test Unit Ready

-> Start
RTPG

-> Start
Read Capacity

-> Start
Read

-> Read Capacity

Report LUNs is required for awareness of any LUN besides LUN 0, but it is not a prerequisite of any command. If Report LUNs is not requested, the specified set of commands will be sent only to LUN 0.

Some of the devscan SCSI commands can consume a SCSI Check Condition type Unit Attention. It is possible this Unit Attention was actually generated by another application on the host, including the device driver. In that case, devscan will consume a Unit Attention that the other application needs to know about, potentially putting the host and the target device into inconsistent states. Because of this possibility, command levels above 3 or command subflags a, r, p, v, t, and c require confirmation that the user wishes to proceed, either on the command line or via the -F flag.

-n, --npiv=

NPIV mode. Devscan masquerades as an NPIV client when running on a VIOS using the given WWPN. The WWPN must be specified as a 64-bit hexadecimal number.

--intra_npiv_delay=

Devscan waits at least the specified time after issuing a STARTINITR for an NPIV login before issuing the corresponding STOPINITR.

--inter_npiv_delay=

Devscan waits at least the specified time after issuing a STOPINITR for an NPIV login before issuing the next STARTINITR.

--dev=

Devscan scans only the specified adapter, rather than all adapters. The device name must be either the adapter or protocol driver instance name, and may optionally be preceded by "/dev/".

--iscsitargets=

Devscan by default will traverse /etc/iscsi/targets or /etc/iscsi/targetshw, depending on the iSCSI adapter type. In addition to the default, the user may pass in another file listing iSCSI targets. The file name may be "-", and devscan will read from stdin. The format of the file is a whitespace-delimited list, similar to the format of /etc/iscsi/targets, except the subsequent fields may be omitted and devscan will substitute the default port of 3260, the default name of "iscsi", and default to using no authentication.

[ [ [ ]]]

--blacklist=
--whitelist=

A file containing a list of descriptors may be passed in to be either white or black listed. The file name may be "-", and devscan will read from stdin. White and black listing may not be used at the same time.

If a LUN does not match any entry on the white list, or does match any entry on the black list, no commands are issued to it, except that Start and Report LUNs will be issued to LUN 0 regardless. This has two primary purposes: to limit the time it takes devscan to run on large SANs, and to limit the number of devices that may be affected if a command level greater than 3 is in use. See -c flag information.

Devices may be specified by name, or by location. To specify by name, simply enter the ODM name of the device, one per line. To enter the location, specify the device type (f, i, v, or s), followed by a "|" delimited list of specifiers appropriate to that type, as follows.

At least one specifier must be provided per entry. More may be provided as desired. Specifiers may be left empty.

--concise

Devscan will output in a machine-parseable format. Every LUN will be displayed on one line in a delimited list. The default delimiter is "|", but another may be passed in using the --delim flag. A header line will be printed describing each field as the first line of output. Error output is suppressed.

--delim=

Specify a string up to 8 characters to use as the delimiter for the --concise flag.

-v, --verbosity=

Verbosity level, from 0 to 9. Default is 3.

-V, --version

Print version information.

-o, --outputfile=

Devscan writes to filename instead of stdout.

-F, --force

Force flag. See -c flag information.

--timestamps=

Timestamps. Valid subflags are l, t, a, and T, and will cause timestamps to be printed for LUN, target, adapter, and total, respectively.

-?, --usage, --help

Print usage information.

Further details

ODM names and path IDs

ODM names and path IDs are provided for convenience, but they are obtained from the ODM. If the ODM has, for whatever reason, errneous data, devscan will be misled. The ODM names and path IDs are therefore not guaranteed to be accurate.

Devscan does not construct the unique ID for SAN devices. Devscan attempts to match devices it finds on the SAN with devices in ODM using their location. The fields it uses to do this vary by adapter type, by necessity. In FCP, devscan uses the WWPN and LUN ID. In SAS, devscan matches the SAS ID and LUN ID. In iSCSI, the target name and LUN ID are matched. In VSCSI, only the LUN ID is needed.

PVID checking

If the command level is 5 or greater, or if the -cv flag is passed in, devscan will read the PVID location on every device it encounters and use it to match that device against the ODM, in addition to the device's location. If the device does not have a PVID, then this field is ignored.

Active/Active, Active/Passive and ALUA devices

Active paths appear with no special designation in devscan.

Passive paths can be revealed on most devices by invoking Test Unit Ready with -ct or -c7, and on all devices by issuing a Read with -cv or -c5. Passive paths will return with a failure condition.

Devscan automatically identifies ALUA-capable devices. ALUA state of each path will be ascertained if the ALUA commands are requested with the -c7 or -ca flag. An extra field will be printed for each ALUA-capable path revealing its state.

Usage examples

To run against all SCSI adapters with the default command set (Start, Report LUNs, and Inquiry):
devscan
To run against only the fscsi3 adapter and gather SCSI Status from all attached devices:
devscan -c7 --dev=fscsi3
To determine what the NPIV client using WWPN C0507601A673002A can see through all Fibre Channel adapters on the VIOS (e.g., because the client cannot boot):
devscan -t f -n C0507601A673002A
To run devscan in machine-parseable mode using "::" as the field delimiter:
devscan --concise --delim="::"
To run devscan against only the VSCSI adapters in the system and write the output to /tmp/vscsi_scan_results:
devscan -tv -o /tmp/vscsi_scan_results
To scan only the storage port 5001738000330193:
echo "f|||5001738000330193" | devscan --whitelist=-
To scan only the storage at SCSI ID 0x010400:
echo "f|010400" | devscan --whitelist=-
To scan only for hdisk15:
echo "hdisk15" | devscan --whitelist=-
To scan for all targets except the one with WWNN 5001738000330000:
echo "f||||5001738000330000" | devscan --blacklist=-
To scan for an iSCSI target at 192.168.3.147:
echo "192.168.3.147" | devscan --iscsitargets=-
To check the SCSI status of hdisk71 on all the Fibre adapters in the system and send the output to /tmp/devscan.out:
echo "hdisk71" | devscan --whitelist=- -o /tmp/devscan.out -tf -c7 -F

Output examples

Processing FC device: Adapter driver: fcs4 Protocol driver: fscsi4 Connection type: none Local SCSI ID: 0x000000 Device ID: df1000fe Microcode level: 271102

The connection type of "none" indicates this adapter has never had a link.
Processing FC device: Adapter driver: fcs0 Protocol driver: fscsi0 Connection type: fabric Link State: down Current link speed: 4 Gbps Local SCSI ID: 0x180600 Device ID: 77102224 Microcode level: 0125040024

The link state of "down" indicates this adapter had a link up since the last time it was configured, but does not currently.
Nameserver query succeeded, but indicated no targets are available on the SAN

This means the adapter's link to the switch is good, but no storage is available, typically because the storage has unexpectedly left the SAN or because it was not zoned to this host port.
Processing iSCSI device: Protocol driver: iscsi0 No targets found Elapsed time this adapter: 0.001358 seconds

For non-Fibre Channel devices, there is no name server, so the no-targets condition looks like this.
00000000001f7d00 0000000000000000 START failed with errno ECONNREFUSED

Devcsan is able to reach this device, so the host is connected to the SAN and the nameserver is reporting it, but we are not able to log in to the device. This is an end device problem.
Vendor ID: IBM Device ID: 2107900 Rev: 5.90 NACA: yes PDQ: Not connected PDT: Unknown or no device Dynamic Tracking Enabled TUR SCSI status: Check Condition (sense key: ABORTED_COMMAND; ASCQ: LOGICAL UNIT NOT SUPPORTED) ALUA-capable device Report LUNs failed with errno ENXIO Extended Inquiry failed with errno ETIMEDOUT Test Unit Ready failed with errno EIO

Devscan is successfully talking to this device, so the complete end-to-end connection is working. The SCSI Inquiry even succeeded, but the device is responding to further SCSI commands with errors for some reason. This is an end device problem.
651b00 0000000000000000 201400a0b82697ac 200400a0b82697ac Vendor ID: IBM Device ID: 1815 Rev: 0914 NACA: yes PDQ: Connected PDT: Block (Disc) Name: No ODM match 1 targets found, reporting 0 LUNs, 1 of which responded to SCIOLSTART. Responsive LUNs can exceed reported LUNs when LUN 0 is not reported, or when the target is a single-LUN device. This is not an error.

Devscan is again talking to this device, so the complete end-to-end connection is working, but only LUN 0 is responding. This is generally a LUN mapping or other configuration problem on the end storage device.

Limitations

ODM name matching is done using location, not unique ID. See Further details, above.

Due to a limitation of the device driver interface, devscan is unable to issue SCSI commands when using the -n flag. Using -n effectively forces the use of -c1 on all NPIV- capable adapters. Note that non-NPIV adapters (e.g., VSCSI or iSCSI adapters) are not affected and will use the default setting or whatever -c level was explicitly passed in.

Devscan supports multiple flags that can be directed to read from stdin, but only one may do so at a time. For example, the following command is invalid.

devscan --blacklist - --iscsitargets -

Exit status

0 Successful completion

>0 Error status

AIX - devscan