Subject: iSCSI: formats for packing long iSCSI names into SCSI alias commands

From: "Jim Hafner" <[email-masked]>
Date: Wed, 16 May 2001 09:43:33 -0700

Folks,

I've been working with T10 on a proposal (T10/00-424r3) to allow iSCSI's
long names to work with some of the limitations of parameter data
structures in some third party commands (most notably EXTENDED COPY).   The
proposal is progressing forward and I'm hoping to get approval in July.
One key aspect of the proposal is that transport protocols (like iSCSI)
must define, in their own documents, what are called the "designation
formats" that apply to that transport. These formats define the way name
and address constructs are embedded in parameter data (in particular in the
CHANGE and REPORT ALIASES commands defined in the proposal). The document
contains an informative clause with my proposal for iSCSI formats.  (It's
informative since T10 can't approve the formats; we have to in this WG as
part of the iSCSI spec.)

I've extracted and reformatted for this list (and to some extent for the
iSCSI documents), the iSCSI-specific clause of that proposal (see
ftp://ftp.t10.org/t10/document.00/00-425r3.pdf for the latest draft of the
complete proposal).    The style is more for T10, use of keywords is
different, etc.

I'm posting it hear for general airing.  Suggestions for editorial, as well
as technical changes are welcome.

Open issues:
1) Does this cover the cases that we want to cover?  Are their other
formats we need with different data?  Are all of these needed?  Do we want
to merge the IPv4 and IPv6 into one format with a flag bit somewhere
indicating which one it is?
2) Is the technical description OK?
3) What iSCSI document and where in that document should this stuff go?  It
is becoming apparent that some document needs a description of the
relationship of iSCSI with SCSI (SAM) (perhaps an annex to the main
document).  It is natural for me that this would go there, but others may
have a different opinion.
4) Other issues in this regard?

Jim Hafner

Clause Y. iSCSI protocol specific alias entry formats

Y.1 iSCSI protocol specific format codes

This clause defines the iSCSI protocol specific alias entry formats and
codes used in the CHANGE ALIASES and REPORT ALIASES commands (see SPC-3) to
designate SCSI devices or ports on an iSCSI service delivery subsystem.
For an iSCSI protocol specific alias entry, the Protocol Identifier shall
be set to 05h (as defined in Table 165 of SPC-2 rev 19) and the Format Code
values are defined in Table Y1.

Table Y1: iSCSI protocol specific Format Code values and Designation formats.

-----------------------------------------------------------------------------
Format  | Designation   | Designation   | Designation content
Coce    | Description   | length        |
        |               | (maximum)     |
-----------------------------------------------------------------------------
00h     | iSCSI Name    | 256 bytes     | Name in UTF-8 format (null
        |               |               | terminated), with pad (see Y.2)
-----------------------------------------------------------------------------
01h     | iSCSI Name    | 268 bytes     | Name in UTF-8 format (null
        | with binary   |               | terminated), binary IPv4 address,
        | IPv4 address  |               | binary TCP port, binary Internet
        |               |               | Protocol Number, with pad (see Y.3)
-----------------------------------------------------------------------------
02h     | iSCSI Name    | 520 bytes     | Name in UTF-8 format (null
        | with ASCII    |               | terminated),  IPname (null
        | IPName        |               | terminated), binary TCP port,
        |               |               | binary Internet Protocol Number,
        |               |               | with pad (see Y.4)
------------------------------------------------------------------------------
03h     | iSCSI Name    | 280 bytes     | Name in UTF-8 format (null
        | with binary   |               | terminated), binary IPv6 address,
        | IPv6 address  |               | binary TCP port, binary Internet
        |               |               | Protocol Number, with pad (see Y.5)
-----------------------------------------------------------------------------
04h-FFh | reserved      | n/a           | n/a
-----------------------------------------------------------------------------

NOTE: a designation that contains no IP addressing information or contains
IP addressing information that does not address the named SCSI device may
require a device server to have access to a name server or to other
discovery protocols to resolve the given iSCSI Name to an IP address
through which the device server may establish iSCSI Login. Access to such a
service is protocol and implementation specific.

Y.2 iSCSI Name designation format

Table Y2 describes the iSCSI Name designation format.

     Table Y2. iSCSI Name designation format.

     Byte /    0       |       1       |       2       |       3       |
        /              |               |               |               |
       |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|
       +---------------+---------------+---------------+---------------+
      0/ iSCSI Name                                                    |
      +/               +---------------+-------------------------------+
      +/               | NULL(0h)      | Pad (if needed) (0h)          |
       +---------------+---------------+---------------+---------------+

The iSCSI Name field shall contain the iSCSI Name of an iSCSI Node. Refer
to RFC XXXX for a description of iSCSI Names.

A Null (0h) byte shall terminate the iSCSI Name.

Zero to three bytes set to zero shall be appended in the Pad field so that
the total length of the designation is a multiple of 4.

An iSCSI Name designation is valid if the device server has access to a
SCSI domain containing an IP network and there exists an iSCSI Node on that
network with the specified iSCSI Name.

[AUTHOR'S NOTE: the above paragraph there to define the rules under which a
designation is "valid" or "invalid".  This terminology is used in the T10
proposal (00-425r3) in contexts where the designation is used.  Similar
paragraphs will be found in the other subsections.]

Y.3 iSCSI Name with binary IPv4 address designation format

