IBM Support

devscan tool

devscan tool

Tab navigation

The following information describes the devscan tool, its options and uses.




Diagnostic tool for Storage Area Networks


devscan [ options ]


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 below 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 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, described below.

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.


-t, --types=<subflags>

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

-c, --commands=<level | subflags>

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

  1. 0

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

  2. 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. 3

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

  4. 5

    Normal behavior, plus PVID checking.

  5. 7

    Everything except performance testing.

  6. 9


The available commands are

  1. l

    Report LUNs

  2. i


  3. t

    Test Unit Ready

  4. a

    ALUA commands (RTPG)

  5. c

    Read Capacity

  6. r

    Reservation commands (PR In & Read)

  7. p

    Performance testing (Read)

  8. 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.

  1. Inquiry

    -> Start

  2. Test Unit Ready

    -> Start

  3. RTPG

    -> Start

  4. Read Capacity

    -> Start

  5. 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=<wwpn>

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.

--intra_npiv_delay=<time in usec>

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.

--inter_npiv_delay=<time in usec>

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.

--dev=<device name>

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.

<hostname or IP address> [ <port number> [ <name> [ <password> ]]]


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.


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.


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

-v, --verbosity=<level>

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

-V, --version

Print version information.

-o, --outputfile=<filename>

Devscan writes to filename instead of stdout.

-F, --force

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.

-?, --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

  1. To run against all SCSI adapters with the default command set (Start, Report LUNs, and Inquiry):
  2. To run against only the fscsi3 adapter and gather SCSI Status from all attached devices:
    devscan -c7 --dev=fscsi3
  3. 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
  4. To run devscan in machine-parseable mode using "::" as the field delimiter:
    devscan --concise --delim="::"
  5. 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
  6. To scan only the storage port 5001738000330193:
    echo "f|||5001738000330193" | devscan --whitelist=-
  7. To scan only the storage at SCSI ID 0x010400:
    echo "f|010400" | devscan --whitelist=-
  8. To scan only for hdisk15:
    echo "hdisk15" | devscan --whitelist=-
  9. To scan for all targets except the one with WWNN 5001738000330000:
    echo "f||||5001738000330000" | devscan --blacklist=-
  10. To scan for an iSCSI target at
    echo "" | devscan --iscsitargets=-
  11. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. Vendor ID: IBM Device ID: 2107900 Rev: 5.90 NACA:
    PDQ: Not connected PDT: Unknown or no device
    Dynamic Tracking Enabled
    TUR SCSI status:

    Check Condition (sense key: ABORTED_COMMAND;
    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.
  7. 651b00 0000000000000000 201400a0b82697ac
    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.
  8. 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

    5f1a00 0000000000000000 500507680110a59c
    5f5a00 0000000000000000 500507680110a61c

    Working NPIV - mode output, reporting targets but not LUNs.


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

Document information

More support for: AIX family

Operating system(s): AIX

Reference #: ools74886e0c

Modified date: 22 June 2018

Translate this page: