.TH SG_LUNS "8" "June 2023" "sg3_utils\-1.48" 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\-\-inhex=FN\fR]
[\fI\-\-inner\-hex\fR] [\fI\-\-json[=JO]\fR] [\fI\-\-js\-file=JFN\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\-\-sinq_inraw=RFN\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
\fIDEVICE\fR
.PP
.B sg_luns
\fI\-\-test=ALUN\fR [\fI\-\-decode\fR] [\fI\-\-hex\fR] [\fI\-\-inner\-hex\fR]
[\fI\-\-lu_cong\fR] [\fI\-\-verbose\fR]
.SH DESCRIPTION
.\" Add any additional description here
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. Notice that this (i.e. how '\-HH' is processed) differs
from the description in sg3_utils(8). The \fI\-\-inner\-hex\fR option has
the same action as '\-HH'. When this option is used three (or more) times the
hex output is suitable for placing in a file and using it with a later
sg_luns invocation with the \fI\-\-inhex=FN\fR option.
.br
[test mode] when this option is given, then decoded component fields of
\fIALUN\fR are output in hex.
.br
When this option is given three or more times, ASCII hex bytes are
output (up to 16 per line) with no leading address or index. This output
is suitable for placing in a file and later invocation of this utility
decoding it with the \fI\-\-inhex=FN\fR option. When this option is used
four times, a comment line (starting with '#' is added before the hex)
describing what the hex was generated by. A file containing such comments
is still parsable by the \fI\-\-inhex=FN\fR option.
.TP
\fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR
\fIFN\fR is expected to be a file name (or '\-' for stdin) which contains
ASCII hexadecimal or binary representing a REPORT LUNS response. This utility
will then decode that response. See the "HEX, BINARY AND JSON FORMATS"
section in the sg3_utils manpage for more information. If the \fI\-\-raw\fR
option is also given then \fIFN\fR is treated as binary.
.TP
\fB\-I\fR, \fB\-\-inner\-hex\fR
used together with the \fI\-\-decode\fR option so that the decoded values are
shown in hexadecimal. The default action is to show decoded values in decimal.
This option has the same action as '\-HH' but the intent is a little clearer
with this option.
.TP
\fB\-j\fR[=\fIJO\fR], \fB\-\-json\fR[=\fIJO\fR]
output is in JSON format instead of plain text form. Note that arguments
to the short and long form are themselves optional and if present start
with "=" and no whitespace is permitted around that "=".
.br
See sg3_utils_json manpage or use '?' for \fIJO\fR to get a summary.
.TP
\fB\-J\fR, \fB\-\-js\-file\fR=\fIJFN\fR
output is in JSON format and it is sent to a file named \fIJFN\fR. If that
file exists then it is truncated. By default, the JSON output is sent to
stdout.
.br
When this option is given, the \fI\-\-json[=JO]\fR option is implied and
need not be given. The \fI\-\-json[=JO]\fR option may still be needed to
set the \fIJO\fR parameter to non-default values.
.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:
    \fB0\fR : most luns excluding well known logical unit numbers
    \fB1\fR : well known logical unit numbers
    \fB2\fR : all luns accessible to this I_T nexus
    \fB0x10\fR : only accessible administrative luns
    \fB0x11\fR : administrative luns plus non-conglomerate luns (see SPC\-4)
    \fB0x12\fR : if \fIDEVICE\fR is an administrative LU, then report its
           lun plus its subsidiary luns
.br
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\-Q\fR, \fB\-\-sinq_inraw\fR=\fIRFN\fR
where \fIRFN\fR is a filename containing binary standard INQUIRY response
data that matches either \fIDEVICE\fR or \fIFN\fR. Linux places this standard
INQUIRY response in its sysfs pseudo filesystem. A typical location is at
/sys/class/scsi_device/<hctl>/device/inquiry where <hctl> is a four part
numeric tuple separated by colons. This tuple distinguishes the device from
any others on the system.
.br
Currently the LU_CONG field is read from the standard INQUIRY response
when this option is given. The \fI\-\-raw\fR option has no effect on this
option. The \fIDEVICE\fR argument may be given with this option.
.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
  [6:0:0:1]    disk    Linux    scsi_debug       0004  /dev/sdb   /dev/sg1
  [6:0:0:2]    disk    Linux    scsi_debug       0004  /dev/sdc   /dev/sg2
  [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
  Lun list length = 16 which implies 2 lun entries
  Report luns [select_report=0x0]:
      0001000000000000
      0002000000000000
.PP
That is a bit noisy so cut down the clutter with \fI\-\-quiet\fR:
.PP
  # sg_luns \-q /dev/sg1
  0001000000000000
  0002000000000000
.PP
Now decode that LUN into its component parts:
.PP
  # sg_luns \-d \-q /dev/sg1
  0001000000000000
        Peripheral device addressing: lun=1
  0002000000000000
        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
  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
  0001000000000000
  0002000000000000
  c101000000000000
.PP
  # sg_luns \-q \-s 2 \-d /dev/sg1
  0001000000000000
        Peripheral device addressing: lun=1
  0002000000000000
        Peripheral device addressing: lun=1
  c101000000000000
        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
  0001000000000000    [1]
  0002000000000000    [2]
  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
  Decoded LUN:
    Peripheral device addressing: lun=2
.PP
  # sg_luns \-\-test="c1 01"
  Decoded LUN:
    REPORT LUNS well known logical unit
.PP
  # sg_luns \-t 0x023a004b \-H
  Decoded LUN:
    Peripheral device addressing: bus_id=0x02, target=0x3a
    >>Second level addressing:
      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
  64 bit LUN in T10 preferred (hex) format:  c1 01 00 00 00 00 00 00
  Decoded LUN:
    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
  Linux 'word flipped' integer LUN representation: 49409
  Decoded LUN:
    REPORT LUNS well known logical unit
.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\-2023 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),sg3_utils(8)