RE: iSCSI 4.1 & 4.2

[Black_David@emc.com]

Some comments/suggestions tagged by DLB> below.

Thanks,
--David

-----Original Message-----
From: Julian Satran [mailto:Julian_Satran@il.ibm.com]
Sent: Saturday, April 27, 2002 12:39 PM
To: ips@ece.cmu.edu
Subject: iSCSI 4.1 & 4.2

Here are the rephrased 4.1 & 4.2 for better context: 

Text Format 
The initiator and target send a set of key=value pairs encoded in UTF-8
Unicode. All the text keys and text values specified in this docu-ment are
to be presented and interpreted in the case they appear in this document.
They are case sensitive. 

The following character symbols are used in this document for text items: 

(a-z, A-Z) - letters 
(0-9) - digits 
" " (0x20) - space 
"." (0x2e) - point 
"-" (0x2d) - minus 
"+" (0x2b) - plus 
"@" (0x40) - commercial at 
"_" (0x5f) - underscore 
"=" (0x3d) - equal 
":" (0x3a) - colon 
"/" (0x2f) - solidus or slash 
"[" (0x5b) - left bracket 
"]" (0x5d) - right bracket 
null(0x00) - null separator 
"," (0x2c) - comma 
"~" (0x7e) - tilde

DLB> It would be good to say at this point that at least space, colon,
DLB> comma, tilde, and null are reserved characters that cannot appear
DLB> in key names or values.  It's also worth saying that any character
DLB> not in the above list is reserved for future use and MUST NOT be used. 

A key is key-name followed by "=". The term key is used frequently in this
document with the meaning of key-name.

DLB> Really?  Including the "=" in the definition of key is
counter-intuitive,
DLB> and the second sentence is an invitation to serious confusion.
DLB> It would be better to introduce this as the separator in a definition
DLB> of key-value-expression or key-value-pair.

A value is whatever follows the = that follows the key-name up to a null
separator - that separates one key value from the next 

The following definitions will be used in the rest of this document: 

key-name: a string defined by the regular expression 
"[A-Z][a-zA-Z0-9.-+@_]*" 

DLB> Need to explain the regular expression syntax.  Also the last
DLB> occurrence of minus needs a \ prefix to indicate that it's character
DLB> rather than a regular expression syntax element.

DLB> Starting here, I'd add a sentence to explain each regular expression.
DLB> For example, "A key-name is a string consisting of letters, numbers,
DLB> and/or the characters .-+@_  ; it MUST begin with a capital letter.

text-value: a string defined by the regular expression 
"[][a-zA-Z0-9.-+@_/\[\]=]*"

DLB> This appears to allow equal to occur in a text-value.  I'd
DLB> recommend against that, as it has obvious potential for confusion.
DLB> It has the same issue with minus as the previous expression.

boolean-value: a string defined by the regular expression 
"Yes|No"

DLB> What about "yes" and "no", "YES" and "NO"?  Weirder things like
DLB> "yEs and "nO" don't seem useful, though.

hex-constant: unsigned hexadecimal constant described by regu-lar expression
"0[xX][0-9a-zA-Z]+"

DLB> That should be "[0-9a-fA-F]" with a note that the letters are case-
DLB> insensitive, and a through f (A through F) represent the decimal
DLB> values 10 through 16 as hex digits.

base-64-constant: unsigned base-64 constant described by regu-lar expression
"0b[A-Za-z0-9+/=]+"

DLB> Occurrence of "=" in the constants is a potential problem, similar to
DLB> allowing it in the text values.  Also, similar to hex, describe what
DLB> the characters other than digits denote, and in addition
DLB> how possible letter "O" vs. number "0" and letter "l" vs. number "1"
DLB> confusion is avoided.

regular-numerical-value :  an unsigned integer less than 2**64 encoded as a
decimal constant, hex constant, or base-64 con-stant 

large-numerical-value :  an unsigned integer larger than 2**64-1 encoded as
a hex constant, or base-64 constant

DLB> Add an explicit statement that decimal representation MUST NOT be used
DLB> for numbers >= 2^64.  I realize that any mathematician or logician
DLB> can figure this out, but we're dealing with implementers who can use
DLB> all the help they can get ...

numerical-value: a regular-numerical-value or a large numeri-cal-value 

numeric-range: two numerical-values separated by a tilde 

simple-value: text-value, boolean-value, numeric-value or a numeric range. 

list-of-values: a sequence of text-values separated by comma 


Key names MUST NOT exceed 63 bytes.  If not otherwise specified, the maximum
length of a simple-value (not its encoded representation) is 255 bytes not
including the delimiter (comma or null). 

Any iSCSI target or initiator MUST support receiving at least 16384 bytes of
key=value data in a negotiation sequence except when indicat-ing support for
very long authentication items such as public key cer-tificates in which
case they MUST support receiving at least 64 kilobytes of key=value data.

DLB> Say how that "support for very long authentication items" is indicated.


Text Mode Negotiation 
During login, and thereafter, some session or connection parameters are
negotiated through an exchange of textual information. 

The initiator starts the negotiation through a Text/Login request and
indicates when it is ready for completion (by setting to 1 and keeping to 1
the F bit in a Text Request or the T bit in the Login Request). 

The general format of text negotiation is: 

Originator-> <key>=<valuex> 
Responder-> <key>=<valuey>|NotUnderstood|Irrelevant|Reject

