Subject: Re: [Netconf] LC on subscribed-notifications-10

From: Kent Watsen <[email-masked]>
Date: Sat, 7 Apr 2018 03:32:54 +0000

Alex/Eric,

I apologize for the long delay, but I just got back from PTO.  Please find my comments below (<KENT>), and know that I'm not up to speed on conversations you've been having with others, so please just let me know of the current status of things where applicable.

Thanks,
Kent  // as a contributor

On 3/18/18, 5:53 AM, "Alexander Clemm" <[email-masked]<mailto:[email-masked]>> wrote:

Kent, thank you for your thorough review and Eric, thank you for your thorough responses!

I agree that most of these are for the most part very small items and Eric has really answered all of them already.  Just adding some small points on a few items, look for <ALEX>

Thanks
--- Alex

From: Netconf <[email-masked]> On Behalf Of Eric Voit (evoit)
Sent: Friday, March 16, 2018 11:41 AM
To: Kent Watsen <[email-masked]>; [email-masked]
Subject: Re: [Netconf] LC on subscribed-notifications-10

Hi Kent,

Thanks so much for the detailed review.   Thoughts in-line.  At this point there doesn’t seem to be anything insurmountable...

A working copy draft which embeds / covering the points documented below is at:

https://github.com/netconf-wg/rfc5277bis/blob/master/draft-ietf-netconf-subscribed-notifications-11.txt<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_netconf-2Dwg_rfc5277bis_blob_master_draft-2Dietf-2Dnetconf-2Dsubscribed-2Dnotifications-2D11.txt&d=DwMFAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=DoO-FEinwnsQ1xowtT-9KNCYTYuzNrC979exYSodTS0&s=63Abs5RCtg85f0BkF6fUWZe7vLlQ2su2BKhdVvzHdN0&e=>

Also a legend for the comments below:

**** indicates a significant item (others might want to read/chime in).

Blue indicates text which is now in the draft (verbatim).

Orange indicates an open question, where I am asking for feedback before making changes.

Note: where I use colors, the wording should still be fine for those WG members using plain text email clients.

Still pending:

- Martin’s comments

- YANG doctor comments

> Kent Watsen, March 14, 2018 9:52 PM

> Here's my review of this draft.

> I'm aware that there may be some overlap with recent messages from Rob and

> Martin.  Please respond to them anyways, if only to explain the resolution

> made.

> BTW, when I make an open-ended question, what I'm many times looking for

> is draft-text that answers the question.  Yes, I want to know the answer but,

> more importantly, I want the answer recorded in the draft.

> PS: I'm prioritizing reviewing all three drafts over trying to reply to responses

> from earlier reviews.

> Thanks,

> Kent // contributor (but revving-up for shepherd write-up)

> <chair-hat> Authors, can you please start planning a presentation to review any

> of the larger open issues during the meeting in London? </chair-hat>

Will do

> Title: the word "custom" is throwing me, what does it mean?  I see the word in

> the Abstract and similar text in the Introduction.  In total, the substring

> "custom" appears six times in the draft, all in the Title, Abstract, and

> Introduction, so the word doesn't seem to carry much weight in the body of

> the draft itself.  Is there a better word?  Perhaps "Subscriber-specific" or

> "Receiver-specific"?   Or maybe you want to say "Customized Subscriptions to a

> Publisher's Event Streams"?

Both paths work.  I switched it to:

Customized Subscriptions to a Publisher's Event Streams

<KENT> fine

> Abstract: The first sentence has three issues: first, there's the

> custom/subscriber-specific comment from before; second, the word

> "capabilities" in the first sentence is unclear (if you mean NETCONF/yang-

> library capabilities, this document does not define any); and third, the word

> "operations" is ambiguous, the draft uses this word sometimes to mean RPCs,

> but other times not.  Putting it all together, maybe this is better?

>    This document defines mechanisms enabling subscriber-specific

>    subscriptions to a publisher's event streams.

Based on Robert's comments on add the YANG Data model, I morphed your proposal to:

This document defines mechanisms and a YANG Data Model enabling subscriber-specific subscriptions to a publisher's event streams.

<KENT> first, "data model" shouldn't be capitalized here.  That said, I question if "YANG data model" is needed at all, since "mechanisms" is even more general, and saying both seems like a mouthful.  Perhaps the two could be turned around. something like "This document defines a YANG data model and associated mechanisms enabling…"?

> Also, in the last sentence, s/Effectively/Combined/ and s/request/request for/?

Tweaked

<KENT> thx

> Introduction: Similar issues with the first sentence as with the Abstract.  Also,

> missing is a statement regarding this draft's compatibility to NMDA (see

> rfc6087bis)

Replicated the first sentence of the abstract to the introduction.  Also added a final sentence to the Intro which says:

The YANG model in this document conforms to the Network Management Datastore Architecture defined in [I-D.ietf-netmod-revised-datastores].

<KENT> thx, but be sure to also replicate any change to the Abstract from above to the Introduction again…

> Motivation:

>   How about this?

>   OLD: There are various [RFC5277] limitations, many of which have been

>        exposed in [RFC7923] which needed to be solved.

>   NEW: Various limitations in [RFC5277] are discussed in [RFC7923].

>        Resolving these issues is the primary motivation for this work.

updated

<KENT> thx

>   s/document includes/document include/

updated

<KENT> thx

>   in the 2nd bullet, remove "statically"?  the word "static" hardly appears...

updated

<KENT> thx

>   in the 3rd bullet point: would appending "in progress" be okay?

updated

<KENT> thx

> Terminology: I think you want to use this one:

>       The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL

>       NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT

> RECOMMENDED",

>       "MAY", and "OPTIONAL" in this document are to be interpreted as

>       described in BCP 14 [RFC2119] [RFC8174] when, and only when, they

>       appear in all capitals, as shown here.

Updated

<KENT> thx

>   For the "Configured subscription" term, I think that replacing "a

>   configuration interface which" with "configuration that" is clearer.

>   If necessary, we could import the term "configuration" from the

>   revised-datastores draft.

I have added the following:

Configuration: defined in [I-D.draft-ietf-netmod-revised-datastores]

Configuration datastore: defined in [I-D.draft-ietf-netmod-revised-datastores]

Configured subscription: A subscription installed via configuration into a configuration datastore.

This addresses the reboot persistence subsystem question (which came up in Robert's review) by more tightly coupling the terms to the revised datastore work.   Let me know if there are still concerns.

<KENT> works for me

>   For the "Event" term, remove the parenthesis and spell out "e.g."?

How about:

Event: An occurrence of something that may be of interest. Examples include, a configuration change, a fault, a change in status, crossing a threshold, or an external input to the system.

<KENT> better, but I don't think the first comma is needed…

>   Remove the term "NACM", since it only appears in the Security

>   Considerations section.

Done

<KENT> thx

>   For the "Notification message" term, is the beginning important?

>   Maybe s/A set of transport encapsulated information/Information/?

Done.

<KENT> thx

>   For the "Publisher" term, why is "Subscription" capitalized?  Is it

>   (and all other terms) capitalized consistently throughout the draft?

Very early iterations of these drafts had all terminology capitalized.  Earlier reviews resulted in downshifting the terms because it hindered readability.   The large "S" is likely something left over which got missed.   It is now a lower case 's'.

<KENT> thx

>   For the "Stream" term, I'm wondering if this should be renamed "Event

>   stream" (matching what's in the title), and then search/replace instances

>   of just "stream" with "event stream" everywhere else in the document.

>   This seems better, less ambiguous.

****

We went back and forth on this.  The term is used so often that always saying "event stream" just made the document more cumbersome to read.  In the end, RFC-5277 used both in the terminology, in a similar way.  For example:

In RFC 5277: "stream" appears 104 times, and "event stream" 47 times.

In this doc: "stream appears 297 times, and "event stream"  39 times.

As using both terms made things more humanly readable, and it seemed ok for RFC-5277, we choose that path.   Let me know if *not* adding event before every use of the word stream is ok with you.

<ALEX> Yes, we had multiple discussions on this.  “Stream” certainly seems more general.  If anything, we could discuss replacing some instances of “event stream” with “stream”, but I think in general from the context it is clear what was meant.  I don’t feel strongly either way.  </ALEX>

 <KENT> when it comes to terms in technical documentation, I have found that being annoyingly long-winded and yet completely unambiguous is a win.  I would personally do it, but I'm okay with getting others opinions and going with the WG consensus.

>   For the "Subscribed event records" term, I recommend removing it, as

>   it only appears three times in the draft and, besides, you already have

>   the "Event record" term.

Done.   (Re-reading, I don't think anything is lost by removing the term either.)

<KENT> thx

>   For the "Subscriber" term, shouldn't you have a 2nd sentence like in

>   the "Receiver" term?

Added the same sentence to the receiver term.

<KENT> thx

>   Since the tree diagrams are scattered throughout the document, it would

>   be good to add the following here:

>      Tree diagrams used in this document follow the notation defined in

>      [I-D.ietf-netmod-yang-tree-diagrams].

Done

<KENT> thx

> Solution Overview

>   what does "instantiated" mean in the 1st paragraph.  suggest removing

>   if not needed.

It just meant "which exists".  Removed.

<KENT> thx

>   in (1), s/RPC/an RPC/.  Also, is "wants" the right word, maybe "is able"?

Made: "is able"

<KENT> thx

>   same with "wish" in the next sentence.

Made "is not able"

<KENT> thx

>  Also, in the last sentence,

>   s/ which would have been accepted/ that, had they been present, would

>   have enabled the dynamic subscription request to be accepted/?

Updated

<KENT> thanks

>   in (2), s/a configuration interface/configuration/.

Done

<KENT> thx

>  Also, replace "this

>   capability" with "configured subscriptions", and maybe append "based on

>   the use of a YANG feature"?

Made it:

Support for configured subscriptions is optional, with its availability  advertised via a YANG feature.

<KENT> thx

>   "For connection-oriented stateful transport" : s/For/For a/ or

>   s/transport/transports/?

Chose: transports

<KENT> thx

>   Looking at "Also note that transport specific transport drafts based

>   on this specification MUST detail the life cycles of both dynamic and

>   configured subscriptions." - do the netconf-event-notifications and

>   restconf-event-notifications drafts do this?

Yes.   It is in non-normative text, but the flow diagrams in both drafts' appendices do this.

<KENT> okay

>   Last paragraph, s/The publisher/A publisher/

Done

<KENT> thx

> Relationship to RFC-5277:

>   In the first bullet point, the "data model" for what, configuration

>   or a notification?   (same issue is in the last bullet point as well)

As there is no configuration of RFC-5277 subscriptions, it was for the notifications.  So I made the bullet:

the data model in this document replaces the Notification Management Schema of [RFC5277], Section 3.4.

<KENT> how about this instead?  "the data model in this document replaces the notification management schema described in Section 3.4 of [RFC5277]."

And I made the last bullet:

a publisher MAY implement both the Notification Management Schema and RPCs defined in [RFC5277] and this new document concurrently,...

<KENT> hmmm, is there an easier way to say this?  perhaps: " a publisher MAY implement both [RFC5277] and this new document concurrently,…"

>   The 4th bullet point isn't true (see Event Streams below)

****

I believe that it is true.   See discussion below.

<KENT> okay, I'll wait for the discussion below…

> Solution:

>   Can you add a paragraph here to introduce what all is in Section 2,

>   how it's organized, or whatever might be helpful?

<KENT> no response to this comment?

> Event Streams:

>   The 2nd paragraph says "except for where it has been explicitly

>   indicated that this the event record MUST be excluded from the

>   NETCONF stream".  This is a redefinition of what RFC5277 says,

>   has this been discussed?  How is this done (syntax/text)?  Has

>   it been done already?

****

<ALEX> I believe it is true by virtue of the fact that we are not defining the NETCONF stream anywhere in this document.  You can refer to the NETCONF stream by name.  The NETCONF stream simply refers to the stream defined in RFC 5277.

Note that in an earlier revision we were using identityrefs and identities to refer to stream.  At that point, we were defining a NETCONF stream as part of the datamodel here (even then, referring to the definition of RFC 5277).  However, the WG decided to take it out and have a reference by string.  We were also defining other streams at that point, but again the WG decided to remove the definition of streams as part of the model, leaving it to implementations to introduce arbitrary streams.  (As a side note, I would not be surprised if at some point in the future there will be an attempt to standardize the definition of new streams).

</ALEX>

Subscription state change notifications as per Section 2.7 are explicitly excluded from anyone but the target receiver.   Since the notifications are per-receiver, they cannot be placed into any NETCONF stream (for either RFC-5277 or subscribed-notifications).  And as they are excluded from the NETCONF stream, I do not see an issue with the Bullet 4 comment above.

To make this clearer in the draft text, here is some proposed/tweaked text for the start of Section 2.7...

Subscription state notifications are unlike other notifications in that they are never included in any stream.  Instead, they are inserted (as defined in the section below) within the sequence of notification messages sent to a particular receiver.  Subscription state notifications cannot be filtered out...

<KENT> this is better for s2.7, but my concern is here in 2.1.  perhaps instead of " except for where it has been explicitly indicated that this the event record MUST be excluded from the NETCONF stream", you mean "except for the subscription state notifications described in Section 2.7."???

>   s/treated a distinct/treated as a distinct/

Done

<KENT> thx

> Event Stream Filters

>   The 1st and 2nd sentences seems to be at odds with each other.

****

I don't believe they are at odds.  But I can tweak the wording.   How about making the second sentence:

A match on a filter always results in an action upon a complete event record. Information is never stripped from within an event record prior to that event record being encapsulated within a notification message.

<KENT> I like it

> QoS

>   What does " MUST work identically" mean?

>   is HTTP a mandatory  transport?

>   RFC 7540 Section 5.3.3 talks about a PRIORITY frame,

>   which is  defined in Section 6.3 of that draft.  How is this

>   suppose to work in a transport-agnostic way?

****

It would be excellent if we can adopt the a subset of prioritization types in HTTP2 without having to redefine the details of the algorithm in this document.  I believe this is possible, but I understand that you want refined wording to make sure this is accomplished explicitly.  Proposed are two snippets of revised text which hopefully accomplishes this:

Snippet 1:

Dequeuing of notification messages across independent subscriptions to a receiver SHOULD be allocated bandwidth proportionally based on each subscription's weight.  For more information on the proper treatment, see stream dependency weighting within RFC 7540, section 5.3.2.

<KENT> fine

Snippet 2

If a subscription has a dependency, then any buffered notification messages containing event records selected by the parent subscription SHOULD be dequeued prior to the notification messages of the dependent subscription.  If notification messages have dependencies on each other, the older notification message MUST go first.  For more information on the proper treatment to stream dependency as described within [RFC7540], section 5.3.1.  If a dependency included within an RPC references a subscription which does not exist or is not visible to that subscriber, that dependency may be silently removed.

<KENT> also fine

Also HTTP is not mandatory.  In fact with the text change, the reference to RFC-7950 now becomes informative rather than normative.

<KENT> good

> Dynamic Subscriptions

>   s/RPC/RPCs/

ok

<KENT> thx

>   Please provide more detail about how extensibility is accomplished,

>   or an example showing the augmentation occurring.

****

Rather than talk about how augmentation might be done in theory, it should be cleaner to the reference to YANG-Push augmentations.  So I added the following sentence...

For examples of such augmentations, see the RPC augmentations within [I-D.ietf-netconf-yang-push]'s YANG model.

<KENT> I generally shy away from upward refs, but yang-push is an informative ref, so I'll blink on this one.

>   For all the subsections, should the title be s/Subscription/Dynamic

> Subscription/?

Done

<KENT> thx

> Dynamic Subscription State Model

>   What does "asserted" mean?  - remove/replace?

Removed

<KENT> thx

>   I'm confused by the diagram and subtitle's use of the word "receiver",

>   when the first sentence of the paragraph above says that the SM is for

>   the publisher...

This is for the Publisher: the publisher must maintain the state of whether a receiver is currently active or suspended.

I changed the title to: "Publisher's state for a dynamic subscription" which should help here.   Other reviewers requested the addition of the word receiver to the states themselves.  This is so people could make a 1:1 correlation with the states of the configured subscription state machine.

<KENT>title is better, though maybe "Publisher's state for a receiver's dynamic subscription" would be better?  (not sure)

>   Only two notifications?

Only two notifications indicate a change in the state of the subscription.

<KENT> okay, but then can you add somewhere that only two notifications are represented because they're the only ones indicating a change in the state of the subscription?

>   Looking at the graphic, how is the reader to

>   distinguish these as notifications?

Added a * to the two notifications, and text at the bottom of the drawing which says:

* indicates a state-change-notification

<KENT> better, but somehow not satisfying…  Mentally removing these two notifications from the diagram entirely, I notice that there is no other arrow going from ACTIVE to SUSPENDED; it seems like you might need one, perhaps labeled something like "<internal state event>"?  Assuming this is done, could we then remove listing these notifications from the diagram?

<KENT> Separately, can you left indent "modify-subscription" a column or two? - it's difficult to read when up against the "receiver ACTIVE" box…

>   The last sentence of the last bullet doesn't square with what's in the

>   graphic.  is "modify-subscription" suppose to be bidirectional?

The diagram is correct.    I have changed the sentence to:

There are no direct controls over resuming a subscription other than to attempt a modification of a subscription in a way which reduces the resources consumed.

<KENT> okay

> Establishing a Subscription

>   I take it that the last two sentences of the first paragraph are

>   intended as requirements for transport-bindings.  Is that correct?

Yes

>   If so, then please say so.

Morphed to:

The transport selected by the subscriber to reach the publisher MUST support multiple establish subscription RPC requests made within the same transport session.  In addition, the transport MUST support the pipelining of RPC requests made on independent subscriptions.

(As interleave seems to have NETCONF implications, am trying to move ay from that to pipelining which is a general computer science term.)

<KENT> good

>   The tree diagram is not identified as a tree diagram.  Nowhere in this

>   document is the tree-diagrams draft referenced.  This needs to be fixed.

Tree diagram reference added to the definitions section.  And also added as part of each figure name.  And each tree diagram also has text and a hyperlink near it pointing to the YANG model for more details.

<KENT> better

>   Are your tree diagrams dynamically-generated?  - is there any concern

>   that they are out-of-date?

Generated from Pyang.   Manually snipped from the output.  Concerns are discussed more below.   Next drafts I am certainly changing my integration environment.

<KENT> the question more regards if they've been generated (via pyang or whatever) recently…

>   Since you're not describing the contents of the data model here, the

>   text should say that a complete description of all the nodes is provided

>   in the YANG module, with a reference.

Every tree in the document now has something like:

Below is a tree diagram for "establish-subscription". All objects contained in this tree are described within the included YANG model within <xref target="data_model"/>.

<KENT> good.

>   why is this "establish-subscription-error-stream" yang-data name having

>   "-stream" at the end?  (same issue with the other yang-data).  It's

>   a rather confusing name.  Maybe "-info" would be better?

****

We have to have a different yang-data structures for hints provided on datastores and on streams.  Because of that -info is not sufficient.   And while it is possible to place stream and datastore at the beginning of the yang-data name, it is kind-of nice to have the error-info hints start off with the same characters.

That said, I have no problem if people want to rename the yang-data both here and in yang-push to:

stream-establish-subscription-error-info

and

datastore-establish-subscription-error-info

Is this what you prefer?

<ALEX> I think this can be renamed.  Really, these are hints, not streams.  Maybe call this “establish-event-subscription-info” and “establish-datastore-subscription-info”?

</ALEX>

<KENT> I recall this being discussed in London.  What's the current thinking on this?

>   Also, just so I'm clear, each transport-binding needs to indicate if and

>   how the yang-data structs are returned, right?  Where is this done in

>   the netconf-notif and restconf-notif drafts?

Yes

<KENT> what about the second question?

> Replay Subscription

>   Should the title being "Replaying Subscriptions", to match the verb

>   tense of the other subsections?

Tweaked to  "Requesting a replay of event records".  Because this is not a new RPC, I figure such differentiation from the other subsections is helpful.

<KENT> fine

>   s/Replay puts no/Supporting replay puts no/ or /The document puts no/?

Chose the " The document puts no "

<KENT> the current sentence doesn't read right, it looks like you accidentally dropped the word "restrictions"…

>   Current text says:

>     """

>     The inclusion of a replay-start-time within an "establish-

>     subscription" RPC indicates a replay request.  If the "replay-start-

>     time" contains a value that is earlier than content stored within the

>     publisher's replay buffer, then the subscription MUST be rejected,

>     and the leaf "replay-start-time-hint" MUST be set in the reply.

>     """

>   Why not just start with what you have, prepended by a special "event

>   record" that says there is a gap?

****

This discussion went around on the alias a few times.  E.g., the thread from mid-October titled " Martin's thoughts on subscribed-notifications"

An underlying design goal of subscribed-notifications and yang-push is to deliver no less than what subscriber explicitly requested.  Especially when YANG-Push is layered in, if we start delivering less for some combination of parameters, we have no certainty that the subscriber is getting what it needs.

For this parameter, if we start replaying more recently than what has been requested, we don't really know if that is what the subscriber wants.  This doesn't give them the chance to reject the subscription while being sent stuff which is not helpful to them without the earlier history.  And you are correct, while we could define a special event record replay actually began on success, we are not delivering on the implicit promise of the subscription "ok".  But by using the no-success result with the included "replay-start-time-hint", we are matching the design paradigm without adding special constructs.

<KENT> I understand what you're saying, but I think that I disagree with the conclusion.  I think that the common case is the receiver wanting to pickup where it left off, or the best the publisher can, and if not lossless, to be informed that there's a gap (and the size of the gap) for its records.  The current logic optimizes for what I think is an unusual case and, assuming it's flipped to be as I'm suggested, such receivers can themselves immediately cancel the subscription as soon as being told that there is a gap.  Besides, by forcing the receiver to have to perform another round-trip, doesn't that potentially increase the size of the gap?

>   OLD: it MAY also be earlier than the current time and MUST

>   NEW: it MAY be earlier than the current time, but MUST

Done

<KENT>better, but you missed removing the word "also"

 <KENT> separately, it looks like to touched the next paragraph (not sure why, but I'm okay with it) and accidentally introduced a typo: "after the after"

>   "subscribers can perform a get on" - rephrase, and use "RPC" somewhere

Made it:

To assess the availability of replay, subscribers can retrieve the "replay-log-creation-time" and "replay-log-aged-time" objects from the YANG model.

<KENT> better, but maybe s/objects/nodes/?

 With that, I don't think RPC is needed.

<KENT> agreed.

> Modifying a Subscription

>   First sentence, no need for the word "previously"

Done

<KENT> thx

>   s/one or multiple times/multiple times -or- any number of times/?

Chose "any number"

<KENT> thx

>   s/via RPC using/via an RPC on/?

Done

<KENT> thx

>   The tree diagram is not identified as a tree diagram.  And since the

>   data model isn't explained, there should be a statement for the reader

>   to look at the YANG module for details, ideally with a hyperlink.

Now done for every tree diagram in the document

<KENT> excellent

> Deleting a Subscription

>   First sentence, no need for the word "previously"

>   Under what conditions could a publisher reject a delete-subscription

>   request?  should there delete-subscription-error-stream hints?

>   The tree diagram is not identified as a tree diagram.  And since the

>   data model isn't explained, there should be a statement for the reader

>   to look at the YANG module for details, ideally with a hyperlink.

>   Last paragraph, no need for the word "previously"

Done

<KENT> thx

> Killing a Subscription

>   Regarding:

>     "This operation MUST be secured so that only connections with

>      sufficiently privileged access rights are able to invoke this RPC."

>   This needs to be in the Security Considerations section and, given

>   that, doesn't need to be here, right?  If you really want it here,

>   then please indicate that such guidance is provided in the SC section.

Moved to Security Considerations

<KENT> thx

>   Replace the paragraph beginning with "The tree structure of" with the

>   actual tree diagram for this RPC..

Done

<KENT> thx

> RPC Failures

>   Please also call-out RESTCONF error handling (RFC8040 Section 7.1).

Done

<KENT> thx

>   The 2nd paragraph is confusing.  mechanism?  how are the 1st and 2nd

>   sentences related? What does the 2nd sentence really mean, esp. wrt.

>   the MUST?

Rewrote the paragraph to:

Specific errors included within this document's YANG model MUST be returned as part of the RPC error response. Following are valid errors which can occur for each RPC:

<KENT> better

>   I can't find any examples of these errors in use.  The

>   netconf-event-notifications draft only has examples for

>   the "establish-subscription-error-datastore" and

>   "modify-subscription-error-datastore" errors.

Figure 10 in the netconf-event-notifications draft works equally for subscribed-notifications, as well as yang-push.   I have identified that example in that document as being relevant to either streams or datastores with the sentence in that draft: "This subscription may have been to either a stream or a datastore."

<KENT> okay…

Here this document, I have added the sentence:

To see a NETCONF based example of an error response from above, see [I-D.draft-ietf-netconf-netconf-event-notifications], Figure 10.

<KENT> good.  Better would be to also have a reference to a RESTCONF-based example.

>   Perhaps the

>   examples in that draft need to be split into examples related

>   to yang-push vs examples related to subscribed-notifications.

As the error mechanisms are identical between the drafts, splitting things in that document might prove more confusing.  That is one reason I identify the error response as being identical for streams and datastores above.   Perhaps additional examples, git repositories, or applications located outside the drafts?

<KENT> maybe, dunno, I'd have to look at that draft again…

 > Configured Subscriptions

>   1st paragraph: s/configuration interface/configuration/g  (two cases)

Done

<KENT> thx

>   the note under the 3rd bullet point seems unnecessary but, if keeping

>   it, then just say that receivers are unaware of the existence of any

>   other receivers.

Done.  Used your proposed text.

<KENT> thx

>   s/In addition to subscription/In addition to the subscription/

>   s/as described in/described in/

Done

<KENT> thx

>   where is the tree diagram for the configuration data model?!

****

It is in the section "Subscriptions Container".  It seemed better to introduce the state machines before getting into the details of the tree.  But if you really want to have it early, it certainly can be moved up.

So do you want it moved here, or is a reference to the later section sufficient?

<KENT> as I recall reading this section, all the previous 2.x sections had tree diagrams and I found it rather odd that there wasn't one here, nor is there any reference to where one can be found.  Perhaps you can add a forward-reference to s3.3, but forward-references are discouraged.  Do we need to rearrange sections to make this right?

>   I don't understand the last bullet point.  First, I'm having trouble

>   parsing the implicit parentheses..  Next, the last sentence seems

>   complicated, maybe just say "unless directed otherwise, the

>   notification messages MUST egress the publisher's default

>   interface towards the receiver."?

Used your text.  Done.

<KENT> thx

> Configured Subscription State Model

>   A better first sentence is needed, something introducing that there

>   exists a state machine for each configured subscription, and states

>   that there are three states (VALID, INVALID, and CONCLUDED), etc.

>   Also should state where this state machine is maintained (publisher,

>   receiver, both?)

Now says:

Below is the state machine for a configured subscription on the publisher.  This state machine describes the three states (VALID, INVALID, and CONCLUDED), as well as the transitions between these states. Start and end states are depicted to reflect configured subscription creation and deletion events.

<KENT> better (ps: the last part, "Start and end states are depicted to reflect configured subscription creation and deletion", isn't there)

>   s/publisher evaluation/evaluation by the publisher/?

Done

<KENT> thx

>   Please move text regarding how to interpret the diagram (uppercase,

>   dashed boxes, parantheses, etc.) into a preamble or postamble element.

Added underneath the diagram.  See diagram below.

<KENT> thx

>   s/itself might itself/itself might/

>   s/in no longer/is no longer/

Done

<KENT> thx

>   The first paragraph under the diagram doesn't match what the diagram

>   shows.  Looking at the diagram, I also see two possible sequence of

>   transitions that get VALID to INVALID, but I'm unsure how they relate

>   to the two mentioned in the text..

Updated paragraph text as per below.  Hopefully it is clearer now.

<KENT> yes

>  The text should call out which

>   parts of the diagram it's referring to.  Many times I number labels

>   in diagrams and then, under the diagram, provide a more thorough

>   explanation for each number.

Added numbers within the diagram, and added text references as per below:

<KENT> better

.........

: start :-.

:.......: |

     create  .---modify-----..----------------------------------.

          |  |              |                                  |

          V  V          .-------.         .......         .---------.

 .----[evaluate]--no--->|INVALID|-delete->: end :<-delete-|CONCLUDED|

 |                      '-------'         :.....:         '---------'

|----[evaluate]--no-.      ^                ^                 ^

 |        ^          |      |                |                 |

yes       |          '->unsupportable      delete           stop-time

 |      modify         (subscription-   (subscription-   (subscription-

 |        |             terminated*)     terminated*)      concluded*)

 |        |                 |                |                 |

 |       (1)               (2)              (3)               (4)

|   .---------------------------------------------------------------.

'-->|                         VALID                                 |

     '---------------------------------------------------------------'

Legend:

dotted boxes: subscription creation and deletion events

dashed boxes with uppercase letters: valid states for a subscription

[evaluate]: decision point on whether the subscription is supportable

(*): resulting subscription state change notification

Also the text below now says:

A valid subscription may become invalid on one of two ways.  First, it may be modified in a way which fails a re-evaluation.  See (1) in the diagram. Second, the publisher itself might determine that the subscription is no longer supportable.  See (2) in the diagram.  In either case, a "subscription-terminated" notification is sent to any active or suspended receivers.  A valid subscription may also transition to a concluded state via (4) if a configured stop time has been reached.  In this case, a "subscription-concluded" is sent to any active or suspended receivers.  Finally, a subscription may be deleted by configuration (3).

<KENT> better

>   Is it "any active or suspended receivers" or "any receivers for an

>   active or suspended subscription"?

The current wording is correct.  A configured subscription is never suspended.  It can be INVALID, or it can be ACTIVE and all its receivers suspended.  But in the second case, at least the receivers get subscription-suspended notifications.

<KENT> okay

>   s/During any times a/When a/?

<KENT> you didn't say you did this one, but I see that you did, thx.

>   Regarding "Below is the state machine for each receiver of a configured

>   subscription." - where is this state machine maintained, on the publisher

>   or on the receiver?

Updated the title to show it is a Publisher state model.

<KENT> did you?  I see " Receiver state for a configured subscription", which seems misleading

>   why is "receiver" in each box?

To drive home the idea that this state machine was for each individual receiver, rather than for the subscription as a whole..

<KENT> okay, I guess, I don't know, it seems confusing, but I see that you explain it in the legend, so that's better…

>   Again, you might look to having a

>   preamble or postamble to describe the syntax used in the diagram.

Per figure below, added the legend as a postamble:

<KENT> thx

>   1st paragraph below diagram: s/to connecting/to "connecting" -or- to

> CONNECTING/?

Now says CONNECTING.   And all receiver states moved to uppercase.

<KENT> good

>   Regarding "and event records are not being dropped due to a publisher

>   buffer overflow" - this seems like it's from out of nowhere.  If not

>   normative, then maybe delete?

****

It is normative.  This is needed to maximize the number of concurrent subscriptions without enforcing continuous transport keep-alive overhead when no event records are being passed, as well as to not prematurely declare a subscription as suspended while there is a chance that transport may be established before event records do get lost.    This allows a configured subscription’s receiver to exist across an intermittent connection, and the receiver can remain active on the publisher as long as events aren’t being lost.  While this can be done with NETCONF, it is probably more likely to be seen in practice with HTTP connections.

Based on that, I rephrased the words above so that it doesn’t feel from out of nowhere.  See the text below the updated figure below...

 <KENT> thx

>   This text is again difficult to reconcile with the diagram.  I again

>   recommend numbering labels and then describe the numbers below.

Done

<KENT> thx

     .-----------------------------------------------------------------.

     |                         VALID                                   |

     |   .----------.                           ..--------.             |

     |   | receiver |------------------timeout->|receiver|             |

     |   |CONNECTING|<------------------reset---|TIMEOUT |             |

     |   |          |<-transport---.            '--------'             |

     |   '----------'  loss,reset  |                                   |

     |      (1)          |         |                                   |

     |  subscription-   (3)        |                                   |

     |  started*    .--------.     |                       .---------. |

     |       '----->|        |     '--------------------(3)|         | |

     |              |receiver|(2)-subscription-suspended*->|receiver | |

     | subscription-| ACTIVE |                             |SUSPENDED| |

     |   modified*  |        |<--subscription-resumed*,----|         | |

     |        '---->'--------'    subscription-modified*   '---------' |

     '-----------------------------------------------------------------'

  Legend:

   dashed boxes which include the word 'receiver' show the possible

   states for an individual receiver of a VALID configured subscription.

   * indicates a state change notification

Individual receivers are moved to an ACTIVE state when a "subscription-started" state change notification is successfully passed to that receiver (1). Configured receivers remain ACTIVE if both transport connectivity can be verified to the receiver, and event records are not being dropped due to a publisher buffer overflow. The result is that a receiver will remain ACTIVE on the publisher as long as events aren’t being lost, or the receiver cannot be reached.  However if there is buffer overflow, or the publisher cannot generate events for a receiver, the receiver MUST be suspended (2).  In addition, a configured subscription's receiver MUST be moved to CONNECTING if transport connectivity cannot be achieved, or if the receiver is reset via configuration operations (3).

<KENT> yes, better, esp. w/ the numbering

>   s/ mechanisms described above is/ mechanisms described above are/

>   What does this mean, how are mechanisms mirrored for RPCs and

>   notifications?

Done

<KENT> thx

>   Regarding " provides an example of such an extension" - which section?

Revised text to:

The YANG model [I-D..ietf-netconf-yang-push] Section 4.1,  provides many such extensions, this includes the augmentation of "/sn:modify-subscription/sn:input/sn:target".

<KENT> better, but:

1) I didn't review yang-push, but I hope that someone pointed out that section 4.1 needs to point to section 5 and, additionally perhaps section 5 should be moved to section 4.5…

2) sentence structure needs help, how about:  "For instance, the YANG module defined in Section 5 of [I-D..ietf-netconf-yang-push]  augments "/sn:modify-subscription/sn:input/sn:target".  ???

> Creating a Configured Subscription

>   1st paragraph: let the first sentence be its own paragraph as with

>   the other 2.5.x sections.

>   For the remainder, I think this is the

>   3rd time that the draft has discussed the differences between

>   configured and dynamic subscriptions.  Please eliminate unnecessary

>   redundancy.  Factor out into another section if needed.

I agree that the following paragraph can be deleted.

There are two key differences between the new RPCs defined in this document and configuration operations for subscription creation. Firstly, configuration operations install a subscription without question, while the RPCs are designed to the support negotiation and rejection of requests. Secondly, while the RPCs mandate that the subscriber establishing the subscription is the only receiver of the notification messages, configuration operations permit specifying receivers independent of any tracked subscriber.

I have just removed this.

<KENT> thx

>   Regarding 2nd/3rd paragraphs, how resilient is the solution to the

>   resumption of the underlying transport?  If messages lost in the

>   write-buffer are lost, could the receiver ever be helplessly out

>   of sync without a full restart?

I think we are clean here.  I have updated the text against the diagram per-above which hopefully provides more descriptive text on why the resumption of  underlying transport is covered.

<KENT> I don't understand this response, can you provide more information?

> Modifying a Configured Subscription

>   s/ ././    ;)

Done

<KENT> thx

> Resetting a Configured Receiver

>   But *how* is it reset? - via a configuration operation?  which one?

>   Should this be part of "Modifying a Configured Subscription"?

Added the sentence:

This is accomplished via the "reset" action within the YANG model at "/subscriptions/subscription/receivers/receiver/reset".

<KENT> thx

> Event Record Delivery

>   First paragraph, last sentence.  I think I commented on similar text

>   before.  Is this a requirement for the transport binding?

Perhaps the word interleave is the wrong choice here, and intermixing is better in this case.  I made that change.

<KENT> okay, but where did the following new paragraph come from?  Also:

   - s/passed receiver/passed to the receiver/?

>  Do the  netconf-notif and restconf-notif drafts satisfy this requirement?

Yes

<KENT> good

> where?

Netconf-notif supports interleaving of requests as described in Section 3.

<KENT> okay

Restconf-notif doesn’t need to explicitly call for pipelining support as it is a basic capability of HTTP.

<KENT> but the question isn't about pipelining.  Even NETCONF supports pipelining, something extra is needed to support "intermixing", right?

>   2nd paragraph: "able to traverse" --> "not blocked by"?

Done

<KENT> thx

>   Also, for

>   the 3rd sentence, call out the "RPC response" is for dynamic and

>   "state-change notification" is for configured?

Yes.   Made text:

A subscription's events MUST NOT be sent to a receiver until after a corresponding RPC response (in the case of a dynamic subscription) or state-change notification (in the case of a configured subscription) has been passed receiver indicating that events should be expected.

<KENT> good

>   Last two paragraphs, this text needs to be removed,

removed

<KENT> thx

>   or else we might

>   need to block this draft on notification-messages.   What do you mean

>   by " this document will be updated to indicate support".

At some point when notification-messages is complete, this draft should be updated as it is a more robust solution (as a subscription id can be provided for event records provided on streams.)

<KENT> you misunderstood, I know what it means, I was questioning why we'd say such a thing.  Anyway, you removed the paragraph already, so it's no longer an issue.

> Subscription State Notifications

>   OLD

>    In addition to subscribed event records, a publisher MUST send

>    subscription state notifications to indicate to receivers that an

>    event related to the subscription management has occurred.

>   NEW

>    In addition to sending event records to receivers, a publisher MUST

>    also send subscription state notifications when events related to

>    the subscription management has occurred.

>   ???

Done.  (Removed the extra ‘the’)

<KENT> thx

>   2nd paragraph: s/directly//

Done

<KENT> thx

>   Also, I'm unsure about the "subscription-state-notif" extension, how

>   is it expected to be used by a YANG processor?

Per above, it ensures that these YANG notifications if encoded in XML are not placed onto the NETCONF stream.

<KENT> actually, I thought that before it only said that the Subscription State Notifications (s2.7) were not placed into the NETCONF stream???

>   Perhaps a generic

>   notification-filtering GUI is envisioned whereby the logic could

>   automatically remove these notifications from selection, but coding

>   for this extension has very limited use, as no other drafts are ever

>   likely to define any.  I suppose it does no harm, but I also think

>   that the text sure be clear.  Personally, I'd rather the extension

>   be removed unless there is a good reason to keep it.

****

The three choices seem to be:
(a) current solution

(b) hardcode the these notifications so none ever go on the NETCONF stream

(c)  make the extension “exclude-from-NETCONF-stream”.  As it is quite possible that other drafts will want to do that.

I am good with any of these.  But the first seems the cleanest, and most self contained.  Let me know it the current doesn’t work for you.

<ALEX> Just to add on:  A reason for the extension (and different solutions were discussed at different points in time) was that since this is a “meta-notification”, it should be treated differently from other notificaitons.  For example, a subscriber should receive these even if not explicitly subscribing to them – they are simply part of the “control protocol” for managing the subscriptions.   They also apply if a subscriber subscribes to something other than the NETCONF stream.

</ALEX>

<KENT> yes, Alex, part of the control protocol, this is why I'm thinking maybe Eric's choice (b) is best.  Is this being discussed elsewhere?

> subscription-started:

>   Regarding the 2nd paragraph, Section 2.4.2.1 implies a contradiction

>   to this statement.

****

A replay subscription can be set for a configured subscription.  There was some carrier on the NETCONF alias who requested this many months ago.  See also dialogs with Martin.

Looking at your comment, it probably isn’t a good idea to embed this fact within the replay text embedded as part of the dynamic subscription section.

The best way to tease this apart is first to separate any configured subscription context the 2.4.2.1.   This can be done simply by replacing the ‘after the "subscription-started" notification’. With ’ after the after a successful establish-subscription RPC response’.

<KENT> okay, modulus the "after the after" typo.

And then to be more explicit that this is supported, we could add move contradicting statement into a new section 2.5.6 where it would no longer appear contradicting.  Replay in a new section looks like this:

2.5.6 Replay for a Configured Subscription

It is possible to place a start time on a configured subscription.  This enables functionality like immediately streaming boot log information off of a publisher immediately after restart.

<KENT> "immediately used twice, suggest removing first instance.  Actually, this needs a rewrite, perhaps "This enables streaming of logged information immediately after restart." ???

When any such configured subscription receivers become ACTIVE, buffered event records (if any) will be sent immediately after the “subscription-started” notification.  The first event sent will be the most recent following the latest of four different times: the "replay-log-creation-time", "replay-log-aged-time", "replay-start-time", or the most recent publisher boot time.

<KENT> I don't understand the 2nd sentence here

All other replay functionality remains the same as with dynamic subscriptions as described in Section 2.4.2.1

<KENT> I'm not sure I like having to look at 2.4.2.1 and trying to figure out what this means.  Can you make this more explicit or, since 5.6 is pretty small, copy the parts into this section?

The good news is that all of this is consistent with text is already reflected in the YANG model.

<KENT> thankfully!

>   The tree diagram is not identified as a tree diagram.  And since the

>   data model isn't explained, there should be a statement for the reader

>   to look at the YANG module for details, ideally with a hyperlink.

Done

<KENT> thx

>   Why is all this sent to the receiver?  Doesn't it already know the

>   protocol and encoding?  What about the other parts?  Which parts

>   are actually useful?

The complete state of the subscription is sent, which can also be useful for debugging.  But beyond that, based on what I am hearing from the CBOR people, even the protocol and encoding might be different between.

<KENT> okay

> subscription-modified

>   1st paragraph: the same parameters, or data model / tree diagram?

>   Also, is "provided" the right word?  Maybe it would be better to

>   have the tree diagram itself, even though only the name changes?

Provided the full tree.   It does chew up space, but that is not really an issue.

<KENT> thx

>   Last two paragraphs, why put "First" and "Second" when they are

>   bullet points.  Maybe you want to use a numbered-list or otherwise

>   rephrase these?

Made a numbered list

<KENT> thx

>   Last paragraph, the last sentence doesn't flow with the first.

>   It seems as if it was copy/pasted from somewhere else.  Is this

>   intended to be a normative statement here?

Yes it is a normative statement, and it is in the correct place.

I added text to smooth the transition.  It now is this:

While this state change will be most commonly used with configured subscriptions, with dynamic subscriptions, there is also one time this notification will be sent. A "subscription-modified" state change notifications MUST be sent if the contents of a filter identified by a "stream-filter-ref" has changed.

<KENT> better

> subscription-terminated

>   1st paragraph, 1st sentence: -e a/The publisher/A publisher/ and

>   also s/the pushing of/pushing/?

Done

 <KENT> thx

>   1st paragraph: "Such a decision may be made for" - should this

>   be "A publisher may terminate a subscription for" ?

Done

 <KENT> thx

>   1st paragraph, for the "first type of reason": does the subscription

>   terminate when the first or last referenced objects are no longer

>   accessible?

This refers to any either any leafref going missing, or the subscription-id being removed.  More in next comment

>  BTW, what do you mean by "via the YANG model", aren't

>   these instance objects in <operational>?

I have updated the text in this section to be much more explicit to cover the intent.  The section now says

   A publisher MAY terminate pushing subscribed event records to a
   receiver.  This notification indicates that no further notification
   messages should be expected from the publisher.  A publisher may
   terminate a subscription for the following reasons:

   1.  Configuration which removes a configured subscription, or a "kill-
       subscription" RPC.  These are identified via the reason "no-such-
       subscription".

   2.  A referenced filter is no longer accessible.  This is identified
       by "filter-unavailable".

   3.  The stream referenced by a subscription is no longer accessible
       by the receiver.  This is identified by "stream-unavailable".

   4.  A suspended subscription has exceeded some timeout.  This is
       identified by "suspension-timeout".

Each of the reasons above correspond one-to-one with a "reason" identityref specified within the YANG model.

<KENT> good

>   1st paragraph, what do you mean by " Identities within the YANG model"?

>   Can the text be more clear that it is referring to the "reason"

>   identityref in the tree diagram?

Text attempted just above.

<KENT> okay

>   The tree diagram is not identified as a tree diagram.

Done

<KENT> thx

>   last paragraph: remove "established".  Also, the first 2 sentences would

>   benefit moving to singular, as plural leads to some ambiguity.

Done.

<KENT> thx

Note: a subscriber can terminate an existing subscription via a "delete-subscription" RPC. In such a case, no "subscription-terminated" state change notification is sent.

<KENT> good

> subscription-suspended

>   Please replace the 2nd paragraph with the actual tree diagram, and then

>   speak to that.

Done

<KENT> thx

   This notification indicates that a publisher has suspended the

   sending of event records to a receiver, and also indicates the

   possible loss of events.  Suspension happens when capacity

   constraints stop a publisher from serving a valid subscription.  The

   two conditions where is this possible are "insufficient-resources"

   and "unsupportable-volume".  These conditions are encoded within the

   reasons.  No further notification will be sent until the subscription

   resumes or is terminated.

   Below is a tree diagram for "subscription-suspended".  All objects

   contained in this tree are described within the included YANG model

   within Section 4.

       +---n subscription-suspended

          +--ro identifier    subscription-id

          +--ro reason        identityref

        Figure 11: subscription-suspended notification tree diagram

<KENT> good

> subscription-resumed

>   The tree diagram is not identified as a tree diagram.

Updated.  As are all other tree diagrams now..

<KENT> thx

> subscription-completed

>   Please replace the 2nd paragraph with the actual tree diagram, and then

>   speak to that.

Updated.  As are all other tree diagrams now..

<KENT> thx

> replay-completed

>   2nd paragraph: s/ If subscription/ If a subscription/ and s/which/that/

Done

<KENT> thx

>   Please replace the last paragraph with the actual tree diagram, and then

>   speak to that.

Done as identical to above.

<KENT> thx

> Subscription Monitoring

>   1st paragraph: s/Container/The container/.

Done.

<KENT> thx

>   How can container "subscriptions" (config true) contain entries for

>   dynamic subscriptions?  Are you assuming in <operational>?

Updated the start of paragraph 1 to:

In the operational datastore, the container "subscriptions" maintains the state of all known subscriptions.

<KENT> thx

Updated paragraph 2 to:

Each subscription is represented as a list element.  While many subscription objects are "config true", dynamic subscriptions are only included within the operational datastore. Operational information which may be monitored includes receiver counter information, the state...

<KENT> thx

>   Also,

>   does it include configured subscriptions that are currently not

>   active for whatever reason?

Yes.   First paragraph above uses the word ‘all’.

<KENT> but if not active, aka operational, why are they in the operational datastore?  This needs to be explained.  Also, maybe you need to be more explicit than just having "all" …

>   You mention NETCONF's <get> (wait, I

>   thought this draft was suppose to be transport agnostic), but not

>   NMDA's <get-data>, so it make me wonder if this paragraph regards

>   the contents of <running> or <operational>...

Yes, we want to make it want to make it agnostic.  So it now says:

Using datastore retrieval operations , or subscribing to...

<KENT> better

>   The 2nd paragraph would make more sense if I was looking at a tree

>   diagram.  But then I realize that this would be the same tree-diagram

>   that should've been presented in Configured Subscriptions.

The tree is in the subscriptions container section just below.  I will gladly reference it wherever it ends up.

<KENT> you already need to be referring to it regardless.  As for where it is, see my previous comment on this topic

> Advertisement

>   The second paragraph seems to be mostly NETCONF specific and

>   therefore belongs in the netconf-binding draft.

Good point.  Moved the first sentence to the end of that draft’s “Compatibility with RFC-5277's create-subscription” section.

<KENT> thx

>   In a transport-

>   agnostic draft, maybe only features should be discussed?

Makes sense

<KENT> did you do this, or is this entire paragraph missing now?

> YANG Data Model Trees

>   s/top level YANG Data Node containers/protocol-accessible nodes/

Done

<KENT> thx

>   " If you would rather see" - please use more formal language.

Made it:

For tree diagrams of state change notifications,

<KENT> thx

> Event Streams Container

>   1st paragraph, last sentence: perhaps rephrase as "This enables

>   clients to discover what streams a publisher supports."?

Done

<KENT> thx

>  BTW, is

>   the " and against which subscription is allowed" part important,

>   if so, why?

Not really.  I was just trying to highlight that different clients might have visibility for different streams.  As this is implicit, I just dropped it and used your text.

<KENT> thx

>   This tree-diagram does not match what I generate.  This indicates

>   that the tree diagrams are not being dynamically-generated.  I

>   strongly suggest updating your build script to dynamically generate

>   the tree diagrams.  We cannot afford to have them be out of alignment.

At the WG request, I segmented the YANG tree into different sections.  However I do not have the tooling which automatically extracts portions of the YANG tree.

Is there a git repository which recommends a continuous integration for sub portions of a YANG tree?  For future drafts, I have certainly built a strong desire for such a continuous integration environment.

<KENT> I have my own tooling using Makefiles and shell scripts to dynamically generate and include the tree diagrams every build.  You should be looking to create similar now, for this draft (not next drafts).   Again, we cannot afford for these things to get out of alignment, and these drafts still have a way to go yet…

> Event Stream Filters Container

>   "and validated" - is this needed, since *all* configuration is validated?

Removed

>   s/ which/ that/

Done

<KENT> thx

>   "referenced and used" - is there a difference?  - can you just use one?

Now just referenced

 <KENT> thx

> Subscriptions Container

>   This tree-diagram does not match what I generate.  This indicates

>   that the tree diagrams are not being dynamically-generated.  I

>   strongly suggest updating your build script to dynamically generate

>   the tree diagrams.  We cannot afford to have them be out of alignment.

I would love to have fully generated scripts.   That is hard for a few reasons here:

(a) The automatically generated trees are getting mangled because they are so wide.  Especially with yang-push, the automatic trees must all be fixed manually each time.

<KENT> pyang already supports folding and pathing, what else are you doing?  Sometimes I need to tweak the pyang output, but I scripted that too and make it part of my build scripts

(b) I have no insights on how to pull portions of a tree into a XML document.   Is there a tool site which provides this?

<KENT> my Makefiles call a shell script to do the insertions…

The delta I see is “rw” vs “ro”.  Fixed now.   I have brought in the current tree.

<KENT> better, but not a lasting fix

> Data Model

>   I going to skip this part, for now at least, as I assume the YANG

>   Doctor will scrutinize it.

> Implementation Considerations

>  s/ For a deployment/To support deployments/

Done

<KENT> thx

>  s/split subscription/it is recommended to split subscription"

Done

 <KENT> thx

>  is " unlikely" the right word?  doesn't it eliminate the concern altogether?

Yes it does solve it.

That way it eliminates the possibility of collisions if…

<KENT> thx

>  Regarding the 2nd-half of the 1st paragraph, is it necessary for

>  interoperability reasons for this draft to define how to split the

>  subscription identifiers into static and dynamic parts.

Not necessary, just a best practice.

>   Is the

>  normative text needed here?  Maybe just describe the current

>  approach as a possible way to go about doing it?  - I think it

>  achieves the same goal without using normative text.

Agree.  Text now says:

A best practice is to use lower half the "identifier" object’s integer space when that "identifier" is assigned by an external entity (such as with a configured subscription). This leaves the upper half of subscription identifiers available to be dynamically assigned by the publisher.

<KENT> thx

>  For the 2nd paragraph, this sounds like normative text from earlier

>  in the document.  If so, then is it needed here again?

No.  Deleted.

<KENT> thx

>  For the 3rd paragraph, I'm not sure if the second sentence needs to

>  be said at all, but at least s/SHOULD/should/ so it's not normative.

Made it non-normative

<KENT> thx

> Security Considerations

>   Regarding the 1st paragraph, aren't *all* operations (configuration

>   or RPCs) always authenticated and authorized?

Yes.   Deleted as redundant.

<KENT> thx

>   Please restructure to follow, in part, the template provided here:

>   https://tools.ietf.org/html/draft-ietf-netmod-rfc6087bis-20#section-3.7.1<https://urldefense.proofpoint.com/v2/url?u=https-3A__tools.ietf.org_html_draft-2Dietf-2Dnetmod-2Drfc6087bis-2D20-23section-2D3.7.1&d=DwMFAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=DoO-FEinwnsQ1xowtT-9KNCYTYuzNrC979exYSodTS0&s=vFecrV4fFJjob2uIQQHfofpCl8aczBrzbWdOFCEhshQ&e=>

Restructured to this:

5.3.  Security Considerations

   The YANG module specified in this document defines a schema for data

   that is designed to be accessed via network management protocols such

   as NETCONF [RFC6241] or RESTCONF [RFC8040].  The lowest NETCONF layer

   is the secure transport layer, and the mandatory-to-implement secure

   transport is Secure Shell (SSH) [RFC6242].  The lowest RESTCONF layer

   is HTTPS, and the mandatory-to-implement secure transport is TLS

   [RFC5246].

   The NETCONF Access Control Model (NACM) [RFC6536bis] provides the

   means to restrict access for particular NETCONF or RESTCONF users to

   a preconfigured subset of all available NETCONF or RESTCONF protocol

   operations and content.

   There are a number of data nodes defined in this YANG module that are

   writable/creatable/deletable (i.e., config true, which is the

   default).  These data nodes may be considered sensitive or vulnerable

   in some network environments.  Write operations (e.g., edit-config)

   to these data nodes without proper protection can have a negative

   effect on network operations.  These are the subtrees and data nodes

   and their sensitivity/vulnerability:

   Container: filters

   o  stream-subtree-filter: updating a filter could increase the

      computational complexity of all referencing subscriptions.

   o  stream-xpath-filter: updating a filter could increase the

      computational complexity of all referencing subscriptions.

   Container: subscriptions

   o  address: can be used to attempt to send traffic to an unwilling

      receiver.

   o  dependency: can force important traffic to wait behind the

      unimportant.

   o  dscp: can send traffic with a higher priority marking that

      warranted.

   o  encoding: none

   o  identifier: can overwrite an existing subscription configured by

      another entity.

   o  port: none

   o  protocol: none

   o  purpose: none

   o  replay-start-time: can be used to push very large logs, wasting

      resources.

   o  source-address: address might not be able to reach a receiver.

   o  source-interface: interface might not be able to reach a receiver.

   o  source-vrf: can push subscribed traffic into a virtual network

      which might not contain receivers able to see the subscribed

      content.

   o  stop-time: none

   o  stream: none

   o  stream-filter-ref: none

   o  stream-subtree-filter: a complex filter can increase the

      computational resources for this subscription.

   o  stream-xpath-filter: a complex filter can increase the

      computational resources for this subscription.

   o  weighting: placing a large weight can overwhelm the dequeuing of

      other subscriptions.

   Some of the readable data nodes in this YANG module may be considered

   sensitive or vulnerable in some network environments.  It is thus

   important to control read access (e.g., via get, get-config, or

   notification) to these data nodes.  These are the subtrees and data

   nodes and their sensitivity/vulnerability:

   Container: streams

   o  name: if access control is not properly configured, can expose

      system internals to those who should have no access to this

      information.

   o  replay-support: if access control is not properly configured, can

      expose logs to those who should have no access.

   Container: subscriptions

   o  pushed-notifications: will show the amount of events a particular

      subscriber actually received from a stream.

   o  excluded-notifications: will show the results of access control,

      and how many event records have been filtered out.

   Some of the RPC operations in this YANG module may be considered

   sensitive or vulnerable in some network environments.  It is thus

   important to control access to these operations.  These are the

   operations and their sensitivity/vulnerability:

   RPC: all

   o  If a malicious or buggy subscriber sends an unexpectedly large number

       of RPCs, the result might be an excessive use of system resources on the

       publisher just to determine that these subscriptions should be declined. In

       such a situation, subscription interactions MAY be terminated by

       terminating the transport session.

   RPC: delete-subscription

   o  No special considerations.

   RPC: establish-subscription

   o  Subscriptions could overload a publisher's resources.  For this

      reason, Publishers MUST ensure that they have sufficient resources

      to fulfill this request or otherwise reject the request.

   RPC: kill-subscription

   o  The "kill-subscription" RPC MUST be secured so that only

      connections with administrative rights are able to invoke this

      RPC.

   RPC: modify-subscription

   o  Subscriptions could overload a publisher's resources.  For this

      reason, Publishers MUST ensure that they have sufficient resources

      to fulfill this request or otherwise reject the request.

<KENT> better, though I'm unsure the "none" nodes need to be listed.

>   Regarding the 2nd and 3rd paragraphs, this sounds good, but isn't

>   this behavior already defined by the draft?  (or should be?)

Yes they are.   I actually refined / incorporated these points in the template above.  As this is what the template appears to be asking to have.

<KENT> thx

>   Regarding the 4th paragraph, why would the publisher need to the

>   terminate the transport session?  wouldn't it have started to

>   reject dynamic subscriptions when it became overloaded?  Or is

>   this trying to say something specific about dropping the transport

>   session as a club?  ;)

Yes, as a club.  Moved this up into the template as part of “RFC: all” and fixed the text to show why the club might need to be used

<KENT> thx

>   Re: the 5th paragraph, this is better than the 1st paragraph, but

>   may not be needed if following the template.

Agree.  This is redundant, and the point is covered as per the template above.

<KENT> thx

>   Re: the 6th paragraph, I'm surprised that requirements for transport-

>   bindings wasn't discussed before in its own section.  It seems like

>   a new thing here, that a receiver's transport might not be secure.

>   I'm okay with and support this, btw, as its sometimes better to

>   offload devices thru the use of a local collector node, for which

>   encryption may not be needed...

Agree with your comments.

<KENT> but where's the change?  Shouldn't this have been discussed

previously in the draft somewhere?

>   Re: the 7th paragraph, this was said before also, right?

Correct, removed.

<KENT> thx

>   Re: 2nd to last paragraph, what is the " very-secure" tag?

Removed, and the overall points moved up into template.  As for the very-secure tag, Andy had mentioned that a few years ago.   It looks like it wasn’t standardized.

<KENT> gotcha

Eric

/kw

---

From: "Eric Voit (evoit)" <[email-masked]>
Date: Mon, 9 Apr 2018 22:31:41 +0000

Hi Kent,

Thanks for the feedback.  Look for thoughts at <Eric2> In-line...

Also everything documented below which made it into the working copy can be seen at:
https://github.com/netconf-wg/rfc5277bis/blob/master/draft-ietf-netconf-subscribed-notifications-12.txt

From: Kent Watsen, April 6, 2018 11:33 PM

Alex/Eric,

Thanks,
Kent  // as a contributor

Thanks
--- Alex

From: Netconf <[email-masked]<mailto:[email-masked]>> On Behalf Of Eric Voit (evoit)
Sent: Friday, March 16, 2018 11:41 AM
To: Kent Watsen <[email-masked]<mailto:[email-masked]>>; [email-masked]<mailto:[email-masked]>
Subject: Re: [Netconf] LC on subscribed-notifications-10

Hi Kent,

Still pending:

- Martin’s comments

- YANG doctor comments

Will do

<KENT> fine

<Eric2>  Your text is adopted.

Tweaked

<KENT> thx

<Eric2>  Your text is adopted.

updated

<KENT> thx

updated

<KENT> thx

updated

<KENT> thx

updated

<KENT> thx

Updated

<KENT> thx

<KENT> works for me

How about:

<Eric2> Comma removed.

Done

