Subject: Review of draft-ietf-netconf-notification-06

From: Phil Shafer <[email-masked]>
Date: Mon, 02 Apr 2007 00:02:34 -0400

Here are my comments in the notification draft.  Apologies that
they are so late.  These are comments from before ietf68, so some
of them were raised at the WG meeting, but others were not.

Thanks,
 Phil

---------------------

>                      NETCONF Event Notifications
>                 draft-ietf-netconf-notification-06.txt

Here are my comments on this draft.  They fall into four categories:

(1) The subscription metaphor is unnecessary and confusing.  There's
    no win from introducing it, since the subscription isn't a visible
    protocol element, nor is it visible to the client application.
    Use something like <start-notifications> instead.

(2) The <notification> element shouldn't be a top-level tag.  The
    first netconf add-on should not require modification to the simple
    RPC protocol we put in netconf.  It's both a bad precedent and
    unnecessary.  The content can live inside a normal <rpc-reply>.

    This draft introduces a modality into the netconf session which is
    both subtle and disturbing.  When a request for notification is
    issued, the session moves from netconf-rpc mode into
    netconf-notification mode.  When the notifications are complete,
    the session silently reverts back to rpc mode.  The transition is
    not signaled by any top-level operation.

(3) The draft as written does not provide a solution to the
    notification problem.  It is a wrapper.  The meat is in the
    notifications themselves, and the draft does nothing to define a
    standard way of carrying the common notification formats.  In
    particular, a syslog and an snmp trap mapping are needed.

(4) Other editorial issues with the draft.  In general, the draft is
    poorly organized, with numerous forward references to content that
    has not been discussed, often in vague terms without a concrete
    reference.

I'd also like to re-address the <foo-bar> .vs. <fooBar> inconsistency,
hoping for a better interest than the handful of people that voted in
the working group meeting.  Are so few people really interested in
this draft?

>   [NETCONF] can be conceptually partitioned into four layers:
>
>   Layer                      Example
>    +-------------+      +----------------------------------------+
>    |   Content   |      |     Configuration data                 |
>    +-------------+      +----------------------------------------+
>              |                           |
>    +-------------+      +-------------------------------------------+
>    | Operations  |      | <get-config>, <edit-config> <notification>|
>    +-------------+      +-------------------------------------------+
>              |                           |                    |
>    +-------------+      +-----------------------------+       |
>    |     RPC     |      |    <rpc>, <rpc-reply>       |       |
>    +-------------+      +-----------------------------+       |
>             |                           |                     |
>    +-------------+      +------------------------------------------+
>    | Transport   |      |   BEEP, SSH, SSL, console                |
>    |   Protocol  |      |                                          |
>    +-------------+      +------------------------------------------+

I was originally quite confused about why this picture was included in
this draft, since I missed the <notification> addition.  Looking at
the new picture, the layer violation becomes more obvious.  I find it
particularly disturbing when I think that this draft modifies all four
of these layers.

My preference is for something that lives within the netconf
framework, without requiring changes throughout it.

>   Managed Object:  A collection of one of more Elements that define an
>      abstract thing of interest.

This term is never referenced.

>   Subscription:  A concept related to the delivery of notifications (if
>      any to send) involving destination and selection of notifications.
>      It is bound to the lifetime of a session.

This definition is very weak.  See above comments re: subscriptions.

>   Operation:  This term is used to refer to NETCONF protocol
>      operations.  Specifically within this document, operation refers
>      to NETCONF protocol operations defined in support of NETCONF
>      notifications.

Can we include terms from the base spec implicitly?

There are _many_ terms missing here, including replay, streams,
profiles, and filters (maybe?).

>   An event is something that happens which may be of interest - a
>   configuration change, a fault, a change in status, crossing a
>   threshold, or an external input to the system, for example.  Often
>   this results in an asynchronous message, sometimes referred to as a
>   notification or event notification, being sent out to interested
>   parties to notify them that this event has occurred.

s/sent out/sent/
s/ to notify them that this event has occurred//

>   This memo defines a mechanism whereby the NETCONF client indicates
>   interest in receiving event notifications from a NETCONF server by
>   creating a subscription to receive event notifications.  The NETCONF
>   server replies to indicate whether the subscription request was
>   successful and, if it was successful, begins sending the event
>   notifications to the NETCONF client as the events occur within the
>   system.  These event notifications will continue to be sent until
>   either the NETCONF session is terminated or the subscription to
>   terminate for some other reason.  The event notification subscription
>   allows a number of options to enable the NETCONF client to specify
>   which events are of interest.  These are specified when the
>   subscription is created.

s/subscription to/subscription/

