Product Documentation
Abstract
AIX Support Center Tools
Content
The following information describes the devscan tool, its options and uses.
Name
devscan
Purpose
Diagnostic tool for Storage Area Networks
Syntax
devscan [ options ]
Description
The purpose of devscan is to make debugging storage problems faster and easier. Devscan does this by rapidly gathering a great deal of information about the SAN and displaying it 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 in Further Details. The data is therefore guaranteed to be 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 :
1) Finds every Fibre Channel, SAS, iSCSI, and VSCSI adapter in the system and traverses each one.
2) 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, described in the "Flags" section.
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
Specify which adapter types to scan. Valid subflags are v, s, i, and f, for VSCSI, SAS, iSCSI, and FCP, respectively.
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 needed.
The levels have the following meanings
The available commands are
Some SCSI commands require other commands. Specifying a command that requires others causes the prerequisite commands to be performed as well.
-
Inquiry
-> Start
-
Test Unit Ready
-> Start
-
RTPG
-> Start
-
Read Capacity
-> Start
-
Read
-> Read Capacity
The Report LUNs command 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 devscan SCSI commands can consume a SCSI Check Condition type Unit Attention. It is possible the Unit Attention message was 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 higher than 3 or command subflags a, r, p, v, t, and c require confirmation that the user wants to proceed, either on the command line or via the -F flag.
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.
Due to a limitation in the AIX SCSI API, devscan in NPIV mode cannot issue SCSI commands. As a result devscan can get a list of target ports from the nameserver, but cannot issue Report LUNs, so you will not see specific disks in the NPIV mode. There are two common scenarios where this flag is appropriate. (1) The client cannot boot, or (2) the WWPN to be scanned is the client's alternate WWPN, e.g., for an LPM environment.
Devscan waits at least the specified time after issuing a STARTINITR for an NPIV login before issuing the corresponding STOPINITR. This flag is ignored if -n is not specified.
Devscan waits at least the specified time after issuing a STOPINITR for an NPIV login before issuing the next STARTINITR. This flag is ignored if -n is not specified.
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/".
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.
A file containing a list of allowed or blocked descriptors may be loaded. The file name may be "-", and devscan will read from stdin. The allowlist and blocklist flags cannot be used together.
<hostname or IP address> [ <port number> [ <name> [ <password> ]]]
--allowlist=<filename>
If a LUN does not match an entry on either allowlist or blocklist, no commands are sent to the LUN. However, Start and Report LUNs commands will always be issued to LUN 0. This design serves two purposes:
1) Limit the time required for devscan to run on large SANs.
2) Limit the number of devices affected when a command level is greater than 3. 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.
f|[scsi_id]|[lun_id]|[wwpn]|[wwnn]
s|[sas_id]|[lun_id]
i|[target_name]|[target_ip_addr]|[lun_id]
v|<lun_id>
At least one specifier must be provided per entry. More may be provided as needed. Specifiers may be left empty.
Devscan outputs machine-parseable data. Every LUN is 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 is printed describing each field as the first line of output. Error output is suppressed.
Specify a string up to 8 characters to use as the delimiter for the --concise flag.
Verbosity level, from 0 to 9. Default is 3.
Print version information.
Devscan writes to filename instead of stdout.
Force flag. See -c flag information.
Timestamps. Valid subflags are l, t, a, and T, and will cause timestamps to be printed for LUN, target, adapter, and total, respectively.
Print usage information.
Further details
ODM names and path IDs are provided for convenience, but they are obtained from the ODM. If the ODM has, for whatever reason, erroneous 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.
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 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 --allowlist=- - To scan only the storage at SCSI ID 0x010400:
echo "f|010400" | devscan --allowlist=- - To scan only for hdisk15:
echo "hdisk15" | devscan --allowlist=- - To scan for all targets except the one with WWNN 5001738000330000:
echo "f||||5001738000330000" | devscan --blocklist=- - 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 --allowlist=- -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. - Name server 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 ECONNREFZZED
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. - Processing FC device:
Adapter driver: fcs0
Protocol driver: fscsi0
Connection type: fabric
Link State: up
Current link speed: 8 Gbps
Local SCSI ID: 0x5f0d5a
Local WWPN: 0x21000024ff41edb4
Local WWNN: 0x20000024ff41edb4
NPIV SCSI ID: 0x5f0d5b
NPIV WWPN: 0xc050760472460108
Device ID: 0x7710322577107501
Microcode level: 0319050702
SCSI ID LUN ID WWPN WWNN
----------------------------------------------
5f1a00 0000000000000000 500507680110a59c
500507680100a59c
5f5a00 0000000000000000 500507680110a61c
500507680100a61c
Working NPIV - mode output, reporting targets but not LUNs.
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 --blocklist - --iscsitargets -
0 Successful completion
>0 Error status
| SUPPORT |
|---|
|
If you require more assistance, use the following step-by-step instructions to contact IBM to open a case for software with an active and valid support contract. 1. Document (or collect screen captures of) all symptoms, errors, and messages related to your issue. 2. Capture any logs or data relevant to the situation. 3. Contact IBM to open a case: -For electronic support, see the IBM Support Community: 4. Provide a clear, concise description of the issue. 5. If the system is accessible, collect a system snap, and upload all of the details and data for your case. - For guidance, see: Working with IBM AIX Support: Collecting snap data |
Related Information
Document Location
Worldwide
Was this topic helpful?
Document Information
Modified date:
14 October 2022
UID
aixtools8cbfead