diff options
Diffstat (limited to 'doc/sg_luns.8')
| -rw-r--r-- | doc/sg_luns.8 | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/doc/sg_luns.8 b/doc/sg_luns.8 new file mode 100644 index 00000000..3ededa9f --- /dev/null +++ b/doc/sg_luns.8 @@ -0,0 +1,319 @@ +.TH SG_LUNS "8" "January 2020" "sg3_utils\-1.45" SG3_UTILS +.SH NAME +sg_luns \- send SCSI REPORT LUNS command or decode given LUN +.SH SYNOPSIS +.B sg_luns +[\fI\-\-decode\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-linux\fR] +[\fI\-\-lu_cong\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-quiet\fR] [\fI\-\-raw\fR] +[\fI\-\-readonly\fR] [\fI\-\-select=SR\fR] [\fI\-\-verbose\fR] +[\fI\-\-version\fR] \fIDEVICE\fR +.PP +.B sg_luns +\fI\-\-test=ALUN\fR [\fI\-\-decode\fR] [\fI\-\-hex\fR] [\fI\-\-lu_cong\fR] +[\fI\-\-verbose\fR] +.SH DESCRIPTION +.\" Add any additional description here +.PP +In the first form shown in the SYNOPSIS this utility sends the SCSI REPORT +LUNS command to the \fIDEVICE\fR and outputs the response. The response +should be a list of LUNs ("a LUN inventory") for the I_T nexus associated +with the \fIDEVICE\fR. 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. +.PP +When the \fI\-\-test=ALUN\fR option is given (the second form in the +SYNOPSIS), then the \fIALUN\fR value is decoded as outlined in various +SCSI Architecture Model (SAM) standards and recent drafts (e.g. SAM\-6 +revision 2, section 4.7) . +.PP +Where required below the first form shown in the SYNOPSIS is called "device +mode" and the second form is called "test mode". +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +.TP +\fB\-d\fR, \fB\-\-decode\fR +decode LUNs into their component parts, as described in the LUN section +of SAM\-3, SAM\-4 and SAM\-5. +.br +[test mode] \fIALUN\fR is decoded irrespective of whether this option is +given or not. If this option is given once then the given \fIALUN\fR is +output in T10 preferred format (which is 8 pairs of hex digits, each +separated by a space). If given twice then the given \fIALUN\fR 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). +.TP +\fB\-h\fR, \fB\-\-help\fR +output the usage message then exit. +.TP +\fB\-H\fR, \fB\-\-hex\fR +[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 \fI\-\-decode\fR to output +component fields in hex rather than decimal. +.br +[test mode] when this option is given, then decoded component fields of +\fIALUN\fR are output in hex. +.TP +\fB\-l\fR, \fB\-\-linux\fR +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 \fI\-\-hex\fR option is given twice (e.g. \-HH) as well then the +Linux LUN integer is output in hexadecimal. +.TP +\fB\-L\fR, \fB\-\-lu_cong\fR +this option is only considered with \fI\-\-decode\fR. 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 \fI\-\-decode\fR is +given then an INQUIRY is sent to the \fIDEVICE\fR and the setting of +its LU_CONG bit is used to decode the list of LUNs. +.br +[test mode] decode \fIALUN\fR as if the LU_CONG bit is set in its +corresponding standard INQUIRY response. In other words treat \fIALUN\fR +as if it is a conglomerate LUN. If not given (or given twice) then decode +\fIALUN\fR as if the LU_CONG bit is clear. +.TP +\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR +where \fILEN\fR is the (maximum) response length in bytes. It is placed in +the cdb's "allocation length" field. If not given (or \fILEN\fR is zero) +then 8192 is used. The maximum allowed value of \fILEN\fR is 1048576. +.TP +\fB\-q\fR, \fB\-\-quiet\fR +output only the ASCII hex rendering of each report LUN, one per line. +Without the \fI\-\-quiet\fR option, there is header information printed +before the LUN listing. +.TP +\fB\-r\fR, \fB\-\-raw\fR +output the SCSI response (i.e. the data\-out buffer) in binary (to stdout). +.TP +\fB\-R\fR, \fB\-\-readonly\fR +open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag). +The default is to open it read\-write. +.TP +\fB\-s\fR, \fB\-\-select\fR=\fISR\fR +\fISR\fR 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 the \fIDEVICE\fR, the +meanings of the \fISR\fR values defined to date for SPC\-4 are: +.br + \fB0\fR : most luns excluding well known logical unit numbers +.br + \fB1\fR : well known logical unit numbers +.br + \fB2\fR : all luns accessible to this I_T nexus +.br + \fB0x10\fR : only accessible administrative luns +.br + \fB0x11\fR : administrative luns plus non-conglomerate luns (see SPC\-4) +.br + \fB0x12\fR : if \fIDEVICE\fR is an administrative LU, then report its +.br + lun plus its subsidiary luns +.PP +For \fISR\fR values 0x10 and 0x11, the \fIDEVICE\fR 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 \fISR\fR . +.TP +\fB\-t\fR, \fB\-\-test\fR=\fIALUN\fR +\fIALUN\fR 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. +\fI\-\-test=0122003a\fR represents T10 LUN: 01 22 00 3a 00 00 00 00). +\fIALUN\fR may be prefixed by '0x' or '0X' (e.g. the previous example could +have been \fI\-\-test=0x0122003a\fR). \fIALUN\fR 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 \fIALUN\fR would need to be surrounded by single or double quotes. +.br +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 \fI\-\-decode\fR option had been +given. Also when \fIALUN\fR 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. +.br +The action when used with \fI\-\-decode\fR is explained under that option. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +increase the level of verbosity, (i.e. debug output). +.TP +\fB\-V\fR, \fB\-\-version\fR +print the version string and then exit. +.SH NOTES +The SCSI REPORT LUNS command is important for Logical Unit (LU) discovery. +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. +.PP +In test mode, if the \fI\-\-hex\fR 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, target=0x3a). +.SH 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. +.PP + # lsscsi \-g +.br + [6:0:0:1] disk Linux scsi_debug 0004 /dev/sdb /dev/sg1 +.br + [6:0:0:2] disk Linux scsi_debug 0004 /dev/sdc /dev/sg2 +.br + [6:0:0:49409]wlun Linux scsi_debug 0004 \- /dev/sg3 +.PP +We could send a REPORT LUNS command (with \fISR\fR 0x0, 0x1 or 0x2) to any +of those file device nodes and get the same result. Below we use /dev/sg1 : +.PP + # sg_luns /dev/sg1 +.br + Lun list length = 16 which imples 2 lun entry +.br + Report luns [select_report=0x0]: +.br + 0001000000000000 +.br + 0002000000000000 +.PP +That is a bit noisy so cut down the clutter with \fI\-\-quiet\fR: +.PP + # sg_luns \-q /dev/sg1 +.br + 0001000000000000 +.br + 0002000000000000 +.PP +Now decode that LUN into its component parts: +.PP + # sg_luns \-d \-q /dev/sg1 +.br + 0001000000000000 +.br + Peripheral device addressing: lun=1 +.br + 0002000000000000 +.br + Peripheral device addressing: lun=2 +.PP +Now use \fI\-\-select=1\fR to find out if there are any well known +LUNs: +.PP + # sg_luns \-q \-s 1 /dev/sg1 +.br + c101000000000000 +.PP +So how many LUNs do we have all together (associated with the current +I_T Nexus): +.PP + # sg_luns \-q \-s 2 /dev/sg1 +.br + 0001000000000000 +.br + 0002000000000000 +.br + c101000000000000 +.PP + # sg_luns \-q \-s 2 \-d /dev/sg1 +.br + 0001000000000000 +.br + Peripheral device addressing: lun=1 +.br + 0002000000000000 +.br + Peripheral device addressing: lun=1 +.br + c101000000000000 +.br + REPORT LUNS well known logical unit +.PP +The following example uses the \fI\-\-linux\fR 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. +.PP + # sg_luns \-q \-s 2 \-l /dev/sg1 +.br + 0001000000000000 [1] +.br + 0002000000000000 [2] +.br + c101000000000000 [49409] +.PP +Now we use the \fI\-\-test=\fR option to decode LUNS input on the command +line (rather than send a REPORT LUNS command and act on the response): +.PP + # sg_luns \-\-test=0002000000000000 +.br + Decoded LUN: +.br + Peripheral device addressing: lun=2 +.PP + # sg_luns \-\-test="c1 01" +.br + Decoded LUN: +.br + REPORT LUNS well known logical unit +.PP + # sg_luns \-t 0x023a004b \-H +.br + Decoded LUN: +.br + Peripheral device addressing: bus_id=0x02, target=0x3a +.br + >>Second level addressing: +.br + Peripheral device addressing: lun=0x4b +.PP +The next example is Linux specific as we try to find out what the +Linux LUN 49409 translates to in the T10 world: +.PP + # sg_luns \-\-test=L49409 +.br + 64 bit LUN in T10 preferred (hex) format: c1 01 00 00 00 00 00 00 +.br + Decoded LUN: +.br + REPORT LUNS well known logical unit +.PP +And the mapping between T10 and Linux LUN representations can be done the +other way: +.PP + # sg_luns \-t c101L +.br + Linux 'word flipped' integer LUN representation: 49409 +.br + Decoded LUN: +.br + REPORT LUNS well known logical unit +.br +.SH EXIT STATUS +The exit status of sg_luns is 0 when it is successful. Otherwise see +the sg3_utils(8) man page. +.SH AUTHORS +Written by Douglas Gilbert. +.SH "REPORTING BUGS" +Report bugs to <dgilbert at interlog dot com>. +.SH COPYRIGHT +Copyright \(co 2004\-2020 Douglas Gilbert +.br +This software is distributed under a BSD\-2\-Clause license. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH "SEE ALSO" +.B sg_inq(8) |