Subject: Proposed Edits to Notification Draft

From: "Sharon Chisholm" <[email-masked]>
Date: Sun, 15 Oct 2006 13:22:31 -0400

Hi

	I've gone through all the comments received and compiled this
list of edits. Note that the source listed is the source of the issue
and may or may not agree with the proposed edit, although any
disagreement was not intentional on my part. I'll also be following up
this email with a list of issues I think might require a bit more
discussion before I'm confident in turning them into editing
instructions. But, feel free to disagree with my interpretation of
having consensus on these issues as well.

	Thanks to everyone who took the time to review the document.

1.	Make it clearer in the document that the notification feature is
an optional capability that builds on the base protocol definitions in
the main protocol specification.  This would go in the abstraction and
section 1, Instruction. (source: Balazs & Bert) 
	2.	In abstract and Introduction, don't use the term
"Framework". We are not defining a framework. (source Andy)
a.	This document defines mechanisms which provide an asynchronous
event notification delivery service for the NETCONF protocol.  It
defines the capabilities, operations, transport mappings, and data
models needed  to support this service.
3.	In section 1.1, as managed entity is defined and never used,
delete it (source Bert)
	4.	There are a few instances in the document where agent
and manger terminology is used instead of client server. These should be
changed to client and server. Note that the Beep transport mapping does
use the terminology of agent and manager, so any references within the
Beep mapping section should be consistent with the Beep draft.
	5.	In section 1.1, define term operation. It is used in
sections like 2.1.1 without definition. (source Andy)
	6.	Consistently refer to Subscription ID, and not
Subscription Id. (source Bert)
	7.	Align indenting of XML Schema to enable easier reading.
(source Bert)
	8.	In various examples, change from <neb> to <top> to be
more consistent (source Andy)
	9.	In section 1.2 last paragraphs, clarify that the netconf
server is not required to process RPC request on the same netconf
session. They are still required to process them on other netconf
sessions. (source: Balazs)
	10.	In section 1.3, paragraph three, replace "A capability
may be defined", with "A capability may be advertised". (source Andy)
	11.	In section 1.4, instead of saying that the requirements
for the solution are the following, indicate that the following
requirements have been addressed by the solution (source Bert)
	12.	Delete the following requirements from section 1.4
(source: Balazs)
a.	The solution should not bind subscriptions to a connection
			b.	solution should support agent initiated
connections
			c.	channels for configuration change
notifications should share fate with a session that includes a
configuration channel
13.	In section 1.4, clarify the location (on the same box as the
netconf server, as oppose to the on the same box as the netconf client)
for the following two requirements (source Bert)
a.	Local logging
			b.	Filtering
14.	In section 2.1.1, in create subscription, clarify what happens
if both filter and named profile are specified. Is this an error or are
they combined? (source Andy).
a.	Combined. Clarify behaviour.
15.	In section 2.1.1, in create subscription (source Andy)
a.	This should be <ok> instead of a <data> element containing the
subscription ID.  The WG decided there is only one stream active per
session.  That means there is no need for a subscription ID in the
document.
16.	In section 2.1.1, in create-subscription, mentioned startTime
(source Andy)
a.	Note that this is only used in the replay command, so I was not
sure if it should go here. It is defined later in the replay section. If
it makes sense to add it here, I'm fine.
17.	In section 2.2.1, mention that <notification> is a top level
element, to make it clear this is not another RPC method as in the
previous section. (source Andy)
	18.	In section 2.2.1, the Positive Response and Negative
Response document format is only for RPC methods, so this text should be
removed instead of saying 'none'. The current text is confusing because
<notification> is a sibling of <rpc> and <rpc-reply> and the behaviour
for <rpc-reply> is not relevant.
	19.	In section 3.2.5.1, replace namespace example.com with
real namespace. Align to section 3.2.5.2 (source: Balazs)
	20.	In section 3.2.5.1, fix references to sessionEventStream
