YANG Patch Media Type
draft-ietf-netconf-yang-patch-14

[Ballot comment]
Update: I've cleared my discuss bases on the authors' intent to clarify that yang-patch is intended to be atomic regardless of the underlying protocol.

-2, 2nd paragraph, last sentence: is the message body mentioned in the last sentence the same as the one described by the media type in the previous sentence? That is, are we talking about one body part, or two? If one, the ordering of the 2nd and 3rd sentence is a bit confusing to me.

-2.2, tree diagram:
If edit-id is optional, how are errors identified if it is not present?

-2.6, first paragraph: "...RESTCONF server SHOULD return a "yang-patch-status" message."

What if it doesn't? (I.e. Why not MUST?)

-2.7, 2nd paragraph: "... SHOULD return a "yang-patch-status" message."

What if it doesn't?

Editorial:
-2, first bullet: s/at within/within

-2, Accept-Patch example: The example seems misplaced, as it seems to apply to the text two paragraphs back, not the immediately proceeding paragraph.

[Ballot comment]

- section 2: I'm not clear what that example of Accept-Patch is
telling me. (And if that's meant to be a figure then a caption
and figure number would be good.)

- 2.2: How do you ensure a patch-id is unique? In what scope?
Random idea: you could specify a way to make these unique if you
hashed a representation of the current resource and the patch
data and the date/resource URI or something. And that might have
nice properties for auditing. Think of "git blame" etc.:-) It
might be possible to do a similar thing for edit-id too I guess.
(Note that I'm only suggesting this as an informative bit of
spec, i.e. as a "here's a good way to do it" kind of thing.)