Table Y3 describes the iSCSI Name with binary IPv4 address designation
format.

     Table Y3. iSCSI Name with binary IPv4 address designation format.

     Byte /    0       |       1       |       2       |       3       |
        /              |               |               |               |
       |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|
       +---------------+---------------+---------------+---------------+
      0/ iSCSI Name                                                    |
      +/               +---------------+-------------------------------+
      +/               | NULL(0h)      | Pad (if needed) (0h)          |
       +---------------+---------------+---------------+---------------+
     4k| IPv4 Address                                                  |
       +---------------+---------------+---------------+---------------+
   4k+4| Reserved (0h)                 | Port Number                   |
       +---------------+---------------+---------------+---------------+
   4k+8| Reserved (0h)                 | Internet Protocol Number      |
       +---------------+---------------+---------------+---------------+

The iSCSI Name field shall contain the iSCSI Name of an iSCSI Node. Refer
to RFC XXXX for a description of iSCSI Names.

A Null (0h) byte shall terminate the iSCSI Name.

Zero to three bytes set to zero shall be inserted in the Pad field so that
the total length of the designation is a multiple of 4.

The IPv4 Address field shall contain an IPv4 address. Refer to RFC 791 for
a description of IPv4 addresses.

The Port Number field shall contain a port number. Refer to RFC 790 for a
description of port numbers.

The Internet Protocol Number field shall contain an Internet protocol
number. Refer to RFC 790 for a description of Internet protocol numbers.

An iSCSI Name with binary IPv4 address designation is valid if the device
server has access to a SCSI domain containing an IP network and there
exists an iSCSI Node on that network with the specified iSCSI Name. The
IPv4 address, port number and internet protocol number provided in the
designation may be used by a device server for addressing to discover and
establish communication with the named iSCSI Node. Alternatively, the
device server may use other protocol specific or vendor specific methods to
discover and establish communication with the named iSCSI Node.

Y.4 iSCSI Name with IPname designation format

Table Y4 describes the iSCSI Name with IPname designation format.

     Table Y4. iSCSI Name with IPname designation format.

     Byte /    0       |       1       |       2       |       3       |
        /              |               |               |               |
       |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|
       +---------------+---------------+---------------+---------------+
      0/ iSCSI Name                                                    |
      +/                               +-------------------------------+
      +/                               | NULL1(0h)     | IPName        |
       +---------------+---------------+---------------+               +
       /                                                               |
      +/               +---------------+-------------------------------+
      +/               | NULL2(0h)     | Pad (if needed) (0h)          |
       +---------------+---------------+---------------+---------------+
     4k| Reserved (0h)                 | Port Number                   |
       +---------------+---------------+---------------+---------------+
   4k+4| Reserved (0h)                 | Internet Protocol Number      |
       +---------------+---------------+---------------+---------------+

The iSCSI Name field shall contain the iSCSI Name of an iSCSI Node. Refer
to RFC XXXX for a description of iSCSI Names.

A Null1 (0h) byte shall terminate the iSCSI Name.

The IPName field shall contain a Internet protocol domain name. Refer to
RFC 1035 for a description of domain names.

A Null2 (0h) byte shall terminate the Internet protocol domain name.

Zero to three bytes set to zero shall be inserted in the Pad field so that
the total length of the designation is a multiple of 4.

An iSCSI Name with IPname designation is valid if the device server has
access to a SCSI domain containing an IP network and there exists an iSCSI
Node on that network with the specified iSCSI Name. The domain name, port
number and internet protocol number provided in the designation may be used
by a device server for addressing to discover and establish communication
with the named iSCSI Node. Alternatively, the device server may use other
protocol specific or vendor specific methods to discover and establish
communication with the named iSCSI Node.

Y.5 iSCSI Name with binary IPv6 address designation format

Table Y5 describes the iSCSI Name with binary IPv6 address designation format.

     Table Y5. iSCSI Name with binary IPv6 adddress designation format.

     Byte /    0       |       1       |       2       |       3       |
        /              |               |               |               |
       |7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|7 6 5 4 3 2 1 0|
       +---------------+---------------+---------------+---------------+
      0/ iSCSI Name                                                    |
      +/               +---------------+-------------------------------+
      +/               | NULL(0h)      | Pad (if needed) (0h)          |
       +---------------+---------------+---------------+---------------+
     4k/ IPv6 Address                                                  |
      +/                                                               |
       +---------------+---------------+---------------+---------------+
  4k+16| Reserved (0h)                 | Port Number                   |
       +---------------+---------------+---------------+---------------+
  4k+20| Reserved (0h)                 | Internet Protocol Number      |
       +---------------+---------------+---------------+---------------+

The iSCSI Name field shall contain the iSCSI Name of an iSCSI Node. Refer
to RFC XXXX for a description of iSCSI Names.

A Null (0h) byte shall terminate the iSCSI Name.

Zero to three bytes set to zero shall be inserted in the Pad field so that
the total length of the designation is a multiple of 4.

The IPv6 Address field shall contain an IPv6 address. Refer to RFC 2373 for
a description of the IPv6 address.

The Port Number field shall contain a port number. Refer to RFC 790 for a
description of port numbers.

The Internet Protocol Number field shall contain an Internet protocol
number. Refer to RFC 790 for a description of Internet protocol numbers.

An iSCSI Name with binary IPv6 address designation is valid if the device
server has access to a SCSI domain containing an IP network and there
exists an iSCSI Node on that network with the specified iSCSI Name. The
IPv6 address, port number and internet protocol number provided in the
designation may be used by a device server for addressing to discover and
establish communication with the named iSCSI Node. Alternatively, the
device server may use other protocol specific or vendor specific methods to
discover and establish communication with the named iSCSI Node.