With-defaults Capability for NETCONF
draft-ietf-netconf-with-defaults-14

[Ballot comment]
Building on Alexey's discuss - as written, this document requires any
client that cares about how defaults are handled to implement all three
(four?) modes. It would help to explicitly call that out in the text.

[Ballot discuss]
2) The phrasing of 2.1.2, 2.2.2, and 2.3.2 is ambiguous. During a conversation
with Dan, I was convinced that the intent was to make them subordinate to
the requirement at the top of section 2 that a server must pick one of the
three basic modes, and that 2.1.2 should be read as

"If the server supports the 'report-all' mode for handling default data,
and the client has requested it by specifying 'report-all' when using
, then the server MUST behave as specified in section 3.1"

and not as

"The server MUST support the 'report-all' mode.

If that's correct, please adjust the text to make it less likely that
someone will misinterpret the requirement. (I thought 2.1.2 and the
third bullet of 4.1 were in conflict before the conversation with
Dan mentioned above).

3) Section 4.3 as written is updating the base NETCONF spec. Was the intent is
to add a requirement to the base protocol, affecting conformance of existing
implementations, or only to promote adoption of this extension? If the former,
the document needs an "Updates" header. If the latter, please remove or rephrase
this section.

[Ballot discuss]
The Gen-ART Review by Richard Barnes on 25-Oct-2010 raises a concern
  with Section 4 that needs to be addressed.  Richard said:

  I'm confused by the existence of Section 4 in light of the fact that
  Sections 2.1.2, 2.2.2, and 2.3.2 say that a server MUST support a
  value for each of the basic modes.  If there are
  cases where a server doesn't support a given mode, what does it mean
  for it to "support the  parameter" with a given value?

[Ballot discuss]
In a Discuss related to Alexey's, I am not clear about the "requirements" placed on servers and clients in this specification. Is the intention to say that "implementations conforming to this sepcification" should/must do stuff. Or, as the language of the I-D implies, "[new] implementations of Netconf" should/must do things?

The former case really needs a little clarification in the text.
The latter case implies that this I-D updates the Netconf spec.

For example:

4.3.  Conformance

  Every NETCONF server SHOULD implement this capability.

which seems to conflict in tone from...

4.1...

  A NETCONF server implementing the :with-defaults capability:

  o  MUST indicate its basic mode behavior by including the 'basic-
      mode' parameter in the capability URI, as defined in Section 4.4.
  o  MUST support the YANG module defined in Section 5.
  o  SHOULD support the 'report-all' or 'report-all-tagged' defaults
      handling mode.
  o  MAY support additional defaults handling modes.


I don't think this is a big deal, but you need to work out exactly what you are requiring, and then make a few tweaks accordingly.

[Ballot comment]
I could not understand the meaning of Section 2.3.1.  I suggest revising it for symmetry with sections 2.1.1 and 2.2.1, which I thought were very clear.  I have proposed text which is probably wrong (since I had trouble with the current text) but at least illustrates what I am suggesting...

OLD
  If a client sets a data node to its schema default value, it MUST
  always be reported.  If the server sets a data node to its schema
  default value, it MUST NOT be reported.  Non-configuration data nodes
  containing the schema default value MUST be reported.

NEW
  When data is retrieved from a server using the 'explicit' basic mode, and
  the  parameter is not present, data nodes MUST be
  reported if explicitly set by the client, even if they contain the schema
  default value.  Non-configuration
  data nodes containing the schema default value MUST NOT be reported.

[Ballot discuss]
The Gen-ART Review by Richard Barnes on 25-Oct-2010 raises a concern
  with Section 4 that needs to be addressed.  Richard said:

  I'm confused by the existence of Section 4 in light of the fact that
  Sections 2.1.2, 2.2.2, and 2.3.2 say that a server MUST support a
  value for each of the basic modes.  If there are
  cases where a server doesn't support a given mode, what does it mean
  for it to "support the  parameter" with a given value?

[Ballot discuss]
1) Building on Alexey's discuss - as written, this document requires any
client that cares about how defaults are handled to implement all three
(four?) modes. It would help to explicitly call that out in the text.  Did the
group consider making one of the modes mandatory to implement at the
server (for instance, making the SHOULD in the third bullet of 4.1 a MUST)?
If so, could the reasons for not doing so be better captured in the document?

2) The phrasing of 2.1.2, 2.2.2, and 2.3.2 is ambiguous. During a conversation
with Dan, I was convinced that the intent was to make them subordinate to
the requirement at the top of section 2 that a server must pick one of the
three basic modes, and that 2.1.2 should be read as

