1SG_LUNS(8) SG3_UTILS SG_LUNS(8)
2
6 sg_luns - send SCSI REPORT LUNS command or decode given LUN
7
9 sg_luns [--decode] [--help] [--hex] [--linux] [--lu_cong]
10 [--maxlen=LEN] [--quiet] [--raw] [--readonly] [--select=SR] [--verbose]
11 [--version] DEVICE
12 sg_luns --test=ALUN [--hex] [--lu_cong] [--verbose]
14
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 In the SPC-3 and SPC-4 SCSI standards support for the REPORT LUNS com‐
22 mand is mandatory.
23 When the --test=ALUN option is given (the second form in the SYNOPSIS),
25 then the ALUN value is decoded as outlined in SAM-3, SAM-4 and SAM-5
26 (revision 13, section 4.7) .
27 Where required below the first form shown in the SYNOPSIS is called
29 "device mode" and the second form is called "test mode".
30
32 Arguments to long options are mandatory for short options as well.
33 -d, --decode
35 decode LUNs into their component parts, as described in the LUN
36 section of SAM-3, SAM-4 and SAM-5.
37 -h, --help
39 output the usage message then exit.
40 -H, --hex
42 [device mode] when given once this utility will output the SCSI
43 response (i.e. the data-out buffer) to the REPORT LUNS command
44 in ASCII hex then exit. When given twice it causes --decode to
45 output component fields in hex rather than decimal.
46 [test mode] when this option is given, then decoded component
47 fields of ALUN are output in hex.
48 -l, --linux
50 this option is only available in Linux. After the T10 represen‐
51 tation of each 64 bit LUN (in 16 hexadecimal digits), if this
52 option is given then to the right, in square brackets, is the
53 Linux LUN integer in decimal. If the --hex option is given
54 twice (e.g. -HH) as well then the Linux LUN integer is output in
55 hexadecimal.
56 -L, --lu_cong
58 this option is only considered with --decode. When given once
59 then the list of LUNs is decoded as if the LU_CONG bit was set
60 in each LU's coresponding INQUIRY response. When given twice the
61 list of LUNs is decoded as if the LU_CONG bit was clear in each
62 LU's coresponding INQUIRY response. When this option is not
63 given and --decode is given then an INQUIRY is sent to the
64 DEVICE and the setting of its LU_CONG bit is used to decode the
65 list of LUNs.
66 [test mode] decode ALUN as if the LU_CONG bit is set in its cor‐
67 responding standard INQUIRY response. In other words treat ALUN
68 as if it is a conglomerate LUN. If not given (or given twice)
69 then decode ALUN as if the LU_CONG bit is clear.
70 -m, --maxlen=LEN
72 where LEN is the (maximum) response length in bytes. It is
73 placed in the cdb's "allocation length" field. If not given (or
74 LEN is zero) then 8192 is used. The maximum allowed value of LEN
75 is 1048576.
76 -q, --quiet
78 output only the ASCII hex rendering of each report LUN, one per
79 line. Without the --quiet option, there is header information
80 printed before the LUN listing.
81 -r, --raw
83 output the SCSI response (i.e. the data-out buffer) in binary
84 (to stdout).
85 -R, --readonly
87 open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
88 The default is to open it read-write.
89 -s, --select=SR
91 SR is placed in the SELECT REPORT field of the SCSI REPORT LUNS
92 command. The default value is 0. Hexadecimal values may be given
93 with a leading "0x" or a trailing "h". For detailed information
94 see the REPORT LUNS command in SPC (most recent is SPC-4 revi‐
95 sion 37 in section 6.33). To simplify, for the I_T nexus associ‐
96 ated with the DEVICE, the meanings of the SR values defined to
97 date for SPC-4 are:
98 0 : most luns excluding well known logical unit numbers
99 1 : well known logical unit numbers
100 2 : all luns accessible to this I_T nexus
101 0x10 : only accessible administrative luns
102 0x11 : administrative luns plus non-conglomerate luns (see
103 SPC-4)
104 0x12 : if DEVICE is an administrative LU, then report its
105 lun plus its subsidiary luns
106 For SR values 0x10 and 0x11, the DEVICE must be either LUN 0 or the
108 REPORT LUNS well known logical unit. Values between 0xf8 and 0xff
109 (inclusive) are vendor specific, other values are reserved. This util‐
110 ity will accept any value between 0 and 255 (0xff) for SR .
111 -t, --test=ALUN
113 ALUN is assumed to be a hexadecimal number in ASCII hex or the
114 letter 'L' followed by a decimal number (see below). The hexa‐
115 decimal number can be up to 64 bits in size (i.e. 16 hexadecimal
116 digits) and is padded to the right if less than 16 hexadecimal
117 digits are given (e.g. --test=0122003a represents T10 LUN
118 0122003a00000000). ALUN may be prefixed by '0x' or '0X' (e.g.
119 the previous example could have been --test=0x0122003a). ALUN
120 may also be given with spaces or tabs between each byte (or
121 other grouping) but then ALUN would need to be surrounded by
122 single or double quotes. In the decimal number case (i.e. fol‐
123 lowing a 'L') that number is assumed to be a Linux "word
124 flipped" LUN which is converted into a T10 LUN representation
125 and printed. In both cases the number is interpreted as a LUN
126 and decoded as if the --decode option had been given. Also when
127 ALUN is a hexadecimal number it can have a trailing 'L' in which
128 case the corresponding Linux "word flipped" LUN value is output.
129 The LUN is decoded in all cases.
130 -v, --verbose
132 increase the level of verbosity, (i.e. debug output).
133 -V, --version
135 print the version string and then exit.
136
138 The SCSI REPORT LUNS command is important for Logical Unit (LU) discov‐
139 ery. After a target device is discovered (usually via some transport
140 specific mechanism), a REPORT LUNS command should either be sent to LUN
141 0 (which is Peripheral device addressing method with bus_id=0 and tar‐
142 get/lun=0) or to the REPORT LUNS well known LUN (i.e.
143 0xc101000000000000). SAM-5 requires that one of these responds with an
144 inventory of LUNS that are contained in this target device.
145 In test mode, if the --hex option is given once then in the decoded
147 output, some of the component fields are printed in hex with leading
148 zeros. The leading zeros are to indicate the size of the component
149 field. For example: in the Peripheral device addressing method (16 bits
150 overall), the bus ID is 6 bits wide and the target/LUN field is 8 bits
151 wide; so both are shown with two hex digits (e.g. bus_id=0x02, tar‐
152 get=0x3a).
153
155 Typically by the time user space programs get to run, SCSI LUs have
156 been discovered. In Linux the lsscsi utility lists the LUs that are
157 currently present. The LUN of a device (LU) is the fourth element in
158 the tuple at the beginning of each line. Below we see a target (or "I_T
159 Nexus": "6:0:0") has two LUNS: 1 and 49409. If 49409 is converted into
160 T10 LUN format it is 0xc101000000000000 which is the REPORT LUNS well
161 known LUN.
162 # lsscsi -g
164 [6:0:0:1] disk Linux scsi_debug 0004 /dev/sdb
165 /dev/sg1
166 [6:0:0:2] disk Linux scsi_debug 0004 /dev/sdc
167 /dev/sg2
168 [6:0:0:49409]wlun Linux scsi_debug 0004 -
169 /dev/sg3
170 We could send a REPORT LUNS command (with SR 0x0, 0x1 or 0x2) to any of
172 those file device nodes and get the same result. Below we use /dev/sg1
173 :
174 # sg_luns /dev/sg1
176 Lun list length = 16 which imples 2 lun entry
177 Report luns [select_report=0x0]:
178 0001000000000000
179 0002000000000000
180 That is a bit noisy so cut down the clutter with --quiet:
182 # sg_luns -q /dev/sg1
184 0001000000000000
185 0002000000000000
186 Now decode that LUN into its component parts:
188 # sg_luns -d -q /dev/sg1
190 0001000000000000
191 Peripheral device addressing: lun=1
192 0002000000000000
193 Peripheral device addressing: lun=2
194 Now use --select=1 to find out if there are any well known LUNs:
196 # sg_luns -q -s 1 /dev/sg1
198 c101000000000000
199 So how many LUNs do we have all together (associated with the current
201 I_T Nexus):
202 # sg_luns -q -s 2 /dev/sg1
204 0001000000000000
205 0002000000000000
206 c101000000000000
207 # sg_luns -q -s 2 -d /dev/sg1
209 0001000000000000
210 Peripheral device addressing: lun=1
211 0002000000000000
212 Peripheral device addressing: lun=1
213 c101000000000000
214 REPORT LUNS well known logical unit
215 The following example uses the --linux option and is not available in
217 other operating systems. The extra number in square brackets is the
218 Linux version of T10 LUN shown at the start of the line.
219 # sg_luns -q -s 2 -l /dev/sg1
221 0001000000000000 [1]
222 0002000000000000 [2]
223 c101000000000000 [49409]
224 Now we use the --test= option to decode LUNS input on the command line
226 (rather than send a REPORT LUNS command and act on the response):
227 # sg_luns --test=0002000000000000
229 Decoded LUN:
230 Peripheral device addressing: lun=2
231 # sg_luns --test="c1 01"
233 Decoded LUN:
234 REPORT LUNS well known logical unit
235 # sg_luns -t 0x023a004b -H
237 Decoded LUN:
238 Peripheral device addressing: bus_id=0x02, target=0x3a
239 >>Second level addressing:
240 Peripheral device addressing: lun=0x4b
241 The next example is Linux specific as we try to find out what the Linux
243 LUN 49409 translates to in the T10 world:
244 # sg_luns --test=L49409
246 64 bit LUN in T10 preferred (hex) format: c1 01 00 00 00 00 00 00
247 Decoded LUN:
248 REPORT LUNS well known logical unit
249 And the mapping between T10 and Linux LUN representations can be done
251 the other way:
252 # sg_luns -t c101L
254 Linux 'word flipped' integer LUN representation: 49409
255 Decoded LUN:
256 REPORT LUNS well known logical unit
257
259 The exit status of sg_luns is 0 when it is successful. Otherwise see
260 the sg3_utils(8) man page.
261
263 Written by Douglas Gilbert.
264
266 Report bugs to <dgilbert at interlog dot com>.
267
269 Copyright © 2004-2014 Douglas Gilbert
270 This software is distributed under a FreeBSD license. There is NO war‐
271 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
272 POSE.
273
275 sg_inq(8)
276sg3_utils-1.39 June SG_LUNS(8)