Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

sg_luns (8)

Name

sg_luns - send SCSI REPORT LUNS command or decode given LUN

Synopsis

sg_luns    [--decode]    [--help]    [--hex]    [--linux]   [--lu_cong]
[--maxlen=LEN] [--quiet] [--raw] [--readonly] [--select=SR] [--verbose]
[--version] DEVICE

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

Description

SG_LUNS(8)                         SG3_UTILS                        SG_LUNS(8)



NAME
       sg_luns - send SCSI REPORT LUNS command or decode given LUN

SYNOPSIS
       sg_luns    [--decode]    [--help]    [--hex]    [--linux]   [--lu_cong]
       [--maxlen=LEN] [--quiet] [--raw] [--readonly] [--select=SR] [--verbose]
       [--version] DEVICE

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

DESCRIPTION
       In  the  first  form  shown in the SYNOPSIS this utility sends the SCSI
       REPORT LUNS command  to  the  DEVICE  and  outputs  the  response.  The
       response should be a list of LUNs ("a LUN inventory") for the I_T nexus
       associated with the DEVICE. Roughly speaking  that  is  all  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 if 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.

       -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 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).

       -h, --help
              output the usage message then exit.

       -H, --hex
              [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 output in hex.

       -l, --linux
              this option is only available in Linux. After the T10  represen-
              tation  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  the
              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 cor-
              responding  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 the 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 revi-
              sion 37 in section 6.33). To simplify, for the I_T nexus associ-
              ated  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 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 util-
       ity will accept any value between 0 and 255 (0xff) for SR .

       -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 hexa-
              decimal 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 hexadec-
              imal  number it can have a trailing 'L' in which case the corre-
              sponding 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.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+--------------------------+
       |ATTRIBUTE TYPE |     ATTRIBUTE VALUE      |
       +---------------+--------------------------+
       |Availability   | system/storage/sg3_utils |
       +---------------+--------------------------+
       |Stability      | Pass-through uncommitted |
       +---------------+--------------------------+

NOTES
       The SCSI REPORT LUNS command is important for Logical Unit (LU) discov-
       ery.   After  a target device is discovered (usually via some transport
       specific mechanism) and after sending an INQUIRY command (to  determine
       the  LU_CONG  setting),  a REPORT LUNS command should either be sent to
       LUN 0 (which is Peripheral device addressing method with  bus_id=0  and
       target/lun=0)   or   to   the   REPORT   LUNS   well  known  LUN  (i.e.
       0xc101000000000000). SAM-5 requires that one of these responds with  an
       inventory of LUNS that are contained in this target device.

       In  test  mode,  if  the --hex option is given once then in the decoded
       output, some of the component fields are printed in  hex  with  leading
       zeros.   The  leading  zeros  are to indicate the size of the component
       field. For example: 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  (e.g.  bus_id=0x02,  tar-
       get=0x3a).

       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source was downloaded from  http://sg.danny.cz/sg/p/sg3_utils-1.46.tgz.

       Further information about this software can be found on the open source
       community website at http://sg.danny.cz/sg/sg3_utils.html.

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 "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.

         # 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. Below we use  /dev/sg1
       :

         # sg_luns /dev/sg1
         Lun list length = 16 which imples 2 lun entry
         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.

AUTHORS
       Written by Douglas Gilbert.

REPORTING BUGS
       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT
       Copyright (C) 2004-2020 Douglas Gilbert
       This software is distributed under a FreeBSD license. There is NO  war-
       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
       POSE.

SEE ALSO
       sg_inq(8)




sg3_utils-1.45                   January 2020                       SG_LUNS(8)