>   An NETCONF server is not required to process RPC requests on the
>   session associated with the subscription until the notification
>   subscription is done and may silently discard these requests.  A
>   capability may be advertised to announce that a server is able to
>   process RPCs while a notification stream is active on a session.

s/An NETCONF/A NETCONF/

>1.3.  Motivation
>
>   The motivation for this work is to enable the sending of asynchronous
>   messages that are consistent with the data model (content) and
>   security model used within a NETCONF implementation.

This section seems odd, since the more detailed model given in 1.2.

>   o  solution should provide a subscription mechanism (A NETCONF server
>      does not send notifications before being asked to do so and the
>      NETCONF client initiates the flow of notifications)

Use of subscriptions isn't the requirement;  the parenthetical sentence
is the real requirement.

>2.  Notification-Related Operations

The underlaying model from Section 3 (Supporting concepts) should
appear before this section.  Diving straight into operations without
giving the reader a framework into which those operations fit puts
syntax over semantics.

>2.1.1.  <create-subscription>
>   Description:
>      This operation initiates an event notification subscription which
>      will send asynchronous event notifications to the initiator of the
>      command until the subscription to terminates.

s/to terminates/is terminated/ or /terminates/

Can this description be improved?  The subscription doesn't send
notifications, but instructs the server to initiate sending
notifications for events that match the given criteria.

>      Stream:
>         An optional parameter that indicates which stream of events is
>         of interest.  If not present, then events in the default
>         NETCONF stream will be sent.

Streams are not defined at the point in the draft.

>      Filter:
>         An optional parameter that indicates which subset of all
>         possible events are of interest.  The format of this parameter
>         is the same as that of the filter parameter in the NETCONF
>         protocol operations.  If not present, all events not precluded
>         by other parameters will be sent.  This is mutually exclusive
>         with the named profile parameter.

Include a reference to the section on filters.

>      Named Profile:
>         An optional parameter that points to a separately defined
>         filter profile.  If not present, no additional filtering will
>         be applied.  Note that changes to the profile after the
>         subscription has been created will have no effect.  This is
>         mutually exclusive with the filter parameter

This needs a forward reference also.

Changes "points to" to "refers to".

Missing period on last sentence.

>      Start Time:
>         A parameter used to trigger the replay feature and indicates
>         that the replay should start at the time specified.  If start
>         time is not present, this is not a replay subscription.

Why not refer to parameters by their real names, like start-time?
Talk about the acceptable formats for this parameter.

>2.2.  Sending Event Notifications
>   Once the subscription has been set up, the NETCONF server sends the
>   event notifications asynchronously along the connection.

s/along/over/

>2.2.1.  <notification>
>
>   Description:
>
>      An event notification is sent to the initiator of a <create-
>      subscription> command asynchronously when an event of interest
>      (i.e. meeting the specified filtering criteria) to them has
>      occurred.  An event notification is a complete and well-formed XML
>      document.  Note that <notification> is not an RPC method but
>      rather the top level element identifying the one way message as a
>      notification.

It should mention that the encoding of this element is transport
specific, which I guess means we need to rev all the transport RFCs.

Use ""client" instead of "initiator".  It's confusing.

It's not clear that "filtering criteria" refers to more than <filter>.

The contents of the <data> element are never discussed.  It should at
least say that the draft is not concerned with content.

>2.3.  Terminating the Subscription
>   Closing of the event notification subscription can be done by
>   terminating the NETCONF session ( <kill-session> ) or the underlying
>   transport session.  If a stop time is provided when the subscription
>   is created, then the subscription will terminate after the stop time
>   is reached.  In this case, the Netconf session will still be an
>   active session.

This introduces a modality into netconf sessions that I dislike,
especially since the triggers that switch the modes are buried inside
the content.  There's nothing at the <rpc> layer to tell you that
you've moved from <rpc> mode to <notification> mode.

The reference to <kill-session> is odd, since I can't see this being
used in any real way.  Are we expecting people to open a second
session to kill their first session?  This is the way the text reads
but I can't imagine that's the intention.

>3.  Supporting Concepts

Supporting concepts (semantics) should appear before syntactic
content.  Otherwise the reader is lost.

>3.2.  Event Streams
>   An event stream is defined herein as a set of event notifications
>   matching some forwarding criteria.

s/herein//  since all definitions are specific to this document.
s/forwarding// since it doesn't make sense.

>   +----+
>   | c1 |---+             available streams
>   +----+   |    +---------+
>   +----+   |    |central  |-> stream 1
>   | c2 |   +--->|event    |-> stream 2    filter +-------+
>   +----+   |    |processor|-> netconf stream --->|netconf|
>    ...     |    |         |-> stream n           |server | see
>   System   |    +---------+                      +-------+ below
>   Components|        |                  //
>    ...     |        |                 //
>   +----+   |        |       (------------)
>   | cn |---+        |       (notification)
>   +----+            +-----> (  logging   )
>                             (  service   )
>                             (------------)

