SORT BY:

LIST ORDER
THREAD
AUTHOR
SUBJECT


SEARCH

IPS HOME


    [Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

    RE: iSCSI 4.1 & 4.2



    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.
    


Home

Last updated: Wed May 01 14:18:24 2002
9919 messages in chronological order