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] [--maxlen=LEN] [--quiet]
10 [--raw] [--select=SR] [--verbose] [--version] DEVICE
11 sg_luns --test=ALUN [--hex] [--verbose]
13
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 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 Where required below the first form shown in the SYNOPSIS is called
28 "device mode" and the second form is called "test mode".
29
31 Arguments to long options are mandatory for short options as well.
32 -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 -h, --help
38 output the usage message then exit.
39 -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 -H, --hex
47 [test mode] when this option is given, then decoded component
48 fields of ALUN are output in hex.
49 -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 -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 -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 -r, --raw
70 output the SCSI response (i.e. the data-out buffer) in binary
71 (to stdout).
72 -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 -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 -v, --verbose
107 increase the level of verbosity, (i.e. debug output).
108 -V, --version
110 print the version string and then exit.
111
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 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
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 # 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 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 # sg_luns /dev/sg1
148 Lun list length = 8 which imples 1 lun entry
149 Report luns [select_report=0x0]:
150 0001000000000000
151 That is a bit noisy so cut down the clutter with --quiet:
153 # sg_luns -q /dev/sg1
155 0001000000000000
156 Now decode that LUN into its component parts:
158 # sg_luns -d -q /dev/sg1
160 0001000000000000
161 Peripheral device addressing: lun=1
162 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 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 # sg_luns -q -s 1 /dev/sg1
172 c101000000000000
173 So how many LUNs do we have all together (associated with the current
175 I_T Nexus):
176 # sg_luns -q -s 2 /dev/sg1
178 0001000000000000
179 c101000000000000
180 # 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 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 # sg_luns -q -s 2 -l /dev/sg1
192 0001000000000000 [1]
193 c101000000000000 [49409]
194 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 # sg_luns --test=0001000000000000
199 Decoded LUN:
200 Peripheral device addressing: lun=1
201 # sg_luns --test="c1 01"
203 Decoded LUN:
204 REPORT LUNS well known logical unit
205 # 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 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 # 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 And the mapping between T10 and Linux LUN representations can be done
221 the other way:
222 # sg_luns -t c101L
224 Linux 'word flipped' integer LUN representation: 49409
225 Decoded LUN:
226 REPORT LUNS well known logical unit
227
229 The exit status of sg_luns is 0 when it is successful. Otherwise see
230 the sg3_utils(8) man page.
231
233 Written by Douglas Gilbert.
234
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
245 sg_inq(8)
246sg3_utils-1.36 May 2013 SG_LUNS(8)