[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Purely editorial changes to the notification draft
Hi,
The attached diff includes suggested textual changes to the notification draft
(version dated July 8, 2007). I hope these improve readability.
netconf -> NETCONF throughout the text...
Should the "must" in 3.2.2 be "MUST"? I believe so but didn't change it.
I have only rudimentarily touched Section 1.4 (Requirements) since it is
getting a rewrite anyway.
I think it would be better to use startTime and stopTime (and other
similar "keywords") throughout rather than using "start time" sometimes
and "startTime" in others. I have, however, not made this change. I would be
happy to make changes to startTime and stopTime if others think this is a
good idea.
Cheers,
David
--- draft-ietf-netconf-notification-08.txt.orig 2007-07-23 14:38:49.000000000 +0200
+++ draft-ietf-netconf-notification-08.txt 2007-07-25 21:58:19.000000000 +0200
@@ -209,11 +209,11 @@
Subscription: An agreement and method to receive event notifications
over a NETCONF session. A concept related to the delivery of
- notifications (if any to send) involving destination and selection
+ notifications (if there are any to send) involving destination and selection
of notifications. It is bound to the lifetime of a session.
Operation: This term is used to refer to NETCONF protocol operations
- [NETCONF]. Specifically within this document, operation refers to
+ [NETCONF]. Within this document, operation refers to
NETCONF protocol operations defined in support of NETCONF
notifications.
@@ -264,9 +264,9 @@
to specify which events are of interest. These are specified when
the subscription is created.
- A NETCONF server is will not read RPC requests, by default, on the
+ A NETCONF server will, by default, not read RPC requests on the
session associated with the subscription until the notification
- subscription is done. A capability may be advertised to announce
+ subscription is completed. A capability may be advertised to announce
that a server is able to process RPCs while a notification stream is
active on a session. The behaviour of such a capability is outside
the scope of this document.
@@ -284,18 +284,18 @@
The following requirements have been addressed by the solution:
- o Initial release should ensure it supports notification in support
+ o Initial release should ensure it supports notifications in support
of configuration operations
o Data content must not preclude the use of the same data model as
used in configuration
- o Solution should support a reasonable message size limit (ie, not
+ o Solution should support a reasonable message size limit (i.e., not
too short)
o Solution should provide reliable delivery of notifications
- o Solution should provide a subscription mechanism (A NETCONF server
+ 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)
@@ -361,13 +361,13 @@
Stream:
An optional parameter that indicates which stream of events is
- of interest. If not present, then events in the default
+ of interest. If not present, events in the default
NETCONF stream will be sent.
Filter:
An optional parameter that indicates which subset of all
- possible events are of interest. The format of this parameter
+ possible events is 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. See section 3.6 for more
@@ -410,12 +410,12 @@
Negative Response:
An <rpc-error> element is included within the <rpc-reply> if the
- request cannot be completed for any reason. Subscription requests
+ request cannot be completed for some reason. Subscription requests
will fail if a filter with invalid syntax is provided or if the
name of a non-existent profile or stream is provided.
If a stopTime is specified in a request without having specified a
- startTime the following error is returned:
+ startTime, the following error is returned:
Tag: missing-element
@@ -473,12 +473,12 @@
Description:
- An event notification is sent to the client who initiated 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
+ When an event of interest occurs (i.e., matches the specified
+ filtering criteria), an event notification is sent asynchronously
+ to client(s) that initiated a <create-subscription> command
+ for the event. 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
+ rather the top level element identifying the one-way message as a
notification.
Parameters:
@@ -490,7 +490,7 @@
Response:
- No response. Not applicable.
+ This is not applicable as there is no response.
@@ -509,7 +509,7 @@
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 created, the subscription will terminate after the stop time
is reached. In this case, the NETCONF session will still be an
active session.
@@ -597,7 +597,7 @@
An event stream is defined as a set of event notifications matching
some forwarding criteria.
- The diagram depicted in Figure 2 illustrates the notification flow
+ 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
@@ -633,7 +633,7 @@
+----+ | +---------+
+----+ | |central |-> stream 1
| c2 | +--->|event |-> stream 2 filter +-------+
- +----+ | |processor|-> NETCONF stream ----->|netconf|
+ +----+ | |processor|-> NETCONF stream ----->|NETCONF|
... | | |-> stream n |server |
System | +---------+ +-------+
Components| | /\
@@ -647,7 +647,7 @@
||
\/
+-------+
- |netconf|
+ |NETCONF|
|client |
+-------+
@@ -690,7 +690,7 @@
3.2.4. Event Stream Sources
With the exception of the default event stream (NETCONF
- notifications) specification of additional event stream sources
+ 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.
@@ -706,7 +706,7 @@
<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 the <name>
- element is mandatory and its value is unique within the scope of a
+ element is mandatory, and its value is unique within the scope of a
NETCONF server. 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
@@ -728,7 +728,7 @@
Internet-Draft NETCONF Event Notifications July 2007
- Example: Retrieving available event stream list using <get>
+ Example: Retrieving the list of available event streams using the <get>
operation:
@@ -755,7 +755,7 @@
<eventStreams xmlns="urn:ietf:params:xml:ns:netmod:notification">
<stream>
<name>NETCONF</name>
- <description>Default netconf event stream
+ <description>Default NETCONF event stream
</description>
<replaySupport>true</replaySupport>
<replayLogStartTime>2007-07-08T00:00:00Z</replayLogStartTime>
@@ -788,9 +788,9 @@
3.2.5.2. Event Stream Subscription
- A NETCONF client may request from the NETCONF server the list of
- event streams available to this session and then issue a <create-
- subscription> request with the desired event stream name. Omitting
+ A NETCONF client may request the list of event streams available to
+ this session from the NETCONF server and 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.
@@ -802,10 +802,10 @@
associated with the event notification subscription and does not
modify the event stream configuration.
- XPATH support for the Notification capability is advertised as part
+ 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
+ advertised via the XPATH capability, XPATH is supported for
+ notification filtering. If XPATH support is not advertised,
XPATH is not supported for notification filtering.
3.3. Notification Replay
@@ -818,7 +818,7 @@
notifications are sent the same way as normal notifications.
A replay of notifications is specified by including an optional
- parameter to the subscription command that indicates the start time
+ parameter (startTime) in the subscription command that indicates the start time
of the replay. The end time is specified using the optional stopTime
parameter. If not present, notifications will continue to be sent
until the subscription is terminated.
@@ -842,7 +842,7 @@
Replay 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. Whether or
+ form of the log, or where it resides within the device. Whether or
not a stream supports replay can be discovered by doing a <get>
operation on the eventStreams element of the Notification Management
Schema. This schema also provides the replayLogStartTime element to
@@ -865,12 +865,11 @@
A replayComplete notification is sent to indicate that all of the
replay notifications have been sent. If this subscription has a stop
- time, then this session becomes a normal NETCONF session again. In
- the case of a subscription without a stop time, after the
- replayComplete notification has been sent, it can be expected that
- any notifications generated since the start of the subscription
- creation will be sent followed by notifications as they arise
- naturally within the system.
+ time, then this session becomes a normal NETCONF session again. If
+ the subscription has no stop time, it can be expected that any
+ notifications generated since the start of the subscription creation
+ will be sent after the replayComplete notification has been sent,
+ followed by notifications as they arise naturally within the system.
3.3.3. Replay Complete Notification
@@ -880,14 +879,14 @@
session becomes normal command-response NETCONF session.
The replayComplete can not be filtered out. It will always be sent
- on a relay subscription that specified a stop time.
+ on a replay subscription that specified a stop time.
3.4. Notification Management Schema
- This Schema is used to learn about the event streams supported on the
- system. It also contains the definition of the replayComplete, which
+ This schema is used to learn about the event streams supported on the
+ system. It also contains the definition of replayComplete, which
is sent to indicate that an event replay has sent all applicable
- notifications."
+ notifications.
@@ -1012,7 +1011,7 @@
While it may be possible to retrieve information about subscriptions
via a get operation, subscriptions are not stored configuration.
- They are non-persistent state information and their lifetime is
+ They are non-persistent state information, and their lifetime is
defined by their session.
3.6. Filter Mechanics
@@ -1065,7 +1064,7 @@
The following figure depicts message flow between a NETCONF client
- (C) and NETCONF server (S) in order create a subscription and begin
+ (C) and NETCONF server (S) in order to create a subscription and begin
the flow of notifications. It is possible that many rpc/rpc-reply
sequences occur before the subscription is created or after a
stopTime in a replay subscription, but this is not depicted in the
@@ -1189,7 +1188,7 @@
<xs:documentation>
An optional parameter that indicates
which subset of all possible events
- are of interest. The format of this
+ is of interest. The format of this
parameter is the same as that of the
filter parameter in the NETCONF
protocol operations. If not present,
@@ -1255,7 +1254,7 @@
<xs:documentation>
The command to create a notification subscription. It
takes as argument the name of the notification stream
- and filter or profile information. All of those options
+ and filter or profile information. All of those options
limit the content of the subscription. In addition,
there are two time-related parameters startTime and
stopTime which can be used to select the time interval
@@ -1351,14 +1350,14 @@
5.1. Subtree Filtering
- XML subtree filtering is not well suited for creating elaborate
+ XML subtree filtering is not well-suited for creating elaborate
filter definitions given that it only supports equality comparisons
and logical OR operations (e.g., in an event subtree give me all
event notifications which have severity=critical or severity=major or
severity=minor). Nevertheless, it may be used for defining simple
event notification forwarding filters as shown below.
- In order to illustrate the use of filter expressions it is necessary
+ In order to illustrate the use of filter expressions, it is necessary
to assume some of the event notification content. The examples
herein assume that the event notification schema definition has an
<events> element at the top level that contains one or more child
@@ -1438,7 +1437,7 @@
Figure 10
- The following example illustrates selecting events which have
+ The following example illustrates how to select events which have
severities of critical, major, or minor (presumably fault events).
The filtering criteria evaluation is as follows:
@@ -1481,7 +1480,7 @@
Figure 11
- The following example illustrates selecting state or config
+ The following example illustrates how to select state or config
EventClasses or fault events that are related to card Ethernet0. The
filtering criteria evaluation is as follows:
@@ -1539,7 +1538,7 @@
5.2. XPATH filters
- The following [XPATH] example illustrates selecting fault EventClass
+ The following [XPATH] example illustrates how to select fault EventClass
notifications that have severities of critical, major, or minor. The
filtering criteria evaluation is as follows:
@@ -1570,7 +1569,7 @@
Figure 13
- The following example illustrates selecting state and config
+ The following example illustrates how to select state and config
EventClasses or fault events that have severities of critical, major,
or minor or come from card Ethernet0. The filtering criteria
evaluation is as follows:
@@ -1626,14 +1625,14 @@
6. Security Considerations
- The security considerations from the base [NETCONF] document apply
- also to the Notification capability.
+ The security considerations from the base [NETCONF] document also
+ apply to the Notification capability.
The access control framework and the choice of transport will have a
major impact on the security of the solution.
The <notification> elements are never sent before the transport layer
- and the netconf layer (capabilities exchange) have been established,
+ and the NETCONF layer (capabilities exchange) have been established,
and the manager has been identified and authenticated.
It is recommended that care be taken to ensure the secure operation
@@ -1647,24 +1646,24 @@
o notification content
- One issue related to the notifications draft is the transport of data
- from non-netconf streams, such as syslog and SNMP. This data may be
+ One issue related to NETCONF event notifications is the transport of data
+ from non-NETCONF streams, such as syslog and SNMP. This data may be
more vulnerable (or is not more vulnerable) when being transported
- over netconf than when being transported using the protocol normally
+ over NETCONF than when being transported using the protocol normally
used for transporting it, depending on the security credentials of
the two subsystems. The NETCONF server is responsible for providing
access control to stream content.
If a user does not have permission to view content via other NETCONF
- operations it does not have permission to access that content via
- Notifications. If a user is not permitted to view one element in the
+ operations, the user does not have permission to access that content via
+ notifications. If a user is not permitted to view one element in the
content of the notification, the notification is not sent to that
user.
If a subscription is created with a stopTime, the NETCONF session
will return to being a normal command-response NETCONF session when
the replay is completed. It is the responsibility of the NETCONF
- client to close off this session when it is no longer of use.
+ client to close this session when it is no longer of use.
@@ -1743,7 +1742,7 @@
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
+ David Partain, Ray Atarashi and Dave Perkins and the following
additional people from the Montreal editing session: Balazs Lengyel,
Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen,
Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig,