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] [--maxlen=LEN] [--quiet]
10       [--raw] [--select=SR] [--verbose] [--version] DEVICE
11
12       sg_luns --test=ALUN [--hex] [--verbose]
13

DESCRIPTION

15       In the first form shown in the SYNOPSIS this  utility  sends  the  SCSI
16       REPORT  LUNS  command  to  the  DEVICE  and  outputs  the response. The
17       response should be a list of LUNs ("a LUN inventory") for the I_T nexus
18       associated  with  the  DEVICE.  Roughly  speaking that is all LUNs that
19       share the target device that the REPORT LUNS command is  sent  through.
20       In  the SPC-3 and SPC-4 SCSI standards support for the REPORT LUNS com‐
21       mand is mandatory.
22
23       When the --test=ALUN option is given (the second form in the SYNOPSIS),
24       then  the  ALUN  value is decoded as outlined in SAM-3, SAM-4 and SAM-5
25       (revision 13, section 4.7) .
26
27       Where required below the first form shown in  the  SYNOPSIS  is  called
28       "device mode" and the second form is called "test mode".
29

OPTIONS

31       Arguments to long options are mandatory for short options as well.
32
33       -d, --decode
34              decode  LUNs into their component parts, as described in the LUN
35              section of SAM-3, SAM-4 and SAM-5.
36
37       -h, --help
38              output the usage message then exit.
39
40       -H, --hex
41              [device mode] when given once this utility will output the  SCSI
42              response  (i.e.  the data-out buffer) to the REPORT LUNS command
43              in ASCII hex then exit. When given twice it causes  --decode  to
44              output component fields in hex rather than decimal.
45
46       -H, --hex
47              [test  mode]  when  this option is given, then decoded component
48              fields of ALUN are output in hex.
49
50       -l, --linux
51              this option is only available in Linux. After the T10  represen‐
52              tation  of  each  64 bit LUN (in 16 hexadecimal digits), if this
53              option is given then to the right, in square  brackets,  is  the
54              Linux  LUN  integer  in  decimal.   If the --hex option is given
55              twice (e.g. -HH) as well then the Linux LUN integer is output in
56              hexadecimal.
57
58       -m, --maxlen=LEN
59              where  LEN  is  the  (maximum)  response  length in bytes. It is
60              placed in the cdb's "allocation length" field. If not given  (or
61              LEN is zero) then 8192 is used. The maximum allowed value of LEN
62              is 1048576.
63
64       -q, --quiet
65              output only the ASCII hex rendering of each report LUN, one  per
66              line.   Without  the --quiet option, there is header information
67              printed before the LUN listing.
68
69       -r, --raw
70              output the SCSI response (i.e. the data-out  buffer)  in  binary
71              (to stdout).
72
73       -s, --select=SR
74              this option sets the SELECT REPORT field (SR) in the SCSI REPORT
75              LUNS command. The default value is 0. For  detailed  information
76              see  the  REPORT LUNS command in SPC (most recent is SPC-4 revi‐
77              sion 36e in section 6.33). To simplify, for the I_T nexus  asso‐
78              ciated with the DEVICE, the meanings of the SR values defined to
79              date for SPC-4 are:
80                0 : all LUNs excluding well known logical units
81                1 : well known logical units
82                2 : all LUNs
83              Values between 0xf8 and 0xff  (inclusive)  are  vendor  specific
84              (SPC-4  rev 36e), other values greater than 2 are reserved. This
85              utility will accept any value between 0 and 255 (0xff) for SR .
86
87       -t, --test=ALUN
88              ALUN is assumed to be a hexadecimal number in ASCII hex  or  the
89              letter  'L'  followed by a decimal number (see below). The hexa‐
90              decimal number can be up to 64 bits in size (i.e. 16 hexadecimal
91              digits)  and  is padded to the right if less than 16 hexadecimal
92              digits are  given  (e.g.   --test=0122003a  represents  T10  LUN
93              0122003a00000000).  ALUN  may  be prefixed by '0x' or '0X' (e.g.
94              the previous example could have  been  --test=0x0122003a).  ALUN
95              may  also  be  given  with  spaces or tabs between each byte (or
96              other grouping) but then ALUN would need  to  be  surrounded  by
97              single  or double quotes.  In the decimal number case (i.e. fol‐
98              lowing a 'L') that  number  is  assumed  to  be  a  Linux  "word
99              flipped"  LUN  which  is converted into a T10 LUN representation
100              and printed. In both cases the number is interpreted  as  a  LUN
101              and decoded as if the --decode option had been given.  Also when
102              ALUN is a hexadecimal number it can have a trailing 'L' in which
103              case the corresponding Linux "word flipped" LUN value is output.
104              The LUN is decoded in all cases.
105
106       -v, --verbose
107              increase the level of verbosity, (i.e. debug output).
108
109       -V, --version
110              print the version string and then exit.
111

NOTES

