Subject: iSCSI Change - Login phase

From: "Julian Satran" <[email-masked]>
Date: Wed, 5 Sep 2001 14:31:41 +0300

After investigating possible simplifications in the Login request/response
Matthew Burbridge and I  found that as we the new Login is assumed to be
composed exclusively out of Login requests/responses we might want to reuse
the status detail field for the T & C bits and the CNxSG fields and save
the flag field for future changes.

The Login request/response text attached. No other parts are affected.

Comments?

Julo
-----------------------------------
1.1  Login Request

   After establishing a TCP connection between an initiator and a target,
   the initiator MUST start a Login phase to gain further access to the
   target's resources.

   The Login Phase (see chapter 4) consists of a sequence of Login requests
   and responses) that carry the same Initiator Task Tag.

   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|X|I| 0x03      | Reserved      | Version-max   | Version-min   |
     +---------------+---------------+---------------+---------------+
    4| Reserved      | DataSegmentLength                             |
     +---------------+---------------+---------------+---------------+
    8| CID                           | Reserved                      |
     +---------------+---------------+---------------+---------------+
   12| ISID                          |TSID                           |
     +---------------+---------------+---------------+---------------+
   16| Initiator Task Tag                                            |
     +---------------+---------------+---------------+---------------+
   20| Reserved                                                      |
     +---------------+---------------+---------------+---------------+
   24| CmdSN                                                         |
     +---------------+---------------+---------------+---------------+
   28| ExpStatSN   or   Reserved                                     |
     +---------------+---------------+---------------+---------------+
   32| Reserved                                                      |
     +---------------+---------------+---------------+---------------+
   36| Reserved      |T|C|0 0| CNxSG | Reserved                      |
     +---------------+---------------+---------------+---------------+
   40/                                                               /
    +/                                                               /
     +---------------+---------------+---------------+---------------+
   48/ DataSegment - Login Parameters in Text Command Format         /
    +/                                                               /
     +---------------+---------------+---------------+---------------+

1.1.1     X - Restart Connection

   If this bit is set to 1 then this command is an attempt to reinstate a
   failed connection or a failed session.

   If TSID is not 0 then this is a connection restart. CID does not change
   and this command performs first the logout function of the old
   connection if an explicit logout was not performed earlier. In sessions
   with a single connection, this may imply the opening of a second
   connection with the sole purpose of cleaning-up the first. Targets
   should support opening a second connection even when not supporting
   multiple connections in full feature phase.  A restart login indicates
   to the target that commands may be missing and therefore it MUST be
   issued as an immediate command.

   If TSID is 0 then the X bit MUST be 0.

   The X bit MAY be set one ONLY on the first request of the Login phase.

1.1.2     I - Immediate

   Login SHOULD be issued as an immediate request (I=1) except for the
   leading login phase in which all requests that MUST have I=0.

1.1.3     Version-max

   Maximum Version number supported.

   All Login requests within the Login phase MUST carry the same
   Version-max.

   The target MUST use the value presented with the login request with C=0
   and MAY check the value when C=1.

1.1.4     Version-min

   Minimum Version supported
   The version number of the current draft is 0x2.

   All Login requests within the Login phase MUST carry the same
   Version-min.

   The target MUST use the value presented with the login request with C=0
   and MAY check the value when C=1.

1.1.5     Connection ID - CID

   This is a unique ID for this connection within the session.

   All Login requests within the Login phase MUST carry the same CID.

   The target MUST use the value presented with the login request with C=0
   and MAY check the value when C=1.

1.1.6     ISID

   This is an initiator-defined session-identifier.  It MUST be the same
   for all connections within a session.  A SCSI initiator port is uniquely
   identified by the value pair (InitiatorName, ISID).

   When a target detects an attempt to open a new session by the same SCSI
   initiator port (same InitiatorName and ISID) to the same target portal
   group it MUST close the old session and a establish a new session.

   All Login requests within the Login phase MUST carry the same ISID.

   The target MUST use the value presented with the login request with C=0
   and MAY check the value when C=1.

1.1.7     TSID

   The TSID is a tag (set by the target) that together with the
   ISID identifies a unique session with the initiator.  On a Login request
   a TSID value of 0 indicates a request to open a new session.
   A non zero TSID indicates a request to add a connection to an existing
   session.

1.1.8     CmdSN

   CmdSN is either the initial command sequence number of a session (for
   the first Login of a session - the "leading" login) or the command
   sequence number in the command stream (e.g., if the leading login
   carries the CmdSN 123 the next non-immediate command carries the number
   124 etc.).

1.1.9     ExpStatSN

   This is ExpStatSN for the old connection.

   This field is valid only if the Login request restarts a connection
   (i.e., X bit is 1 and TSID is not zero).

1.1.10    T (Transit) Bit

   If set to 1 indicates that the initiator is ready to transit to next
   stage

   If the next stage part in CNxSG is FullFeaturePhase and the T bit is set
   to 1 then this is also indicating that the initiator is ready for the
   Final Login Response (see chapter 4).

1.1.11    C (Continuation) Bit

   If set to 1 indicates that this is not the first Login request in the
   Login Phase