<KENT> thx

Done.

<KENT> thx

<KENT> thx

****

<Eric2>  To make thing unambiguous, and to progress towards closure, I converted to “event stream”.  You can see the results in:
https://github.com/netconf-wg/rfc5277bis/blob/master/draft-ietf-netconf-subscribed-notifications-12.txt

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> thx

Made: "is able"

<KENT> thx

Made "is not able"

<KENT> thx

Updated

<KENT> thanks

Done

<KENT> thx

Made it:

<KENT> thx

Chose: transports

<KENT> thx

<KENT> okay

Done

<KENT> thx

<Eric> Further tweaking of the wording happened with Martin.   Including your suggestion above, it now says:

“the data model in this document is used instead of the data model in Section 3.4 of [RFC5277]  for the new operations.”

<Eric>  As RFC5277’s notification capability is still always used, some modifier is needed to show what actually can and cannot be used together between the drafts.  Not sure how to simplify more.

****

<Eric2>  I should have pointed out that comments very early in the review cycle had me pull the introduction of Section 2 just above into Section 1.3 “Solution Overview”.    So placing details here initially seemed redundant.

So to cover your request, I just added to the beginning of Section 2: “Per the overview provided in Section 1.3, this section details the overall context, state machines, and subsystems which may be assembled to allow the subscription of events from a publisher.”

****

</ALEX>

<Eric2> Made this change.  Text now says:

There is only one reserved event stream name within this document: "NETCONF".  The "NETCONF" event stream contains all NETCONF XML event record information supported by the publisher, except for the subscription state notifications described in Section 2.7.  Among these included NETCONF XML event records are individual YANG 1.1 notifications described in section 7.16 of [RFC7950].  Each of these YANG 1.1 notifications will be treated as a distinct event record.

Done

<KENT> thx

****

<KENT> I like it

****

Snippet 1:

<KENT> fine

Snippet 2

<KENT> also fine

<KENT> good

ok

<KENT> thx

****

Done

<KENT> thx

Removed

<KENT> thx

<Eric2> I kind of like the simplicity of the current text.  Will change if you have a very strong preference.

<Eric2> Text now says:

The two state change notifications "subscription-suspended" and "subscription-resumed" are shown.  These are under the control of a publisher. These are the only two state change notifications which indicate a change in state of a dynamic subscription.

<Eric2> My reading of your comment is that you don’t like the identification of the “suspend subscription” transition cause via the “subscription-suspended*” notification.   To clarify, I have removed all state change notifications from the diagram, and described them in the text below...

                        .........
                        : start :
                        :.......:
                            |
                   establish-subscription
                            |
                            |   .------modify-subscription-------.
                            v   v                                |
                      .-----------.                        .-----------.
           .--------. | receiver  |--suspend-subscription->| receiver  |
       modify-       '|  ACTIVE   |                        | SUSPENDED |
       subscription   |           |<--resume-subscription--|           |
           ---------->'-----------'                        '-----------'
                            |                                    |
                 delete/kill-subscription                   delete/kill-
                            |                               subscription
                            v                                    |
                        .........                                |
                        :  end  :<-------------------------------'
                        :.......:

          Figure 1: Publisher's state for a dynamic subscription

Of interest in this state machine are the following:
...(snip)...

   o  A publisher may choose to suspend a subscription, this is notified to a subscriber with a "subscription-suspended" state change notification.

   o  A resume subscription state change is notified to a subscriber "subscription-resumed". There are no direct external controls over resuming a subscription other than for a subscriber to attempt the modification of a subscription in a way which reduces the resources consumed.

<Eric2> Done, above

<KENT> okay

Yes

Morphed to:

<KENT> good

<KENT> better

<Eric2> With the tool Martin pointed me to for automatically generating to a fixed column width, life is much easier now.

<KENT> good.

****

and

Is this what you prefer?

</ALEX>

Yes

<Eric2> In the netconf-notif draft, it is in Section 8.   The text including this is not yet published in Restconf-notif.

<KENT> fine

<Eric2> Yes, I dropped it.  Re-added.

****

<Eric2>   Yes later dialogs with Martin convinced me exactly that another round-trip can drive churn unnecessarily.   The latest version posted starts replay immediately.   To cover the issue discussed above, there is a new parameter returned *only* if the replay start time has been modified.   This parameter is: “replay-start-time-revision”.

Done

<Eric2> I don’t see “also” in the current v11.

<Eric2> corrected before the current v11.

Made it:

<eric2>  Based on other comments, it now is: To assess the timeframe available for replay, subscribers can read the leafs  "replay-log-creation-time" and "replay-log-aged-time".

<KENT> agreed.

Done

<KENT> thx

Chose "any number"

<KENT> thx

Done

<KENT> thx

<KENT> excellent

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

Done

<KENT> thx

<KENT> better

<KENT> okay…

<eric2> Understood.  Didn’t know how to do that and not introduce a publication dependency.

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

****

<Eric2> I placed a two forward references in v11.  One is to Figure 20 for the tree, the other is to the YANG model.

Used your text.  Done.

<KENT> thx

<Eric2> Based on further comments on the various options, broke specific parameters to bulleted text.  Your text is still used.

Now says:

<Eric2> Good catch.  Not sure where that went.  Re-added.

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> yes

<KENT> better

.........

: start :-.

:.......: |

          |  |               |                                  |

 |        ^          |      |                |                 |

 |        |                 |                |                 |

 |       (1)               (2)              (3)               (4)

'-->|                         VALID                                 |

Legend:

<KENT> better

<KENT> okay

<Eric2> Tweaked to “Receiver state for a configured subscription on a Publisher”

<KENT> thx

<KENT> good

****

 <KENT> thx

Done

<KENT> thx

     |                         VALID                                   |

     |   .----------.                           .--------.             |

     |      (1)          |         |                                   |

     |  subscription-   (3)        |                                   |

  Legend:

Done

<KENT> thx

Revised text to:

<KENT> better, but:

<Eric2>   I think you are suggesting that the YANG push tree model in 4.1 needs to point to the YANG model section number.  And that perhaps the YANG model section itself shouldn’t be in an independent top level section, but rather fall into section 4.     I have no issues with that.   **Alex, do you want to update, this should be a very minor update?

<Eric2> Adopted your text.

<KENT> thx

<Eric2>  For a configured subscription, transport can safely come/go as long as events are not lost or delayed because a connection with a receiver is unavailable.   Instead it is whether events are dropped before they can be transmitted.

To support this, the text says:

“However if there is buffer overflow, or the publisher cannot generate notification messages for a receiver, the receiver MUST be moved to SUSPENDED (2).”   The result is that a receiver will know that event records may have been lost if a subscription-suspended and/or subscription-resumed are received.    On such a resume, a subscriber can attempt a replay if it needs the older events.

Done

<KENT> thx

Added the sentence:

<KENT> thx

<KENT> okay, but where did the following new paragraph come from?

<Eric2> WG threads/dialogs with Martin.

Also:

<Eric2> Don’t see that text.  Looks like it was cleaned up already.

Yes

<KENT> good

<KENT> okay

<Eric2> Yes.  And we do have that intermixing included in document requirements within this section.   Text says:

“In all cases, a single transport session MUST be capable of supporting the intermixing of RPCs and notifications from different subscriptions.”

I think that change was made after conversations with Martin, so it didn’t come back explicitly via this subthread.

Done

<KENT> thx

Yes.   Made text:

<KENT> good

removed

<KENT> thx

<KENT> thx

Done

<KENT> thx

<Eric2> Subscription state notifications are a type of YANG notification, as they are encoded in the YANG model.  Per the London WG discussion on slide “Question 2”, I believe it easier to mark these.  See next comment below.

****

</ALEX>

<Eric2> We had a discussion on this in London:

https://youtu.be/KJtg-J-6CZM?t=1963

As there was no comment in the room, I was hoping we had actually had some form of consensus between us on (a).   So I hadn’t spun up a separate question on this yet.

But it seems there is an issue.  I will open up a thread now.

****

<Eric2> I can find no “after the after” in v11.  Perhaps I already fixed this.

<Eric2> Adopted your text.

<Eric2>   Rewrote to: “The leading event record sent will be the first event record subsequent to the latest of four different times: the "replay-log-creation-time", "replay-log-aged-time", "replay-start-time", or the most recent publisher boot time.”

<Eric2> I initially had all the text in 2.4.2.1.  But this hid the fact that you can do replay on a configured subscription.  So your comment above lead to this section being introduced.  Which is a good thing.   But as 2.4.2.1 is not very small, to me it feels like repeating all that text here might be overkill.

<KENT> thankfully!

Done

<KENT> thx

<KENT> okay

<KENT> thx

Made a numbered list

<KENT> thx

<KENT> better

Done

 <KENT> thx

Done

 <KENT> thx

<KENT> good

<KENT> okay

Done

<KENT> thx

Done.

<KENT> thx

<KENT> good

Done

<KENT> thx

   within Section 4.

          +--ro reason        identityref

<KENT> good

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> thx

Done.

<KENT> thx

<KENT> thx

Updated paragraph 2 to:

<KENT> thx

<KENT> but if not active, aka operational, why are they in the operational datastore?  This needs to be explained.

<Eric2> Two thoughts.  First, a configured subscription can be VALID without having any ACTIVE receivers. Second, the status of a configured subscription is a “config false” element which includes both the INVALID and CONCLUDED states that are not configurable.  (text below)

Also, maybe you need to be more explicit than just having "all" …

<Eric2> You are correct, some more detail is needed.  And more description of the counters is needed.  I shook things up.  Here is what it says now:

In the operational datastore, the container "subscriptions" maintains the state of all dynamic subscriptions, as well as all configured subscriptions.  Using datastore retrieval operations, or subscribing to the "subscriptions" container via [I-D.ietf-netconf-yang-push] allows the state of subscriptions and their connectivity to receivers to be monitored.

Each subscription in the operational datastore is represented as a list element. Included in this list are event counters for each receiver, the state of each receiver, as well as the  subscription parameters currently in effect. The appearance of the leaf "configured-subscription-state" indicates that a particular subscription came into being via configuration.  This leaf also indicates if current state of that subscription is VALID,  INVALID, and CONCLUDED.

To understand the flow of event records within a subscription, there are two counters available for each receiver.  The first counter is "pushed-notifications" which shows the quantity of events actually identified for sending to a receiver.  The second counter is "excluded-notifications" which shows event records not sent to receiver.  "excluded-notifications" shows the combined results of both access control and per-subscription filtering.  For configured subscriptions, counters are reset whenever the subscription is evaluated to VALID (see (1) in Figure 8).

Dynamic subscriptions do not appear outside of the operational datastore, and are removed from the operational datastore once they expire (reaching stop-time) or when they are terminated.

<KENT> better

<Eric2> References to Figure 20 has been made.   If the tree must be moved up, it can be.   I think it fits better where it is.

<KENT> thx

Makes sense

<Eric2> I did this.   Current section “Compatibility with RFC-5277's create-subscription” of NETCONF-notif says:

If a publisher supports this specification but not subscriptions via [RFC5277], the publisher MUST NOT advertise "urn:ietf:params:netconf:capability:notification:1.0".

Done

<KENT> thx

Made it:

<KENT> thx

Done

<KENT> thx

<KENT> thx

<Eric2> I have not seen automated tooling from pyang which pulls individual RPCs and Notification Trees into extracts.  Not finding a way to do this with –tree-path, I tried guessing.  But didn’t get there.   As the majority of my trees are RPCs and Notifications, I don’t see a fully automated solution available as yet.

Removed

Done

<KENT> thx

Now just referenced

 <KENT> thx

<Eric2> Martin taught me how to fold/path.  So that is a welcome fix.

<Eric2>  My environment has certainly shown itself to be insufficient.  If WG requires Makefiles rather than what many of us use (yes, I really built most of this via NOTEPAD++, and I know there are multiple others doing this), then the WG should document expected toolsets to be used.  Note that based on my pain here that I do have my eye on an alternative tooling after these 3 drafts complete WGLC.  If there is a lull subsequent review cycles, perhaps I will convert if my experiences with the next set of drafts work.

<Eric2> Would the NETMOD WG be willing to put together a wiki of the development tool recommendations?    As a user, I know it would be welcomed.

Done

<KENT> thx

Done

 <KENT> thx

Yes it does solve it.

<KENT> thx

Agree.  Text now says:

<KENT> thx

No.  Deleted.

<KENT> thx

Made it non-normative

<KENT> thx

<KENT> thx

Restructured to this:

   [RFC5246].

   operations and content.

   Container: filters

   Container: subscriptions

      receiver.

      unimportant.

      warranted.

   o  encoding: none

      another entity.

   o  port: none

   o  protocol: none

   o  purpose: none

      resources.

      content.

   o  stop-time: none

   o  stream: none

      other subscriptions.

   Container: streams

      information.

   Container: subscriptions

   RPC: all

   RPC: delete-subscription

   RPC: kill-subscription

      RPC.

   RPC: modify-subscription

 <Eric2> The template text  “These are the subtrees and data nodes and their sensitivity/vulnerability” appears to make the list of all node mandatory.  As this was not your intent, I pulled the “none” out.

<KENT> thx

<KENT> thx

<KENT> thx

<Eric2> The vast majority of transport binding discussions are addressed in the transport document.  So I see this as guidance to a documenter of a transport document.  Perhaps that is unnecessary for this document, and the paragraph should be removed.  I would be fine with that.

Correct, removed.

<KENT> thx

<KENT> gotcha

<Eric2>  Thanks again for your time on this.  I see these as good additions...

Eric

Eric

/kw

---

From: Alexander Clemm <[email-masked]>
Date: Tue, 10 Apr 2018 22:52:13 +0000

Hi,

in response to the **Alex question, per the below:

<KENT> better, but:

I am not clear what the ask is.  Section 4.1 depicts the data tree of YANG-push, which augments the model of subscribed-notifications.  We can mention the specific module names and indicate the sections where to find the YANG module definitions.  And if the YANG module itself should not be in a separate section 5, but instead in a subsection of 4 (i.e. 4.5), that is certainly an easy change.  Kent, is this what you mean?

Thanks
--- Alex

From: Netconf [mailto:[email-masked]] On Behalf Of Eric Voit (evoit)
Sent: Monday, April 09, 2018 3:32 PM
To: Kent Watsen <[email-masked]>; Alexander Clemm <[email-masked]>; [email-masked]
Subject: Re: [Netconf] LC on subscribed-notifications-10

Hi Kent,

Thanks,
Kent  // as a contributor

Thanks
--- Alex

Hi Kent,

Still pending:

- Martin’s comments

- YANG doctor comments

Will do

<KENT> fine

Tweaked

<KENT> thx

updated

<KENT> thx

updated

<KENT> thx

updated

<KENT> thx

updated

<KENT> thx

Updated

<KENT> thx

<KENT> works for me

How about:

<Eric2> Comma removed.

Done

<KENT> thx

Done.

<KENT> thx

<KENT> thx

****

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> thx

Made: "is able"

<KENT> thx

Made "is not able"

<KENT> thx

Updated

<KENT> thanks

Done

<KENT> thx

Made it:

<KENT> thx

Chose: transports

<KENT> thx

<KENT> okay

Done

<KENT> thx

****

****

</ALEX>

Done

<KENT> thx

****

<KENT> I like it

****

Snippet 1:

<KENT> fine

Snippet 2

<KENT> also fine

<KENT> good

ok

<KENT> thx

****

Done

<KENT> thx

Removed

<KENT> thx

<Eric2> Text now says:

                        .........
                        : start :
                        :.......:
                            |
                   establish-subscription
                            |

<Eric2> Done, above

<KENT> okay

Yes

Morphed to:

<KENT> good

<KENT> better

<KENT> good.

****

and

Is this what you prefer?

</ALEX>

Yes

<KENT> fine

****

Done

Made it:

<KENT> agreed.

Done

<KENT> thx

Chose "any number"

<KENT> thx

Done

<KENT> thx

<KENT> excellent

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

Done

<KENT> thx

<KENT> better

<KENT> okay…

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

****

Used your text.  Done.

<KENT> thx

Now says:

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> yes

<KENT> better

.........

: start :-.

:.......: |

          |  |               |                                  |

 |        ^          |      |                |                 |

 |        |                 |                |                 |

 |       (1)               (2)              (3)               (4)

'-->|                         VALID                                 |

Legend:

<KENT> better

<KENT> okay

<KENT> thx

<KENT> good

****

 <KENT> thx

Done

<KENT> thx

     |                         VALID                                   |

     |      (1)          |         |                                   |

     |  subscription-   (3)        |                                   |

  Legend:

Done

<KENT> thx

Revised text to:

<KENT> better, but:

<KENT> thx

Done

<KENT> thx

Added the sentence:

<KENT> thx

Also:

Yes

<KENT> good

<KENT> okay

Done

<KENT> thx

Yes.   Made text:

<KENT> good

removed

<KENT> thx

<KENT> thx

Done

<KENT> thx

****

</ALEX>

****

<KENT> thankfully!

Done

<KENT> thx

<KENT> okay

<KENT> thx

Made a numbered list

<KENT> thx

<KENT> better

Done

 <KENT> thx

Done

 <KENT> thx

<KENT> good

<KENT> okay

Done

<KENT> thx

Done.

<KENT> thx

<KENT> good

Done

<KENT> thx

   within Section 4.

          +--ro reason        identityref

<KENT> good

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> thx

Done.

<KENT> thx

<KENT> thx

Updated paragraph 2 to:

<KENT> thx

<KENT> better

<KENT> thx

Makes sense

Done

<KENT> thx

Made it:

<KENT> thx

Done

<KENT> thx

<KENT> thx

Removed

Done

<KENT> thx

Now just referenced

 <KENT> thx

Done

<KENT> thx

Done

 <KENT> thx

Yes it does solve it.

<KENT> thx

Agree.  Text now says:

<KENT> thx

No.  Deleted.

<KENT> thx

Made it non-normative

<KENT> thx

<KENT> thx

Restructured to this:

   [RFC5246].

   operations and content.

   Container: filters

   Container: subscriptions

      receiver.

      unimportant.

      warranted.

   o  encoding: none

      another entity.

   o  port: none

   o  protocol: none

   o  purpose: none

      resources.

      content.

   o  stop-time: none

   o  stream: none

      other subscriptions.

   Container: streams

      information.

   Container: subscriptions

   RPC: all

   RPC: delete-subscription

   RPC: kill-subscription

      RPC.

   RPC: modify-subscription

<KENT> thx

<KENT> thx

<KENT> thx

Correct, removed.

<KENT> thx

<KENT> gotcha

Eric

Eric

/kw

---

From: Kent Watsen <[email-masked]>
Date: Tue, 17 Apr 2018 19:54:55 +0000

I was making two comments:

1) when tree diagrams are listed, it is generally a good idea to introduce that as being the tree diagram for a specific YANG module (or part thereof).  When in the same draft, this is most easily accomplished via an <xref/>.

2) as Alex says, that maybe the YANG module itself should not be in a separate section 5, but instead in a subsection of 4 (i.e. 4.5).  At least, I was thinking that it might be better - what do you think?

K.

On 4/10/18, 6:52 PM, "Alexander Clemm" <[email-masked]<mailto:[email-masked]>> wrote:

Hi,

<KENT> better, but:

Thanks
--- Alex

Hi Kent,

Also everything documented below which made it into the working copy can be seen at:
https://github.com/netconf-wg/rfc5277bis/blob/master/draft-ietf-netconf-subscribed-notifications-12.txt<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_netconf-2Dwg_rfc5277bis_blob_master_draft-2Dietf-2Dnetconf-2Dsubscribed-2Dnotifications-2D12.txt&d=DwMGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=oBsUxRB22EwhHm6c_dTajdFXC5e_oOcw5sUNOIOmkX4&s=7h5447JFGtcGfuqr09g-QIYM4v9EA6cviiZh42gfk0Y&e=>

Thanks,
Kent  // as a contributor

Thanks
--- Alex

Hi Kent,

Still pending:

- Martin’s comments

- YANG doctor comments

Will do

<KENT> fine

Tweaked

<KENT> thx

updated

<KENT> thx

updated

<KENT> thx

updated

<KENT> thx

updated

<KENT> thx

Updated

<KENT> thx

<KENT> works for me

How about:

<Eric2> Comma removed.

Done

<KENT> thx

Done.

<KENT> thx

<KENT> thx

****

<Eric2>  To make thing unambiguous, and to progress towards closure, I converted to “event stream”.  You can see the results in:
https://github.com/netconf-wg/rfc5277bis/blob/master/draft-ietf-netconf-subscribed-notifications-12.txt<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_netconf-2Dwg_rfc5277bis_blob_master_draft-2Dietf-2Dnetconf-2Dsubscribed-2Dnotifications-2D12.txt&d=DwMGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=oBsUxRB22EwhHm6c_dTajdFXC5e_oOcw5sUNOIOmkX4&s=7h5447JFGtcGfuqr09g-QIYM4v9EA6cviiZh42gfk0Y&e=>

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> thx

Made: "is able"

<KENT> thx

Made "is not able"

<KENT> thx

Updated

<KENT> thanks

Done

<KENT> thx

Made it:

<KENT> thx

Chose: transports

<KENT> thx

<KENT> okay

Done

<KENT> thx

****

****

</ALEX>

Done

<KENT> thx

****

<KENT> I like it

****

Snippet 1:

<KENT> fine

Snippet 2

<KENT> also fine

<KENT> good

ok

<KENT> thx

****

Done

<KENT> thx

Removed

<KENT> thx

<Eric2> Text now says:

                        .........
                        : start :
                        :.......:
                            |
                   establish-subscription
                            |

<Eric2> Done, above

<KENT> okay

Yes

Morphed to:

<KENT> good

<KENT> better

<KENT> good.

****

and

Is this what you prefer?

</ALEX>

Yes

<KENT> fine

****

Done

Made it:

<KENT> agreed.

Done

<KENT> thx

Chose "any number"

<KENT> thx

Done

<KENT> thx

<KENT> excellent

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

Done

<KENT> thx

<KENT> better

<KENT> okay…

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

****

Used your text.  Done.

<KENT> thx

Now says:

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> yes

<KENT> better

.........

: start :-.

:.......: |

          |  |               |                                  |

 |        ^          |      |                |                 |

 |        |                 |                |                 |

 |       (1)               (2)              (3)               (4)

'-->|                         VALID                                 |

Legend:

<KENT> better

<KENT> okay

<KENT> thx

<KENT> good

****

 <KENT> thx

Done

<KENT> thx

     |                         VALID                                   |

     |      (1)          |         |                                   |

     |  subscription-   (3)        |                                   |

  Legend:

Done

<KENT> thx

Revised text to:

<KENT> better, but:

<KENT> thx

Done

<KENT> thx

Added the sentence:

<KENT> thx

Also:

Yes

<KENT> good

<KENT> okay

Done

<KENT> thx

Yes.   Made text:

<KENT> good

removed

<KENT> thx

<KENT> thx

Done

<KENT> thx

****

</ALEX>

https://youtu.be/KJtg-J-6CZM?t=1963<https://urldefense.proofpoint.com/v2/url?u=https-3A__youtu.be_KJtg-2DJ-2D6CZM-3Ft-3D1963&d=DwMGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=oBsUxRB22EwhHm6c_dTajdFXC5e_oOcw5sUNOIOmkX4&s=6oSXNcYaJFZpeX7kH0rUNuHX0FiKjckNtQ9DzjnfrSU&e=>

****

<KENT> thankfully!

Done

<KENT> thx

<KENT> okay

<KENT> thx

Made a numbered list

<KENT> thx

<KENT> better

Done

 <KENT> thx

Done

 <KENT> thx

<KENT> good

<KENT> okay

Done

<KENT> thx

Done.

<KENT> thx

<KENT> good

Done

<KENT> thx

   within Section 4.

          +--ro reason        identityref

<KENT> good

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> thx

Done.

<KENT> thx

<KENT> thx

Updated paragraph 2 to:

<KENT> thx

<KENT> better

<KENT> thx

Makes sense

Done

<KENT> thx

Made it:

<KENT> thx

Done

<KENT> thx

<KENT> thx

Removed

Done

<KENT> thx

Now just referenced

 <KENT> thx

Done

<KENT> thx

Done

 <KENT> thx

Yes it does solve it.

<KENT> thx

Agree.  Text now says:

<KENT> thx

No.  Deleted.

<KENT> thx

Made it non-normative

<KENT> thx

<KENT> thx

Restructured to this:

   [RFC5246].

   operations and content.

   Container: filters

   Container: subscriptions

      receiver.

      unimportant.

      warranted.

   o  encoding: none

      another entity.

   o  port: none

   o  protocol: none

   o  purpose: none

      resources.

      content.

   o  stop-time: none

   o  stream: none

      other subscriptions.

   Container: streams

      information.

   Container: subscriptions

   RPC: all

   RPC: delete-subscription

   RPC: kill-subscription

      RPC.

   RPC: modify-subscription

<KENT> thx

<KENT> thx

<KENT> thx

Correct, removed.

<KENT> thx

<KENT> gotcha

Eric

Eric

/kw

---

From: Kent Watsen <[email-masked]>
Date: Tue, 17 Apr 2018 22:54:03 +0000

[just back from PTO]

Hi Eric,

Please see my follow-ups below: <Kent2>

Kent // as a contributor

On 4/9/18, 6:31 PM, "Eric Voit (evoit)" <[email-masked]<mailto:[email-masked]>> wrote:

Hi Kent,

Also everything documented below which made it into the working copy can be seen at:
https://github.com/netconf-wg/rfc5277bis/blob/master/draft-ietf-netconf-subscribed-notifications-12.txt<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_netconf-2Dwg_rfc5277bis_blob_master_draft-2Dietf-2Dnetconf-2Dsubscribed-2Dnotifications-2D12.txt&d=DwMGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=6hc_72tEh2fXZOBFRTk-tRPRujVYmmltu_pxFONHQCs&s=UONL_m1_J94PYNQraXzNK0Ma1G3hKFPThShVSIjd0M0&e=>

Thanks,
Kent  // as a contributor

Thanks
--- Alex

Hi Kent,

Still pending:

- Martin’s comments

- YANG doctor comments

Will do

<KENT> fine

<Kent2> thx

Tweaked

<KENT> thx

<Kent2> thx

updated

<KENT> thx

updated

<KENT> thx

updated

<KENT> thx

updated

<KENT> thx

Updated

<KENT> thx

<KENT> works for me

How about:

<Eric2> Comma removed.
<Kent2> thx

Done

<KENT> thx

Done.

<KENT> thx

<KENT> thx

****

<Eric2>  To make thing unambiguous, and to progress towards closure, I converted to “event stream”.  You can see the results in:
https://github.com/netconf-wg/rfc5277bis/blob/master/draft-ietf-netconf-subscribed-notifications-12.txt<https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_netconf-2Dwg_rfc5277bis_blob_master_draft-2Dietf-2Dnetconf-2Dsubscribed-2Dnotifications-2D12.txt&d=DwMGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=6hc_72tEh2fXZOBFRTk-tRPRujVYmmltu_pxFONHQCs&s=UONL_m1_J94PYNQraXzNK0Ma1G3hKFPThShVSIjd0M0&e=>

 <Kent2> thx

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> thx

Made: "is able"

<KENT> thx

Made "is not able"

<KENT> thx

Updated

<KENT> thanks

Done

<KENT> thx

Made it:

<KENT> thx

Chose: transports

<KENT> thx

<KENT> okay

Done

<KENT> thx

****

<Kent2> perfect.

****

</ALEX>

 <Kent2> thx

Done

<KENT> thx

****

<KENT> I like it

****

Snippet 1:

<KENT> fine

Snippet 2

<KENT> also fine

<KENT> good

ok

<KENT> thx

****

Done

<KENT> thx

Removed

<KENT> thx

<Eric2> I kind of like the simplicity of the current text.  Will change if you have a very strong preference.
<Kent2> not really, but keep an eye on if anyone stumbles over this section

<Eric2> Text now says:

 <Kent2> better, but s/only two state/only state/ - right?

                        .........
                        : start :
                        :.......:
                            |
                   establish-subscription
                            |

<Kent2> er, you said that the all state change notifications were removed from the diagram, but the diagram still looks the same to me, listing "suspend-subscription" and "resume-subscription".  Also, which is it, "resume-subscription" (in the diagram) or " subscription-resumed" in the text above?

<Eric2> Done, above

<Kent2> thx

<KENT> okay

Yes

Morphed to:

<KENT> good

<KENT> better

<Eric2> With the tool Martin pointed me to for automatically generating to a fixed column width, life is much easier now.
<Kent2> so now the tree-diagrams are automatically generated?

<KENT> good.

****

and

Is this what you prefer?

</ALEX>

Yes

<Eric2> In the netconf-notif draft, it is in Section 8.   The text including this is not yet published in Restconf-notif.
<Kent2> please add it to the restconf-notif doc now (strike while the iron is hot)

<KENT> fine

<Kent2> thx

****

<Kent2> okay

Done

 <Kent2> strange, okay

<Kent2> okay

Made it:

<Kent2> better

<KENT> agreed.

Done

<KENT> thx

Chose "any number"

<KENT> thx

Done

<KENT> thx

<KENT> excellent

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

Done

<KENT> thx

<KENT> better

<KENT> okay…

<eric2> Understood.  Didn’t know how to do that and not introduce a publication dependency.
<Kent2> it won't block publication if it's an Informational reference, but I continue to be uncomfortable about the restconf-notif documents not progressing.  It doesn't have to be published with these (though it would be better if it were), but it should be tracking the latest developments and what not…

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

****

<Kent2> better

Used your text.  Done.

<KENT> thx

<Kent2> okay

Now says:

 <Kent2> okay

Done

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> yes

<KENT> better

.........

: start :-.

:.......: |

          |  |               |                                  |

 |        ^          |      |                |                 |

 |        |                 |                |                 |

 |       (1)               (2)              (3)               (4)

'-->|                         VALID                                 |

Legend:

<KENT> better

<KENT> okay

 <Kent2> better

<KENT> thx

<KENT> good

****

 <KENT> thx

Done

<KENT> thx

     |                         VALID                                   |

     |      (1)          |         |                                   |

     |  subscription-   (3)        |                                   |

  Legend:

Done

<KENT> thx

Revised text to:

<KENT> better, but:

<Eric2>   I think you are suggesting that the YANG push tree model in 4.1 needs to point to the YANG model section number.  And that perhaps the YANG model section itself shouldn’t be in an independent top level section, but rather fall into section 4.     I have no issues with that.   **Alex, do you want to update, this should be a very minor update?
<Kent2> Alex responded in another email

<Kent2> thx

<KENT> thx

<Kent2> okay

Done

<KENT> thx

Added the sentence:

<KENT> thx

<Kent2> okay

Also:

<Kent2> okay

Yes

<KENT> good

<KENT> okay

<Kent2> okay, but the question isn't what's in this draft, but where in the restconf-notif draft is this requirement satisfied?

Done

<KENT> thx

Yes.   Made text:

<KENT> good

removed

<KENT> thx

<KENT> thx

Done

<KENT> thx

<Kent2> no, you're missing my point.  before you wrote that only Subscription State Notifications were not placed in the NETCONF stream, but that seems misleading if you also mean to include any notifications having the "subscription-state-notif" extension.

****

</ALEX>

https://youtu.be/KJtg-J-6CZM?t=1963<https://urldefense.proofpoint.com/v2/url?u=https-3A__youtu.be_KJtg-2DJ-2D6CZM-3Ft-3D1963&d=DwMGaQ&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=6hc_72tEh2fXZOBFRTk-tRPRujVYmmltu_pxFONHQCs&s=i43hXrkycPDoO1v9EUv0DdOmQe7TkbG9rpTtams9rMI&e=>

<Kent2> I just responded to that "thread"

****

<Kent2> not in the draft, you wrote "after the after" three lines above…  ;)

<Kent2> thx

<Eric2>   Rewrote to: “The leading event record sent will be the first event record subsequent to the latest of four different times: the "replay-log-creation-time", "replay-log-aged-time", "replay-start-time", or the most recent publisher boot time.”
<Kent2> Still confusing.   I think that you may need to expand this into a paragraph where you more carefully discuss the four times and how they're used here, or perhaps use an example to explain it…

<Kent2> hmmm, maybe factor the relevant text in 2.4.2.1 to yet another section and have both refer to it instead?

<KENT> thankfully!

Done

<KENT> thx

<KENT> okay

<KENT> thx

Made a numbered list

<KENT> thx

<KENT> better

Done

 <KENT> thx

Done

 <KENT> thx

<KENT> good

<KENT> okay

Done

<KENT> thx

Done.

<KENT> thx

<KENT> good

Done

<KENT> thx

   within Section 4.

          +--ro reason        identityref

<KENT> good

<KENT> thx

<KENT> thx

Done

<KENT> thx

<KENT> thx

Done.

<KENT> thx

<KENT> thx

Updated paragraph 2 to:

<KENT> thx

<Kent2> see below

<Kent2> better.  Though I wonder if it's possible for "excluded-notifications" to have an accurate count.  Assuming access-control affects the subscription request (not per-notification filtering), then this info may not be known.

<KENT> better

<Kent2> reference by figure-number is okay, but you might want to also again which section the figure appears in.

<KENT> thx

Makes sense

<Kent2> okay

Done

<KENT> thx

Made it:

<KENT> thx

Done

<KENT> thx

<KENT> thx

<Kent2> right, this is why I wrote "and shell scripts".  I sometimes post-process the pyang tree output to e.g., cherry-pick something…

Removed

Done

<KENT> thx

Now just referenced

 <KENT> thx

<kent2> good

<Kent2> The WG does not require Makefiles or any particular environment, but we do require that the drafts are accurate, and history has shown that tree-diagrams/modules/examples are commonly not accurate and yet easy to automate generation/validation for.   Most people doing this use Makefiles, and you're welcome to use or pilfer content from mine if you like (e.g., the zerotouch draft).   That said, I am working on something that might lead to tooling modifications, though I'd imagine it might take a couple years to get it to market…

<Kent2> Currently folks just copy/paste/modify with starting a new draft.  In lieu of anything else, I recommend folks copy from one of my current draft repos (as I'm always tweaking to make better).

Done

<KENT> thx

Done

 <KENT> thx

Yes it does solve it.

<KENT> thx

Agree.  Text now says:

<KENT> thx

No.  Deleted.

<KENT> thx

Made it non-normative

<KENT> thx

<KENT> thx

Restructured to this:

   [RFC5246].

   operations and content.

   Container: filters

   Container: subscriptions

      receiver.

      unimportant.

      warranted.

   o  encoding: none

      another entity.

   o  port: none

   o  protocol: none

   o  purpose: none

      resources.

      content.

   o  stop-time: none

   o  stream: none

      other subscriptions.

   Container: streams

      information.

   Container: subscriptions

   RPC: all

   RPC: delete-subscription

   RPC: kill-subscription

      RPC.

   RPC: modify-subscription

<Kent2> not my template, so it's not so much a question of my intent, per se.   But what I do is to call out the nodes with special considerations (i.e., having an NACM extension statement) and state that everything else isn't noteworthy.

<KENT> thx

<KENT> thx

<KENT> thx

<Kent2> wait, I don't think you can offload transport-requirements to the transport-binding documents.   I think that this document needs to define the requirements and the transport-binding documents then show how they adhere to them.   Does this make sense?

Correct, removed.

<KENT> thx

<KENT> gotcha

<Kent2> getting there!  :)

---

From: "Eric Voit (evoit)" <[email-masked]>
Date: Wed, 18 Apr 2018 02:56:49 +0000

Hi Kent,

Thanks again for the comments.  See [snip] where I removed closed items.   Everything else is in-line with <Eric3>...

From: Kent Watsen, April 17, 2018 6:54 PM

[just back from PTO]

Hi Eric,

Kent // as a contributor

Hi Kent,

[snip]

<Eric3> Will do...

<Eric2> Text now says:

<Eric3> I should have been more explicit and said these are the only two state change notifications which signal a new state for an ACTIVE dynamic subscription.  There are other state change notifications used, but they don’t indicate a state change when ACTIVE.

In any case, ‘two’ isn’t in the draft text itself, and the key question is hit within the point below.

                        .........
                        : start :
                        :.......:
                            |
                   establish-subscription
                            |

<Eric3>  I read your point <KENT> as you wanted to show the cause of the state transition (e.g., suspend subscription) rather than the resulting notification (e.g., “subscription-suspended”).  So what I was trying to do with the top part of the picture was to remove the names of the state change notifications, and just show the event which drives the subscription from one state to the other.  Otherwise the document would be confusing/overly-verbose if it tried to show both on a link (e.g., suspend subscription “subscription-suspended”) .

I can go back to the ‘*’ version of the diagram if you prefer.  Do you have a different suggestion?

[snip]

<eric3> Every tree was automatically generated just before posting.  The only hand editing was to remove extra “|” connectors between discrete Notifications & RPCs.

[snip]

Yes

<Eric3> It will be my next action after this email.

<KENT> okay…

<Eric3> I will do this first thing in the AM.

[snip]

Revised text to:

<KENT> better, but:

[snip]

Yes

<KENT> good

<KENT> okay

<Eric3> Per above, RESTCONF-notif is my first thing for tomorrow.   I am now feeling more comfortable I won’t be churning contexts there as the rest of the documents’ frameworks settle.

[snip]

<Eric3> I think we can let this get picked up by the “Question 2: Subscription State Notifications” thread which Alex needs to re-frame (per your email earlier today).

</ALEX>

<Eric3>  Yes, let’s track there.

[snip]

<Eric3>  Added the descriptive paragraph requested in the middle of the three paragraphs below...

It is possible to place a start time on a configured subscription.  This enables streaming of logged information immediately after restart.

Replay of events records created since restart can be quite useful.  This allows event records generated before transport connectivity was supportable by a publisher to be passed to a receiver.  In addition, event records logged before restart are not sent.  This avoids the potential for accidental event record duplication.  Such duplication might otherwise be likely as a configured subscription’s identifier before and after the reboot is the same, and there may be not be evidence to a receiver that a restart has occurred.  By establishing restart as the earliest potential time for event records to be included in notification messages, a well-understood timeframe for replay is defined.

Therefore, when configured replay subscription receivers first become ACTIVE, buffered event records (if any) will be sent immediately after the "subscription-started" notification.  And the leading event record sent will be the first event record subsequent to the latest of four different times: the "replay-log-creation-time", "replay-log-aged-time", "replay-start-time", or the most recent publisher boot time.

<Eric3> If we move the relevant Replay to a new Section just before 2.6, then we create harder difficulties.   For example, there are establish-subscription errors specific to replay in Section 2.4 -- we shouldn’t talk about these errors before replay is introduced.   And if we tried to fix this by replicating a different table for establish-subscription errors related to replay, we would confuse to readers.  I believe the current partitioning is a reasonable approach.

[snip]

<Kent2> see below

<Eric2> It should be knowable.  You can count how many were sent to a receiver. You can tell how came in from event stream since subscription start.    If the number of exclusions is protected information, the “excluded-notifications” object could be access protected.

[snip]

<Eric3>  Now says:

   A tree diagram describing these parameters is shown in Figure 20
   within Section 3.3.

[snip]

[snip]

<Eric3> Right now I am depending on:

pyang -f tree  ietf-subscribed-notifications.yang ietf-yang-push.yang  --tree-line-length 69

As I learn a new YANG tooling environment as I work with the notification-messages draft, I might be able to back-port my learnings with shell scripts.

[snip]

<Eric3>  Ok,  I tweaked the template to say:

These are the subtrees and data nodes where there is a specific sensitivity/vulnerability:

[snip]

 <Eric3>With the varied transports of NETCONF, HTTP/RESTCONF, UDP, CoAP already in drafts my belief is that only a high level subset of transport requirements spanning the universe of potential transports can potentially be abstracted in this document.  The secure transport requirement is one such example, and that is a recommendation.  The Security Considerations section is a good place for that one.  Beyond the security recommendation there aren’t too many transport independent possibilities.   I did just added one new transport requirement to the very end of “Event Streams” section though (which perhaps wasn’t explicit enough elsewhere).  This requirement is:

“Event records MUST NOT be delivered to a receiver in a different order than they were placed onto an event stream.”

What other transport-independent transport requirements might there be which are not already documented?

Stepping back, I see the transport draft plus this drafts providing the aggregate set of requirements for a full solution.  And I had thought it would be up to the draft authors plus WGs to validate that the sum of the documents is sufficient.

[snip]

<KENT> gotcha

[Eric3]  Thanks again!

Eric3

---

From: "t.petch" <[email-masked]>
Date: Thu, 19 Apr 2018 12:41:44 +0100

Eric

I see some quirks in this I-D that I think need fixing

It lacks a note to the RFC Editor asking that XXXX be replaced with the
number assigned to the I-D

It lacks a note to the RFC Editor asking that the two dates in the YANG
module be replaced with the date of publication

I see no Copyright in the YANG module

The YANG module references

6991
7223  (which is  superseded)
7951
7540

none of which I see in the References of the I-D

Good practice is to have a section just before the YANG module itself
which lists the documents from whiuch imports are made or to which
references are made (if you simply add RFC6991 as a Reference, you will
get an unused Reference error).  See, for example, RFC8344

There are a number of Informative References which I think should be
Normative namely
8040
5246
6241
6242
7950

Tom Petch

---

From: "Eric Voit (evoit)" <[email-masked]>
Date: Thu, 19 Apr 2018 14:48:56 +0000

Hi Tom,

Thanks for the review.  You can see the updated draft at:
https://github.com/netconf-wg/rfc5277bis/blob/master/draft-ietf-netconf-subscribed-notifications-13.txt 

Some details inline...

> -----Original Message-----
> From: t.petch, April 19, 2018 7:42 AM
> To: Eric Voit (evoit) <[email-masked]>; Kent Watsen <[email-masked]>;
> Alexander Clemm <[email-masked]>; [email-masked]
> Subject: subscribed-notifications-12
> 
> Eric
> 
> It lacks a note to the RFC Editor asking that XXXX be replaced with the number
> assigned to the I-D

Placed this at the front of the section leading in to the YANG model

> It lacks a note to the RFC Editor asking that the two dates in the YANG module
> be replaced with the date of publication

Placed this at the front of the section leading in to the YANG model
 
> none of which I see in the References of the I-D

Fixed.
 
> Good practice is to have a section just before the YANG module itself which
> lists the documents from whiuch imports are made or to which references are
> made (if you simply add RFC6991 as a Reference, you will get an unused
> Reference error).  See, for example, RFC8344

Done.  

> There are a number of Informative References which I think should be

Done.  Agree this should be Normative based on the use of yang-data.

Done.

Done

Done

I believe this one is an informative reference.  I.e., the reference in the YANG model is to an example of analogous behavior from HTTP2.  My reading of rfc7950 section 7.21.4 doesn't seem to require a reference to be normative.  If it does, I can move the information into the description. 

Thanks again,
Eric

---

From: "t.petch" <[email-masked]>
Date: Fri, 20 Apr 2018 11:08:54 +0100

Eric

OK so far.

I am puzzled by the features for encoding.

I can see four cases for a publisher; no features, encode-xml and
encode-json, encode-xml only, encode-json only.

The first case seems clear; the stream uses the encoding of the
subscription.

The second also seems clear; the subscriber can choose either encoding.

The third and the fourth puzzle me.  If only encode-xml is present, and
the subscription is in xml, then the stream will be in xml, whether or
not the encoding is specified.  If the subscription is in json, and the
encoding is not specified, then the stream will be in json.  If the
subscription is in json and the encoding is specified as xml, then the
stream will be in xml.

If only encode-json is present, then it is vice versa, mutatis mutandis.

I find this an odd combination to specificy.

Tom Petch

----- Original Message -----
From: "Eric Voit (evoit)" <[email-masked]>
To: "t.petch" <[email-masked]>
Sent: Thursday, April 19, 2018 3:48 PM

> Thanks for the review.  You can see the updated draft at:
https://github.com/netconf-wg/rfc5277bis/blob/master/draft-ietf-netconf-
subscribed-notifications-13.txt
> I believe this one is an informative reference.  I.e., the reference
in the YANG model is to an example of analogous behavior from HTTP2.  My
reading of rfc7950 section 7.21.4 doesn't seem to require a reference to
be normative.  If it does, I can move the information into the
description.

---

From: "Eric Voit (evoit)" <[email-masked]>
Date: Fri, 20 Apr 2018 17:23:59 +0000

Hi Tom,

> From: t.petch, April 20, 2018 6:09 AM
> 
> Eric
> 
> OK so far.
> 
> I can see four cases for a publisher; no features, encode-xml and encode-json,
> encode-xml only, encode-json only.
> 
> The first case seems clear; the stream uses the encoding of the subscription.
> 
> The third and the fourth puzzle me.  If only encode-xml is present, and the
> subscription is in xml, then the stream will be in xml, whether or not the
> encoding is specified.  If the subscription is in json, and the encoding is not
> specified, then the stream will be in json.  If the subscription is in json and the
> encoding is specified as xml, then the stream will be in xml.
> 

The ability to specify a particular encoding also is a function of  valid combinations of transport+encoding.  Independently of subscription, this general issue was recently articulated by Juergen:
https://www.ietf.org/mail-archive/web/netconf/current/msg14395.html 

To handle this in subscribed-notifications, a subscription is unable to select an encoding when alternative encodings are not supported on a selected transport.  The solution to this was proposed by Martin in:
https://www.ietf.org/mail-archive/web/netconf/current/msg14402.html
(search for "configurable-encoding")

So here are the specifics:

    leaf encoding {
      when 'derived-from(../transport, "sn:configurable-encoding")';
          ...
    }

This means that leaf encoding can only be set when the transport allows for configurable encodings.  So getting back to your third and fourth cases, the transport identity "netconf" does not have "configurable-encoding"*.  So these cases are explicitly not allowed for NETCONF.   Where there are transports where multiple encodings are possible (how often we will see this is TBD), we add a new error identity to the transport specific YANG model stating that this encoding is not available.

* To see the "netconf" identity, go to the YANG model in draft-ietf-netconf-netconf-event-notifications:
https://github.com/netconf-wg/notif-netconf/blob/master/draft-ietf-netconf-netconf-event-notifications-09.txt 
(the only reason this version isn't posted yet is that it is pending Einar's script tests on the appendix examples.)

Thanks,
Eric

> reading of rfc7950 section 7.21.4 doesn't seem to require a reference to be
> normative.  If it does, I can move the information into the description.
> >
> > Thanks again,
> > Eric
> >
> >
> > > Tom Petch
> >
> >

---

From: Kent Watsen <[email-masked]>
Date: Mon, 23 Apr 2018 20:50:48 +0000

[further trimming]

<Eric2> Text now says:

<Kent3> true, my goal below is to remove these notifications from the diagram altogether…  (see below)

                        .........
                        : start :
                        :.......:
                            |
                   establish-subscription
                            |

<Eric3>  I read your point <KENT> as you wanted to show the cause of the state transition (e.g., suspend subscription) rather than the resulting notification (e.g., “subscription-suspended”).

<Kent3> correct

So what I was trying to do with the top part of the picture was to remove the names of the state change notifications, and just show the event which drives the subscription from one state to the other.

<Kent3> I'm still confused, are there typos in your diagram or not - e.g., suspend-subscription should be subscription-suspended, right?  Maybe I'm not being clear enough, what's bothering me it that all the other transitions are via RPCs so, for these two transitions, it seems that the diagram should either identify an RPC or put something like "implicit" or "internal event" here - makes sense?

Otherwise the document would be confusing/overly-verbose if it tried to show both on a link (e.g., suspend subscription “subscription-suspended”).
I can go back to the ‘*’ version of the diagram if you prefer.  Do you have a different suggestion?

<Kent3> I agree that it would be cluttered.  Of course, my hope is to remove the notifications from the diagram altogether, I just want the diagram to identify what caused the transition to occur…

<Kent3> right, I sometimes find myself needing to make similar edits as well, though I do so via scripts with lots of `sed` and `grep` commands…

<snip/>

<Kent3> okay, any ETA on when an update might be posted?

<Kent3> Hmmm, I'm having a negative reaction to the "event records logged before restart are not sent" bit.  I know what you are trying to do, but I worry that this behavior might drop important logs, perhaps to the advantage of an adversary.  Note that some devices implement an <edit-config> with a restart.  Maybe the solution should require publishers to maintain a per configured-subscription awareness of (roughly) which log was sent last?   - and notify the receiver when a restart has occurred, or when the replaying of events occurs, so that they can be aware that there might be some duplicates?

<Kent3> Going back to my original comment, the new paragraph helps, it certainly caught my attention regarding reboots wiping out the replay log buffer.  But this wasn't quite what I was looking for either.   What I was hoping for was something akin to references (e.g., <xref>), or perhaps just starting that the "replay-log-creation-time" and "replay-log-aged-time" are identified as being via the read-only "streams" data tree, and "replay-start-time" is configured in the "subscription" tree.  It's clear what you mean by the publisher boot time, though I have to admit that, before, I didn't understand its envisioned impact.

<Kent3> still seems clunky, but it will do.

<Eric3>  Now says:

 <Kent3> perfect.

<Kent3> okay

[snip]

<Kent3> unsure.  For example, RFC 6241has Section 2 (Transport Protocol Requirements) that the SSH and TLS binding drafts refer to.  It seems that this draft should have a similar section that highlights what MUST or MUST NOT be supported.  It could even include some additional text indicating that bindings MAY introduce additional requirements.

Kent

---

From: "Eric Voit (evoit)" <[email-masked]>
Date: Tue, 24 Apr 2018 20:53:37 +0000

Hi Kent,

See <Eric4>...

From: Kent Watsen, April 23, 2018 4:51 PM

[further trimming]

<Eric2> Text now says:

<Eric 4>   Yes, they are removed from the diagram.  (Full answer below)

                        .........
                        : start :
                        :.......:
                            |
                   establish-subscription
                            |

<Kent3> correct

 <Eric4>  Ahhh.  I got it now.  The two reasons are:

·       Insufficient resources (e.g., CPU)

·       Unsupportable volume (i.e., a bandwidth constraint)

I adjusted the diagram to:
                      .........
                      : start :
                      :.......:
                          |
                 establish-subscription
                          |
                          |   .------modify-subscription-------.
                          v   v                                |
                    .-----------.                        .-----------.
         .--------. | receiver  |-insufficient CPU, b/w->| receiver  |
     modify-       '|  ACTIVE   |                        | SUSPENDED |
     subscription   |           |<---CPU, b/w sufficient-|           |
         ---------->'-----------'                        '-----------'
                          |                                    |
               delete/kill-subscription                   delete/kill-
                          |                               subscription
                          v                                    |
                      .........                                |
                      :  end  :<-------------------------------'
                      :.......:

With the supporting bullet items under the diagram:

·       A publisher may choose to suspend a subscription when there is insufficient CPU or bandwidth available to service the subscription. This is notified to a subscriber with a "subscription-suspended" state change notification.

·       A suspended subscription may be modified by the subscriber (for example in an attempt to use fewer resources).  Successful modification returns the subscription to an active state.

·       Even without a "modify-subscription" request, a publisher may return a subscription to the active state should the resource constraints clear.  This is announced to the subscriber via the "subscription-resumed" subscription state change notification.

<snip/>

<Eric4> Goal is about a week from now.

<Eric4>  The current solution guarantees no duplicates, and also informs the receiver of each new “start-time”.  This allows the receiver to attempt to reconstruct any gaps from the last event previously pushed, should the choose to attempt such reconstruction.   As a dynamic subscription has no such boundary constraints on replay and boot time, all a subsequent dynamic subscription needs to do is to request the events between the last received event previously received from that configured subscription and the new replay-start-time.

Note that this solution acts identically for loss of events when the platform *doesn’t* reboot, and events are just lost due to some overflow.  See the Section 2.5.2 text:
   “However if events are lost (rather than just delayed) due to replay buffer overflow, a new "subscription-started" must be sent.  This new "subscription-started" indicates an event record discontinuity.”
I.e., this way the receiver doesn’t have to do forensics to determine and attempt to determine the cause of a transient loss of events on a publisher.

In any case, tracking the last event sent to each receiver will be a pretty hard requirement to meet during a publisher crash.  Things are simpler to just let the receiver attempt a reconstruction should they need to.

<Kent3> Going back to my original comment, the new paragraph helps, it certainly caught my attention regarding reboots wiping out the replay log buffer.

<Eric4>  There is no requirement that the reboot wipe outs out the buffer (the solution is agnostic to that).   The only requirement is that a configured subscription replay start no earlier than the last reboot time.

But this wasn't quite what I was looking for either.   What I was hoping for was something akin to references (e.g., <xref>), or perhaps just starting that the "replay-log-creation-time" and "replay-log-aged-time" are identified as being via the read-only "streams" data tree, and "replay-start-time" is configured in the "subscription" tree.  It's clear what you mean by the publisher boot time, though I have to admit that, before, I didn't understand its envisioned impact.

<Eric4> Added a subsequent sentence including <xref> which says:
“The "replay-log-creation-time" and "replay-log-aged-time" are discussed in Section 2.4.2.1, and "replay-start-time" in Section 2.7.1.”

<Eric3>  Now says:

 <Kent3> perfect.

<Kent3> okay

[snip]

<Eric4> I re-read RFC6241 Section 2 a couple times.  There are a comparisons can be made from that document to a subset of requirements currently in this document’s security section.  But I don’t see anything missing on the MUST and MUST NOT side of things.   FYI: the specific requirements I am thinking of are:

   For both configured and dynamic subscriptions the publisher MUST

   authenticate and authorize a receiver via some transport level

   mechanism before sending any updates.

   A secure transport is highly recommended and the publisher MUST

   ensure that the receiver has sufficient authorization to perform the

   function they are requesting against the specific subset of content

   involved.

   With configured subscriptions, one or more publishers could be used

   to overwhelm a receiver.  Notification messages SHOULD NOT be sent to

   any receiver which does not support this specification.  Receivers

   that do not want notification messages need only terminate or refuse

   any transport sessions from the publisher.

That is about it for common stuff.  Considering the wide variety of potential transports, and ubiquity for the need of stream transports, I am simply not aware of any more common requirements.  If you need me to,  I can extract these three requirements, and put this under a separate transport requirements section.   But this seems excessive, especially as we have transport specific documents with eyes on them from the WG.  But if really do want this, I will place these into a new, separate section; and I will add your text: “bindings MAY introduce additional requirements.”

Eric

Kent

---

From: Kent Watsen <[email-masked]>
Date: Wed, 25 Apr 2018 22:07:18 +0000

[further trimming]

<KENT4> yes, this is it.  Just a couple nits, can you widen the diagram a couple characters to give more dashes (-) around the "insufficient" line?   Also, in the 3rd bullet, maybe replace "resource constraints clear" to "resource constraints become sufficient again" so that it binds with the words in the diagram?

<snip/>

<Kent4> So, the receiver is informed of each new "start-time" via the "subscription-started" control message, and then MUST do a short-lived dynamic subscription to scoop-up any possibly-missed logs, for which there may be none?   If we choose to keep this behavior, the draft should say this more clearly, perhaps in the Security Considerations section…

<Eric4>  Note that this solution acts identically for loss of events when the platform *doesn’t* reboot, and events are just lost due to some overflow.  See the Section 2.5.2 text:
   “However if events are lost (rather than just delayed) due to replay buffer overflow, a new "subscription-started" must be sent.  This new "subscription-started" indicates an event record discontinuity.”
I.e., this way the receiver doesn’t have to do forensics to determine and attempt to determine the cause of a transient loss of events on a publisher.

<Kent4> okay, but note that this section refers to Section 2.4.2.1 (not 2.5.2).   I understand what you mean, but I think more text is needed to convey it to readers…

<Kent4> this I agree with, but I really don't like the fact that receiver MUST do a short-lived dynamic subscription to scoop-up any possibly-missed logs, for which there may be none.  Perhaps we could add more values into the "subscription-started" notification message that would enable to receiver to make a local determination if such a dynamic subscription would be  helpful?

<Kent4> I'm glad to hear that the logs before restart aren't lost, just rather that there is no attempt to send them by default.   This wasn't all that obvious to me from what you wrote before.   I suggest adding text that clarifies this, and details the need for a short-lived dynamic-subscription.

<snip/>

<Kent4> perfect.

<snip/>

   involved.

<Kent4> yes, this is what I'm thinking is needed, even if just for these 3 requirements + a statement that each transport MAY impose additional limitations (not so much a "requirement" as a "fact of life using said transport" I think)

Kent // contributor

---

From: "Eric Voit (evoit)" <[email-masked]>
Date: Thu, 26 Apr 2018 16:49:17 +0000

Hi Kent,

All changes below are also in the latest in the pending v13 draft within:
https://github.com/netconf-wg/rfc5277bis/blob/master/draft-ietf-netconf-subscribed-notifications-13.txt

From: Kent Watsen, April 25, 2018 6:07 PM

[further trimming]

<KENT4> yes, this is it.  Just a couple nits, can you widen the diagram a couple characters to give more dashes (-) around the "insufficient" line?

<Eric5> Done.

Also, in the 3rd bullet, maybe replace "resource constraints clear" to "resource constraints become sufficient again" so that it binds with the words in the diagram?

<Eric5> Done.  I also inserted changes matching your “insufficient CPU, b/w” request into the Configured receivers Section 2.5.1.

<snip/>

<Eric5> Added the following text as the last paragraph in the Implementation Considerations Section...

For configured replay subscriptions, the receiver is protected from duplicated events being pushed after a publisher is rebooted.  However it is possible that a receiver might want to acquire event records which failed to be delivered just prior to the reboot. Delivering these event records be accomplished by leveraging the “eventTime” from the last event record received prior to the receipt of a “subscription-started” state change notification.  With this “eventTime” and  the “replay-start-time” from the “subscription-started” notification, an independent dynamic subscription can be established which retrieves any event records which may have been generated but not sent to the receiver.

<Eric5> Added the sentence:

The most recent publisher boot time ensures that duplicate event records are not replayed from a previous time the publisher was booted.

<Eric5> I recommend against providing extra objects/reasons in the “subscription-started” at this time.  Publishers might not want to advertise a reboot, and they might not want to advertise why there was loss in event continuity.   All that should matter to a receiver is that such a discontinuity existed, and they have a way to try to fill event the gap should they care.  If the need for more data and the cause of the discontinuity turns out to be required, we can always augment here with future objects.

<Kent4> I'm glad to hear that the logs before restart aren't lost, just rather that there is no attempt to send them by default.   This wasn't all that obvious to me from what you wrote before.

<Eric4>  Tweaked a Section 2.4.2.1 sentence to say:

This document puts no restrictions on the size or form of the log, where it resides within the publisher, or when event record entries in the log are purged.

I suggest adding text that clarifies this, and details the need for a short-lived dynamic-subscription.

<Eric4> The tweak above, with the suggested text in the Implementation Considerations section above hopefully covers this.

<snip/>

   involved.

<Eric5>  Move to a new section just before Security Considerations.   Added the last sentence:

Additional transport requirements will be dictated by the choice of transport used with a subscription. For an example of such requirements with NETCONF transport, see [I-D.draft-ietf-netconf-netconf-event-notifications].

/Eric5

Kent // contributor