113       The SCSI REPORT LUNS command is important for Logical Unit (LU) discov‐
114       ery.   After  a target device is discovered (usually via some transport
115       specific mechanism), a REPORT LUNS command should either be sent to LUN
116       0  (which is Peripheral device addressing method with bus_id=0 and tar‐
117       get/lun=0)   or   to   the   REPORT   LUNS   well   known   LUN   (i.e.
118       0xc101000000000000).  SAM-5 requires that one of these responds with an
119       inventory of LUNS that are contained in this target device.
120
121       In test mode, if the --hex option is given once  then  in  the  decoded
122       output,  some  of  the component fields are printed in hex with leading
123       zeros.  The leading zeros are to indicate the  size  of  the  component
124       field. For example: in the Peripheral device addressing method (16 bits
125       overall), the bus ID is 6 bits wide and the target/LUN field is 8  bits
126       wide;  so  both  are  shown with two hex digits (e.g. bus_id=0x02, tar‐
127       get=0x3a).
128

EXAMPLES

130       Typically by the time user space programs get to  run,  SCSI  LUs  have
131       been  discovered.  In  Linux  the lsscsi utility lists the LUs that are
132       currently present. The LUN of a device (LU) is the  fourth  element  in
133       the tuple at the beginning of each line. Below we see a target (or "I_T
134       Nexus": "6:0:0") has two LUNS: 1 and 49409. If 49409 is converted  into
135       T10  LUN  format it is 0xc101000000000000 which is the REPORT LUNS well
136       known LUN.
137
138         # lsscsi -g
139         [6:0:0:1]     disk     Linux      scsi_debug         0004    /dev/sdb
140       /dev/sg1
141         [6:0:0:49409]wlun        Linux        scsi_debug           0004     -
142       /dev/sg2
143
144       We could send a REPORT LUNS command to  either  /dev/sdb,  /dev/sg1  or
145       /dev/sg2 and get the same result. Below we use /dev/sg1 :
146
147         # sg_luns /dev/sg1
148         Lun list length = 8 which imples 1 lun entry
149         Report luns [select_report=0x0]:
150             0001000000000000
151
152       That is a bit noisy so cut down the clutter with --quiet:
153
154         # sg_luns -q /dev/sg1
155         0001000000000000
156
157       Now decode that LUN into its component parts:
158
159         # sg_luns -d -q /dev/sg1
160         0001000000000000
161               Peripheral device addressing: lun=1
162
163       Would like to see how wide that component LUN field is:
164         # sg_luns -d -q -HH /dev/sg1
165         0001000000000000
166               Peripheral device addressing: lun=0x01
167
168       So  it  is 8 bits wide (actually between 5 and 8 bits wide, inclusive).
169       Now use --select=1 to find out if there are any well known LUNs:
170
171         # sg_luns -q -s 1 /dev/sg1
172         c101000000000000
173
174       So how many LUNs do we have all together (associated with  the  current
175       I_T Nexus):
176
177         # sg_luns -q -s 2 /dev/sg1
178         0001000000000000
179         c101000000000000
180
181         # sg_luns -q -s 2 -d /dev/sg1
182         0001000000000000
183               Peripheral device addressing: lun=1
184         c101000000000000
185               REPORT LUNS well known logical unit
186
187       The  following  example uses the --linux option and is not available in
188       other operating systems. The extra number in  square  brackets  is  the
189       Linux version of T10 LUN shown at the start of the line.
190
191         # sg_luns -q -s 2 -l /dev/sg1
192         0001000000000000    [1]
193         c101000000000000    [49409]
194
195       Now  we use the --test= option to decode LUNS input on the command line
196       (rather than send a REPORT LUNS command and act on the response):
197
198         # sg_luns --test=0001000000000000
199         Decoded LUN:
200           Peripheral device addressing: lun=1
201
202         # sg_luns --test="c1 01"
203         Decoded LUN:
204           REPORT LUNS well known logical unit
205
206         # sg_luns -t 0x023a004b -H
207         Decoded LUN:
208           Peripheral device addressing: bus_id=0x02, target=0x3a
209           >>Second level addressing:
210             Peripheral device addressing: lun=0x4b
211
212       The next example is Linux specific as we try to find out what the Linux
213       LUN 49409 translates to in the T10 world:
214
215         # sg_luns --test=L49409
216         64 bit LUN in T10 preferred (hex) format:  c1 01 00 00 00 00 00 00
217         Decoded LUN:
218           REPORT LUNS well known logical unit
219
220       And  the  mapping between T10 and Linux LUN representations can be done
221       the other way:
222
223         # sg_luns -t c101L
224         Linux 'word flipped' integer LUN representation: 49409
225         Decoded LUN:
226           REPORT LUNS well known logical unit
227

EXIT STATUS

229       The exit status of sg_luns is 0 when it is  successful.  Otherwise  see
230       the sg3_utils(8) man page.
231

AUTHORS

233       Written by Douglas Gilbert.
234

REPORTING BUGS

236       Report bugs to <dgilbert at interlog dot com>.
237
239       Copyright © 2004-2013 Douglas Gilbert
240       This  software is distributed under a FreeBSD license. There is NO war‐
241       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
242       POSE.
243

SEE ALSO

245       sg_inq(8)
246
247
248
249sg3_utils-1.36                     May 2013                         SG_LUNS(8)
Impressum