1SG_LUNS(8)                         SG3_UTILS                        SG_LUNS(8)
2
3
4

NAME

6       sg_luns - send SCSI REPORT LUNS command or decode given LUN
7

SYNOPSIS

9       sg_luns    [--decode]    [--help]    [--hex]    [--linux]   [--lu_cong]
10       [--maxlen=LEN] [--quiet] [--raw] [--readonly] [--select=SR] [--verbose]
11       [--version] DEVICE
12
13       sg_luns --test=ALUN [--decode] [--hex] [--lu_cong] [--verbose]
14

DESCRIPTION

16       In  the  first  form  shown in the SYNOPSIS this utility sends the SCSI
17       REPORT LUNS command  to  the  DEVICE  and  outputs  the  response.  The
18       response should be a list of LUNs ("a LUN inventory") for the I_T nexus
19       associated with the DEVICE. Roughly speaking  that  is  all  LUNs  that
20       share  the  target device that the REPORT LUNS command is sent through.
21       This command is defined in the SPC-3 and SPC-4 SCSI standards  and  its
22       support is mandatory. The most recent draft if SPC-6 revision 1.
23
24       When the --test=ALUN option is given (the second form in the SYNOPSIS),
25       then the ALUN value is decoded as outlined in various SCSI Architecture
26       Model (SAM) standards and recent drafts (e.g. SAM-6 revision 2, section
27       4.7) .
28
29       Where required below the first form shown in  the  SYNOPSIS  is  called
30       "device mode" and the second form is called "test mode".
31

OPTIONS

