Netconf Notifications WC LC: Issues & Proposed Resolutions - Part 1

["Sharon Chisholm" <schishol@nortel.com>]

hi

Here are proposed resolutions to the first set of issues on the working
group last call list. More to come.

1.	Section 1.2 (Source Ken)

The spec says that a capability can be used to announce that the netconf
server can process rpcs while sending notifications.  I think that it
very important that the device NOT process any new <create-subscription>
requests while sending notifications as there is no per-notification
subscription-identifier - thus it is not impossible for the client to
differentiate which subscription its receiving a notification for

Proposed Resolution: If the client is unable to support any optional
features that are advertised, it does not need to use them. Add text at
the end of the third paragraph that says "The behaviour of such a
capability is outside the scope of this document.   

2.	Section 2.1.1 (Source Ken)

The "negative response" section should clearly indicate what happens
when either the start-time is set but the stream doesn't support replay
or when the stop-time is set without having the start-time set - both of
these conditions are marked as illegal by the spec without any clear
statement about what will happen (i.e. what rpc-error will be returned)

Proposed Resolution: 

Add the following text to Section 2.1.1 under Negative Response
"If a stop-time is specified in a request without having specified a
start-time the following error is returned

   Tag:         bad-element
   Error-type:  protocol
   Severity:    error
   Error-info:  <start-time> 
   Description: An element value is not correct; e.g., wrong type,
                out of range, pattern mismatch.

   If the optional replay feature is requested but it is not supported
by the NETCONF server, the following error is returned:

   Tag:         operation-failed
   Error-type:  protocol
   Severity:    error
   Error-info:  none
   Description: Request could not be completed because the requested
                operation failed for some reason not covered by
                any other error condition."

Note these are currently defined in section 6.3, but with the merge of
section 6 to this one (and section 3), this becomes the correct place to
update them.

3. Section 3.3 (Source Ken)

It doesn't make sense for the namedProfile to include the "lastModified"
element - as it is not usable without any API to discover which
subscriptions are active and when they began...

Proposed resolution: You can query independently for subscription
information. Propose no change. 

4. Section 3.4 (Source Ken)

It is very unfortunate that <createSubscriptionType> only allows at most
one stream at a time (i.e. its not maxOccurs=0) - as the only
alternative is for the client to open a separate netconf session for
each stream, but this is both awkward and not efficient for either the
client or the server.   I fear that, unless this is fixed,
implementations will only support the required "netconf" stream and use
subscription filters to select what to receive, effectively rendering
the "stream" concept useless

Proposed Resolution: While I agree this is unfortunate, it does reflect
working group consensus. Propose no change.

5. Section 5.2 (Source Ken)

The spec does not indicate if XPATH filters must be supported - this
would be surprising to me as the base netconf protocol lets XPATH be an
optional capability.  Maybe :notifications can use XPATH filters if and
only if the :xpath capability is advertised?

Proposed Resolution: Add text to section 3.2.5.2.1 which says "XPATH
support for the Notification capability is advertised as part of the
normal XPATH capability advertisement. If XPATH support is advertised
via the XPATH capability then XPATH is supported for notification
filtering and if this capability is not advertised, then XPATH is not
supported for notification filtering."

6.	Section 6.3  (Source Ken)

In addition to the special replayCompleteNotification notification, it
would be nice for there to also be a special eventsDroppedNotification
(or something) that can be used whenever a device drops an event (i.e.
buffer full, etc.)

Proposed Resolution: Given that events are often dropped due to resource
constraints, this does not seem like a good plan. Propose no change.

7. pg 3, ToC: Suggest title change of sec. 3.4 'Subscriptions not
Configuration Data'  (Source Andy)

Proposed Resolution: Replace title section of 3.4 of 'Subscriptions not
Configuration Data' with 'Subscriptions Data'

8. pg 3, ToC: Sec. 5 title : Capitalize examples (Source Andy)

Proposed Resolution: Substitute title of section 5 from 'Filtering
examples' to "Filtering Examples'

9. ToC: No entry for IANA Considerations (no section either) (Source
Andy)

Proposed Resolution: Add an 'IANA Considerations' section to request
allocation of namespaces for the Schemas. 