and systemEventStream to reflect just eventStream, as defined in the
actual schema in section 3.2.5.2 (source Balazs & Bert)
	21.	In section 3.2.5.1, it does not need to use both <get>
and <get-config>. <get> seems the more appropriate verb since this
information is defined as read-only. (source: Balazs & Martin)
	22.	In section 3.2.5.1, verify order of closing tags (page
13). Also verify the plurality of eventStream versus eventStreams in the
tag names (page 14). (Source Bert)
	23.	In section 3.2.5.2, fix the description clause in
<nm:description> which claims this is about subscription retrieval
instead of stream retrieval (source Balazs)
	24.	In section 3.3, clarify the distinction between not
being stored in the datastore as appose to not being retrievable via a
get operation. Subscriptions are like sessions in that respect. (source
Balazs & Andy)
	25.	Delete section 3.5 (source Andy, others)
	26.	In section 4, add missing stream tag to subscription
definition. Allow for more then one stream to be specified. (source
Balazs)
	27.	In section 4, add missing data to notificationType
(source Martin & Balazs) [Editor's note: I swear I've already fixed this
at least once already. Gremlins]
	28.	In section 4, fix errors of missing close element tag.
	29.	In section 5.1, make corrections as outlined by Martin
	30.	In section 5, (source Andy)
a.	- the <interface> element in the example should be in a
container called <interfaces>. Also, any assumptions about naming and
keys in the examples need to be stated.
31.	In section 5.2.1.1 remove reference to rpc-one-way message
	32.	In section 6.1, make corrections as outlined by Martin 
	33.	In section 7.1, paragraph 3, the expected warning
message need to be more formally defined (aligned with how this was done
in the base specification).  Define it in 7.5.1 (source: Balazs & Andy)
	34.	In section 7.1, paragraph 3, it should be clarified why
the warning message is required. The subscriber needs to be able to
differentiate between when no messages were sent in a given timeframe
and when no messages are in the log for a given timeframe (source:
Martin)
	35.	In section 7.1, define an event notification that gets
sent when the replay is done to alert the client that replay is
completed.  The session will also be available to process commands at
this point, but I don't believe this is a sufficient way to tell replay
is done. (source Martin)
	36.	In section 7.3, fix replay capability to be uri instead
of http. (source Bert & Andy)
	37.	In section 8 (Security Considerations), add some text as
follows: (source Andy & Dave)
a.	Note that the <notification> elements are never sent before the
transport layer and the netconf layer (capabilities exchange) have been
established, and the manager has been identified and authenticated.
			b.	It is recommended that care be taken to
ensure the secure operation of the following commands: 
i.	 <create-subscription> invocation
				ii.	 use of <kill-session>
				iii.	 read-only data models
				iv.	 read-write data models
				v.	 notification content
c.	One issue related to the notifications draft is the transport of
data from non-netconf streams, such as syslog and SNMP. Note that this
data may be more vulnerable (or is not more vulnerable) when being
transported over netconf than when being transported using the protocol
normally used for transporting it, depending on the security credentials
of the two subsystems.
38.	Misc reference Issues (source Bert)

Edits that need to be done if Sharon's tools allow her to
1.	Split references into Normative and Informative (Note, I don't
think we have any informative references) (source Andy)
2.	refs.RFCXXXX instead of RFCXXXX (source Andy)
3.	The base protocol specification has headers like <get-config>,
while this draft as create-subscription
4.	There is a piece of text that indicates that the IETF has been
notified about an IPR claim.

Sharon Chisholm
Nortel 
Ottawa, Ontario
Canada

---

From: "Sharon Chisholm" <[email-masked]>
Date: Wed, 18 Oct 2006 09:00:40 -0400

hi
 
I have a clarifying question on one of the editing instructions.  I had
interpreted the following to be decoupled from the subscriptionId or not
subscriptionId discussion which is listed in the issues for discussion
section. I had interpreted this to simply be that Andy is saying the
correct way to return the subscription Id is with <ok> and not <data>.
On re-read,  that sounds a bit off. What is the correct way to return a
subscription ID?

 >  1  5.     In section 2.1.1, in create subscription (source Andy) 
 >  a.      This should be <ok> instead of a <data> element containing
the subscription ID.  The WG decided there is only one stream active
per session.  That means there is no need for a subscription ID in the
document. 

--
to unsubscribe send a message to [email-masked] with
the word 'unsubscribe' in a single line as the message text body.
archive: <http://ops.ietf.org/lists/netconf/>

---

From: Andy Bierman <[email-masked]>
Date: Wed, 18 Oct 2006 06:41:32 -0700

> On re-read,  that sounds a bit off. What is the correct way to return a

I think the WG already decided we do not need or want
the subscriptionId parameter at all.

The <ok> rpc-reply should be used because there is no data
that needs to be returned.  You do not return any data with <ok>.

The WG did not decide to keep the subscriptionId "in case we want
it someday in the future", as you have interpreted it.

Andy

---

From: "Sharon Chisholm" <[email-masked]>
Date: Wed, 18 Oct 2006 14:31:26 -0400

Hi

I don't remember any discussion explicitly as to whether we needed this
identifier which is why I added it to the list of issues to discuss. 

Yes, it is obviously helpful for implementations which support
proprietary or future capabilities that build on the base notification
specification. There are a number of add-ons that could result in the
one-session to one subscription ratio not being true. I know you aren't
really into supporting extensibility in that way, so I just want to
confirm that we don't need it to support the base specification.

For implementations only supporting the base protocol specification,
there is a one-to-one correspondence between session id and subscription
id. In these cases the session id can be used for many of the cases
where you would want subscription id. One potential case, even with the
current minimal base, where you would still have more then one
subscription associated with the same session is if you had a replay
subscription and after it completes you start another subscription.
Since these don't exist at the same time, it may not be necessary to be
able to distinguish them.

I guess we can live without it for the base specification and find a way
to recover when supporting extended content.

Sharon

-----Original Message-----
From: Andy Bierman [mailto:[email-masked]] 
Sent: Wednesday, October 18, 2006 9:42 AM
To: Chisholm, Sharon (CAR:ZZ00)
Cc: [email-masked]
Subject: Re: Proposed Edits to Notification Draft

Sharon Chisholm wrote:
> hi
>  
> I have a clarifying question on one of the editing instructions.  I 
> had interpreted the following to be decoupled from the subscriptionId 
> or not subscriptionId discussion which is listed in the issues for 
> discussion section. I had interpreted this to simply be that Andy is 
> saying the correct way to return the subscription Id is with <ok> and
not <data>.
> On re-read,  that sounds a bit off. What is the correct way to return 
> a subscription ID?

I think the WG already decided we do not need or want the subscriptionId
parameter at all.

The <ok> rpc-reply should be used because there is no data that needs to
be returned.  You do not return any data with <ok>.

The WG did not decide to keep the subscriptionId "in case we want it
someday in the future", as you have interpreted it.

Andy

> document.
> 
>  
> 
> 
> --
> to unsubscribe send a message to [email-masked] with the

> word 'unsubscribe' in a single line as the message text body.

---

From: Andy Bierman <[email-masked]>
Date: Wed, 18 Oct 2006 12:13:19 -0700

> able to distinguish them.

IMO it is bad engineering to add extra cruft because you might
need it someday.  The WG consensus is that we do not need this
feature at all.  If we ever change our minds, it is cleaner
engineering to add the parameter if and when we actually need it.

If you add a under-specified parameter in "1.0", it will in no way
indicate that the agent supports some future multi-subscription
notification capability.  Then you have to specify how the real
capability interacts and coexists with the "old" subscriptionID.
In that case, we incur extra complexity for no benefit.

Proprietary 'replacements' to the standard (e.g., use your own
<create-subscription> RPC) are somewhat out of scope.

> to recover when supporting extended content.

Yes we can live without it.  The sessionID is sufficient.

Andy