Uses information in sysfs (Linux kernel series 2.6 and later) to list SCSI devices (or hosts) currently attached to the system. Options can be used to control the amount and form of information provided for each device.
If a H:C:T:L argument is given then it acts as a filter and only devices that match it are listed. The colons don't have to be present, and '-', '*', '?' or missing arguments at the end are interpreted as wildcards. The default is '*:*:*:*' which means to match everything. Any filter string using '*' of '?' should be surrounded by single or double quotes to stop shell expansions. If '-' is used as a wildcard then the whole filter argument should be prefixed by '-- ' to tell this utility there are no more options on the command line to be interpreted. A leading '[' and trailing ']' are permitted (e.g. '[1:0:0]' matches all LUNs on 1:0:0). May also be used to filter --hosts in which case only the H is active and may be either a number or in the form "host<n>" where <n> is a host number.
By default in this utility device node names (e.g. "/dev/sda" or "/dev/root_disk") are obtained by noting the major and minor numbers for the listed device obtained from sysfs (e.g. the contents of "/sys/block/sda/dev") and then looking for a match in the "/dev" directory. This "match by major and minor" will allow devices that have been given a different name by udev (for example) to be correctly reported by this utility.
In some situations it may be useful to see the device node name that Linux would produce by default, so the --kname option is provided. An example of where this may be useful is kernel error logs which tend to report disk error messages using the disk's default kernel name.
When the --transport option is given for devices (i.e. --hosts not given) then most of the information produced by lsscsi is associated with the target, or more precisely: the target port, through which SCSI commands pass that access a logical unit.
Typically this utility provides one line of output per "device" or host. Significantly more information can be obtained by adding the --list option. When used together with the --transport option, after the summary line, multiple lines of transport specific information in the form "<attribute_name>=<value>" are output, each indented by two spaces. Using a filter argument will reduce the volume of output if a lot of devices or hosts are present.
The transports that are currently recognized are: IEEE 1394, ATA, FC, iSCSI, SAS, SATA, SPI and USB.
For IEEE 1394 (a.k.a. Firewire and "SBP" when storage is involved), the EUI-64 based target port name is output when --transport is given, in the absence of the --hosts option. When the --hosts option is given then the EUI-64 initiator port name is output. Output on the summary line specific to the IEEE 1394 transport is prefixed by "sbp:".
to detect ATA and SATA a crude check is performed on the driver name (after the checks for other transports are exhausted). Based on the driver name either ATA or SATA transport type is chosen. Output on the summary line is either "ata:" or "sata:". No other attributes are given. Most device and hosts flagged as "ata:" will use the parallel ATA transport (PATA).
For Fibre Channel (FC) the port name and port identifier are output when --transport is given. In the absence of the --hosts option these ids will be for the target port associated with the device (logical unit) being listed. When the --hosts option is given then the ids are for the initiator port used by the host. Output on the summary line specific to the FC transport is prefixed by "fc:". If FCoE (over Ethernet) is detected the prefix is changed to "fcoe:".
For iSCSI the target port name is output when --transport is given, in the absence of the --hosts option. This is made up of the iSCSI name and the target portal group tag. Since the iSCSI name starts with "iqn" no further prefix is used. When the --hosts option is given then only "iscsi:" is output on the summary line.
For Serial Attached SCSI the SAS address of the target port (or initiator port if --hosts option is also given) is output. This will be a naa-5 address. For SAS HBAs and SAS targets (such as SAS disks and tape drives) the SAS address will be world wide unique. For SATA disks attached to a SAS expander, the expander provides the SAS address by adding a non zero value to its (i.e. the expander's) SAS address (e.g. expander_sas_address + phy_id + 1). SATA disks directly attached to SAS HBAs seem to have an indeterminate SAS address. Output on the summary line specific to the SAS transport is prefixed by "sas:".
For the SCSI Parallel Interface (SPI) the target port identifier (usually a number between 0 and 15 inclusive) is output when --transport is given, in the absence of the --hosts option. When the --hosts option is given then only "spi:" is output on the summary line.
When a USB transport is detected, the summary line will contain "usb:" followed by a USB device name. The USB device name has the form "<b>-<p1>[.<p2>[.<p3>]]:<c>.<i>" where <b> is the USB bus number, <p1> is the port on the host. <p2> is a port on a host connected hub, if present. If needed <p3> is a USB hub port closer to the USB storage device. <c> refers to the configuration number while <i> is the interface number. There is a separate SCSI host for each USB (SCSI) target. A USB SCSI target may contain multiple logical units. Thus the same "usb: <device_name>" string appears for a USB SCSI host and all logical units that belong to the USB SCSI target associated with that USB SCSI host.
Up until 2013, Linux mapped SCSI LUNs to a 32 bit integer by taking the first 4 bytes of the SCSI LUN and ignoring the last 4 bytes. Linux treated the first two bytes of the SCSI LUN as a unit (a word) and it became the least significant 16 bits in the Linux LUN integer. The next two bytes of the SCSI LUN became the upper 16 bits in the Linux LUN integer. The rationale for this was to keep commonly used LUNs small Linux LUN integers. The most common LUN (by far) in SCSI LUN (hex) notation is 00 00 00 00 00 00 00 00 and this becomes the Linux LUN integer 0. The next most common LUN is 00 01 00 00 00 00 00 00 and this becomes the Linux LUN integer 1.
In 2013 it is proposed to increase Linux LUNs to a 64 bit integer by extending the mapping outlined above. In this case all information that is possible to represent in a SCSI LUN is mapped a Linux LUN (64 bit) integer. And the mapping can be reversed without losing information.
This version of the utility supports both 32 and 64 bit Linux LUN integers. By default the LUN shown at the end of the tuple commencing each line is a Linux LUN as a decimal integer. When the --lunhex option is given then the LUN is in SCSI LUN format with the 8 bytes run together, with the output in hexadecimal and prefixed by '0x'. The LUN is decoded according to SAM-5's description and trailing zeros (i.e. digits to the right) are not shown. So LUN 0 (i.e. 00 00 00 00 00 00 00 00) is shown as 0x0000 and LUN 65 (i.e. 00 41 00 00 00 00 00 00) is shown as 0x0041. If the --lunhex option is given twice then the full 64 bits (i.e. 16 hexadecimal digits) are shown.
If the --lunhex option is not given on the command line then the environment variable LSSCSI_LUNHEX_OPT is checked. If LSSCSI_LUNHEX_OPT is present then its associated value becomes the number of times the --lunhex is set internally. So, for example, 'LSSCSI_LUNHEX_OPT=2 lsscsi' and 'lsscsi -xx' are equivalent.
Generic SCSI devices can also be accessed via the bsg driver in Linux. By default, the bsg driver's device node names are of the form '/dev/bsg/H:C:T:L'. So, for example, the SCSI device shown by this utility on a line starting with the tuple '6:0:1:2' could be accessed via the bsg driver with the '/dev/bsg/6:0:1:2' device node name.
lsscsi version 0.21 or later is required to correctly display SCSI devices in Linux kernel 2.6.26 (and possibly later) when the CONFIG_SYSFS_DEPRECATED_V2 kernel option is not defined.