1.1.12    CNxSG

   Through this field, called Current-Next Stage (CNxSG), the Login
   negotiation commands and responses are associated with a specific stage
   in the session (SecurityNegotiation, LoginOperationalNegotiation,
   FullPhaseOperationalNegotiations) and may indicate the next stage they
   want to move to (see chapter 4).

   The current stage is coded in bits 0-1 and the next stage in bits 2-3.
   The next stage value is valid only when the T bit is 1 and can be
   ignored otherwise.

   The stage codes are:

      - 0 - SecurityNegotiation
      - 1 - LoginOperationalNegotiation
      - 3 - FullFeaturePhase

1.1.13    Login Parameters

   The initiator MAY provide some basic parameters in order to enable the
   target to determine if the initiator may use the target's resources and
   the initial text parameters for the security exchange.  The format of
   the parameters is as specified for the Text Command.    Keys and their
   explanations are listed in the Appendixes.

1.2  Login Response

   The Login Response indicates the progress and/or end of the login phase.
   Note that after security is established, the login response is
   authenticated.

   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|1|1| 0x23      | Reserved      | Version-max   | Version-active|
     +---------------+---------------+---------------+---------------+
    4| Reserved      | DataSegmentLength                             |
     +---------------+---------------+---------------+---------------+
    8| Reserved                                                      |
     +---------------+---------------+---------------+---------------+
   12| ISID                          |TSID                           |
     +---------------+---------------+---------------+---------------+
   16| Initiator Task Tag                                            |
     +---------------+---------------+---------------+---------------+
   20| Reserved                                                      |
     +---------------+---------------+---------------+---------------+
   24| StatSN                                                        |
     +---------------+---------------+---------------+---------------+
   28| ExpCmdSN                                                      |
     +---------------+---------------+---------------+---------------+
   32| MaxCmdSN                                                      |
     +---------------+---------------+---------------+---------------+
   36| Status-Class  | Status-Detail | Reserved                      |
     |               |     or        |                               |
     |               |T|0 0 0| CNxSG |                               |
     +---------------+---------------+---------------+---------------+
   40/ Reserved                                                      /
    +/                                                               /
     +---------------+---------------+---------------+---------------+
   48| Digests if any...                                             |
     +---------------+---------------+---------------+---------------+
     / DataSegment - Login Parameters in Text Command Format         /
    +/                                                               /
     +---------------+---------------+---------------+---------------+

1.2.1     Version-max

   This is the highest version number supported by the target.

   All Login responses within the Login phase MUST carry the same
   Version-max.

   The initiator MUST use the value presented as response to the login
   request with C=0 and MAY check the value otherwise.

1.2.2     Version-active

   Indicates the version supported (the highest version supported by the
   target and initiator). If the target does not support a version within
   the range specified by the initiator, the target rejects the login and
   this field indicates the lowest version supported by the target.

   All Login responses within the Login phase MUST carry the same
   Version-active.

   The initiator MUST use the value presented as response to the login
   request with C=0 and MAY check the value otherwise.

1.2.3     TSID

   The TSID is a tag set by the target that together with the
   ISID identifies a unique session with the initiator.  It MUST be valid
   only in the final response.

1.2.4     StatSN

   For the first Login Response (the response to a Login Request with C=0)
   this is the starting status Sequence Number for the connection (the next
   response of any kind will carry this number + 1). This field is valid
   only if the Status Class is 0.