"If the server supports the 'report-all' mode for handling default data,
and the client has requested it by specifying 'report-all' when using
, then the server MUST behave as specified in section 3.1"

and not as

"The server MUST support the 'report-all' mode.

If that's correct, please adjust the text to make it less likely that
someone will misinterpret the requirement. (I thought 2.1.2 and the
third bullet of 4.1 were in conflict before the conversation with
Dan mentioned above).

3) Section 4.3 as written is updating the base NETCONF spec. Was the intent is
to add a requirement to the base protocol, affecting conformance of existing
implementations, or only to promote adoption of this extension? If the former,
the document needs an "Updates" header. If the latter, please remove or rephrase
this section.

[Ballot comment]
1. I would like to echo Alexey's "discuss-discuss".

2. It's not clear why the 'default' attribute qualified by the "urn:ietf:params:xml:ns:netconf:default:1.0" namespace is called "the 'wd:default' attribute"; does this assume that the attribute will always be prefixed with "wd:"? If so, why?

3. The text mentions that a server will check if default="true", but the boolean datatype in XML Schema Part 2 has two lexical representations for logical TRUE (both "true" and "1" are valid). An implementation note might be appropriate, such as:

  In accordance with Section 3.2.2.1 of XML Schema Part 2: Datatypes,
  the allowable lexical representations for the xs:boolean datatype are
  the strings "0" and "false" for the concept of false and the strings "1" and
  "true" for the concept of true; implementations MUST support both styles
  of lexical representation.

[Ballot comment]
1. I support Alexey's "discuss-discuss" because I am concerned about pushing complexity onto the client.

2. It's not clear why the 'default' attribute qualified by the "urn:ietf:params:xml:ns:netconf:default:1.0" namespace is called "the 'wd:default' attribute"; does this assume that the attribute will always be prefixed with "wd:"? If so, why?

3. The text mentions that a server will check if default="true", but the boolean datatype in XML Schema Part 2 has two lexical representations for logical TRUE (both "true" and "1" are valid). An implementation note might be appropriate, such as:

  In accordance with Section 3.2.2.1 of XML Schema Part 2: Datatypes,
  the allowable lexical representations for the xs:boolean datatype are
  the strings "0" and "false" for the concept of false and the strings "1" and
  "true" for the concept of true; implementations MUST support both styles
  of lexical representation.

[Ballot discuss]
While I was initially skeptical about usability of this extension, I think the document is making a compelling argument for having this extension.

However, there is one question I would like to discuss:

  A NETCONF server implementing the :with-defaults capability:

  o  MUST indicate its basic mode behavior by including the 'basic-
      mode' parameter in the capability URI, as defined in Section 4.4.
  o  MUST support the YANG module defined in Section 5.
  o  SHOULD support the 'report-all' or 'report-all-tagged' defaults
      handling mode.
  o  MAY support additional defaults handling modes.

DISCUSS DISCUSS (this might result in no changes to the document):
Is the goal here to allow servers to advertise what they support, but pushing complexity of dealing with multiple modes to clients? My personal experience with other protocols suggest that simpler operations for clients would result in more widespread deployment of extensions.

So to translate this into something actionable: I am a bit concerned that various things are optional for compliant servers to support. I would feel more comfortable changing the SHOULD/MAY to MUSTs (at least for the SHOULD).
Is this something that was discussed in the WG?

IANA understands that this document is dependent upon approval of
another, related document [ draft-ietf-netmod-yang ]. Please see the
third action, below, for a description of that dependency.

IANA understands that, upon approval of this document, there are three
IANA actions which must be completed.

First, in the Network Configuration Protocol (NETCONF) Capability URNs
registry located at:

http://www.iana.org/assignments/netconf-capability-urns/netconf-capability-urns.xhtml

The following registration should be added:

Capability Capability Identifier Reference
---------- ------------------------------------------------ --------
with-defaults urn:ietf:params:netconf:capability:with-defaults:1.0
[RFC-to-be]

Second, in the ns (namespace) class of the IANA XML Registry located at:

http://www.iana.org/assignments/xml-registry-index.html

two new registrations should be made

ID: netconf-default-1.0
URL: urn:ietf:params:xml:ns:netconf:default:1.0
Registration Template: None
Reference: [RFC-to-be]

ID: yang-ietf-netconf-with-defaults
URL: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults
Registration Template: None
Reference: [RFC-to-be]

Third, IANA understands that a new registration is to be created in a
yet-to-be-crated registry as defined in the document:

draft-ietf-netmod-yang

This document registers one module name in the 'YANG Module Names'
registry, defined in document above:

name: ietf-netconf-with-defaults
prefix: ncwd
namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults
RFC: [RFC-to-be]