What are the "//" marks for?  The "see below" is confusing, since the
"below" boxes look like orphans.

>3.2.1.  Event Stream Definition
>
>   Event streams are predefined on the managed device.  The
>   configuration of event streams is outside the scope of this document.
>   However, it is envisioned that event streams are either pre-
>   established by the vendor (pre-configured) or user configurable (e.g.
>   part of the device's configuration) or both.  Device vendors may
>   allow event stream configuration via NETCONF protocol (i.e. edit-
>   config operation)

3.2 starts with the definition of event streams.

This section doesn't read well.  It would be better to start with the
event model, add event streams, add netconf, and then draw a picture
of the final world view.

>3.2.2.  Event Stream Content Format
>   The contents of all event streams made available to a NETCONF client
>   (i.e. the notification sent by the NETCONF server) must be encoded in
>   XML.

XML, but what sort?  Can I just put a string under <data>?  Do I need
my own container tag?  Can I put multiple elements in a <data>?  Are
there any rules?

>3.2.3.  Default Event Stream
>   A NETCONF server implementation supporting the notification
>   capability must support the "NETCONF" notification event stream.
>   This stream contains all NETCONF XML event notifications supported by
>   the NETCONF server.  The definition of the event notification and
>   their contents for this event stream is outside the scope of this
>   document.

We define a stream without a notification data model?  How does this
work?  What possible purpose could it serve?  Clients spontaneously
"know" how to interpret these events?

s/event notification/event notifications/ ?

>3.2.4.  Event Stream Sources
>   With the exception of the default event stream (NETCONF
>   notifications) specification of additional event stream sources (e.g.
>   SNMP, syslog, etc.) is outside the scope of this document.  NETCONF
>   server implementations may leverage any desired event stream source
>   in the creation of supported event streams.

I don't understand this section.  Is it placing any sort of limitation
on an NETCONF implementation?  What should be NETCONF implementor read
into it?  Just that they can do what they want?  Do we need to tell
them that explicitly?

>3.2.5.1.  Name Retrieval using <get> operation
>
>   The list of available event streams is retrieved by requesting the
>   <eventStreams> subtree via a <get>operation.  Available event streams
>   for the requesting session are returned in the reply containing the
>   <name> and <description> elements, where <name> element is mandatory
>   and its value is unique.  The returned list must only include the
>   names of those event streams for which the NETCONF session has
>   sufficient privileges.  The NETCONF session privileges are determined
>   via access control mechanisms which are beyond the scope of this
>   document.  An empty reply is returned if there are no available event
>   streams.  The information is retrieved by requesting the
>   <eventStreams> subtree via a <get> operation.

s/<get>operation/<get> operation/

> <rpc message-id="101"
>    xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
>   <get>
>    <filter type="subtree">
>          <eventStreams xmlns="urn:ietf:params:xml:ns:netmod:base:1.0"/>
>     </filter>
>   </get>
> </rpc>

What is "netmod"?  Should this be under ":netconf:notification:1.0"?
Are we intentionally making "netmod" .vs. "netconf" distinctions?  Can
you explain the distinction?

>3.2.5.2.  Event Stream Subscription
>   A NETCONF client may request from the NETCONF server the list of
>   available event streams to this session and then issue a <create-
>   subscription> request with the desired event stream name.  Omitting
>   the event stream name from the <create-subscription> request results
>   in subscription to the default NETCONF event stream.

Why is this a feature, rather than a bug in the client code?  Are we
expecting an overwhelming use of the NETCONF stream that it makes
sense to use it as the default?

I skipped the schema, but will note that there normative text in the
schema that is not in the real text.  I don't know if this is
intentional or not, but it's a bit confusing, especially given that
people don't tend to read the schemas.  <xs:documentation> elements
are a poor source of specificiation.  Better to move these discussion
into the text.

In particular, the bits about profiledata imply that it's
configuration data, but there's no data model to go with it.
For example, how to I change the <name> of a named-profile?

Also there are some odd rules about timestamps, and the interaction
between fielded requests and the profiles.  IMHO, this is best left to
the implementation because (a) it's a corner case and (b) it's
expensive to treat corner cases in ways that your implementation
considered unnatural.  If you force rigid behavior, you're likely to
be ignored anyway.  Best to leave it undefined.

>3.4.  Subscriptions not Configuration Data

s/not/are not/

>While it may be possible to retrieve information about subscriptions
>via a get operation, subscriptions are not stored configuration.

This makes it sound like you can get configuration via <get>, which is
not true.  Better to just explain that subscriptions are not
configuration data, and their lifetime is defined by their session.

>   Named profiles, if used, are considered configuration data.

Profiles may also be built into the device, right?

>3.5.  Filter Dependencies

s/Dependencies/Mechanics/?

>3.5.1.  Named Profiles
>   A named profile is a filter that is created ahead of time and applied
>   at the time an event notification subscription is created .  Note
>   that changes to the profile after the subscription has been created
>   will have no effect on the subscription.  Since named profiles exist
>   outside of the subscription, they persist after the subscription has
>   been torn down.

s/created ./created./

Again, the "changes" part is better seen as implementation-specific behavior.

>4.  XML Schema for Event Notifications

Why are some imports documented and other not?

>6.   Notification Replay

FWIW, I found this section much better laid out and easier to read.

>6.1.  Overview
>
>   Replay is the ability to create an event subscription that will
>   resend recently sent notifications.  These notifications are sent the
>   same way as normal notifications.

s/recently sent/recently generated/ since they may not have been sent
anywhere.

>   The actual number of stored notifications available for retrieval at
>   any given time is an NETCONF server implementation specific matter.
>   Control parameters for this aspect of the feature are outside the
>   scope of the current work.

s/the current work/this document/

>   This feature is dependent on a notification stream supporting some
>   form of notification logging, although it puts no restrictions on the
>   size or form of the log, nor where it resides within the device.

s/This feature/Replay/

>6.2.  Creating a Subscription with Replay
>   This feature uses optional parameters to the <create-subscription>
>   command called 'startTime' and 'stopTime'. 'startTime' identifies the
>   earliest date and time of interest for event notifications being
>   replayed and also indicates that a subscription will be providing
>   replay of notifications.  Events generated before this time are not
>   matched. 'stopTime' specifies the latest date and time of interest
>   for event notifications being replayed.  If it is not present, then
>   notifications will continue to be sent until the subscription is
>   terminated.

Talk about the transition to live events.

>   Note that while a notification has three potential times associated
>   it - the time it was generated, the time it was logged and the time
>   it was sent out by the NETCONF server - the startTime and stopTime
>   parameters are related to generation time.

This paragraph should just say event time should be relative to the
time the event occurred and the notification was generated.
Discussing the other times is confusing.

Is there a way to say <stop-time>now</stop-time> to avoid waiting for
live events?

>   Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing
>   their input into the early work on this document.  In addition, the
>   editors would like to acknowledge input at the Vancouver editing
>   session from the following people: Orly Nicklass, James Balestriere,
>   Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington,
>   Dave Partain, Ray Atarashi and Dave Perkins and the following
>   additional people from the Montreal editing session: Balazs Lengyel,
>   Phil Shafer, Rob Ennes, Andy Bierman, Dan Romascanu, Bert Wijnen,
>   Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig,
>   Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William
>   Chow.

s/Ennes/Enns/

So my final comment is just this:  This draft doesn't seem to follow
in the same mold as netconf.  Namespaces are different, tags are
different, content is different, and the general feel is completely
different.  Is that a good thing?  Are these differences viewed as
"things netconf got wrong that need repaired"?  Why is this draft so
far afield from the original netconf RFCs?  Shouldn't there be more
harmony, consistency, and cohesiveness between the documents?

Thanks,
 Phil

--
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: Sun, 01 Apr 2007 21:49:22 -0700

> of them were raised at the WG meeting, but others were not.

I can tell you have a lot of concerns about this draft.
There has been a clash of design philosophy from the start I think.
You and I want to deliver notifications while changing the protocol
as little as possible, while the design in the notifications draft
all along seems to want to change as much as possible.

Most importantly, we seem to have strayed very far from
our original design for notifications (use RFC 3195 syslog over beep),
to what we have now.

We seem to have started out trying to have little or no protocol overhead
and 100% operationally useful feature (syslog content).

We ended up with a 100% architectural solution with little or
no operational value.  The notification replay feature was not
even in the charter, yet most of the complexity is related to that.

We started out saying we at least need a config-change notification,
and we don't even have that.

I would really like to know if anybody is implementing this draft
and if so, whether the draft is complete enough to produce an
implementation.  If nobody is implementing, then that is a warning
sign in itself.

>  Phil

Andy

---

From: "Hector Trevino \(htrevino\)" <[email-masked]>
Date: Thu, 5 Apr 2007 09:40:54 -0700

Andy,

We have implemented notifications based on earlier versions of the
draft. 
Hector

-----------

I would really like to know if anybody is implementing this draft and if
so, whether the draft is complete enough to produce an implementation.
If nobody is implementing, then that is a warning sign in itself.

Andy