1.2.5     Status-Class and Status-Detail

   The Status returned in a Login Response indicates the execution status
   of the login phase. The status includes:

      Status-Class
      Status-Detail

   A 0 Status-Class indicates success. In this case, the status detail
   field is replaced by the T and CNxSG fields.

   A non-zero Status-Class indicates exception. In this case, Status-Class
   is sufficient for a simple initiator to use when handling errors,
   without having to look at the Status-Detail.  The Status-Detail allows
   finer-grained error recovery for more sophisticated initiators, as well
   as better information for error logging.

   The status classes are as follows:

      0 - Success - indicates that the iSCSI target successfully received,
      understood, and accepted the request. The numbering fields (StatSN,
      ExpCmdSN, MaxCmdSN are valid only if Status-Class is 0) and the
      Status-Detail is replaced by the T and CNxSG fields.

      1 - Redirection - indicates that further action must be taken by the
      initiator to complete the request. This is usually due to the target
      moving to a different address. All of the redirection status class
      responses MUST return one or more text key parameters of the type
      "TargetAddress", which indicates the target's new address.

      2 - Initiator Error - indicates that the initiator likely caused the
      error. This MAY be due to a request for a resource for which the
      initiator does not have permission.  The request should not be tried
      again.

      3 - Target Error - indicates that the target sees no errors in the
      initiator's login request, but is currently incapable of fulfilling
      the request.  The client may re-try the same login request later.

   The table below shows all of the currently allocated status codes.  The
   codes are in hexadecimal; the first byte is the status class and the
   second byte is the status detail.  The allowable state of the Transit
   (T) bit in responses with each of the codes is also displayed.

   -----------------------------------------------------------------
   Status        | Code | Description
                 |(hex) |
   -----------------------------------------------------------------
   Success       | 00xx | Login is proceeding OK (*1)
   -----------------------------------------------------------------
   Target Moved  | 0101 | The requested ITN has moved
   Temporarily   |      | temporarily to the address provided.
   -----------------------------------------------------------------
   Target Moved  | 0102 | The requested ITN has moved
   Permanently   |      | permanently to the address provided.
   -----------------------------------------------------------------
   Initiator     | 0200 | Miscellaneous iSCSI initiator
   Error         |      | errors
   ----------------------------------------------------------------
   Authentication| 0201 | The initiator could not be
   Failure       |      | successfully authenticated.
   -----------------------------------------------------------------
   Authorization | 0202 | The initiator is not allowed access
   Failure       |      | to the given target.
   -----------------------------------------------------------------
   Not Found     | 0203 | The requested ITN does not
                 |      | exist at this address.
   -----------------------------------------------------------------
   Target Removed| 0204 | The requested ITN has been removed
                 |      | No forwarding address is provided.
   -----------------------------------------------------------------
   Unsupported   | 0205 | The requested iSCSI version range is
   Version       |      | not supported by the target.
   -----------------------------------------------------------------
   Initiator     | 0206 | Invalid SID - no more connections
   SID error     |      | accepted
   -----------------------------------------------------------------
   Missing       | 0207 | Missing parameters (e.g., iSCSI
   parameter     |      | Initiator and/or Target Name)
   -----------------------------------------------------------------
   Can't include | 0208 | Target does not support session
   in session    |      | spanning to this connection (address)
   -----------------------------------------------------------------
   Session type  | 0209 | Target does not support this type of
   Not supported |      | of session (not from this Initiator)
   -----------------------------------------------------------------
   Target Error  | 0300 | Target hardware or software error.
   -----------------------------------------------------------------
   Service       | 0301 | The iSCSI service or target is not
   Unavailable   |      | currently operational.
   -----------------------------------------------------------------
   Out of        | 0302 | The target has insufficient session,
   Resources     |      | connection, or other resources.
   -----------------------------------------------------------------

   (*1)If the response T bit is 1 and the next stage part is
   FullFeaturePhase in both the request and the response) the login phase
   is finished and the initiator may proceed to issue SCSI commands.

   If the Status Class is not 0, the initiator and target MUST close the
   TCP connection.

   If the target wishes to reject the login request for more than one
   reason, it should return the primary reason for the rejection.

1.2.6     T (Transit) bit

   T bit is set to 1 as an indicator of end of stage. If the next stage
   part in CNxSG is FullFeaturePhase and the T bit is set to 1 then this is
   also the Final Login Response (see chapter 4). A T bit of 0 indicates a
   "partial" response, which means "more negotiation needed".

   A login response with a T bit set to 1 MUST NOT contain key=value pairs
   that may require additional answers from the initiator within the same
   stage.

---

From: Mark Bakke <[email-masked]>
Date: Wed, 05 Sep 2001 10:02:45 -0500

Julian and Matthew-

This is looking good; I have just a few comments:

>    leading login phase in which all requests that MUST have I=0.

Did you mean "leading connection"?  If so, the only thing that is
special about the leading connection is that it needs to communicate
the initial CmdSN value; there is no reason to use I=0 for the
login requests themselves.

To make this interoperate easier, I would like to get rid of
the SHOULD.  How about:

   Login MUST be issued as an immediate request (I=1) except for the
   leading login request of the leading connection in a session, which
   MUST have I=0 and a valid CmdSN.

I think that this would be simpler, and still get what we need,
which is to communicate a CmdSN to start with when we hit full
feature phase.

>    carries the CmdSN 123 the next non-immediate command carries the number

If we make the above change regarding the Immediate bit, this changes to:

   CmdSN is the initial command sequence number of a session, and is
   valid on the first login request of the leading connection in a
   session.  This determines the CmdSN used in the next non-immediate
   command in the session (e.g., if the leading login request carries
   the CmdSN 123 the next non-immediate command carries the number
   124 etc.).

-- 
Mark A. Bakke
Cisco Systems
[email-masked]
763.398.1054

---

From: "Ayman Ghanem" <[email-masked]>
Date: Wed, 5 Sep 2001 11:49:15 -0500

Since all login requests are immediate, the first non-immediate command is
actually the first command in full feature phase. I would suggest changing
the reference to "the next non-immediate command" to be "the first command
in full feature phase". Section 1.1.8 would read:

    CmdSN is the initial command sequence number of a session, and is
    valid on the first login request of the leading connection in a
    session.  This determines the CmdSN used in the first command after
    full feature phase on the session (e.g., if the leading login request
carries
    the CmdSN 123 the first command in full feature phase carries the number
    124 etc.).

-Ayman

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]]On Behalf Of
> Mark Bakke
> Sent: Wednesday, September 05, 2001 10:03 AM
> To: Julian Satran
> Cc: [email-masked]
> Subject: Re: iSCSI Change - Login phase
>
>
>
> Julian and Matthew-
>