"This document registers two URIs for the NETCONF XML namespace in the
   IETF XML registry [7].

   Following the format in RFC 3688, IANA has made the following
   registration.

   URI: urn:ietf:params:netconf:capability:notification:1.0
   
   URI: urn:ietf:params:xml:ns:netmod:notification

   Registrant Contact: The IESG.

   XML: N/A, the requested URI is an XML namespace."

Update various references to content namespace to use this tag.

10. pg 4, middle of page: Move 'Figure 1' above the para, and directly
below the figure (Source Andy)

Proposed resolution, in section 1, move the label 'Figure 1' to be just
under the picture.

11. p4 4. sec. 1.1 Terms Managed Object is unclear, not used anywhere,
should be removed (Source Andy)

Proposed Resolution: In section 1.2, delete the term Managed Object.

12. p5 Terms Operation: 2nd sentence is not true.  Term used as stated
only in sentence 1. (Source Andy) 

Proposed Resolution: As this was added at someone's request. I'd like to
verify there is consensus to remove it.

13. p5 sec1.2: Put first para in Terms section as 'Event' (Source Andy)

Proposed Resolution: Move definition of event in first paragraph section
1.2 to section 1.1 as a definition.

14. pg 7, bottom: missing period after parameter (Source Andy)

Proposed Resolution: In section 2.1.1, in the named profile text,
complete the final sentence with a period.

15. pg 7 - 8: General comments on create-subscription (Source Andy)

a.	need to specify conceptual data types for all parameters in this
section
b.	need to show usage examples in this section
c.	need to combine entire section 6 (Replay) into this section
since it is confusing to introduce just the parameters but not the
feature
d.	once again, we are creating parameter dependencies that XSD
cannot represent. (Just as happy to rant against XSD than change things
though ;-)

Proposed resolution: In section 2.1.1, add the following usage example

<rpc message-id="101"
             xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
   <create-subscription>
   </create-subscription>
</rpc>

Also move section 6 into section 2.1.1 as makes sense and the rest into
section 3 (supporting concepts).

While we can represent more in XSD then we are, I'm not exactly sure
what the specific issue is. Propose no change.

16. pg 8, Start Time and Stop Time comments (Source Andy)

a.	What if a legal start-time (or start/stop pair) specifies some
time in the future?
b.	What if the timezone is given and it is not the same as the
agent's timezone?
c.	What if a time change (e.g., daylight savings time) happens?
d.	Explain how both parameters handle forward and backward boundary
conditions

Proposed Resolution: According to the discussion in the working group
meeting, future start times are now allowed.  Add text to section 3 (in
the text merged from section 6) that says "It is valid to specify start
and stop times that are later than the current time."

For the other points. I'm not sure what we want to say about these. I
think it is up to the system to support time properly. I'd suggest
either no change or a statement to that effect. 

17. pg 8, sec 2.1.1, Negative Response (Source Andy) 

a.	This section is correct, but inconsistent with the text in sec.
6.1, para 3.
b.	There is no mention of a 'warning-and-continue' mode of
operation here. (More reason why sec 6. create-sub. details needs to be
integrated into this section.)

Proposed Resolution: I think we briefly discussed this in Prague, but I
don't remember the consensus, if any. An edit is definitely required to
make these consistent with each other. The reasons why warn and continue
is required it to allow the client to create a replay request without
actually needing to know the exact time of the earliest available log.
Propose adding text to section 2.1.1 to reflect the warn and continue
method discussed in section 6.  Create a new section between "Positive
Response" and "Negative Response" called "Warn and Continue" with the
following text "If the NETCONF server can satisfy the request, but the
start time specified is too early then the <rpc-error> element will be
included a warning message, but the client can expect <notifications> to
be along the Netconf session. "

18. pg 9, sec 2.3, Terminating the Subscription (Source Andy)
a.	Does the <kill-session> have to come from another session? (I
think so)
b.	IMO, since we do not have an endless RPC reply model, it is not
a burden to the agent to accept a <close-session> from the session
getting notifications 
c.	Does sentence 2 mean after the last replayed notification that
meets the stop time criteria, the session is terminated? last sentence,
capitalize Netconf to NETCONF

Proposed Resolution: If you don't have an interactive session
<kill-session> does have to come from another session, but I don't think
we need to discuss this. If we are not processing commands then we are
not processing commands. It seems to add unnecessary complexity to say
we are not processing commands, except ... Propose no change.

Note that The session is not terminated when the subscription is done.
The text already says "In this case, the Netconf session will still be
an active session". Propose no change. 
  