- section 5: you very reasonably say that a server SHOULD
"prevent system disruption due to excessive resource
consumption" but you don't say how to do that. Is that ok?  At
least some references would help implementers not go so wrong I
think. (Sorry, I don't have such references to hand.)

[Ballot comment]
This document may have the clearest terminology section I've ever seen in a draft. Thank you all for that!

I have the same question as Ben did in his Discuss, about just how atomic a patch operation is. I'll watch the discussion in that thread.

[Ballot discuss]
Hopefully this is easy to resolve, and is probably just confusion on my part. But I am confused by whether or not the edits in a single patch are expected to be atomic. I assumed no, since the results can speak to multiple edits, but section 5 mentions atomicity as a RESTCONF requirement. Is atomicity not required by yang-patch in general, but required when using RESTCONF?

Section 5 goes on to talk about disruption due to partial processing, which further confuses me if RESTCONF requires atomicity.

[Ballot comment]
-2, 2nd paragraph, last sentence: is the message body mentioned in the last sentence the same as the one described by the media type in the previous sentence? That is, are we talking about one body part, or two? If one, the ordering of the 2nd and 3rd sentence is a bit confusing to me.

-2.2, tree diagram:
If edit-id is optional, how are errors identified if it is not present?

-2.6, first paragraph: "...RESTCONF server SHOULD return a "yang-patch-status" message."

What if it doesn't? (I.e. Why not MUST?)

-2.7, 2nd paragraph: "... SHOULD return a "yang-patch-status" message."

What if it doesn't?

Editorial:
-2, first bullet: s/at within/within

-2, Accept-Patch example: The example seems misplaced, as it seems to apply to the text two paragraphs back, not the immediately proceeding paragraph.

[Ballot discuss]
This should be easy to resolve through discussion or some text tweaks.  In the security considerations section, I see some text that hints at my questions below, but isn't clear enough, so I'd like to discuss it to see if these things are covered, or why they are not, and to see if we can tweak the text a bit.

The following text is helpful, is PATCH described in [I-D.ietf-netconf-restconf]?
  This document defines edit processing
  instructions for a variant of the PATCH method, as used within the
  RESTCONF protocol.

I see section 2.7 discusses error handling and validating the YANG module, but is there a way that the hash (or some other mechanism) of the patch could be validated to ensure the patch was not altered.  Is that already described for PATCH?

I also see this text in the security considerations section:
  It is important for RESTCONF server implementations to carefully
  validate all the edit request parameters in some manner.

Is the source of the patch authenticated?  Can the client receiving the patch be authenticated?  Is this handled through RESTCONF?  Since YANG modules could add in write capabilities, unauthenticated patches could result in opening backdoors or revealing information that was not intended.  You are covering it with that statement, but it's not clear if both ends can be authenticated and there are attacks if they are not authenticated.

[Ballot comment]
Thank you for a well written document. A couple of small nits in your media type registration:

4.2.1.  Media Type application/yang-patch+xml

      Subtype name: yang-patch

Should be "yang-patch+xml"

      Encoding considerations: 8-bit
        Each conceptual YANG data node is encoded according to the
        XML Encoding Rules and Canonical Format for the specific
        YANG data node type defined in [RFC7950].
        In addition, the "yang-patch" YANG Patch template found
        in [RFCXXXX] defines the structure of a YANG Patch request.

If you are allowing any of UTF-16 encodings, then the above is not correct and should say "Binary".

      Fragment identifier considerations: Fragment identifiers
        for this type are not defined.

I suggest you just say "The same as for application/xml".

It would be good if you register a new file extension for this media type.

(Via drafts-lastcall-comment@iana.org): IESG/Authors/WG Chairs:

The IANA Services Operator has completed its review of draft-ietf-netconf-yang-patch-12.txt. If any part of this review is inaccurate, please let us know.

We have a question about one of the actions requested in the IANA Considerations section of this document.

Upon approval of this document, we understand that there are five registry actions to complete.

First, in the ns subregistry of the IETF XML registry located at:

https://www.iana.org/assignments/xml-registry/

a single, new namespace is to be registered as follows:

ID: yang:ietf-yang-patch
URI: urn:ietf:params:xml:ns:yang:ietf-yang-patch
Filename: [ TBD-at-registration ]
Reference: [ RFC-to-be ]

As this is an Expert Review (see RFC 5226) registry, we will initiate the required review via a separate request. Approval by the expert is required for registration. 

Second, in the YANG Module Names subregistry of the YANG Parameters registry located at:

https://www.iana.org/assignments/yang-parameters/

a new module name is to be registered as follows:

Name: ietf-yang-patch
Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-patch
Prefix: ypatch
Module:
Reference: [ RFC-to-be ]

Third, in the application Media Types registry located at:

https://www.iana.org/assignments/media-types/

a new media type is to be registered as follows:

Name: yang-patch+xml
Template: [ TBD-at-registration ]
Reference: [ RFC-to-be ]

Fourth, also in the application Media Types registry located at:

https://www.iana.org/assignments/media-types/

another new media type is to be registered as follows:

Name: yang-patch+json
Template: [ TBD-at-registration ]
Reference: [ RFC-to-be ]

Fifth, the authors request the registration of "one capability identifier in "RESTCONF Protocol Capability URNs" registry" as follows:

Index
Capability Identifier
------------------------

:yang-patch
urn:ietf:params:restconf:capability:yang-patch:1.0

Question --> We are unaware of such a registry in the List of all IANA maintained protocol at the following location:

https://www.iana.org/protocols

Is it possible that the authors are referring to the Capability URNs registry in the Network Configuration Protocol (NETCONF) Capability URNs registry located at:

https://www.iana.org/assignments/netconf-capability-urns/

We request that the IANA action in section 4.3 be reconsidered by the authors and rewritten to reflect the authors' request accurately.

We understand that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is only to confirm what actions will be performed.

Thank you,

Sabrina Tanamal
IANA Services Specialist

The following Last Call announcement was sent out:

From: The IESG
To: "IETF-Announce"
CC: bclaise@cisco.com, draft-ietf-netconf-yang-patch@ietf.org, mjethanandani@gmail.com, netconf-chairs@ietf.org, netconf@ietf.org
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (YANG Patch Media Type) to Proposed Standard


The IESG has received a request from the Network Configuration WG
(netconf) to consider the following document:
- 'YANG Patch Media Type'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2016-10-17. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  This document describes a method for applying patches to
  configuration datastores using data defined with the YANG data
  modeling language.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-netconf-yang-patch/

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-netconf-yang-patch/ballot/


No IPR declarations have been submitted directly on this I-D.