---------------------
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 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/>