The originator can either be the initiator or the target and the responder
can either be the target or initiator, respectively. Target requests are not
limited to respond to key=value pairs as offered by the initiator. The
target may offer key=value pairs of its own. 

All negotiations are stateless and explicit (i.e., the result MUST be based
only on newly exchanged values). There is no such thing as implicit offers.
If an explicit offer is not made then a reply cannot be expected.

DLB> Delete "stateless and", as there is state retained (e.g., is the
response
DLB> the same as what was offered).  Is this the place to put in the
requirement
DLB> that any value that has a significant affect on the correct operation
or
DLB> performance of an implementation MUST be negotiated?  In other words, a
DLB> default value MUST NOT be relied upon when use of some other value by
the
DLB> other party has serious consequences - implementers are free to decide
DLB> which consequences are serious, but we need this requirement to prevent
DLB> "It's not my fault, that other implementation didn't use the default"
DLB> interoperability/finger-pointing problems.

The value offered can be an numerical-value, a numerical-range defined by
lower and upper value - both integers separated by tilde, a text-value, a
boolean-value (Yes or No), or a list of comma sepa-rated text-values. A
range MAY ONLY be offered if it is explicitly allowed for a key. A selected
value can be an numerical-value, a text-value or a boolean-value. 

In list negotiation, the originator sends a list of values (which may
include "None") for each key in its order of preference.

The responding party answers with the first value that it supports and is
allowed to use for the specific originator selected from the orig-inator
list.

DLB> "first" is a potential problem.  If this was intended, it needs to
DLB> come with a warning that when larger numeric values are preferred,
DLB> numeric lists need to be listed in descending order rather than
DLB> ascending order ... but this convention does not apply to ranges,
DLB> which is peculiar.  I'm not sure about this priority order convention.

The constant "None" MUST always be used to indicate a missing func-tion.
However, None is a valid selection only if it is explicitly offered. 

If a responder does not understand any particular value in a list it MUST
ignore it. If a responder does not support, does not understand or is not
allowed to use all of the offered options with a specific originator, it MAY
use the constant "Reject".  The selection of a value not admissible under
the selection rules is considered a negoti-ation failure and is handled
accordingly.

DLB> That "MAY" is a problem.  It should be a MUST, possibly with some
DLB> rephrasing.  If the "MAY" remains, a sentence explaining the
alternative(s)
DLB> needs to be added.

For simple-value negotiations, the responding party MUST respond with the
required key. The value it selects, based on the selection rule specific to
the key, becomes the negotiation result. For a numerical range the value
selected must be an integer within the offered range or "Reject" (if the
range is unacceptable).  An offer of a value not admissible MAY be answered
with the constant "Reject". The selection of a value not admissible under
the selection rules is considered a negotiation failure and is handled
accordingly.

DLB> Use upper case MUST in "value selected must", Also the MAY for "Reject"
DLB> has the same problem as the previous MAY compounded by the need for
DLB> an explanation of "value not admissible".

For boolean negotiations (keys taking the values Yes or No), the responding
party MUST respond with the required key and the result of the negotiation
when the received value does not determine that result by itself. The last
value transmitted becomes the negotiation result. The rules for selecting
the value with which to respond are expressed as Boolean functions of the
value received and the value that the responding party would select in the
absence of knowledge of the received value. 
  
Specifically, the two cases in which responses are OPTIONAL are: 

- The boolean function is "AND" and the value "No" is received. The outcome
of the negotiation is "No". 
- The boolean function is "OR" and the value "Yes" is received. The outcome
of the negotiation is "Yes".

DLB> On further reflection, this seems a bit on the clever side and a minor
DLB> optimization.  Does anyone else care?  The alternative would be to
DLB> always require explicit responses (even when there is only one
DLB> acceptable response) at the possible cost of an extra negotiation
DLB> round trip.

Responses are REQUIRED in all other cases, and the value chosen and sent by
the responder becomes the outcome of the negotiation. 

An offer of a value not admissible MAY be answered with the constant
"Reject". The selection of a value not admissible under the selection rules
is considered a negotiation failure and is handled accordingly.

DLB> Need to define "offer of a value not admissible".

If a specific key is not relevant for the current negotiation, the responder
may answer with the constant "Irrelevant" for all types of negotiation.
However the negotiation is not considered as failed if the response is
Irrelevant.

DLB> But, but ... if the Initiator considers the key important, the
negotiation
DLB> may fail.  Implementers should (lower case) be cautious and
conservative
DLB> in using "Irrelevant", as humoring the other party to the negotiation
DLB> when it behaves in a somewhat clue-impaired fashion improves inter-
DLB> operability. 

Any other key not understood by the responder may be ignored by the
responder without affecting the basic function. However, the Text Response
for a key not understood MUST be key=NotUnderstood. 

The constants "None", "Reject", "Irrelevant", and "NotUnderstood" are
reserved and must only be used as described here.

DLB> Do we want to reserve any other strings for future use?

Some basic key=value pairs are described in Chapter 11. All keys in Chapter
11, except for the X- extension format, MUST be supported by iSCSI
initiators and targets and MUST NOT be answered with NotUnder-stood. 

Manufacturers may introduce new keys by prefixing them with X- fol-lowed by
their (reversed) domain name. For example the company owning the domain
acme.com can issue: 

X-com.acme.bar.foo.do_something=3

DLB> Change "Manufacturers" to "Implementers" and "company" to "entity" for
DLB> generality.