SG_LUNS(8)

📦

version 1.49 · 4 versions

1.49 · arch rolling, nixpkgs unstable (latest)
1.48~20221101+8.02dda5f · opensuse-leap 16.0
1.47 · centos-stream 9, debian bookworm, ubuntu jammy, ubuntu noble
1.48 · alpine 3.24, centos-stream 10, debian trixie, fedora 43, fedora 44, nixos 26.05, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

sg_luns (from the sg3_utils bestie crew) — send the SCSI REPORT LUNS command, or decode a LUN you hand it. 💅✨

🎀 SYNOPSIS 🎀

sg_luns [--decode] [--help] [--hex] [--inhex=FN] [--inner-hex]
[--json[=JO]] [--js-file=JFN] [--linux] [--lu_cong] [--maxlen=LEN]
[--quiet] [--raw] [--readonly] [--select=SR] [--sinq_inraw=RFN]
[--verbose] [--version] DEVICE

sg_luns --test=ALUN [--decode] [--hex] [--inner-hex] [--lu_cong]
[--verbose]

🦋 DESCRIPTION 🦋

okay so in the first form shown in the SYNOPSIS, this utility sends the SCSI REPORT LUNS command to DEVICE and outputs the response. That response should be a list of LUNs, aka “a LUN inventory”, for the I_T nexus associated with DEVICE. Roughly speaking, that’s all the LUNs that share the target device that the REPORT LUNS command is sent through. This command is defined in the SPC-3 and SPC-4 SCSI standards, and its support is mandatory. The most recent draft is SPC-6 revision 1. 😌✨

When the --test=ALUN option is given (the second form in the SYNOPSIS), then the ALUN value is decoded as outlined in various SCSI Architecture Model (SAM) standards and recent drafts (e.g. SAM-6 revision 2, section 4.7). 🫶

Where required below, the first form shown in the SYNOPSIS is called “device mode” and the second form is called “test mode”. 💖

✨ OPTIONS ✨

Arguments to long options are mandatory for short options as well. no cap. 💅

