{ "mode": "man", "parameter": "sg_luns", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sg_luns/8/json", "generated": "2026-10-08T09:24:45Z", "synopsis": "sgluns [--decode] [--help] [--hex] [--linux] [--lucong] [--maxlen=LEN] [--quiet] [--raw]\n[--readonly] [--select=SR] [--verbose] [--version] DEVICE\nsgluns --test=ALUN [--decode] [--hex] [--lucong] [--verbose]", "sections": { "NAME": { "content": "sgluns - send SCSI REPORT LUNS command or decode given LUN\n", "subsections": [] }, "SYNOPSIS": { "content": "sgluns [--decode] [--help] [--hex] [--linux] [--lucong] [--maxlen=LEN] [--quiet] [--raw]\n[--readonly] [--select=SR] [--verbose] [--version] DEVICE\n\nsgluns --test=ALUN [--decode] [--hex] [--lucong] [--verbose]\n", "subsections": [] }, "DESCRIPTION": { "content": "In the first form shown in the SYNOPSIS this utility sends the SCSI REPORT LUNS command to\nthe DEVICE and outputs the response. The response should be a list of LUNs (\"a LUN inven‐\ntory\") for the IT nexus associated with the DEVICE. Roughly speaking that is all LUNs that\nshare the target device that the REPORT LUNS command is sent through. This command is defined\nin the SPC-3 and SPC-4 SCSI standards and its support is mandatory. The most recent draft if\nSPC-6 revision 1.\n\nWhen the --test=ALUN option is given (the second form in the SYNOPSIS), then the ALUN value\nis decoded as outlined in various SCSI Architecture Model (SAM) standards and recent drafts\n(e.g. SAM-6 revision 2, section 4.7) .\n\nWhere required below the first form shown in the SYNOPSIS is called \"device mode\" and the\nsecond form is called \"test mode\".\n", "subsections": [] }, "OPTIONS": { "content": "Arguments to long options are mandatory for short options as well.\n", "subsections": [ { "name": "-d --decode", "content": "decode LUNs into their component parts, as described in the LUN section of SAM-3,\nSAM-4 and SAM-5.\n[test mode] ALUN is decoded irrespective of whether this option is given or not. If\nthis option is given once then the given ALUN is output in T10 preferred format (which\nis 8 pairs of hex digits, each separated by a space). If given twice then the given\nALUN is output in an alternate T10 format made up of four quads of hex digits with\neach quad separated by a \"-\" (e.g. C101-0000-0000-0000).\n", "flag": "-d", "long": "--decode" }, { "name": "-h --help", "content": "output the usage message then exit.\n", "flag": "-h", "long": "--help" }, { "name": "-H --hex", "content": "[device mode] when given once this utility will output the SCSI response (i.e. the\ndata-out buffer) to the REPORT LUNS command in ASCII hex then exit. When given twice\nit causes --decode to output component fields in hex rather than decimal.\n[test mode] when this option is given, then decoded component fields of ALUN are out‐\nput in hex.\n", "flag": "-H", "long": "--hex" }, { "name": "-l --linux", "content": "this option is only available in Linux. After the T10 representation of each 64 bit\nLUN (in 16 hexadecimal digits), if this option is given then to the right, in square\nbrackets, is the Linux LUN integer in decimal. If the --hex option is given twice\n(e.g. -HH) as well then the Linux LUN integer is output in hexadecimal.\n", "flag": "-l", "long": "--linux" }, { "name": "-L --lu_cong", "content": "this option is only considered with --decode. When given once then the list of LUNs is\ndecoded as if the LUCONG bit was set in each LU's corresponding INQUIRY response.\nWhen given twice the list of LUNs is decoded as if the LUCONG bit was clear in each\nLU's corresponding INQUIRY response. When this option is not given and --decode is\ngiven then an INQUIRY is sent to the DEVICE and the setting of its LUCONG bit is used\nto decode the list of LUNs.\n[test mode] decode ALUN as if the LUCONG bit is set in its corresponding standard IN‐\nQUIRY response. In other words treat ALUN as if it is a conglomerate LUN. If not given\n(or given twice) then decode ALUN as if the LUCONG bit is clear.\n", "flag": "-L", "long": "--lu_cong" }, { "name": "-m --maxlen", "content": "where LEN is the (maximum) response length in bytes. It is placed in the cdb's \"allo‐\ncation length\" field. If not given (or LEN is zero) then 8192 is used. The maximum al‐\nlowed value of LEN is 1048576.\n", "flag": "-m", "long": "--maxlen" }, { "name": "-q --quiet", "content": "output only the ASCII hex rendering of each report LUN, one per line. Without the\n--quiet option, there is header information printed before the LUN listing.\n", "flag": "-q", "long": "--quiet" }, { "name": "-r --raw", "content": "output the SCSI response (i.e. the data-out buffer) in binary (to stdout).\n", "flag": "-r", "long": "--raw" }, { "name": "-R --readonly", "content": "open the DEVICE read-only (e.g. in Unix with the ORDONLY flag). The default is to\nopen it read-write.\n", "flag": "-R", "long": "--readonly" }, { "name": "-s --select", "content": "SR is placed in the SELECT REPORT field of the SCSI REPORT LUNS command. The default\nvalue is 0. Hexadecimal values may be given with a leading \"0x\" or a trailing \"h\". For\ndetailed information see the REPORT LUNS command in SPC (most recent is SPC-4 revision\n37 in section 6.33). To simplify, for the IT nexus associated with the DEVICE, the\nmeanings of the SR values defined to date for SPC-4 are:\n0 : most luns excluding well known logical unit numbers\n1 : well known logical unit numbers\n2 : all luns accessible to this IT nexus\n0x10 : only accessible administrative luns\n0x11 : administrative luns plus non-conglomerate luns (see SPC-4)\n0x12 : if DEVICE is an administrative LU, then report its\nlun plus its subsidiary luns\n\nFor SR values 0x10 and 0x11, the DEVICE must be either LUN 0 or the REPORT LUNS well known\nlogical unit. Values between 0xf8 and 0xff (inclusive) are vendor specific, other values are\nreserved. This utility will accept any value between 0 and 255 (0xff) for SR .\n", "flag": "-s", "long": "--select" }, { "name": "-t --test", "content": "ALUN is assumed to be a hexadecimal number in ASCII hex or the letter 'L' followed by\na decimal number (see below). The hexadecimal number can be up to 64 bits in size\n(i.e. 16 hexadecimal digits) and is padded to the right if less than 16 hexadecimal\ndigits are given (e.g. --test=0122003a represents T10 LUN: 01 22 00 3a 00 00 00 00).\nALUN may be prefixed by '0x' or '0X' (e.g. the previous example could have been\n--test=0x0122003a). ALUN may also be given with spaces, tabs, or a '-' between each\nbyte (or other grouping (e.g. c101-0000-0000-0000)). However in the case of space or\ntab separators the ALUN would need to be surrounded by single or double quotes.\nIn the leading 'L' case the, following decimal number (hex if preceded by '0x') is as‐\nsumed to be a Linux \"word flipped\" LUN which is converted into a T10 LUN representa‐\ntion and printed. In both cases the number is interpreted as a LUN and decoded as if\nthe --decode option had been given. Also when ALUN is a hexadecimal number it can have\na trailing 'L' in which case the corresponding Linux \"word flipped\" LUN value is out‐\nput. The LUN is decoded in all cases.\nThe action when used with --decode is explained under that option.\n", "flag": "-t", "long": "--test" }, { "name": "-v --verbose", "content": "increase the level of verbosity, (i.e. debug output).\n", "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "content": "print the version string and then exit.\n", "flag": "-V", "long": "--version" } ] }, "NOTES": { "content": "The SCSI REPORT LUNS command is important for Logical Unit (LU) discovery. After a target\ndevice is discovered (usually via some transport specific mechanism) and after sending an IN‐\nQUIRY command (to determine the LUCONG setting), a REPORT LUNS command should either be sent\nto LUN 0 (which is Peripheral device addressing method with busid=0 and target/lun=0) or to\nthe REPORT LUNS well known LUN (i.e. 0xc101000000000000). SAM-5 requires that one of these\nresponds with an inventory of LUNS that are contained in this target device.\n\nIn test mode, if the --hex option is given once then in the decoded output, some of the com‐\nponent fields are printed in hex with leading zeros. The leading zeros are to indicate the\nsize of the component field. For example: in the Peripheral device addressing method (16 bits\noverall), the bus ID is 6 bits wide and the target/LUN field is 8 bits wide; so both are\nshown with two hex digits (e.g. busid=0x02, target=0x3a).\n", "subsections": [] }, "EXAMPLES": { "content": "Typically by the time user space programs get to run, SCSI LUs have been discovered. In Linux\nthe lsscsi utility lists the LUs that are currently present. The LUN of a device (LU) is the\nfourth element in the tuple at the beginning of each line. Below we see a target (or \"IT\nNexus\": \"6:0:0\") has two LUNS: 1 and 49409. If 49409 is converted into T10 LUN format it is\n0xc101000000000000 which is the REPORT LUNS well known LUN.\n\n# lsscsi -g\n[6:0:0:1] disk Linux scsidebug 0004 /dev/sdb /dev/sg1\n[6:0:0:2] disk Linux scsidebug 0004 /dev/sdc /dev/sg2\n[6:0:0:49409]wlun Linux scsidebug 0004 - /dev/sg3\n\nWe could send a REPORT LUNS command (with SR 0x0, 0x1 or 0x2) to any of those file device\nnodes and get the same result. Below we use /dev/sg1 :\n\n# sgluns /dev/sg1\nLun list length = 16 which imples 2 lun entry\nReport luns [selectreport=0x0]:\n0001000000000000\n0002000000000000\n\nThat is a bit noisy so cut down the clutter with --quiet:\n\n# sgluns -q /dev/sg1\n0001000000000000\n0002000000000000\n\nNow decode that LUN into its component parts:\n\n# sgluns -d -q /dev/sg1\n0001000000000000\nPeripheral device addressing: lun=1\n0002000000000000\nPeripheral device addressing: lun=2\n\nNow use --select=1 to find out if there are any well known LUNs:\n\n# sgluns -q -s 1 /dev/sg1\nc101000000000000\n\nSo how many LUNs do we have all together (associated with the current IT Nexus):\n\n# sgluns -q -s 2 /dev/sg1\n0001000000000000\n0002000000000000\nc101000000000000\n\n# sgluns -q -s 2 -d /dev/sg1\n0001000000000000\nPeripheral device addressing: lun=1\n0002000000000000\nPeripheral device addressing: lun=1\nc101000000000000\nREPORT LUNS well known logical unit\n\nThe following example uses the --linux option and is not available in other operating sys‐\ntems. The extra number in square brackets is the Linux version of T10 LUN shown at the start\nof the line.\n\n# sgluns -q -s 2 -l /dev/sg1\n0001000000000000 [1]\n0002000000000000 [2]\nc101000000000000 [49409]\n\nNow we use the --test= option to decode LUNS input on the command line (rather than send a\nREPORT LUNS command and act on the response):\n\n# sgluns --test=0002000000000000\nDecoded LUN:\nPeripheral device addressing: lun=2\n\n# sgluns --test=\"c1 01\"\nDecoded LUN:\nREPORT LUNS well known logical unit\n\n# sgluns -t 0x023a004b -H\nDecoded LUN:\nPeripheral device addressing: busid=0x02, target=0x3a\n>>Second level addressing:\nPeripheral device addressing: lun=0x4b\n\nThe next example is Linux specific as we try to find out what the Linux LUN 49409 translates\nto in the T10 world:\n\n# sgluns --test=L49409\n64 bit LUN in T10 preferred (hex) format: c1 01 00 00 00 00 00 00\nDecoded LUN:\nREPORT LUNS well known logical unit\n\nAnd the mapping between T10 and Linux LUN representations can be done the other way:\n\n# sgluns -t c101L\nLinux 'word flipped' integer LUN representation: 49409\nDecoded LUN:\nREPORT LUNS well known logical unit\n", "subsections": [] }, "EXIT STATUS": { "content": "The exit status of sgluns is 0 when it is successful. Otherwise see the sg3utils(8) man\npage.\n", "subsections": [] }, "AUTHORS": { "content": "Written by Douglas Gilbert.\n", "subsections": [] }, "REPORTING BUGS": { "content": "Report bugs to .\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright © 2004-2020 Douglas Gilbert\nThis software is distributed under a FreeBSD license. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n", "subsections": [] }, "SEE ALSO": { "content": "", "subsections": [ { "name": "sg_inq(8)", "content": "sg3utils-1.45 January 2020 SGLUNS(8)" } ] } }, "summary": "sgluns - send SCSI REPORT LUNS command or decode given LUN", "flags": [ { "flag": "-d", "long": "--decode", "arg": null, "description": "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 irrespective of whether this option is given or not. If this option is given once then the given ALUN is output in T10 preferred format (which is 8 pairs of hex digits, each 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)." }, { "flag": "-h", "long": "--help", "arg": null, "description": "output the usage message then exit." }, { "flag": "-H", "long": "--hex", "arg": null, "description": "[device mode] when given once this utility will output the SCSI response (i.e. the data-out buffer) to the REPORT LUNS command in ASCII hex then exit. When given twice it causes --decode to output component fields in hex rather than decimal. [test mode] when this option is given, then decoded component fields of ALUN are out‐ put in hex." }, { "flag": "-l", "long": "--linux", "arg": null, "description": "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." }, { "flag": "-L", "long": "--lu_cong", "arg": null, "description": "this option is only considered with --decode. When given once then the list of LUNs is decoded as if the LUCONG bit was set in each LU's corresponding INQUIRY response. When given twice the list of LUNs is decoded as if the LUCONG 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 the DEVICE and the setting of its LUCONG bit is used to decode the list of LUNs. [test mode] decode ALUN as if the LUCONG bit is set in its corresponding standard IN‐ QUIRY 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 LUCONG bit is clear." }, { "flag": "-m", "long": "--maxlen", "arg": null, "description": "where LEN is the (maximum) response length in bytes. It is placed in the cdb's \"allo‐ cation length\" field. If not given (or LEN is zero) then 8192 is used. The maximum al‐ lowed value of LEN is 1048576." }, { "flag": "-q", "long": "--quiet", "arg": null, "description": "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." }, { "flag": "-r", "long": "--raw", "arg": null, "description": "output the SCSI response (i.e. the data-out buffer) in binary (to stdout)." }, { "flag": "-R", "long": "--readonly", "arg": null, "description": "open the DEVICE read-only (e.g. in Unix with the ORDONLY flag). The default is to open it read-write." }, { "flag": "-s", "long": "--select", "arg": null, "description": "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 IT nexus associated with the 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 IT 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 ." }, { "flag": "-t", "long": "--test", "arg": null, "description": "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 as‐ sumed to be a Linux \"word flipped\" LUN which is converted into a T10 LUN representa‐ tion 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 out‐ put. The LUN is decoded in all cases. The action when used with --decode is explained under that option." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "increase the level of verbosity, (i.e. debug output)." }, { "flag": "-V", "long": "--version", "arg": null, "description": "print the version string and then exit." } ], "examples": [ "Typically by the time user space programs get to run, SCSI LUs have been discovered. 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 \"IT", "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.", "# lsscsi -g", "[6:0:0:1] disk Linux scsidebug 0004 /dev/sdb /dev/sg1", "[6:0:0:2] disk Linux scsidebug 0004 /dev/sdc /dev/sg2", "[6:0:0:49409]wlun Linux scsidebug 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. Below we use /dev/sg1 :", "# sgluns /dev/sg1", "Lun list length = 16 which imples 2 lun entry", "Report luns [selectreport=0x0]:", "0001000000000000", "0002000000000000", "That is a bit noisy so cut down the clutter with --quiet:", "# sgluns -q /dev/sg1", "0001000000000000", "0002000000000000", "Now decode that LUN into its component parts:", "# sgluns -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:", "# sgluns -q -s 1 /dev/sg1", "c101000000000000", "So how many LUNs do we have all together (associated with the current IT Nexus):", "# sgluns -q -s 2 /dev/sg1", "0001000000000000", "0002000000000000", "c101000000000000", "# sgluns -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 sys‐", "tems. The extra number in square brackets is the Linux version of T10 LUN shown at the start", "of the line.", "# sgluns -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):", "# sgluns --test=0002000000000000", "Decoded LUN:", "Peripheral device addressing: lun=2", "# sgluns --test=\"c1 01\"", "Decoded LUN:", "REPORT LUNS well known logical unit", "# sgluns -t 0x023a004b -H", "Decoded LUN:", "Peripheral device addressing: busid=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:", "# sgluns --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:", "# sgluns -t c101L", "Linux 'word flipped' integer LUN representation: 49409", "Decoded LUN:", "REPORT LUNS well known logical unit" ], "see_also": [] }