33       Arguments to long options are mandatory for short options as well.
34
35       -d, --decode
36              decode  LUNs into their component parts, as described in the LUN
37              section of SAM-3, SAM-4 and SAM-5.
38              [test mode] ALUN is decoded irrespective of whether this  option
39              is  given  or  not.  If this option is given once then the given
40              ALUN is output in T10 preferred format (which is 8 pairs of  hex
41              digits,  each  separated  by  a  space). If given twice then the
42              given ALUN is output in an alternate T10 format made up of  four
43              quads  of  hex  digits  with  each quad separated by a "-" (e.g.
44              C101-0000-0000-0000).
45
46       -h, --help
47              output the usage message then exit.
48
49       -H, --hex
50              [device mode] when given once this utility will output the  SCSI
51              response  (i.e.  the data-out buffer) to the REPORT LUNS command
52              in ASCII hex then exit. When given twice it causes  --decode  to
53              output component fields in hex rather than decimal.
54              [test  mode]  when  this option is given, then decoded component
55              fields of ALUN are output in hex.
56
57       -l, --linux
58              this option is only available in Linux. After the T10  represen‐
59              tation  of  each  64 bit LUN (in 16 hexadecimal digits), if this
60              option is given then to the right, in square  brackets,  is  the
61              Linux  LUN  integer  in  decimal.   If the --hex option is given
62              twice (e.g. -HH) as well then the Linux LUN integer is output in
63              hexadecimal.
64
65       -L, --lu_cong
66              this  option  is  only considered with --decode. When given once
67              then the list of LUNs is decoded as if the LU_CONG bit  was  set
68              in  each  LU's  corresponding INQUIRY response. When given twice
69              the list of LUNs is decoded as if the LU_CONG bit was  clear  in
70              each  LU's  corresponding  INQUIRY response. When this option is
71              not given and --decode is given then an INQUIRY is sent  to  the
72              DEVICE  and the setting of its LU_CONG bit is used to decode the
73              list of LUNs.
74              [test mode] decode ALUN as if the LU_CONG bit is set in its cor‐
75              responding  standard INQUIRY response. In other words treat ALUN
76              as if it is a conglomerate LUN. If not given  (or  given  twice)
77              then decode ALUN as if the LU_CONG bit is clear.
78
79       -m, --maxlen=LEN
80              where  LEN  is  the  (maximum)  response  length in bytes. It is
81              placed in the cdb's "allocation length" field. If not given  (or
82              LEN is zero) then 8192 is used. The maximum allowed value of LEN
83              is 1048576.
84
85       -q, --quiet
86              output only the ASCII hex rendering of each report LUN, one  per
87              line.   Without  the --quiet option, there is header information
88              printed before the LUN listing.
89
90       -r, --raw
91              output the SCSI response (i.e. the data-out  buffer)  in  binary
92              (to stdout).
93
94       -R, --readonly
95              open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
96              The default is to open it read-write.
97
98       -s, --select=SR
99              SR is placed in the SELECT REPORT field of the SCSI REPORT  LUNS
100              command. The default value is 0. Hexadecimal values may be given
101              with a leading "0x" or a trailing "h". For detailed  information
102              see  the  REPORT LUNS command in SPC (most recent is SPC-4 revi‐
103              sion 37 in section 6.33). To simplify, for the I_T nexus associ‐
104              ated  with  the DEVICE, the meanings of the SR values defined to
105              date for SPC-4 are:
106                0 : most luns excluding well known logical unit numbers
107                1 : well known logical unit numbers
108                2 : all luns accessible to this I_T nexus
109                0x10 : only accessible administrative luns
110                0x11 : administrative luns  plus  non-conglomerate  luns  (see
111              SPC-4)
112                0x12 : if DEVICE is an administrative LU, then report its
113                       lun plus its subsidiary luns
114
115       For  SR  values  0x10  and 0x11, the DEVICE must be either LUN 0 or the
116       REPORT LUNS well known logical  unit.  Values  between  0xf8  and  0xff
117       (inclusive)  are vendor specific, other values are reserved. This util‐
118       ity will accept any value between 0 and 255 (0xff) for SR .
119
120       -t, --test=ALUN
121              ALUN is assumed to be a hexadecimal number in ASCII hex  or  the
122              letter  'L'  followed by a decimal number (see below). The hexa‐
123              decimal number can be up to 64 bits in size (i.e. 16 hexadecimal
124              digits)  and  is padded to the right if less than 16 hexadecimal
125              digits are given (e.g.  --test=0122003a represents T10  LUN:  01
126              22  00  3a  00  00 00 00).  ALUN may be prefixed by '0x' or '0X'
127              (e.g. the previous example could have  been  --test=0x0122003a).
128              ALUN  may also be given with spaces, tabs, or a '-' between each
129              byte (or other grouping (e.g.  c101-0000-0000-0000)). However in
130              the  case  of  space or tab separators the ALUN would need to be
131              surrounded by single or double quotes.
132              In the leading 'L' case the, following decimal  number  (hex  if
133              preceded  by  '0x')  is assumed to be a Linux "word flipped" LUN
134              which is converted into a T10 LUN representation and printed. In
135              both  cases the number is interpreted as a LUN and decoded as if
136              the --decode option had been given. Also when ALUN is a hexadec‐
137              imal  number it can have a trailing 'L' in which case the corre‐
138              sponding Linux "word flipped" LUN value is output.  The  LUN  is
139              decoded in all cases.
140              The  action  when  used  with  --decode  is explained under that
141              option.
142
143       -v, --verbose
144              increase the level of verbosity, (i.e. debug output).
145
146       -V, --version
147              print the version string and then exit.
148

NOTES

150       The SCSI REPORT LUNS command is important for Logical Unit (LU) discov‐
151       ery.   After  a target device is discovered (usually via some transport
152       specific mechanism) and after sending an INQUIRY command (to  determine
153       the  LU_CONG  setting),  a REPORT LUNS command should either be sent to
154       LUN 0 (which is Peripheral device addressing method with  bus_id=0  and
155       target/lun=0)   or   to   the   REPORT   LUNS   well  known  LUN  (i.e.
156       0xc101000000000000). SAM-5 requires that one of these responds with  an
157       inventory of LUNS that are contained in this target device.
158
159       In  test  mode,  if  the --hex option is given once then in the decoded
160       output, some of the component fields are printed in  hex  with  leading
161       zeros.   The  leading  zeros  are to indicate the size of the component
162       field. For example: in the Peripheral device addressing method (16 bits
163       overall),  the bus ID is 6 bits wide and the target/LUN field is 8 bits
164       wide; so both are shown with two hex  digits  (e.g.  bus_id=0x02,  tar‐
165       get=0x3a).
166

EXAMPLES