-d, --decode — decode LUNs into their component parts, as described in the LUN section of SAM-3, SAM-4 and SAM-5. [test mode] ALUN is decoded whether or not this option is given. If this option is given once, then the given ALUN is output in T10 preferred format, which is 8 pairs of hex digits with each pair separated by a space. If given twice, then the given ALUN is output in an alternate T10 format made up of four quads of hex digits, with each quad separated by a - (e.g. C101-0000-0000-0000). 👑
-h, --help — output the usage message, then exit. simple. iconic. ✨
-H, --hex — [device mode] when given once, this utility outputs the SCSI response (i.e. the data-out buffer) to the REPORT LUNS command in ASCII hex, then exits. When given twice, it causes --decode to output component fields in hex rather than decimal. Notice that this (i.e. how -HH is processed) differs from the description in sg3_utils(8). The --inner-hex option has the same action as -HH. When this option is used three (or more) times, the hex output is suitable for placing in a file and using it with a later sg_luns invocation with the --inhex=FN option. [test mode] when this option is given, decoded component fields of ALUN are output in hex. When this option is given three or more times, ASCII hex bytes are output (up to 16 per line) with no leading address or index. This output is suitable for placing in a file and later invocation of this utility decoding it with the --inhex=FN option. When this option is used four times, a comment line (starting with #) is added before the hex, describing what generated the hex. A file containing such comments is still parsable by the --inhex=FN option. 💜
-i, --inhex=FN — FN is expected to be a file name (or - for stdin) which contains ASCII hexadecimal or binary representing a REPORT LUNS response. This utility will then decode that response. See the “HEX, BINARY AND JSON FORMATS” section in the sg3_utils manpage for more information. If the --raw option is also given, then FN is treated as binary. 🍓
-I, --inner-hex — used together with the --decode option so that the decoded values are shown in hexadecimal. The default action is to show decoded values in decimal. This option has the same action as -HH, but the intent is a little clearer with this option. 🎀
-j[=JO], --json[=JO] — output is in JSON format instead of plain text form. Note that arguments to the short and long form are themselves optional, and if present they start with = and no whitespace is permitted around that =. See the sg3_utils_json manpage or use ? for JO to get a summary. 🌈
-J, --js-file=JFN — output is in JSON format and it is sent to a file named JFN. If that file exists, then it is truncated. By default, the JSON output is sent to stdout. When this option is given, the --json[=JO] option is implied and need not be given. The --json[=JO] option may still be needed to set the JO parameter to non-default values. 🦋
-l, --linux — this option is only available in Linux. After the T10 representation of each 64 bit LUN (in 16 hexadecimal digits), if this option is given then to the right, in square brackets, is the Linux LUN integer in decimal. If the --hex option is given twice (e.g. -HH) as well, then the Linux LUN integer is output in hexadecimal. 🔥
-L, --lu_cong — this option is only considered with --decode. When given once, then the list of LUNs is decoded as if the LU_CONG bit was set in each LU’s corresponding INQUIRY response. When given twice, the list of LUNs is decoded as if the LU_CONG bit was clear in each LU’s corresponding INQUIRY response. When this option is not given and --decode is given, then an INQUIRY is sent to DEVICE and the setting of its LU_CONG bit is used to decode the list of LUNs. [test mode] decode ALUN as if the LU_CONG bit is set in its corresponding standard INQUIRY response. In other words, treat ALUN as if it is a conglomerate LUN. If not given (or given twice), then decode ALUN as if the LU_CONG bit is clear. 💖
-m, --maxlen=LEN — where LEN is the (maximum) response length in bytes. It is placed in the cdb’s “allocation length” field. If not given (or LEN is zero), then 8192 is used. The maximum allowed value of LEN is 1048576. 😌
-q, --quiet — output only the ASCII hex rendering of each report LUN, one per line. Without the --quiet option, there is header information printed before the LUN listing. ✨
-r, --raw — output the SCSI response (i.e. the data-out buffer) in binary (to stdout). 🫶
-R, --readonly — open DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write. 💅
-s, --select=SR — SR is placed in the SELECT REPORT field of the SCSI REPORT LUNS command. The default value is 0. Hexadecimal values may be given with a leading 0x or a trailing h. For detailed information, see the REPORT LUNS command in SPC (most recent is SPC-4 revision 37 in section 6.33). To simplify, for the I_T nexus associated with DEVICE, the meanings of the SR values defined to date for SPC-4 are:
- 0 — most luns excluding well known logical unit numbers
- 1 — well known logical unit numbers
- 2 — all luns accessible to this I_T nexus
- 0x10 — only accessible administrative luns
- 0x11 — administrative luns plus non-conglomerate luns (see SPC-4)
- 0x12 — if DEVICE is an administrative LU, then report its lun plus its subsidiary luns

For SR values 0x10 and 0x11, the DEVICE must be either LUN 0 or the REPORT LUNS well known logical unit. Values between 0xf8 and 0xff (inclusive) are vendor specific, other values are reserved. This utility will accept any value between 0 and 255 (0xff) for SR. 👑

-Q, --sinq_inraw=RFN — where RFN is a filename containing binary standard INQUIRY response data that matches either DEVICE or FN. Linux places this standard INQUIRY response in its sysfs pseudo filesystem. A typical location is at /sys/class/scsi_device/<hctl>/device/inquiry where <hctl> is a four part numeric tuple separated by colons. This tuple distinguishes the device from any others on the system. Currently the LU_CONG field is read from the standard INQUIRY response when this option is given. The --raw option has no effect on this option. The DEVICE argument may be given with this option. 🌸
-t, --test=ALUN — ALUN is assumed to be a hexadecimal number in ASCII hex or the letter L followed by a decimal number (see below). The hexadecimal number can be up to 64 bits in size (i.e. 16 hexadecimal digits) and is padded to the right if less than 16 hexadecimal digits are given (e.g. --test=0122003a represents T10 LUN: 01 22 00 3a 00 00 00 00). ALUN may be prefixed by 0x or 0X (e.g. the previous example could have been --test=0x0122003a). ALUN may also be given with spaces, tabs, or a - between each byte (or other grouping, e.g. c101-0000-0000-0000). However, in the case of space or tab separators, the ALUN would need to be surrounded by single or double quotes. In the leading L case, the following decimal number (hex if preceded by 0x) is assumed to be a Linux “word flipped” LUN, which is converted into a T10 LUN representation and printed. In both cases, the number is interpreted as a LUN and decoded as if the --decode option had been given. Also, when ALUN is a hexadecimal number, it can have a trailing L, in which case the corresponding Linux “word flipped” LUN value is output. The LUN is decoded in all cases. The action when used with --decode is explained under that option. 🧚
-v, --verbose — increase the level of verbosity (i.e. debug output). 💀
-V, --version — print the version string and then exit. 🌟

🫶 NOTES 🫶

Okay bestie, listen — the SCSI REPORT LUNS command is literally the main character of Logical Unit (LU) discovery. Like, it's that girl. Here's the lore: after a target device gets discovered (usually through some transport specific mechanism, iykyk) and after an INQUIRY command has been sent (that's how you figure out the LU_CONG setting), a REPORT LUNS command should be sent either:

to LUN 0 — that's the Peripheral device addressing method with bus_id=0 and target/lun=0, or
to the REPORT LUNS well known LUN, aka 0xc101000000000000 ✨

And SAM-5 requires that one of these responds with an inventory of LUNS that live inside this target device. No cap, that's the whole vibe check.

Now, about test mode 🧪 — if the --hex option is given once, then in the decoded output, some of the component fields get printed in hex with leading zeros. And bestie, those leading zeros aren't just cute, they're informative — they tell you the size of the component field. Example time: in the Peripheral device addressing method (16 bits overall), the bus ID is 6 bits wide and the target/LUN field is 8 bits wide; so both are shown with two hex digits (like bus_id=0x02, target=0x3a). 💅

🌈 EXAMPLES 🌈

Typically, by the time user space programs get to run, SCSI LUs have already been discovered (they got there first, honestly 💀). In Linux the lsscsi utility lists the LUs that are currently present. The LUN of a device (LU) is the fourth element in the tuple at the beginning of each line.

Below we see a target (or "I_T Nexus": 6:0:0) has two LUNS: 1 and 49409. If 49409 is converted into T10 LUN format it is 0xc101000000000000 which is the REPORT LUNS well known LUN. Obsessed. 🎀

# lsscsi -g
[6:0:0:1]    disk    Linux    scsi_debug       0004  /dev/sdb   /dev/sg1
[6:0:0:2]    disk    Linux    scsi_debug       0004  /dev/sdc   /dev/sg2
[6:0:0:49409]wlun    Linux    scsi_debug       0004  -          /dev/sg3

We could send a REPORT LUNS command (with SR 0x0, 0x1 or 0x2) to any of those file device nodes and get the same result. Iconic behavior. Below we use /dev/sg1:

# sg_luns /dev/sg1
Lun list length = 16 which implies 2 lun entries
Report luns [select_report=0x0]:
    0001000000000000
    0002000000000000

That is a bit noisy 😭 so cut down the clutter with --quiet:

# sg_luns -q /dev/sg1
0001000000000000
0002000000000000

Now decode that LUN into its component parts:

# sg_luns -d -q /dev/sg1
0001000000000000
     Peripheral device addressing: lun=1
0002000000000000
     Peripheral device addressing: lun=2

Now use --select=1 to find out if there are any well known LUNs:

# sg_luns -q -s 1 /dev/sg1
c101000000000000

So how many LUNs do we have all together (associated with the current I_T Nexus)? 👀

# sg_luns -q -s 2 /dev/sg1
0001000000000000
0002000000000000
c101000000000000

# sg_luns -q -s 2 -d /dev/sg1
0001000000000000
     Peripheral device addressing: lun=1
0002000000000000
     Peripheral device addressing: lun=1
c101000000000000
     REPORT LUNS well known logical unit

The following example uses the --linux option and is not available in other operating systems. The extra number in square brackets is the Linux version of T10 LUN shown at the start of the line:

# sg_luns -q -s 2 -l /dev/sg1
0001000000000000    [1]
0002000000000000    [2]
c101000000000000    [49409]

Now we use the --test= option to decode LUNS input on the command line (rather than send a REPORT LUNS command and act on the response):

# sg_luns --test=0002000000000000
Decoded LUN:
  Peripheral device addressing: lun=2

# sg_luns --test="c1 01"
Decoded LUN:
  REPORT LUNS well known logical unit

# sg_luns -t 0x023a004b -H
Decoded LUN:
  Peripheral device addressing: bus_id=0x02, target=0x3a
  >>Second level addressing:
    Peripheral device addressing: lun=0x4b

The next example is Linux specific as we try to find out what the Linux LUN 49409 translates to in the T10 world:

# sg_luns --test=L49409
64 bit LUN in T10 preferred (hex) format:  c1 01 00 00 00 00 00 00
Decoded LUN:
  REPORT LUNS well known logical unit

And the mapping between T10 and Linux LUN representations can be done the other way:

# sg_luns -t c101L
Linux 'word flipped' integer LUN representation: 49409
Decoded LUN:
  REPORT LUNS well known logical unit

💀 EXIT STATUS 💀

The exit status of sg_luns is 0 when it is successful. Otherwise see the sg3_utils(8) man page. Simple as that, bestie. ✨

👑 AUTHORS 👑

Written by Douglas Gilbert. (We stan a legend 🫶)

🙈 REPORTING BUGS 🙈

Report bugs to <dgilbert at interlog dot com>.

🍓 COPYRIGHT 🍓

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

🧚 SEE ALSO 🧚

sg_inq(8)
sg3_utils(8)

Okay that's the whole page, you made it to the end, I'm so proud of you 🥹💜

Mwah, go forth and discover LUNs. This was sg3_utils-1.48, dated June 2023, and the page itself is SG_LUNS(8). Slay, goodbye, ily! 🌸🦋

📦 where this page comes from

arch rolling: sg3_utils 1.49-1 · GPL-2.0-or-later AND BSD-2-Clause
nixpkgs unstable: sg3_utils 1.49
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms