Guidelines for Creating New DHCPv6 Options
draft-ietf-dhc-option-guidelines-17

This is a very fine document, and a very good read.  I think it's an important document.  So, while all my comments below are non-blocking, I think most of them are important to clarity, and I ask you to consider them.  Please chat with me about them if you think it'll help.  (It's especially important to get the advice to the ADs clear; we tend to get all verblunget otherwise.)

-- Section 5.2 --

   Sometimes it is useful to convey a single flag that can either take
   on or off values.  Instead of specifying an option with one bit of
   usable data and 7 bits of padding, it is better to define an option
   without any content.  It is the presence or absence of the option
   that conveys the value.  This approach has the additional benefit of
   absent option designating the default, i.e. administrator has to take
   explicit actions to deploy the opposite of the default value.

First, a nit: the "either" is misplaced; it should say "that can take either on or off values."

Now, the substance: The intent of this is to say that the absence of the option represents the default value and the presence of the option represents the other value, but that this does *not* necessarily mean that absence is "off" (or "false") and presence is "on" (or "true").  That is, if it's desired that the default value for a bistable option is "true"/"on", then the presence of that option would turn it off (make it false).

That seems a potentially confusing point that should be made extremely clear, and I think a bit more text here to clarify it would really help.  It's too easy for someone who doesn't read carefully enough to assume that, naturally, the presence of the option always means "on", and the absence, "off".  If you're saying otherwise, I think that glaringly clear text is needed.

-- Section 5.8 --

   A string must not
   enclude any terminator (such as a null byte).

Misspelling: "enclude".  There's one thing I find unclear about this sentence: is it trying to say that certain characters (such as U+0000) are not allowed in strings?  Or is it simply saying that the representation here is of the string itself, and does not include any applicable termination characters?  It would be good to make this clear, either way.

-- Section 8 --

I'd like to see the conversation from Richard's DISCUSS.  I agree that addresses are better than FQDNs for lower-layer, shorter-term information -- perhaps how to contact VPNs, and such, where the address will be used and then discarded, to be re-obtained next time.  But for options that are used to configure app-layer things (SIP or IMAP server addresses, say), where clients will retain the information and use it long-term, FQDNs are much more appropriate.

-- Section 9 --

I see that Brian's DISCUSS might cause a significant change here, but in case some of this remains I want to point this out:  "SHOULD NOT under any circumstances" makes no sense in a 2119 context.  "SHOULD NOT", by definition (see RFC 2119) allows that there might indeed be circumstances when you might choose to do otherwise.

-- Section 13 --

   This is true whether the new fragment type has the same
   structure as an existing fragment type, but has different semantics.
   It is equally true when the new format has a new structure.

This misuses "whether", to the point that I find it confusing.  "Whether" requires alternatives: "This is true whether <case A> or <case B>."  I don't understand what this means to say.  Does it, perhaps, mean this?:

   This is true whether the new fragment type has the same
   structure as an existing fragment type but has different semantics,
   or the new format has a new structure.

(And, are "new fragment type" and "new format" meant to be different?)  Perhaps some re-wording would be better.

   Responsible Area Directors for working groups that wish to add a work
   item to a working group charter to define a new DHCP option should
   get clarity from the working group as to whether the new option is a
   simple DHCP option with no new fragment type or new fragment
   semantics, or whether it in fact will require new fragment types.

This is a long, involved sentence, so let's be sure it's clear.  Do you mean "no new fragment type and no new fragment semantics"?  The "or" seems unclear.  Then the next part, "or whether it in fact will require new fragment types," leaves me to question what the case should be if it might require new semantics -- that case isn't covered.

Maybe this will work better, and will put the focus in the right place?:

NEW
   Responsible Area Directors for working groups that wish to add a work
   item to a working group charter to define a new DHCP option should
   get clarity from the working group as to whether the new option will
   require a new fragment type or new semantics, or whether it is a
   simple DHCP option that fits existing definitions.
END

   If a working group needs a new fragment type, it is preferable to
   seek out a working group whose members already have sufficient
   expertise to evaluate the new work and try to come up with a new
   format that generalizes well and can be reused, rather than a single-
   use fragment type.

I'm again confused, and I think this and the subsequent text could use some factoring out.  You have a few ideas intermixed here:
1a. Try to find another working group with the right expertise.
1b. Failing that, look for DHCP experts to help.
2. The new option should be defined in a separate document.
3. In defining the new option, it's important to look for a generalizable format, not a single-use thing.

How about if we tease these apart and reorganize two paragraphs?  Maybe this?:

NEW
   If a working group needs a new fragment type, it is preferable to
   see if another working group exists whose members already have
   sufficient expertise to evaluate the new work.  If such a working
   group is available, the work should be chartered in that working
   group instead.  If there is no other working group with DHCP
   expertise that can define the new fragment type, the responsible AD
   should seek help from known DHCP experts within the IETF to provide
   advice and frequent early review as the original working group
   defines the new fragment type.

   In either case, the new option should be defined in a separate
   document, and the work should focus on defining a new format that
   generalizes well and can be reused, rather than a single-use
   fragment type.  The working group that needs the new fragment type
   can define their new option referencing the new fragment type
   document, and the work can generally be done in parallel, avoiding
   unnecessary delays.  Having the definition in its own document will
   foster reuse of the new fragment type.
   
   The responsible AD should work with all relevant working group
   chairs and DHCP experts to ensure that the new fragment type
   document has in fact been carefully reviewed by the experts and
   appears satisfactory.
END

-- Section 15 --

Pet peeve alert:

   In general, if a lot of data needs to be configured (i.e. large
   option lengths)

Is "i.e." really what you want here?  Are large option lengths the *only* reason that a lot of data might need to be configured?  Or could there be other reasons (maybe a large number of short options)?

I think you mean this:

NEW
   In general, if a lot of data needs to be configured (for example,
   some option lengths are quite large)
END

Make "an URI" be "a URI" (or the RFC Editor will).  People don't really say, "an oo-ree", do they?  Everyone I know says, "a yoo-are-eye".  And, by the way, strictly speaking, the URI specifies where (not "how") to obtain the actual configuration information.

-- Section 16 --

   Allowing multiple option instances often leads to confusion.
   Consider the following example.

Considered.  But wasn't the failure there not that there could be multiple instances, but that no one had defined what multiple instances *meant*?  Might it be good here to say that you should avoid multiple instances, but that if you do have to use them it's important to clearly document what to do with them?

-- Section 17 --

   Option order, either the order among many DHCPv6 options or the order
   of multiple instances of the same option, SHOULD NOT be significant
   and MUST NOT be assumed.

What does that sequence of 2119 key words mean?  I think my confusion comes from the second one being orphaned in some way here.  What you're saying is this:
1. Option order SHOULD NOT be significant.
2. Option order MUST NOT be assumed.

1 is fine, and it makes sense.  For 2, I don't know what it means; it's missing something.  And even if I guess, I don't know what the combination of SHOULD NOT and MUST NOT is trying to tell me.  Perhaps you can re-word this?

By the way, a related anecdote: the IMAP email protocol has a number of situations in which things are almost always sent in a certain order by all servers, but the protocol definition doesn't require that ordering.  Someone once wrote an IMAP server that spit those things out in arbitrary order, which differed from response to response.  That server uncovered a lot of client bugs.  :-)

Thanks

Brian's point is germain and should be corrected. 5908 is for better or worse a standards track document which the community approved and the IESG reviewed.

As per my email, I am very interested in the result of the DISCUSSion with Richard. I am left wondering whether the document should loosen the language in section 8, or tighten the language elsewhere.

Thanks to the authors for making section 8 much more balanced.

---old comments---

I realize that v4 is old news, but since not everyone has turned off DHCPv4 yet, is there a reason that this document is v6-only?

In section 5.3, it looks odd to see prefix6-Len in the math, where the "-" character would normally be subtraction.

RFC 5986, 5223 could also be references for 5.10.

Support Stephen's point.

Thanks for nicely addressing my discuss points about privacy.

--- old comments below

- 5.7 supports 16 bit URI lengths - maybe you could note
that that's a bit bigger than is likely to be useful

- section 8: that made me wonder if you've any guidance on
whether URIs should include FQDNs or addresses. Just a nit.

- section 8, last para on p15: another nit - there's a case
where an option might be an FQDN that's sent in another
protocol (e.g. HTTP) to a proxy and only then resolved to an
address.

- section 23, 1st para: this should say clearly that the
authentication stuff is hardly used. The 2nd para assume
that but its not explicitly stated and should be.

typo: participates in leasequery protocol

This an excellent document with a utility that transcends
its primary purpose.

One surprising omission from the security section is the
need to clear padding to prevent the inadvertent transmission
as a result of buffer reuse.