168       Typically  by  the  time  user space programs get to run, SCSI LUs have
169       been discovered. In Linux the lsscsi utility lists  the  LUs  that  are
170       currently  present.  The  LUN of a device (LU) is the fourth element in
171       the tuple at the beginning of each line. Below we see a target (or "I_T
172       Nexus":  "6:0:0") has two LUNS: 1 and 49409. If 49409 is converted into
173       T10 LUN format it is 0xc101000000000000 which is the REPORT  LUNS  well
174       known LUN.
175
176         # lsscsi -g
177         [6:0:0:1]      disk      Linux      scsi_debug        0004   /dev/sdb
178       /dev/sg1
179         [6:0:0:2]     disk     Linux      scsi_debug         0004    /dev/sdc
180       /dev/sg2
181         [6:0:0:49409]wlun        Linux        scsi_debug           0004     -
182       /dev/sg3
183
184       We could send a REPORT LUNS command (with SR 0x0, 0x1 or 0x2) to any of
185       those  file device nodes and get the same result. Below we use /dev/sg1
186       :
187
188         # sg_luns /dev/sg1
189         Lun list length = 16 which imples 2 lun entry
190         Report luns [select_report=0x0]:
191             0001000000000000
192             0002000000000000
193
194       That is a bit noisy so cut down the clutter with --quiet:
195
196         # sg_luns -q /dev/sg1
197         0001000000000000
198         0002000000000000
199
200       Now decode that LUN into its component parts:
201
202         # sg_luns -d -q /dev/sg1
203         0001000000000000
204               Peripheral device addressing: lun=1
205         0002000000000000
206               Peripheral device addressing: lun=2
207
208       Now use --select=1 to find out if there are any well known LUNs:
209
210         # sg_luns -q -s 1 /dev/sg1
211         c101000000000000
212
213       So how many LUNs do we have all together (associated with  the  current
214       I_T Nexus):
215
216         # sg_luns -q -s 2 /dev/sg1
217         0001000000000000
218         0002000000000000
219         c101000000000000
220
221         # sg_luns -q -s 2 -d /dev/sg1
222         0001000000000000
223               Peripheral device addressing: lun=1
224         0002000000000000
225               Peripheral device addressing: lun=1
226         c101000000000000
227               REPORT LUNS well known logical unit
228
229       The  following  example uses the --linux option and is not available in
230       other operating systems. The extra number in  square  brackets  is  the
231       Linux version of T10 LUN shown at the start of the line.
232
233         # sg_luns -q -s 2 -l /dev/sg1
234         0001000000000000    [1]
235         0002000000000000    [2]
236         c101000000000000    [49409]
237
238       Now  we use the --test= option to decode LUNS input on the command line
239       (rather than send a REPORT LUNS command and act on the response):
240
241         # sg_luns --test=0002000000000000
242         Decoded LUN:
243           Peripheral device addressing: lun=2
244
245         # sg_luns --test="c1 01"
246         Decoded LUN:
247           REPORT LUNS well known logical unit
248
249         # sg_luns -t 0x023a004b -H
250         Decoded LUN:
251           Peripheral device addressing: bus_id=0x02, target=0x3a
252           >>Second level addressing:
253             Peripheral device addressing: lun=0x4b
254
255       The next example is Linux specific as we try to find out what the Linux
256       LUN 49409 translates to in the T10 world:
257
258         # sg_luns --test=L49409
259         64 bit LUN in T10 preferred (hex) format:  c1 01 00 00 00 00 00 00
260         Decoded LUN:
261           REPORT LUNS well known logical unit
262
263       And  the  mapping between T10 and Linux LUN representations can be done
264       the other way:
265
266         # sg_luns -t c101L
267         Linux 'word flipped' integer LUN representation: 49409
268         Decoded LUN:
269           REPORT LUNS well known logical unit
270

EXIT STATUS

272       The exit status of sg_luns is 0 when it is  successful.  Otherwise  see
273       the sg3_utils(8) man page.
274

AUTHORS

276       Written by Douglas Gilbert.
277

REPORTING BUGS

279       Report bugs to <dgilbert at interlog dot com>.
280
282       Copyright © 2004-2020 Douglas Gilbert
283       This  software is distributed under a FreeBSD license. There is NO war‐
284       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
285       POSE.
286

SEE ALSO

288       sg_inq(8)
289
290
291
292sg3_utils-1.45                   January 2020                       SG_LUNS(8)
Impressum