320 lines
12 KiB
Groff
320 lines
12 KiB
Groff
.TH SG_LUNS "8" "January 2020" "sg3_utils\-1.45" SG3_UTILS
|
|
.SH NAME
|
|
sg_luns \- send SCSI REPORT LUNS command or decode given LUN
|
|
.SH SYNOPSIS
|
|
.B sg_luns
|
|
[\fI\-\-decode\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-linux\fR]
|
|
[\fI\-\-lu_cong\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-quiet\fR] [\fI\-\-raw\fR]
|
|
[\fI\-\-readonly\fR] [\fI\-\-select=SR\fR] [\fI\-\-verbose\fR]
|
|
[\fI\-\-version\fR] \fIDEVICE\fR
|
|
.PP
|
|
.B sg_luns
|
|
\fI\-\-test=ALUN\fR [\fI\-\-decode\fR] [\fI\-\-hex\fR] [\fI\-\-lu_cong\fR]
|
|
[\fI\-\-verbose\fR]
|
|
.SH DESCRIPTION
|
|
.\" Add any additional description here
|
|
.PP
|
|
In the first form shown in the SYNOPSIS this utility sends the SCSI REPORT
|
|
LUNS command to the \fIDEVICE\fR and outputs the response. The response
|
|
should be a list of LUNs ("a LUN inventory") for the I_T nexus associated
|
|
with the \fIDEVICE\fR. Roughly speaking that is all LUNs that share the
|
|
target device that the REPORT LUNS command is sent through. This command
|
|
is defined in the SPC\-3 and SPC\-4 SCSI standards and its support is
|
|
mandatory. The most recent draft if SPC\-6 revision 1.
|
|
.PP
|
|
When the \fI\-\-test=ALUN\fR option is given (the second form in the
|
|
SYNOPSIS), then the \fIALUN\fR value is decoded as outlined in various
|
|
SCSI Architecture Model (SAM) standards and recent drafts (e.g. SAM\-6
|
|
revision 2, section 4.7) .
|
|
.PP
|
|
Where required below the first form shown in the SYNOPSIS is called "device
|
|
mode" and the second form is called "test mode".
|
|
.SH OPTIONS
|
|
Arguments to long options are mandatory for short options as well.
|
|
.TP
|
|
\fB\-d\fR, \fB\-\-decode\fR
|
|
decode LUNs into their component parts, as described in the LUN section
|
|
of SAM\-3, SAM\-4 and SAM\-5.
|
|
.br
|
|
[test mode] \fIALUN\fR is decoded irrespective of whether this option is
|
|
given or not. If this option is given once then the given \fIALUN\fR is
|
|
output in T10 preferred format (which is 8 pairs of hex digits, each
|
|
separated by a space). If given twice then the given \fIALUN\fR is output
|
|
in an alternate T10 format made up of four quads of hex digits with each
|
|
quad separated by a "-" (e.g. C101\-0000\-0000\-0000).
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
output the usage message then exit.
|
|
.TP
|
|
\fB\-H\fR, \fB\-\-hex\fR
|
|
[device mode] when given once this utility will output the SCSI
|
|
response (i.e. the data\-out buffer) to the REPORT LUNS command in ASCII
|
|
hex then exit. When given twice it causes \fI\-\-decode\fR to output
|
|
component fields in hex rather than decimal.
|
|
.br
|
|
[test mode] when this option is given, then decoded component fields of
|
|
\fIALUN\fR are output in hex.
|
|
.TP
|
|
\fB\-l\fR, \fB\-\-linux\fR
|
|
this option is only available in Linux. After the T10 representation of
|
|
each 64 bit LUN (in 16 hexadecimal digits), if this option is given then
|
|
to the right, in square brackets, is the Linux LUN integer in decimal.
|
|
If the \fI\-\-hex\fR option is given twice (e.g. \-HH) as well then the
|
|
Linux LUN integer is output in hexadecimal.
|
|
.TP
|
|
\fB\-L\fR, \fB\-\-lu_cong\fR
|
|
this option is only considered with \fI\-\-decode\fR. When given once
|
|
then the list of LUNs is decoded as if the LU_CONG bit was set in
|
|
each LU's corresponding INQUIRY response. When given twice the list of
|
|
LUNs is decoded as if the LU_CONG bit was clear in each LU's corresponding
|
|
INQUIRY response. When this option is not given and \fI\-\-decode\fR is
|
|
given then an INQUIRY is sent to the \fIDEVICE\fR and the setting of
|
|
its LU_CONG bit is used to decode the list of LUNs.
|
|
.br
|
|
[test mode] decode \fIALUN\fR as if the LU_CONG bit is set in its
|
|
corresponding standard INQUIRY response. In other words treat \fIALUN\fR
|
|
as if it is a conglomerate LUN. If not given (or given twice) then decode
|
|
\fIALUN\fR as if the LU_CONG bit is clear.
|
|
.TP
|
|
\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
|
|
where \fILEN\fR is the (maximum) response length in bytes. It is placed in
|
|
the cdb's "allocation length" field. If not given (or \fILEN\fR is zero)
|
|
then 8192 is used. The maximum allowed value of \fILEN\fR is 1048576.
|
|
.TP
|
|
\fB\-q\fR, \fB\-\-quiet\fR
|
|
output only the ASCII hex rendering of each report LUN, one per line.
|
|
Without the \fI\-\-quiet\fR option, there is header information printed
|
|
before the LUN listing.
|
|
.TP
|
|
\fB\-r\fR, \fB\-\-raw\fR
|
|
output the SCSI response (i.e. the data\-out buffer) in binary (to stdout).
|
|
.TP
|
|
\fB\-R\fR, \fB\-\-readonly\fR
|
|
open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag).
|
|
The default is to open it read\-write.
|
|
.TP
|
|
\fB\-s\fR, \fB\-\-select\fR=\fISR\fR
|
|
\fISR\fR is placed in the SELECT REPORT field of the SCSI REPORT LUNS
|
|
command. The default value is 0. Hexadecimal values may be given with
|
|
a leading "0x" or a trailing "h". For detailed information see the
|
|
REPORT LUNS command in SPC (most recent is SPC\-4 revision 37 in section
|
|
6.33). To simplify, for the I_T nexus associated with the \fIDEVICE\fR, the
|
|
meanings of the \fISR\fR values defined to date for SPC\-4 are:
|
|
.br
|
|
\fB0\fR : most luns excluding well known logical unit numbers
|
|
.br
|
|
\fB1\fR : well known logical unit numbers
|
|
.br
|
|
\fB2\fR : all luns accessible to this I_T nexus
|
|
.br
|
|
\fB0x10\fR : only accessible administrative luns
|
|
.br
|
|
\fB0x11\fR : administrative luns plus non-conglomerate luns (see SPC\-4)
|
|
.br
|
|
\fB0x12\fR : if \fIDEVICE\fR is an administrative LU, then report its
|
|
.br
|
|
lun plus its subsidiary luns
|
|
.PP
|
|
For \fISR\fR values 0x10 and 0x11, the \fIDEVICE\fR must be either LUN 0 or
|
|
the REPORT LUNS well known logical unit. Values between 0xf8 and
|
|
0xff (inclusive) are vendor specific, other values are reserved. This
|
|
utility will accept any value between 0 and 255 (0xff) for \fISR\fR .
|
|
.TP
|
|
\fB\-t\fR, \fB\-\-test\fR=\fIALUN\fR
|
|
\fIALUN\fR is assumed to be a hexadecimal number in ASCII hex or the
|
|
letter 'L' followed by a decimal number (see below). The hexadecimal number
|
|
can be up to 64 bits in size (i.e. 16 hexadecimal digits) and is padded to
|
|
the right if less than 16 hexadecimal digits are given (e.g.
|
|
\fI\-\-test=0122003a\fR represents T10 LUN: 01 22 00 3a 00 00 00 00).
|
|
\fIALUN\fR may be prefixed by '0x' or '0X' (e.g. the previous example could
|
|
have been \fI\-\-test=0x0122003a\fR). \fIALUN\fR may also be given with
|
|
spaces, tabs, or a '\-' between each byte (or other grouping (e.g.
|
|
c101\-0000\-0000\-0000)). However in the case of space or tab separators
|
|
the \fIALUN\fR would need to be surrounded by single or double quotes.
|
|
.br
|
|
In the leading 'L' case the, following decimal number (hex if preceded
|
|
by '0x') is assumed to be a Linux "word flipped" LUN which is converted
|
|
into a T10 LUN representation and printed. In both cases the number is
|
|
interpreted as a LUN and decoded as if the \fI\-\-decode\fR option had been
|
|
given. Also when \fIALUN\fR is a hexadecimal number it can have a
|
|
trailing 'L' in which case the corresponding Linux "word flipped" LUN value
|
|
is output. The LUN is decoded in all cases.
|
|
.br
|
|
The action when used with \fI\-\-decode\fR is explained under that option.
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-verbose\fR
|
|
increase the level of verbosity, (i.e. debug output).
|
|
.TP
|
|
\fB\-V\fR, \fB\-\-version\fR
|
|
print the version string and then exit.
|
|
.SH NOTES
|
|
The SCSI REPORT LUNS command is important for Logical Unit (LU) discovery.
|
|
After a target device is discovered (usually via some transport specific
|
|
mechanism) and after sending an INQUIRY command (to determine the LU_CONG
|
|
setting), a REPORT LUNS command should either be sent to LUN 0 (which
|
|
is Peripheral device addressing method with bus_id=0 and target/lun=0)
|
|
or to the REPORT LUNS well known LUN (i.e. 0xc101000000000000). SAM\-5
|
|
requires that one of these responds with an inventory of LUNS that are
|
|
contained in this target device.
|
|
.PP
|
|
In test mode, if the \fI\-\-hex\fR option is given once then in the decoded
|
|
output, some of the component fields are printed in hex with leading zeros.
|
|
The leading zeros are to indicate the size of the component field. For
|
|
example: in the Peripheral device addressing method (16 bits overall), the
|
|
bus ID is 6 bits wide and the target/LUN field is 8 bits wide; so both are
|
|
shown with two hex digits (e.g. bus_id=0x02, target=0x3a).
|
|
.SH EXAMPLES
|
|
Typically by the time user space programs get to run, SCSI LUs have been
|
|
discovered. In Linux the lsscsi utility lists the LUs that are currently
|
|
present. The LUN of a device (LU) is the fourth element in the tuple at the
|
|
beginning of each line. Below we see a target (or "I_T Nexus": "6:0:0") has
|
|
two LUNS: 1 and 49409. If 49409 is converted into T10 LUN format it is
|
|
0xc101000000000000 which is the REPORT LUNS well known LUN.
|
|
.PP
|
|
# lsscsi \-g
|
|
.br
|
|
[6:0:0:1] disk Linux scsi_debug 0004 /dev/sdb /dev/sg1
|
|
.br
|
|
[6:0:0:2] disk Linux scsi_debug 0004 /dev/sdc /dev/sg2
|
|
.br
|
|
[6:0:0:49409]wlun Linux scsi_debug 0004 \- /dev/sg3
|
|
.PP
|
|
We could send a REPORT LUNS command (with \fISR\fR 0x0, 0x1 or 0x2) to any
|
|
of those file device nodes and get the same result. Below we use /dev/sg1 :
|
|
.PP
|
|
# sg_luns /dev/sg1
|
|
.br
|
|
Lun list length = 16 which imples 2 lun entry
|
|
.br
|
|
Report luns [select_report=0x0]:
|
|
.br
|
|
0001000000000000
|
|
.br
|
|
0002000000000000
|
|
.PP
|
|
That is a bit noisy so cut down the clutter with \fI\-\-quiet\fR:
|
|
.PP
|
|
# sg_luns \-q /dev/sg1
|
|
.br
|
|
0001000000000000
|
|
.br
|
|
0002000000000000
|
|
.PP
|
|
Now decode that LUN into its component parts:
|
|
.PP
|
|
# sg_luns \-d \-q /dev/sg1
|
|
.br
|
|
0001000000000000
|
|
.br
|
|
Peripheral device addressing: lun=1
|
|
.br
|
|
0002000000000000
|
|
.br
|
|
Peripheral device addressing: lun=2
|
|
.PP
|
|
Now use \fI\-\-select=1\fR to find out if there are any well known
|
|
LUNs:
|
|
.PP
|
|
# sg_luns \-q \-s 1 /dev/sg1
|
|
.br
|
|
c101000000000000
|
|
.PP
|
|
So how many LUNs do we have all together (associated with the current
|
|
I_T Nexus):
|
|
.PP
|
|
# sg_luns \-q \-s 2 /dev/sg1
|
|
.br
|
|
0001000000000000
|
|
.br
|
|
0002000000000000
|
|
.br
|
|
c101000000000000
|
|
.PP
|
|
# sg_luns \-q \-s 2 \-d /dev/sg1
|
|
.br
|
|
0001000000000000
|
|
.br
|
|
Peripheral device addressing: lun=1
|
|
.br
|
|
0002000000000000
|
|
.br
|
|
Peripheral device addressing: lun=1
|
|
.br
|
|
c101000000000000
|
|
.br
|
|
REPORT LUNS well known logical unit
|
|
.PP
|
|
The following example uses the \fI\-\-linux\fR option and is not available
|
|
in other operating systems. The extra number in square brackets is the
|
|
Linux version of T10 LUN shown at the start of the line.
|
|
.PP
|
|
# sg_luns \-q \-s 2 \-l /dev/sg1
|
|
.br
|
|
0001000000000000 [1]
|
|
.br
|
|
0002000000000000 [2]
|
|
.br
|
|
c101000000000000 [49409]
|
|
.PP
|
|
Now we use the \fI\-\-test=\fR option to decode LUNS input on the command
|
|
line (rather than send a REPORT LUNS command and act on the response):
|
|
.PP
|
|
# sg_luns \-\-test=0002000000000000
|
|
.br
|
|
Decoded LUN:
|
|
.br
|
|
Peripheral device addressing: lun=2
|
|
.PP
|
|
# sg_luns \-\-test="c1 01"
|
|
.br
|
|
Decoded LUN:
|
|
.br
|
|
REPORT LUNS well known logical unit
|
|
.PP
|
|
# sg_luns \-t 0x023a004b \-H
|
|
.br
|
|
Decoded LUN:
|
|
.br
|
|
Peripheral device addressing: bus_id=0x02, target=0x3a
|
|
.br
|
|
>>Second level addressing:
|
|
.br
|
|
Peripheral device addressing: lun=0x4b
|
|
.PP
|
|
The next example is Linux specific as we try to find out what the
|
|
Linux LUN 49409 translates to in the T10 world:
|
|
.PP
|
|
# sg_luns \-\-test=L49409
|
|
.br
|
|
64 bit LUN in T10 preferred (hex) format: c1 01 00 00 00 00 00 00
|
|
.br
|
|
Decoded LUN:
|
|
.br
|
|
REPORT LUNS well known logical unit
|
|
.PP
|
|
And the mapping between T10 and Linux LUN representations can be done the
|
|
other way:
|
|
.PP
|
|
# sg_luns \-t c101L
|
|
.br
|
|
Linux 'word flipped' integer LUN representation: 49409
|
|
.br
|
|
Decoded LUN:
|
|
.br
|
|
REPORT LUNS well known logical unit
|
|
.br
|
|
.SH EXIT STATUS
|
|
The exit status of sg_luns is 0 when it is successful. Otherwise see
|
|
the sg3_utils(8) man page.
|
|
.SH AUTHORS
|
|
Written by Douglas Gilbert.
|
|
.SH "REPORTING BUGS"
|
|
Report bugs to <dgilbert at interlog dot com>.
|
|
.SH COPYRIGHT
|
|
Copyright \(co 2004\-2020 Douglas Gilbert
|
|
.br
|
|
This software is distributed under a BSD\-2\-Clause license. There is NO
|
|
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
.SH "SEE ALSO"
|
|
.B sg_inq(8)
|