Blame doc/lsscsi.8

Packit a8f112
.TH lsscsi "8" "June 2018" "lsscsi\-0.30" LSSCSI
Packit a8f112
.SH NAME
Packit a8f112
lsscsi \- list SCSI devices (or hosts), list NVMe devices
Packit a8f112
.SH SYNOPSIS
Packit a8f112
.B lsscsi
Packit a8f112
[\fI\-\-brief\fR] [\fI\-\-classic\fR] [\fI\-\-controllers\fR]
Packit a8f112
[\fI\-\-device\fR] [\fI\-\-generic\fR] [\fI\-\-help\fR] [\fI\-\-hosts\fR]
Packit a8f112
[\fI\-\-kname\fR] [\fI\-\-list\fR] [\fI\-\-long\fR] [\fI\-\-long\-unit\fR]
Packit a8f112
[\fI\-\-lunhex\fR] [\fI\-\-no\-nvme\fR] [\fI\-\-pdt\fR] [\fI\-\-protection\fR]
Packit a8f112
[\fI\-\-protmode\fR] [\fI\-\-scsi_id\fR] [\fI\-\-size\fR]
Packit a8f112
[\fI\-\-sysfsroot=PATH\fR] [\fI\-\-sz\-lbs] [\fI\-\-transport\fR]
Packit a8f112
[\fI\-\-unit\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-wwn\fR]
Packit a8f112
[\fIH:C:T:L\fR]
Packit a8f112
.SH DESCRIPTION
Packit a8f112
.\" Add any additional description here
Packit a8f112
.PP
Packit a8f112
Uses information in sysfs (Linux kernel series 2.6 and later) to list SCSI
Packit a8f112
devices (or hosts) currently attached to the system. Many non\-SCSI storage
Packit a8f112
devices (but not all) used the SCSI subsystem in Linux. In lsscsi version
Packit a8f112
0.30 support was added to list NVMe devices.
Packit a8f112
.PP
Packit a8f112
In single line per device (LU or NVMe namespace) mode, the default, each
Packit a8f112
line starts with a 4 element tuple surrounded by square brackets. For SCSI
Packit a8f112
devices the first element 'H' is the host number, the second element 'C' is
Packit a8f112
the controller number, the third element 'T' is the target number and the
Packit a8f112
final element is the Logical Unit Number (LUN). All four are integers.
Packit a8f112
For NVMe namespaces see two paragraphs down. When the \fI\-\-hosts\fR option
Packit a8f112
is given for SCSI devices the tuple is reduced to one element: the host
Packit a8f112
number.
Packit a8f112
.PP
Packit a8f112
If a \fIH:C:T:L\fR tuple is given as an argument on the command line then
Packit a8f112
it acts as a filter and only devices that match it are listed. The colons
Packit a8f112
don't have to be present, and '\-', '*', '?' or missing components at the
Packit a8f112
end are interpreted as wildcards. The default is '*:*:*:*' which means to
Packit a8f112
match devices (i.e.  Logical Units). Any filter string using '*' of '?'
Packit a8f112
should be surrounded by single or double quotes to stop shell expansions.
Packit a8f112
If '\-' is used as a wildcard then the whole filter tuple should be prefixed
Packit a8f112
by '\-\- ' to tell this utility there are no more options on the command
Packit a8f112
line to be interpreted.  A leading '[' and trailing ']' are permitted (
Packit a8f112
e.g. '[1:0:0]' matches all LUNs on 1:0:0). May also be used to filter
Packit a8f112
\fI\-\-hosts\fR in which case only the \fIH\fR is active and may be either
Packit a8f112
a number or in the form "host<n>" where <n> is a host number.
Packit a8f112
.PP
Packit a8f112
For NVMe devices and controllers almost all of the previous paragraph
Packit a8f112
applies. The main difference is that "N" appears in the 'H' (first) position.
Packit a8f112
The 'C' position for NVMe is the controller's Linux generated "char" device
Packit a8f112
minor number which is the first number that appears in a typical NVMe
Packit a8f112
controller name, for example: "/dev/nvme2". The 'T' position for NVMe is
Packit a8f112
the "CNTLID" value. The final 'L' position is the NVMe namespace identifier
Packit a8f112
which is typically a sequential value starting at 1. The leading explicit "N"
Packit a8f112
for NVMe devices is converted internally into a large value (32,767) that
Packit a8f112
should not interfere with any Linux generated SCSI host number; it also means
Packit a8f112
that the numeric sort used to show hosts (controllers) and devices (LUs or
Packit a8f112
logical units) will always place NVMe devices and controllers after those
Packit a8f112
that use the SCSI subsystem. To filter using a \fIH:C:T:L\fR argument for
Packit a8f112
NVMe controllers, "hostN", "hostN:<num>", "N" or "N:<num>" may be used; when
Packit a8f112
no "<num>" is given, only NVMe controllers will be listed (i.e. it lists no
Packit a8f112
SCSI hosts (HBAs)).
Packit a8f112
.PP
Packit a8f112
By default in this utility device node names (e.g. "/dev/sda"
Packit a8f112
or "/dev/root_disk") are obtained by noting the major and minor numbers for
Packit a8f112
the listed device obtained from sysfs (e.g. the contents
Packit a8f112
of "/sys/block/sda/dev") and then looking for a match in the "/dev"
Packit a8f112
directory. This "match by major and minor" will allow devices that have been
Packit a8f112
given a different name by udev (for example) to be correctly reported by
Packit a8f112
this utility.
Packit a8f112
.PP
Packit a8f112
In some situations it may be useful to see the device node name that
Packit a8f112
Linux would produce by default, so the \fI\-\-kname\fR option is provided.
Packit a8f112
An example of where this may be useful is kernel error logs which tend to
Packit a8f112
report disk error messages using the disk's default kernel name.
Packit a8f112
.SH OPTIONS
Packit a8f112
Arguments to long options are mandatory for short options as well. The options
Packit a8f112
are arranged in alphabetical order based on the long option name. Hyphenated
Packit a8f112
long options can also take underscore, and vice versa (e.g. \fI\-\-scsi_id\fR
Packit a8f112
or \fI\-\-scsi\-id\fR are acceptable).
Packit a8f112
.TP
Packit a8f112
\fB\-b\fR, \fB\-\-brief\fR
Packit a8f112
reduces one line per device output to the tuple and the primary device name.
Packit a8f112
This may simplify scripts that process the output of this utility. With the
Packit a8f112
\fI\-\-generic\fR option it will show on each line the tuple (from which
Packit a8f112
the bsg pass\-through device name can be deduced), the primary device
Packit a8f112
name (which the block subsystem uses) and the sg device name (also a
Packit a8f112
pass\-through).
Packit a8f112
.br
Packit a8f112
When the \fI\-\-pdt\fR option is used together with this option the SCSI
Packit a8f112
Peripheral Device Type (PDT) is displayed in hex (with a leading "0x")
Packit a8f112
between the tuple and the primary device name. For NVMe namespaces "0x0"
Packit a8f112
is displayed (for a disk or direct access device).
Packit a8f112
.TP
Packit a8f112
\fB\-c\fR, \fB\-\-classic\fR
Packit a8f112
The output is similar to that obtained from 'cat /proc/scsi/scsi'
Packit a8f112
.TP
Packit a8f112
\fB\-C\fR, \fB\-\-controllers\fR
Packit a8f112
Lists NVMe controllers and SCSI hosts. This is a synonym for the
Packit a8f112
\fI\-\-hosts\fR option.
Packit a8f112
.TP
Packit a8f112
\fB\-d\fR, \fB\-\-device\fR
Packit a8f112
After outputting the (probable) SCSI device name the device node
Packit a8f112
major and minor numbers are shown in brackets (e.g. "/dev/sda[8:0]").
Packit a8f112
.TP
Packit a8f112
\fB\-g\fR, \fB\-\-generic\fR
Packit a8f112
Output the SCSI generic device file name. Note that if the sg driver
Packit a8f112
is a module it may need to be loaded otherwise '\-' may appear.
Packit a8f112
.br
Packit a8f112
NVMe does not have generic (char) devices in the same sense as SCSI.
Packit a8f112
Instead NVMe Admin, NVM (i.e. block type commands such as Read and
Packit a8f112
Write) and MI (Management Interface (e.g. to an enclosure)) commands
Packit a8f112
are all sent to the containing controller whose device name is shown
Packit a8f112
when the \fI\-\-hosts\fR option is used.
Packit a8f112
.br
Packit a8f112
To unclutter the single line per device mode the \fI\-\-brief\fR option
Packit a8f112
combined with this option should help.
Packit a8f112
.TP
Packit a8f112
\fB\-h\fR, \fB\-\-help\fR
Packit a8f112
Output the usage message and exit.
Packit a8f112
.TP
Packit a8f112
\fB\-H\fR, \fB\-\-hosts\fR
Packit a8f112
List the SCSI hosts and NVMe controllers currently attached to
Packit a8f112
the system. If this option is not given (and the \fI\-\-controllers\fR
Packit a8f112
option is not given) then SCSI devices (logical units (LUs)) followed by
Packit a8f112
NVMe devices (namespaces) are listed.
Packit a8f112
.TP
Packit a8f112
\fB\-k\fR, \fB\-\-kname\fR
Packit a8f112
Use Linux default algorithm for naming devices (e.g. block major 8,
Packit a8f112
minor 0 is "/dev/sda") rather than the "match by major and minor"
Packit a8f112
in the "/dev" directory as discussed above.
Packit a8f112
.TP
Packit a8f112
\fB\-L\fR, \fB\-\-list\fR
Packit a8f112
Output additional information in <attribute_name>=<value> pairs, one pair
Packit a8f112
per line preceded by two spaces. This option has the same effect as '\-lll'.
Packit a8f112
.TP
Packit a8f112
\fB\-l\fR, \fB\-\-long\fR
Packit a8f112
Output additional information for each SCSI device (host). Can be
Packit a8f112
used multiple times for more output in which case the shorter option
Packit a8f112
form is more convenient (e.g. '\-lll'). When used three times (i.e. '\-lll')
Packit a8f112
outputs SCSI device (host) attributes one per line; preceded by
Packit a8f112
two spaces; in the form "<attribute_name>=<value>".
Packit a8f112
.TP
Packit a8f112
\fB\-U\fR, \fB\-\-long\-unit\fR
Packit a8f112
Output logical unit name in full, if available. It replaces the normal
Packit a8f112
vendor, product and revision strings given in the single logical unit per
Packit a8f112
line mode. If no logical unit name is found "none" is printed. If the
Packit a8f112
logical unit name is long (e.g. a UUID) then following fields are pushed
Packit a8f112
further to the right as required. This option is functionally equivalent to
Packit a8f112
the '\-uuu' option.
Packit a8f112
.br
Packit a8f112
If the option is used twice (e.g. '\-UU') then EUI, NAA, UUID and T10 vendor
Packit a8f112
ID formats are prefixed by "eui.", "naa.", "uuid." and "t10." respectively.
Packit a8f112
Note that SCSI name format used by iSCSI should already be prefixed
Packit a8f112
by 'iqn.'. Using the '\-\-unit' option 4 or more times (e.g. '\-uuuu') will
Packit a8f112
have the same action as '\-UU'.
Packit a8f112
.br
Packit a8f112
\fI\-\-long_unit\fR is also an acceptable form when invoking this option.
Packit a8f112
.TP
Packit a8f112
\fB\-x\fR, \fB\-\-lunhex\fR
Packit a8f112
when this option is used once the LUN in the tuple (at the start of each
Packit a8f112
device line) is shown in "T10" format which is up to 16 hexadecimal
Packit a8f112
digits. It is prefixed by "0x" to distinguish the LUN from the decimal
Packit a8f112
value shown in the absence of this option. Also hierarchal LUNs are
Packit a8f112
shown with a "_" character separating the levels. For example the
Packit a8f112
two level LUN: 0x0355006600000000 will appear as 0x0355_0066. If this
Packit a8f112
option is given twice (e.g. using the short form: '\-xx') then the full
Packit a8f112
16 hexadecimal digits are shown for each LUN, prefixed by "0x".
Packit a8f112
.br
Packit a8f112
For NVMe, the namespace identifier (nsid) is shown in the "L" position. The
Packit a8f112
nsid is a 32 bit unsigned quantities with 0x0 and 0xffffffff reserved.
Packit a8f112
Without this option, the nsid is shown in decimal. When this option is used
Packit a8f112
once the nsid is output in hex with a lead 0x and with up to 3 leading zeros.
Packit a8f112
When this option is used twice the nsid is output in hex with up to 7 leading
Packit a8f112
zeros.
Packit a8f112
.TP
Packit a8f112
\fB\-N\fR, \fB\-\-no\-nvme\fR
Packit a8f112
this option excludes NVMe devices and controllers for the output. This option
Packit a8f112
may be needed to stop NVMe device output interfering with specific format
Packit a8f112
output like that produced when the \fI\-\-classic\fR option is used.
Packit a8f112
.br
Packit a8f112
To only show NVMe devices, use 'lsscsi N', to only show NVMe controllers,
Packit a8f112
use 'lsscsi \-H N'.
Packit a8f112
.TP
Packit a8f112
\fB\-D\fR, \fB\-\-pdt\fR
Packit a8f112
this option displays the SCSI Peripheral Device Type (PDT) in hex preceded
Packit a8f112
by "0x". For NVME namespaces "0x0' is displayed which corresponds to a
Packit a8f112
disk ("Direct Access Device" or SSD). In single line output this hex PDT
Packit a8f112
replaces the device type abbreviation (e.g. "0x0     " replaces "disk    ")
Packit a8f112
and appears after the tuple.
Packit a8f112
.TP
Packit a8f112
\fB\-p\fR, \fB\-\-protection\fR
Packit a8f112
Output target (DIF) and initiator (DIX) protection types.
Packit a8f112
.TP
Packit a8f112
\fB\-P\fR, \fB\-\-protmode\fR
Packit a8f112
Output effective protection information mode for each disk device.
Packit a8f112
.TP
Packit a8f112
\fB\-i\fR, \fB\-\-scsi_id\fR
Packit a8f112
outputs the udev derived matching id found in /dev/disk/by\-id/scsi* .
Packit a8f112
This is only for disk (and disk like) devices. If no match is found
Packit a8f112
then "dm\-uuid\-mpath*" and "usb*" are searched in the same directory.
Packit a8f112
If there is still no match then the /sys/class/block/<disk>/holders
Packit a8f112
directory is searched. The matching id is printed following the device
Packit a8f112
name (e.g.  /dev/sdc) and if there is no match "\-" is output.
Packit a8f112
.TP
Packit a8f112
\fB\-s\fR, \fB\-\-size\fR
Packit a8f112
Print disk capacity in human readable form. When given once, normal base
Packit a8f112
10 SI units are used as a prefix for 'B' which is bytes (aka octets).
Packit a8f112
For example MB, GB and TB stand for 10^6, 10^9 and 10^12 bytes
Packit a8f112
respectively. When given twice, IEC 80000\-3 prefixes for 'B' are used;
Packit a8f112
for example MiB, GiB and TiB stand for 2^20, 2^30 and 2^40
Packit a8f112
bytes respectively. The output is rounded to 3 or less significant
Packit a8f112
figures in order to fit on a single line.
Packit a8f112
.br
Packit a8f112
If given three times (short form is the more convenient: '\-sss') then
Packit a8f112
the disk capacity as a logical block count is given. This is an exact
Packit a8f112
figure in decimal reported by the storage device at discovery. Discovery
Packit a8f112
is typically just after boot time, or when it was last attached if the
Packit a8f112
storage device is removable.
Packit a8f112
.br
Packit a8f112
To unclutter the single line per device mode the \fI\-\-brief\fR option
Packit a8f112
combined with this option should help.
Packit a8f112
.TP
Packit a8f112
\fB\-y\fR, \fB\-\-sysfsroot\fR=\fIPATH\fR
Packit a8f112
assumes sysfs is mounted at PATH instead of the default '/sys' . If this
Packit a8f112
option is given PATH should be an absolute path (i.e. start with '/').
Packit a8f112
.TP
Packit a8f112
\fB\-S\fR, \fB\-\-sz\-lbs\fR
Packit a8f112
Print disk capacity as a number of logical blocks (which is the same
Packit a8f112
as '\-sss'). When used twice a comma is added followed by the logical
Packit a8f112
block size in bytes. It should be a number like 512 or 4096.
Packit a8f112
.br
Packit a8f112
If the logical block size cannot be found (e.g. because the version of
Packit a8f112
Linux predates the /sys/block/<dev_name>/queue directory) then the number
Packit a8f112
of 512 byte blocks followed comma and then '512' is output irrespective of
Packit a8f112
what the true logical block size of the device is. This special case
Packit a8f112
action occurs whether this option is given one or more times.
Packit a8f112
.br
Packit a8f112
To unclutter the single line per device mode the \fI\-\-brief\fR option
Packit a8f112
combined with this option should help.
Packit a8f112
.TP
Packit a8f112
\fB\-t\fR, \fB\-\-transport\fR
Packit a8f112
Output transport information. This will be target related information or,
Packit a8f112
if \fI\-\-hosts\fR is given, initiator related information. When used without
Packit a8f112
\fI\-\-list\fR, a name or identifier (or both) are output on a single line,
Packit a8f112
usually prefixed by the type of transport. For devices this information
Packit a8f112
replaces the normal vendor, product and revision strings. When the
Packit a8f112
\fI\-\-list\fR option is also given then additionally multiple lines
Packit a8f112
of attribute_name=value pairs are output, each indented by two spaces. See
Packit a8f112
the section on transports below.
Packit a8f112
.TP
Packit a8f112
\fB\-u\fR, \fB\-\-unit\fR
Packit a8f112
Output logical unit name, if available. If this option is given once or
Packit a8f112
twice, then the 30 character field where the vendor, product and revision
Packit a8f112
strings are usually placed is expanded to 32 characters and replaced by the
Packit a8f112
logical unit name. If no logical unit name is found "none" is printed.
Packit a8f112
The first found of the NAA, EUI\-64 or SCSI name string is output unless a
Packit a8f112
SCSI name string is found and the associated target port indicates the
Packit a8f112
iSCSI protocol, in which case the SCSI name string is preferred. Finally
Packit a8f112
if there is no match on the above and a T10 Vendor ID descriptor is found
Packit a8f112
then it is used.
Packit a8f112
.br
Packit a8f112
If the name cannot fit in the 32 character field then it is truncated to
Packit a8f112
the right and a trailing '_' character is used to alert the reader to the
Packit a8f112
truncation. The 32 character width is chosen since that is large enough to
Packit a8f112
hold 16 byte NAA or EUI\-64 identifiers. However SCSI name strings as used
Packit a8f112
by iSCSI can be larger than that.
Packit a8f112
.br
Packit a8f112
If this option is used twice then this field is also 32 character wide. If
Packit a8f112
the logical unit name cannot fit then it will be truncated to the left and
Packit a8f112
a leading '_' character is used to alert the reader to the truncation.
Packit a8f112
.br
Packit a8f112
If this option is used three times the whole logical unit name is
Packit a8f112
output, followed by several spaces.
Packit a8f112
.br
Packit a8f112
In order for this option to work, it needs a Linux kernel from and including
Packit a8f112
3.15 . It accesses the sysfs vpd_pg83 file for the device in question. Old
Packit a8f112
SCSI and ATA (SATA) equipment may not provide this information. If it is
Packit a8f112
provided by ATA (SATA) then it will be the WWN.
Packit a8f112
.TP
Packit a8f112
\fB\-v\fR, \fB\-\-verbose\fR
Packit a8f112
outputs directory names where information is found. Use multiple times for
Packit a8f112
more output.
Packit a8f112
.TP
Packit a8f112
\fB\-V\fR, \fB\-\-version\fR
Packit a8f112
outputs version information then exits. If used once outputs to stderr; if
Packit a8f112
used twice outputs to stdout and shortens the date to yyyymmdd numeric
Packit a8f112
format.
Packit a8f112
.TP
Packit a8f112
\fB\-w\fR, \fB\-\-wwn\fR
Packit a8f112
outputs the WWN for disks instead of manufacturer, model and revision (or
Packit a8f112
instead of transport information). The World Wide Name (WWN) is typically
Packit a8f112
64 bits long (16 hex digits) but could be up to 128 bits long. To indicate
Packit a8f112
the WWN is hexadecimal, it is prefixed by "0x". The ATA/SATA WWN is
Packit a8f112
referred to as LU name in SCSI jargon; hence this option is more or less
Packit a8f112
superseded by the \fI\-\-unit\fR and \fI\-\-long\-unit\fR options.
Packit a8f112
.SH TRANSPORTS
Packit a8f112
This utility lists SCSI devices which are known as logical units (LU) in
Packit a8f112
the SCSI Architecture Model (ref: SAM\-5 at http://www.t10.org) or hosts
Packit a8f112
when the \fI\-\-hosts\fR option is given. A host is called an initiator in
Packit a8f112
SAM\-5. A SCSI command travels out via an initiator, across some transport
Packit a8f112
to a target and then onwards to a logical unit. A target device may contain
Packit a8f112
several logical units. A target device has one or more ports that can be
Packit a8f112
viewed as transport end points. Each FC and SAS disk is a single target
Packit a8f112
that has two ports and contains one logical unit. If both target ports
Packit a8f112
on a FC or SAS disk are connected and visible to a machine, then lsscsi
Packit a8f112
will show two entries. Initiators (i.e. hosts) also have one or more ports
Packit a8f112
and some HBAs in Linux have a host entry per initiator port while others
Packit a8f112
have a host entry per initiator device.
Packit a8f112
.PP
Packit a8f112
When the \fI\-\-transport\fR option is given for devices (i.e.
Packit a8f112
\fI\-\-hosts\fR not given) then most of the information produced by lsscsi
Packit a8f112
is associated with the target, or more precisely: the target port, through
Packit a8f112
which SCSI commands pass that access a logical unit.
Packit a8f112
.PP
Packit a8f112
Typically this utility provides one line of output per "device" or host.
Packit a8f112
Significantly more information can be obtained by adding the \fI\-\-list\fR
Packit a8f112
option. When used together with the \fI\-\-transport\fR option, after
Packit a8f112
the summary line, multiple lines of transport specific information in the
Packit a8f112
form "<attribute_name>=<value>" are output, each indented by two spaces.
Packit a8f112
Using a filter argument will reduce the volume of output if a lot of
Packit a8f112
devices or hosts are present.
Packit a8f112
.PP
Packit a8f112
The transports that are currently recognized are: IEEE 1394, ATA, FC,
Packit a8f112
iSCSI, SAS, SATA, SPI, SRP and USB.
Packit a8f112
.PP
Packit a8f112
For IEEE 1394 (a.k.a. Firewire and "SBP" when storage is involved), the
Packit a8f112
EUI\-64 based target port name is output when \fI\-\-transport\fR is given,
Packit a8f112
in the absence of the \fI\-\-hosts\fR option. When the \fI\-\-hosts\fR
Packit a8f112
option is given then the EUI\-64 initiator port name is output. Output on
Packit a8f112
the summary line specific to the IEEE 1394 transport is prefixed by "sbp:".
Packit a8f112
.PP
Packit a8f112
To detect ATA and SATA devices a crude check is performed on the driver
Packit a8f112
name (after the checks for other transports are exhausted). Based on the
Packit a8f112
driver name either the ATA or SATA transport type is chosen. Output on
Packit a8f112
the summary line is either "ata:" or "sata:". A search is made for an
Packit a8f112
associated vpd_pg83 file in sysfs, if found it may contain the device's
Packit a8f112
WWN which is output if present. The WWN will not appear in Linux kernels
Packit a8f112
before 3.15 and with old PATA and SATA devices. Most device and hosts
Packit a8f112
flagged as "ata:" will use the parallel ATA transport (PATA). For SATA
Packit a8f112
devices that are attached via a SAS expander, see the SAS paragraph below.
Packit a8f112
.PP
Packit a8f112
For Fibre Channel (FC) the port name and port identifier are output
Packit a8f112
when \fI\-\-transport\fR is given. In the absence of the \fI\-\-hosts\fR
Packit a8f112
option these ids will be for the target port associated with the
Packit a8f112
device (logical unit) being listed. When the \fI\-\-hosts\fR option is
Packit a8f112
given then the ids are for the initiator port used by the host. Output
Packit a8f112
on the summary line specific to the FC transport is prefixed by "fc:".
Packit a8f112
If FCoE (over Ethernet) is detected the prefix is changed to "fcoe:".
Packit a8f112
.PP
Packit a8f112
For iSCSI the target port name is output when \fI\-\-transport\fR is given,
Packit a8f112
in the absence of the \fI\-\-hosts\fR option. This is made up of the
Packit a8f112
iSCSI name and the target portal group tag. Since the iSCSI name starts
Packit a8f112
with "iqn" no further prefix is used. When the \fI\-\-hosts\fR option
Packit a8f112
is given then only "iscsi:" is output on the summary line.
Packit a8f112
.PP
Packit a8f112
For Serial Attached SCSI the SAS address of the target port (or initiator
Packit a8f112
port if \fI\-\-hosts\fR option is also given) is output. This will be a naa\-5
Packit a8f112
address. For SAS HBAs and SAS targets (such as SAS disks and tape drives)
Packit a8f112
the SAS address will be world wide unique. For SATA disks attached to a
Packit a8f112
SAS expander, the expander provides the SAS address by adding a non zero
Packit a8f112
value to its (i.e. the expander's) SAS address (e.g. expander_sas_address +
Packit a8f112
phy_id + 1). SATA disks directly attached to SAS HBAs seem to have an
Packit a8f112
indeterminate SAS address. Output on the summary line specific to the SAS
Packit a8f112
transport is prefixed by "sas:".
Packit a8f112
.PP
Packit a8f112
For SATA devices, see the paragraph above on ATA devices. As noted in the
Packit a8f112
previous paragraph, SATA devices attached to SAS expanders will display a
Packit a8f112
manufactured SAS transport address (manufactured by the expander) rather
Packit a8f112
than the SATA device's WWN.
Packit a8f112
.PP
Packit a8f112
For the SCSI Parallel Interface (SPI) the target port identifier (usually
Packit a8f112
a number between 0 and 15 inclusive) is output when \fI\-\-transport\fR is
Packit a8f112
given, in the absence of the \fI\-\-hosts\fR option. When the \fI\-\-hosts\fR
Packit a8f112
option is given then only "spi:" is output on the summary line.
Packit a8f112
.PP
Packit a8f112
For the PCIe transport (a.k.a. PCI Express) there at two possible storage
Packit a8f112
types: NVMe and SOP/PQI (SCSI over PCIe). There are very few examples of the
Packit a8f112
latter currently so this utility concentrates on NVMe. NVMe uses its own
Packit a8f112
command set and not SCSI but has many things in common. Rather than
Packit a8f112
re\-invent everything currently in use that SCSI has accumulated over nearly
Packit a8f112
40 years, NVMe is beginning to use some parts of SCSI. A recent example is
Packit a8f112
the SES\-3 standard for enclosure management which has been adopted by NVMe.
Packit a8f112
In SCSI a SES device is a logical unit with a peripheral device type (PDT)
Packit a8f112
of 0xd (for enclosure) so it will appear when the lsscsi utility is invoked
Packit a8f112
without any options. In NVMe is seems that an enclosure with appear as
Packit a8f112
attached to the management interface (MI) of a NVMe controller. This means
Packit a8f112
it should appear when "lsscsi \-\-hosts" is invoked. It is unclear whether
Packit a8f112
such a NVMe controller can have any storage namespaces associated with
Packit a8f112
it. The sg_ses utility (in the sg3_utils package) can then be given that NVMe
Packit a8f112
controller's device name (e.g. /dev/nmve1).
Packit a8f112
.br
Packit a8f112
When the \fI\-\-transport\fR option is given, after "pcie" the NVMe
Packit a8f112
controller's subsystem vendor id and device id are output, separated by a
Packit a8f112
colon (e.g. "pcie 0x8086:0x390a").
Packit a8f112
.PP
Packit a8f112
For the SCSI RDMA Protocol (SRP) the IB (InfiniBand) port's GUID is given.
Packit a8f112
As an example, it has a form like this: 0002:c903:00fa:abcd .
Packit a8f112
.PP
Packit a8f112
When a USB transport is detected, the summary line will contain "usb:"
Packit a8f112
followed by a USB device name. The USB device name has the
Packit a8f112
form "\-<p1>[.<p2>[.<p3>]]:<c>." where  is the USB bus number, <p1>
Packit a8f112
is the port on the host. <p2> is a port on a host connected hub, if present.
Packit a8f112
If needed <p3> is a USB hub port closer to the USB storage device. <c>
Packit a8f112
refers to the configuration number while  is the interface number. There
Packit a8f112
is a separate SCSI host for each USB (SCSI) target. A USB SCSI target may
Packit a8f112
contain multiple logical units. Thus the same "usb: <device_name>" string
Packit a8f112
appears for a USB SCSI host and all logical units that belong to the USB
Packit a8f112
SCSI target associated with that USB SCSI host.
Packit a8f112
.SH LUNS
Packit a8f112
For historical reasons and as used by several other Unix based Operating
Packit a8f112
Systems, Linux uses a tuple of integers to describe (a path to) a SCSI
Packit a8f112
device (also know as a Logical Unit (LU)). The last element of that tuple
Packit a8f112
is the so\-called Logical Unit Number (LUN). And originally in SCSI a
Packit a8f112
LUN was an integer, at first 3 bits long, then 8 then 16 bits. SCSI LUNs
Packit a8f112
today (SAM\-5 section 4.7) are 64 bits but SCSI standards now consider
Packit a8f112
a LUN to be an array of 8 bytes.
Packit a8f112
.PP
Packit a8f112
Up until 2013, Linux mapped SCSI LUNs to a 32 bit integer by taking the
Packit a8f112
first 4 bytes of the SCSI LUN and ignoring the last 4 bytes. Linux treated
Packit a8f112
the first two bytes of the SCSI LUN as a unit (a word) and it became the
Packit a8f112
least significant 16 bits in the Linux LUN integer. The next two bytes of
Packit a8f112
the SCSI LUN became the upper 16 bits in the Linux LUN integer. The rationale
Packit a8f112
for this was to keep commonly used LUNs small Linux LUN integers. The most
Packit a8f112
common LUN (by far) in SCSI LUN (hex) notation is 00 00 00 00 00 00 00 00
Packit a8f112
and this becomes the Linux LUN integer 0. The next most common LUN is
Packit a8f112
00 01 00 00 00 00 00 00 and this becomes the Linux LUN integer 1.
Packit a8f112
.PP
Packit a8f112
In 2013 it is proposed to increase Linux LUNs to a 64 bit integer by extending
Packit a8f112
the mapping outlined above. In this case all information that is possible
Packit a8f112
to represent in a SCSI LUN is mapped a Linux LUN (64 bit) integer. And the
Packit a8f112
mapping can be reversed without losing information.
Packit a8f112
.PP
Packit a8f112
This version of the utility supports both 32 and 64 bit Linux LUN integers.
Packit a8f112
By default the LUN shown at the end of the tuple commencing each line is
Packit a8f112
a Linux LUN as a decimal integer. When the \fI\-\-lunhex\fR option is given
Packit a8f112
then the LUN is in SCSI LUN format with the 8 bytes run together, with the
Packit a8f112
output in hexadecimal and prefixed by '0x'. The LUN is decoded according
Packit a8f112
to SAM\-5's description and trailing zeros (i.e. digits to the right) are not
Packit a8f112
shown. So LUN 0 (i.e. 00 00 00 00 00 00 00 00) is shown as 0x0000 and
Packit a8f112
LUN 65 (i.e. 00 41 00 00 00 00 00 00) is shown as 0x0041.
Packit a8f112
If the \fI\-\-lunhex\fR option is given twice then the full 64 bits (i.e. 16
Packit a8f112
hexadecimal digits) are shown.
Packit a8f112
.PP
Packit a8f112
If the \fI\-\-lunhex\fR option is not given on the command line then the
Packit a8f112
environment variable LSSCSI_LUNHEX_OPT is checked. If LSSCSI_LUNHEX_OPT is
Packit a8f112
present then its associated value becomes the number of times the
Packit a8f112
\fI\-\-lunhex\fR is set internally. So, for
Packit a8f112
example, 'LSSCSI_LUNHEX_OPT=2  lsscsi' and 'lsscsi \-xx' are equivalent.
Packit a8f112
.SH EXAMPLES
Packit a8f112
Information about this utility including examples can also be found at:
Packit a8f112
http://sg.danny.cz/scsi/lsscsi.html .
Packit a8f112
.SH NOTES
Packit a8f112
Information for this command is derived from the sysfs file system,
Packit a8f112
which is assumed to be mounted at /sys unless specified otherwise
Packit a8f112
by the user.
Packit a8f112
SCSI (pseudo) devices that have been detected by the SCSI mid level
Packit a8f112
will be listed even if the required upper level drivers (i.e. sd, sr,
Packit a8f112
st, osst or ch) have not been loaded. If the appropriate upper level
Packit a8f112
driver has not been loaded then the device file name will appear
Packit a8f112
as '\-' rather than something like '/dev/st0'. Note that some
Packit a8f112
devices (e.g. scanners and medium changers) do not have a primary upper
Packit a8f112
level driver and can only be accessed via a SCSI generic (sg) device
Packit a8f112
name.
Packit a8f112
.PP
Packit a8f112
Generic SCSI devices can also be accessed via the bsg driver in Linux.
Packit a8f112
By default, the bsg driver's device node names are of the
Packit a8f112
form '/dev/bsg/\fIH:C:T:L\fR'. So, for example, the SCSI device shown
Packit a8f112
by this utility on a line starting with the tuple '6:0:1:2' could be
Packit a8f112
accessed via the bsg driver with the '/dev/bsg/6:0:1:2' device node
Packit a8f112
name.
Packit a8f112
.PP
Packit a8f112
lsscsi version 0.21 or later is required to correctly display SCSI devices
Packit a8f112
in Linux kernel 2.6.26 (and possibly later) when the
Packit a8f112
CONFIG_SYSFS_DEPRECATED_V2 kernel option is not defined.
Packit a8f112
.SH AUTHOR
Packit a8f112
Written by Doug Gilbert
Packit a8f112
.SH "REPORTING BUGS"
Packit a8f112
Report bugs to <dgilbert at interlog dot com>.
Packit a8f112
.SH COPYRIGHT
Packit a8f112
Copyright \(co 2003\-2018 Douglas Gilbert
Packit a8f112
.br
Packit a8f112
This software is distributed under the GPL version 2. There is NO
Packit a8f112
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Packit a8f112
.SH "SEE ALSO"
Packit a8f112
.B lspci
Packit a8f112
.B lsusb
Packit a8f112
.B lsblk