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 [--decode] [--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 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 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 Where required below the first form shown in the SYNOPSIS is called
30 "device mode" and the second form is called "test mode".
31
33 Arguments to long options are mandatory for short options as well.
34 -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 -h, --help
47 output the usage message then exit.
48 -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 -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 -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 -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 -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 -r, --raw
91 output the SCSI response (i.e. the data-out buffer) in binary
92 (to stdout).
93 -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 -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 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 -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 -v, --verbose
144 increase the level of verbosity, (i.e. debug output).
145 -V, --version
147 print the version string and then exit.
148
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 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
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 # 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 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 # 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 That is a bit noisy so cut down the clutter with --quiet:
195 # sg_luns -q /dev/sg1
197 0001000000000000
198 0002000000000000
199 Now decode that LUN into its component parts:
201 # sg_luns -d -q /dev/sg1
203 0001000000000000
204 Peripheral device addressing: lun=1
205 0002000000000000
206 Peripheral device addressing: lun=2
207 Now use --select=1 to find out if there are any well known LUNs:
209 # sg_luns -q -s 1 /dev/sg1
211 c101000000000000
212 So how many LUNs do we have all together (associated with the current
214 I_T Nexus):
215 # sg_luns -q -s 2 /dev/sg1
217 0001000000000000
218 0002000000000000
219 c101000000000000
220 # 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 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 # sg_luns -q -s 2 -l /dev/sg1
234 0001000000000000 [1]
235 0002000000000000 [2]
236 c101000000000000 [49409]
237 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 # sg_luns --test=0002000000000000
242 Decoded LUN:
243 Peripheral device addressing: lun=2
244 # sg_luns --test="c1 01"
246 Decoded LUN:
247 REPORT LUNS well known logical unit
248 # 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 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 # 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 And the mapping between T10 and Linux LUN representations can be done
264 the other way:
265 # sg_luns -t c101L
267 Linux 'word flipped' integer LUN representation: 49409
268 Decoded LUN:
269 REPORT LUNS well known logical unit
270
272 The exit status of sg_luns is 0 when it is successful. Otherwise see
273 the sg3_utils(8) man page.
274
276 Written by Douglas Gilbert.
277
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
288 sg_inq(8)
289sg3_utils-1.45 January 2020 SG_LUNS(8)