Subject: RE: iSCSI: All text keys MUST be supported?

From: [email-masked]
Date: Wed, 13 Jun 2001 20:32:03 +0300

1.2.4 reads now:

1.1.1     Text Mode Negotiation

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

   In "list" negotiation, the offering party sends a list of values for a
   key in its order of preference.

   The responding party answers with the first value from the list it
   supports and is allowed to use for the specific initiator.

   The value "none" MUST always be used to indicate a missing function.
   However, none is a valid selection only if it is explicitly offered and
   MAY be selected by omission (i.e., <key>=none MAY be omitted).

   If a target is not supporting, or not allowed to use with a specific
   initiator, any of the offered options, it may use the value "reject".
   The values "none" and "reject" are reserved and must be used only as
   described here.  Any key not understood is answered with
   "NotUnderstood".

   The general format of text negotiation is:

      Offer-> <key>=<value1>,<value2>,...,<valuen>
      Answer-> <key>=<valuex>|reject|NotUnderstood

   In "numerical" negotiations, the offering and responding party state a
   numerical value. The result of the negotiation is key dependent;
   frequently the lower or the higher of the two values is used.

   Although the initiator is the requesting party and controls the
   request-response initiation and termination the target can offer
   key=value pairs of its own as part of a sequence and not only in
   response to an identical key=value pair offered by the initiator.

   And 2.8.3 reads:

1.1.1     Text

   The initiator sends the target a set of key=value or key=list pairs
   encoded in UTF-8 Unicode. The key and value are separated by a '='
   (0x3D) delimiter. Many key=value pairs can be included in the Text block
   by separating them with null (0x00) delimiters.  A list is a set of
   values separated by comma (0x2C). Large binary items can be encoded
   using their hexadecimal representation (e.g., 8190 is 0x1FFE) or decimal
   representation. The maximum length of an individual value (not its
   string representation) is 255 bytes.

   The data length of a text command or response SHOULD be less than 4096
   bytes.  Key names MUST NOT exceed 64 bytes. Key values MUST NOT exceed
   255 characters.

   Character strings are represented as plain text. Numeric and binary
   values are represented using either decimal numbers or the hexadecimal
   0x'ffff' notation. The result is adjusted to the specific key.

   The target responds by sending its response back to the initiator. The
   response text format is similar to the request text format.

   Some basic key=value pairs are described in Appendix A and D. All of
   these keys, except for the X- extension format, MUST be supported by
   iSCSI initiators and targets.

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

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

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

   Text operations are usually meant for parameter setting/negotiations but
   can be used also to perform some active operations.

   It is recommended that Text operations that will take a long time should
   be placed in their own Text command.

   A session may have only one outstanding text command at any given time.

   Julo

"KRUEGER,MARJORIE (HP-Roseville,ex1)" <[email-masked]> on
13-06-2001 20:09:18

Please respond to "KRUEGER,MARJORIE (HP-Roseville,ex1)"
      <[email-masked]>

To:   "'Eddy Quicksall'" <[email-masked]>, Julian
      Satran/Haifa/IBM@IBMIL, [email-masked]
cc:
Subject:  RE: iSCSI: All text keys MUST be supported?

I interpret 2.8.3 to mean "an iSCSI implementation is REQUIRED to recognize
and answer all text keys specified in the iSCSI protocol document.  Some
features negotiated with these text commands are OPTIONAL to implement."

Julian, is that your intention?  Would you make the wording more explicit?

The further text is implicitly refering to 'proprietary' text keys a vendor
may dream up.

Marj

> -----Original Message-----
> From: Eddy Quicksall [mailto:[email-masked]]
> Sent: Tuesday, June 12, 2001 10:20 AM
> To: [email-masked]; [email-masked]
> Subject: iSCSI: All text keys MUST be supported?
>
>
>
> Section "2.8.3 Text" says:
>
>     All of these keys, except for the X- extension format,
>     MUST be supported by iSCSI initiators and targets.
>
> But it further says:
>
>    Any other key not understood by the target may be ignored without
>    affecting basic function. If the Text Response does not
> contain a key
>    that was requested, the initiator must assume that the key was not
>    understood by the target or, whenever appropriate, that
> the response
>    was "none".
>
> These two statements seem contradictory (I don't think the
> 2nd is talking
> about only the X keys). I vote for removing the 1st paragraph above
> and going with the 2nd. That way we would not have to insist
> that every
> key be supported ... the requester would just take the default if the
> receiver did not support the key.
>
> Actually, section "2.9.3 Text Response Data"  says:
>
>    If the Text Response does not contain a key that
>    was requested, the initiator must assume that the key was not
>    understood by the target or that the answer is <key>=none.
>
> This seems to backup the 2nd paragraph above.
>
>
>
> [email-masked]
>

---

From: "Eddy Quicksall" <[email-masked]>
Date: Wed, 13 Jun 2001 19:30:01 -0400

Looks good, but what about 2.9.3? Should that have the following statement
removed? Because you could use that fact to just ignore the key if you don't
understand it. If the statement stands, one would have to wonder what the
original intent was.

    2.9.3 says:

Eddy

---

From: "Matt Wakeley" <[email-masked]>
Date: Mon, 25 Jun 2001 15:00:11 -0700

>    MAY be selected by omission (i.e., <key>=none MAY be omitted).

Why MAY "<key>=none" be selected by omission?  This is just another one of
those "options" that we all hate.  If it's none, explicitely say so.