In section 2.3, last sentence, replace Netconf with NETCONF.

19. pg 10, sec 3.1.2, cap. exchange example (Source Andy)

IMO, this section should be removed.  Sec. 3.1.1 defines the capability
identifier. Just say that RFC 4741 defines the capability exchange.

Proposed resolution: I think the example adds value. Propose no change.

20.	pg 11, diagram (Source Andy)

This is a good diagram but there should be text following it explaining
all the boxes, why they are there, and where in this document the
relevant definitions can be found

Proposed Resolution: In section 3.2, add figure caption: Figure 2.
Replace the second and third paragraph as indicated and add some new
text.

Replace:

'System components generate event notifications which are passed to a
   central component for classification and distribution.  The central
   component inspects each event notification and matches the event
   notification against the set of stream definitions.  When a match
   occurs, the event notification is considered to be a member of that
   event stream.  An event notification may be part of multiple event
   streams.

   When a NETCONF client subscribes to a given event stream, user-
   defined filters, if applicable, are applied to the event stream and
   matching event notifications are forwarded to the NETCONF server for
   distribution to subscribed NETCONF clients.'

with 

"The diagram depicted in Figure 2 illustrates the notification flow and
concepts identified in this document. The following is observed from the
diagram below:  
   System components (c1..cn) generate event notifications which are
passed to a
   central component for classification and distribution.  The central
   component inspects each event notification and matches the event
   notification against the set of stream definitions.  When a match
   occurs, the event notification is considered to be a member of that
   event stream (stream 1..stream n).  An event notification may be part
of multiple 
   event streams.

   When a NETCONF client subscribes to a given event stream, user-
   defined filters (filter - see filter in <create-subscription>), if
applicable, are applied to the event stream and
   matching event notifications are forwarded to the NETCONF server for
   distribution to subscribed NETCONF clients. "


Add new text following this as follows:
"A Notification Logging Service (see replay under <create-subscription>)
may also be available, in which case, the central component logs
notifications. The NETCONF server may later retrieve logged
notifications via the optional replay feature."

21. 	pg 11, 3.2.1-2, typos (Source Andy)

a.	s/via NETCONF protocol/via the NETCONF protocol/
b.	missing period after last sentence
c.	s/i.e. the notification/i.e., the notification/

Proposed Resolution: In section 3.2.1 and section 3.2.2, perform the
following edits
a.	s/via NETCONF protocol/via the NETCONF protocol/
b.	Add missing period after last sentence
c.	s/i.e. the notification/i.e., the notification/

22. pg 11, sec 3.2.3, Default Event Stream (Source Andy)

a.	Mentions the "NETCONF" notification event stream but this is not
defined anywhere.
b.	Need to put this in the IANA considerations section that will be
added.

Proposed resolution: I don't understand why this is an IANA
consideration. We agreed there would be a Netconf event stream which
would contain Netconf content. What's the specific edit? 

23. pg 12, typos (Source Andy)
a.	para 1,   s/e.g. SNMP, syslog, etc./e.g., SNMP, syslog/
b.	para 3, missing space after <get> and before operation

Proposed Resolution: make these changes in section 3.2.5.1
i.	para 1,   s/e.g. SNMP, syslog, etc./e.g., SNMP, syslog/
ii.	para 3, add missing space after <get> and before operation

24. pg 12, Name Retrieval comments (Source Andy)

a. Need introduction and formal description of the data model for
retrieving stream names. 
b.	Can we use just one namespace for all NETCONF data model
objects, put the definition in IANA, and use it for notification data?
c.	agree with comment to change <eventStreams> to <event-streams>
for better consistency with rest of this doc, and RFC 4741.

Proposed Resolution: Add the following text to the beginning of section
3.3: "This Schema is used to learn about the event streams supported on
the system and the query and modify named profiles. It also contains the
definition of the replayCompleteNotification, which is sent to indicate
that an event replay has sent all applicable notifications."

Merge the event replay complete notification into the other content
Schema.

As discussed in Prague, lower camel is consistently done for the data
model versus the protocol. Propose no change.

25. pg 13, bad XML style (Source Andy)

<description> end tags on new line introduces significant whitespace
into the element content

Proposed Resolution: This isn't bad XML Style. It makes it more
readable. Whitespace is free. Propose no changes.

Sharon Chisholm
Nortel
Ottawa, Ontario
Canada

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