PROTO write-up by Bert Wijnen

(1.a) Who is the Document Shepherd for this document? Has the Document Shepherd personally reviewed this version of the document and, in particular, does he or she believe this version is ready for forwarding to the IESG for publication?

Bert Wijnen is the document shepherd.
I have reviewed the document many times, including version -10, that I believe is ready for forwarding to the AD/IESG.
Note: V11 introduces only a minor terminology change.

(1.b) Has the document had adequate review both from key WG members and from key non-WG members? Does the Document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

The document has had wide review and re-reviews of NETCONF WG members. I do not have any concerns regarding the level of review for this document.

(1.c) Does the Document Shepherd have concerns that the document needs more review from a particular or broader perspective, e.g., security, operational complexity, someone familiar with AAA, internationalization or XML?

I do not believe any extra special review (other than normal IETF Last Call) is needed.

(1.d) Does the Document Shepherd have any specific concerns or issues with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here. Has an IPR disclosure related to this document been filed? If so, please include a reference to the disclosure and summarize the WG discussion and conclusion on this issue.

I do not have any specific concerns.
No IPR disclosure been filed as far as we know.

(1.e) How solid is the WG consensus behind this document?
Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

The content of the document has strong WG consensus. There is a more or less 50/50 division on one topic, and that is that some WG members want to parts (or even all) of the content of this document merged into rfc4741bis. But our charter called for a separate document, and a merge at this late stage in the process only creates extra work and potential delays.
The main editors are also in favor of publication of this document as a separate Proposed Standard RFC.
So as the WG chairs we decided it is best to go ahead and request publication of this document (as per our WG charter).

(1.f) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is entered into the ID Tracker.)

No-one has threatened with an appeal or expressed extreme discontent. But pls note my comments in sect 1e above.

(1.g) Has the Document Shepherd personally verified that the document satisfies all ID nits? (See http://www.ietf.org/ID-Checklist.html and http://tools.ietf.org/tools/idnits/). Boilerplate checks are not enough; this check needs to be thorough. Has the document met all formal review criteria it needs to, such as the MIB Doctor, media type and URI type reviews?

Document passes ID-nits (as shown by the IETF idnits tool:
http://tools.ietf.org/idnits?url=http://tools.ietf.org/id/
draft-ietf-netconf-with-defaults-09.txt)


(1.h) Has the document split its references into normative and informative? Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the strategy for their completion? Are there normative references that are downward references, as described in [RFC3967]? If so, list these downward references to support the Area Director in the Last Call procedure for them [RFC3967].

The document has only Normative references. All normative documents have been published except draft-ietf-netconf-rfc4741bis, but that is heavily worked on in the NETCONF WG as we speak.

(1.i) Has the Document Shepherd verified that the document IANA consideration section exists and is consistent with the body of the document? If the document specifies protocol extensions, are reservations requested in appropriate IANA registries? Are the IANA registries clearly identified? If the document creates a new registry, does it define the proposed initial contents of the registry and an allocation procedure for future registrations? Does it suggest a reasonable name for the new registry? See [RFC5226]. If the document describes an Expert Review process has Shepherd conferred with the Responsible Area Director so that the IESG can appoint the needed Expert during the IESG Evaluation?

IANA considerations are present and complete. No new namespaces are created and so no new Expert is needed.

(1.j) Has the Document Shepherd verified that sections of the document that are written in a formal language, such as XML code, BNF rules, MIB definitions, etc., validate correctly in an automated checker?

The XSD section has been checked by Mehmet Ersue (co-chair of the WG) and has been found to be valid. The YANG module has been checked by Martin Bjorklund.

(1.k) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up? Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary

    The NETCONF protocol defines ways to read and edit configuration data
    from a NETCONF server.  In some cases, part of this data may not be
    set by the NETCONF client, but rather a default value known to the
    server is used instead.  In many situations the NETCONF client has a
    priori knowledge about default data, so the NETCONF server does not
    need to save it in a NETCONF datastore or send it to the client in a
    retrieval operation reply.  In other situations the NETCONF client
    will need this data from the server.  Not all server implementations
    treat this default data the same way.  This document defines a
    capability-based extension to the NETCONF protocol that allows the
    NETCONF client to identify how defaults are processed by the server,
    and also defines new mechanisms for client control of server
    processing of default data.


Working Group Summary

The working group went over several versions of the document. The comments and reviews helped improve the document a lot and brought us to consensus on the 9th revision of the docuemnt.

Document Quality
There are prelimenary implementations of this protocol and updates to comply with this spec are in plan. Others are planning to implement this spec too.