You also need to remove the "none MUST always be used to indicate a missing
function" because the following paragraph allows the use of "reject" or
"NotUnderstood" to indicate a missing function.

These two paragraphs need cleaning up.

>    bytes.  Key names MUST NOT exceed 64 bytes. Key values MUST NOT exceed

data length should be less than PDUlength.

-Matt

---

From: "Eddy Quicksall" <[email-masked]>
Date: Tue, 26 Jun 2001 16:17:47 -0400

1. When I read "MAY be selected by omission", I read that if one omits
<key>=none, then it means the same thing as <key>=none. And that the other
guy MUST adhere to that rule.

What is your interpretation of the current text?

2. Why should we limit the length to 4095 bytes when 4096 is not a strange
number? Especially when we have to round things to 4 byte multiples anyway
(which means 4095+one wasted byte becomes 4096). It seems we just cheated
ourselves out of 1 byte.

Eddy

---

From: "Matt Wakeley" <[email-masked]>
Date: Wed, 27 Jun 2001 09:31:24 -0700

> What is your interpretation of the current text?

That's the problem - it can be interpreted many different ways.
Just delete the "MAY be selected by omission".  Make everything explicitely
selected.

Ok, so I should have said "less than or equal to PDUlength".
My point is, that if PDUlength is less than 4096, the message length must not
be larger than PDUlength.

-Matt

---

From: "Eddy Quicksall" <[email-masked]>
Date: Thu, 28 Jun 2001 13:43:48 -0400

1. Without something like "MAY be selected by omission", one would think it
can't be omitted. Can you think of alternate text?
2. When I was "complaining" about the "less than 4096" below, I was not
referring to what you said ... I was referring to what the spec says ("The
data length of a text command or response SHOULD be less than 4096 bytes.").
Does anyone know why we can't go to 4096 instead of 4095 as the spec
currently says.

Eddy

----- Original Message -----
From: "Matt Wakeley" <[email-masked]>
To: <[email-masked]>
Sent: Wednesday, June 27, 2001 12:31 PM
Subject: Re: iSCSI: All text keys MUST be supported?

> > > >    In "list" negotiation, the offering party sends a list of values
for
> > a
> > > >    However, none is a valid selection only if it is explicitly
offered
> > and
> > > >    In "numerical" negotiations, the offering and responding party
state
> > a
> > > >    (0x3D) delimiter. Many key=value pairs can be included in the
Text
> > block

---

From: "Rod Harrison" <[email-masked]>
Date: Thu, 28 Jun 2001 21:50:49 +0100

We could make "none" required to be offered, alternatively
remove the restriction that prevents <key>=none if "none"
isn't explicitly offered.

	- Rod

  >  From: [email-masked]
  >  [mailto:[email-masked]]On Behalf Of
  >  Eddy Quicksall
  >  Sent: Thursday, June 28, 2001 6:44 PM
  >  To: Matt Wakeley; [email-masked]
  >  > > <key>=none, then it means the same thing
  >  as <key>=none. And that the
  >  other
  >  > Just delete the "MAY be selected by
  >  omission".  Make everything
  >  explicitely
  >  > selected.
  >  >
  >  > My point is, that if PDUlength is less than
  >  4096, the message length must
  >  not
  >  > > 2. Why should we limit the length to 4095
  >  bytes when 4096 is not a
  >  strange
  >  > > number? Especially when we have to round
  >  things to 4 byte multiples
  >  anyway
  >  > > (which means 4095+one wasted byte becomes
  >  4096). It seems we just
  >  cheated
  >  > > ourselves out of 1 byte.
  >  > >
  >  > > Eddy
  >  > >
  >  > > > >    During login and thereafter some
  >  session or connection parameters
  >  are
  >  > > > >    The responding party answers with
  >  the first value from the list
  >  it
  >  > > > >    The value "none" MUST always be
  >  used to indicate a missing
  >  function.
  >  > > > Why MAY "<key>=none" be selected by
  >  omission?  This is just another
  >  one of
  >  > > > You also need to remove the "none MUST
  >  always be used to indicate a
  >  > > missing
  >  > > > function" because the following
  >  paragraph allows the use of "reject"
  >  or
  >  > > > >    If a target is not supporting, or
  >  not allowed to use with a
  >  specific
  >  > > > >    initiator, any of the offered
  >  options, it may use the value
  >  "reject".
  >  > > > >    The values "none" and "reject" are
  >  reserved and must be used only
  >  as
  >  > > > >    The initiator sends the target a
  >  set of key=value or key=list
  >  pairs
  >  > > > >    encoded in UTF-8 Unicode. The key
  >  and value are separated by a
  >  '='
  >  > > > >    by separating them with null (0x00)
  >  delimiters.  A list is a set
  >  of
  >  > > > >    values separated by comma (0x2C).
  >  Large binary items can be
  >  encoded
  >  > > > >    using their hexadecimal
  >  representation (e.g., 8190 is 0x1FFE) or
  >  > > decimal
  >  > > > >    representation. The maximum length
  >  of an individual value (not
  >  its
  >  > > > >    The data length of a text command
  >  or response SHOULD be less than
  >  > > 4096
  >  > > > >    bytes.  Key names MUST NOT exceed
  >  64 bytes. Key values MUST NOT
  >  > > exceed
  >  > > > >    255 characters.
  >  > > >