draft-ietf-netconf-notification-08.txt | draft-ietf-netconf-notification-09.txt | |||
---|---|---|---|---|
Network Working Group S. Chisholm | Network Working Group S. Chisholm | |||
Internet-Draft Nortel | Internet-Draft Nortel | |||
Intended status: Standards Track H. Trevino | Intended status: Standards Track H. Trevino | |||
Expires: January 9, 2008 Cisco | Expires: March 13, 2008 Cisco | |||
July 8, 2007 | September 10, 2007 | |||
NETCONF Event Notifications | NETCONF Event Notifications | |||
draft-ietf-netconf-notification-08.txt.pre-release | draft-ietf-netconf-notification-09.txt | |||
Status of this Memo | Status of this Memo | |||
By submitting this Internet-Draft, each author represents that any | By submitting this Internet-Draft, each author represents that any | |||
applicable patent or other IPR claims of which he or she is aware | applicable patent or other IPR claims of which he or she is aware | |||
have been or will be disclosed, and any of which he or she becomes | have been or will be disclosed, and any of which he or she becomes | |||
aware will be disclosed, in accordance with Section 6 of BCP 79. | aware will be disclosed, in accordance with Section 6 of BCP 79. | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF), its areas, and its working groups. Note that | Task Force (IETF), its areas, and its working groups. Note that | |||
skipping to change at page 1, line 35 | skipping to change at page 1, line 35 | |||
and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
The list of current Internet-Drafts can be accessed at | The list of current Internet-Drafts can be accessed at | |||
http://www.ietf.org/ietf/1id-abstracts.txt. | http://www.ietf.org/ietf/1id-abstracts.txt. | |||
The list of Internet-Draft Shadow Directories can be accessed at | The list of Internet-Draft Shadow Directories can be accessed at | |||
http://www.ietf.org/shadow.html. | http://www.ietf.org/shadow.html. | |||
This Internet-Draft will expire on January 9, 2008. | This Internet-Draft will expire on March 13, 2008. | |||
Copyright Notice | Copyright Notice | |||
Copyright (C) The IETF Trust (2007). | Copyright (C) The IETF Trust (2007). | |||
Abstract | Abstract | |||
This document defines mechanisms which provide an asynchronous | This document defines mechanisms that provide an asynchronous message | |||
message notification delivery service for the NETCONF protocol. This | notification delivery service for the NETCONF protocol. This is an | |||
is an optional capability built on top of the base NETCONF | optional capability built on top of the base NETCONF definition. | |||
definition. This document defines the capabilities and operations | This document defines the capabilities and operations necessary to | |||
necessary to support this service. | support this service. | |||
Table of Contents | Table of Contents | |||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 4 | 1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 4 | |||
1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 | 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
1.3. Event Notifications in NETCONF . . . . . . . . . . . . . . 5 | 1.3. Event Notifications in NETCONF . . . . . . . . . . . . . . 6 | |||
1.4. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6 | ||||
2. Notification-Related Operations . . . . . . . . . . . . . . . 7 | 2. Notification-Related Operations . . . . . . . . . . . . . . . 7 | |||
2.1. Subscribing to Receive Event Notifications . . . . . . . . 7 | 2.1. Subscribing to Receive Event Notifications . . . . . . . . 7 | |||
2.1.1. <create-subscription> . . . . . . . . . . . . . . . . 7 | 2.1.1. <create-subscription> . . . . . . . . . . . . . . . . 7 | |||
2.2. Sending Event Notifications . . . . . . . . . . . . . . . 9 | 2.2. Sending Event Notifications . . . . . . . . . . . . . . . 9 | |||
2.2.1. <notification> . . . . . . . . . . . . . . . . . . . . 9 | 2.2.1. <notification> . . . . . . . . . . . . . . . . . . . . 9 | |||
2.3. Terminating the Subscription . . . . . . . . . . . . . . . 10 | 2.3. Terminating the Subscription . . . . . . . . . . . . . . . 10 | |||
3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 11 | 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 11 | |||
3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 11 | 3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 11 | |||
3.1.1. Capability Identifier . . . . . . . . . . . . . . . . 11 | 3.1.1. Capability Identifier . . . . . . . . . . . . . . . . 11 | |||
3.1.2. Capability Example . . . . . . . . . . . . . . . . . . 11 | 3.1.2. Capability Example . . . . . . . . . . . . . . . . . . 11 | |||
3.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 11 | 3.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 11 | |||
3.2.1. Event Stream Definition . . . . . . . . . . . . . . . 12 | 3.2.1. Event Stream Definition . . . . . . . . . . . . . . . 13 | |||
3.2.2. Event Stream Content Format . . . . . . . . . . . . . 13 | 3.2.2. Event Stream Content Format . . . . . . . . . . . . . 13 | |||
3.2.3. Default Event Stream . . . . . . . . . . . . . . . . . 13 | 3.2.3. Default Event Stream . . . . . . . . . . . . . . . . . 13 | |||
3.2.4. Event Stream Sources . . . . . . . . . . . . . . . . . 13 | 3.2.4. Event Stream Sources . . . . . . . . . . . . . . . . . 13 | |||
3.2.5. Event Stream Discovery . . . . . . . . . . . . . . . . 13 | 3.2.5. Event Stream Discovery . . . . . . . . . . . . . . . . 13 | |||
3.3. Notification Replay . . . . . . . . . . . . . . . . . . . 15 | 3.3. Notification Replay . . . . . . . . . . . . . . . . . . . 16 | |||
3.3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 15 | 3.3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 16 | |||
3.3.2. Creating a Subscription with Replay . . . . . . . . . 16 | 3.3.2. Creating a Subscription with Replay . . . . . . . . . 17 | |||
3.3.3. Replay Complete Notification . . . . . . . . . . . . . 16 | 3.4. Notification Management Schema . . . . . . . . . . . . . . 17 | |||
3.4. Notification Management Schema . . . . . . . . . . . . . . 16 | 3.5. Subscriptions Data . . . . . . . . . . . . . . . . . . . . 21 | |||
3.5. Subscriptions Data . . . . . . . . . . . . . . . . . . . . 19 | 3.6. Filter Mechanics . . . . . . . . . . . . . . . . . . . . . 21 | |||
3.6. Filter Mechanics . . . . . . . . . . . . . . . . . . . . . 19 | 3.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 21 | |||
3.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 19 | 3.7. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 21 | |||
3.7. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 19 | 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 24 | |||
4. XML Schema for Event Notifications . . . . . . . . . . . . . . 21 | 5. Filtering Examples . . . . . . . . . . . . . . . . . . . . . . 28 | |||
5. Filtering Examples . . . . . . . . . . . . . . . . . . . . . . 25 | 5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 32 | |||
5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 25 | 5.2. XPATH filters . . . . . . . . . . . . . . . . . . . . . . 33 | |||
5.2. XPATH filters . . . . . . . . . . . . . . . . . . . . . . 28 | 6. Security Considerations . . . . . . . . . . . . . . . . . . . 35 | |||
6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 | 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 | |||
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 | 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 37 | |||
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 32 | 9. Normative References . . . . . . . . . . . . . . . . . . . . . 38 | |||
9. Normative References . . . . . . . . . . . . . . . . . . . . . 33 | Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 39 | |||
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 34 | A.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 39 | |||
A.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 34 | A.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . . 41 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 37 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 44 | |||
Intellectual Property and Copyright Statements . . . . . . . . . . 38 | Intellectual Property and Copyright Statements . . . . . . . . . . 45 | |||
1. Introduction | 1. Introduction | |||
[NETCONF] can be conceptually partitioned into four layers: | [NETCONF] can be conceptually partitioned into four layers: | |||
Layer Example | Layer Example | |||
+-------------+ +----------------------------------------+ | +-------------+ +----------------------------------------+ | |||
| Content | | Configuration data | | | Content | | Configuration data | | |||
+-------------+ +----------------------------------------+ | +-------------+ +----------------------------------------+ | |||
| | | | | | |||
skipping to change at page 4, line 45 | skipping to change at page 4, line 45 | |||
1.1. Definition of Terms | 1.1. Definition of Terms | |||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | |||
document are to be interpreted as described in [RFC2119]. | document are to be interpreted as described in [RFC2119]. | |||
Element: An [XML] Element. | Element: An [XML] Element. | |||
Subscription: An agreement and method to receive event notifications | Subscription: An agreement and method to receive event notifications | |||
over a NETCONF session. A concept related to the delivery of | 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 | |||
of notifications. It is bound to the lifetime of a session. | selection of notifications. It is bound to the lifetime of a | |||
session. | ||||
Operation: This term is used to refer to NETCONF protocol operations | 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 | |||
NETCONF protocol operations defined in support of NETCONF | protocol operations defined in support of NETCONF notifications. | |||
notifications. | ||||
Event: An event is something that happens which may be of interest - | Event: An event is something that happens which may be of interest - | |||
a configuration change, a fault, a change in status, crossing a | a configuration change, a fault, a change in status, crossing a | |||
threshold, or an external input to the system, for example. Often | threshold, or an external input to the system, for example. Often | |||
this results in an asynchronous message, sometimes referred to as | this results in an asynchronous message, sometimes referred to as | |||
a notification or event notification, being sent to interested | a notification or event notification, being sent to interested | |||
parties to notify them that this event has occurred. | parties to notify them that this event has occurred. | |||
Replay: The ability to send/re-send previously logged notifications | Replay: The ability to send/re-send previously logged notifications | |||
upon request. These notifications are sent asynchronously. This | upon request. These notifications are sent asynchronously. This | |||
feature is implemented by the NETCONF server and invoked by the | feature is implemented by the NETCONF server and invoked by the | |||
NETCONF client. | NETCONF client. | |||
Stream: An event stream is a set of event notifications matching | Stream: An event stream is a set of event notifications matching | |||
some forwarding criteria and it is available to NETCONF clients | some forwarding criteria and available to NETCONF clients for | |||
for subscription. | subscription. | |||
Filter: A parameter that indicates which subset of all possible | Filter: A parameter that indicates which subset of all possible | |||
events are of interest. | events are of interest. A filter is defined as one or more filter | |||
element [NETCONF], which each identifies a portion of the overall | ||||
filter. | ||||
1.2. Motivation | 1.2. Motivation | |||
The motivation for this work is to enable the sending of asynchronous | The motivation for this work is to enable the sending of asynchronous | |||
messages that are consistent with the data model (content) and | messages that are consistent with the data model (content) and | |||
security model used within a NETCONF implementation. | security model used within a NETCONF implementation. | |||
The scope of the work aims meeting the following operational needs: | ||||
o Initial release should ensure it supports notifications in support | ||||
of configuration operations. | ||||
o It should be possible to use the same data model for notifications | ||||
as for configuration operations. | ||||
o Solution should support a reasonable message size limit (i.e., not | ||||
too short) | ||||
o The notifications should be carried over a connection-oriented | ||||
delivery mechanism. | ||||
o A subscription mechanism for notifications should be provided. | ||||
This takes into account that a NETCONF server does not send | ||||
notifications before being asked to do so and that it is the | ||||
NETCONF client who initiates the flow of notifications. | ||||
o A filtering mechanism for sending notifications should be put in | ||||
place within the NETCONF server. | ||||
o The information contained in a notification should be sufficient | ||||
so that it can be analyzed independent of the transport mechanism. | ||||
In other words the data content fully describes a notification; | ||||
protocol information is not needed to understand a notification. | ||||
o The server should have the capability to replay locally logged | ||||
notifications. | ||||
1.3. Event Notifications in NETCONF | 1.3. Event Notifications in NETCONF | |||
This memo defines a mechanism whereby the NETCONF client indicates | This memo defines a mechanism whereby the NETCONF client indicates | |||
interest in receiving event notifications from a NETCONF server by | interest in receiving event notifications from a NETCONF server by | |||
creating a subscription to receive event notifications. The NETCONF | creating a subscription to receive event notifications. The NETCONF | |||
server replies to indicate whether the subscription request was | server replies to indicate whether the subscription request was | |||
successful and, if it was successful, begins sending the event | successful and, if it was successful, begins sending the event | |||
notifications to the NETCONF client as the events occur within the | notifications to the NETCONF client as the events occur within the | |||
system. These event notifications will continue to be sent until | system. These event notifications will continue to be sent until | |||
either the NETCONF session is terminated or the subscription | either the NETCONF session is terminated or the subscription | |||
terminates for some other reason. The event notification | terminates for some other reason. The event notification | |||
subscription allows a number of options to enable the NETCONF client | subscription allows a number of options to enable the NETCONF client | |||
to specify which events are of interest. These are specified when | to specify which events are of interest. These are specified when | |||
the subscription is created. | the subscription is created. | |||
A NETCONF server is will not read RPC requests, by default, on the | The NETCONF server MUST accept and process the close-session | |||
session associated with the subscription until the notification | operation, even while the notification subscription is active. The | |||
subscription is done. A capability may be advertised to announce | NETCONF server MAY accept and process other commands, otherwise they | |||
that a server is able to process RPCs while a notification stream is | will be rejected and the server MUST send a 'resource-denied' error. | |||
active on a session. The behaviour of such a capability is outside | An example of when other commands would be processed is if a separate | |||
the scope of this document. | capability was advertised indicating support of this functionality. | |||
1.4. Requirements | ||||
The following requirements have been addressed by the solution: | ||||
o Initial release should ensure it supports notification 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 | ||||
too short) | ||||
o Solution should provide reliable delivery of notifications | ||||
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) | ||||
o Solution should provide a filtering mechanism within the NETCONF | ||||
server | ||||
o Solution should send sufficient information in a notification so | ||||
that it can be analyzed independent of the transport mechanism | ||||
(data content fully describes a notification; protocol information | ||||
is not needed to understand a notification) | ||||
o Solution should support replay of locally logged notifications | ||||
2. Notification-Related Operations | 2. Notification-Related Operations | |||
2.1. Subscribing to Receive Event Notifications | 2.1. Subscribing to Receive Event Notifications | |||
The event notification subscription is initiated by the NETCONF | The event notification subscription is initiated by the NETCONF | |||
client and responded to by the NETCONF server. When the event | client and responded to by the NETCONF server. A subscription is | |||
notification subscription is created, the events of interest are | bound to a single stream for the lifetime of the subscription. When | |||
specified. | the event notification subscription is created, the events of | |||
interest are specified. | ||||
Content for an event notification subscription can be selected by | Content for an event notification subscription can be selected by | |||
applying user-specified filters. | applying user-specified filters. | |||
2.1.1. <create-subscription> | 2.1.1. <create-subscription> | |||
Description: | Description: | |||
This operation initiates an event notification subscription which | This operation initiates an event notification subscription which | |||
will send asynchronous event notifications to the initiator of the | will send asynchronous event notifications to the initiator of the | |||
command until the subscription terminates. | command until the subscription terminates. | |||
Parameters: | Parameters: | |||
Stream: | Stream: | |||
An optional parameter that indicates which stream of events is | An optional parameter, <stream>, that indicates which stream of | |||
of interest. If not present, then events in the default | events is of interest. If not present, events in the default | |||
NETCONF stream will be sent. | NETCONF stream will be sent. | |||
Filter: | Filter: | |||
An optional parameter that indicates which subset of all | An optional parameter, <filter>, that indicates which subset of | |||
possible events are of interest. The format of this parameter | all possible events is of interest. The format of this | |||
is the same as that of the filter parameter in the NETCONF | parameter is the same as that of the filter parameter in the | |||
protocol operations. If not present, all events not precluded | NETCONF protocol operations. If not present, all events not | |||
by other parameters will be sent. See section 3.6 for more | precluded by other parameters will be sent. See section 3.6 | |||
information on filters. | for more information on filters. | |||
Start Time: | Start Time: | |||
A parameter used to trigger the replay feature and indicate | A parameter, <startTime>, used to trigger the replay feature | |||
that the replay should start at the time specified. If | and indicate that the replay should start at the time | |||
startTime is not present, this is not a replay subscription. | specified. If <startTime> is not present, this is not a replay | |||
It is valid to specify start times that are later than the | subscription. It is not valid to specify start times that are | |||
current time. If the startTime specified is earlier than the | later than the current time. If the <startTime> specified is | |||
log can support, the replay will begin with the earliest | earlier than the log can support, the replay will begin with | |||
available notification. This parameter is of type dateTime. | the earliest available notification. This parameter is of type | |||
dateTime. | ||||
Stop Time: | Stop Time: | |||
An optional parameter used with the optional replay feature to | An optional parameter, <stopTime>, used with the optional | |||
indicate the newest notifications of interest. If stop time is | replay feature to indicate the newest notifications of | |||
not present, the notifications will continue until the | interest. If stop time is not present, the notifications will | |||
subscription is terminated. Must be used with and be later | continue until the subscription is terminated. Must be used | |||
than 'startTime'. It is valid to specify stop times that are | with and be later than <startTime>. A stop times that is later | |||
later than the current time. This parameter is of type | than the current time, will be interpreted as being the time of | |||
dateTime. | the subscription creation (current time). This parameter is of | |||
type dateTime. | ||||
Positive Response: | Positive Response: | |||
If the NETCONF server can satisfy the request, the server sends an | If the NETCONF server can satisfy the request, the server sends an | |||
<ok> element. | <ok> element. | |||
Negative Response: | Negative Response: | |||
An <rpc-error> element is included within the <rpc-reply> if the | 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 any reason. Subscription requests | |||
will fail if a filter with invalid syntax is provided or if the | will fail if a filter with invalid syntax is provided or if the | |||
name of a non-existent profile or stream is provided. | name of a non-existent stream is provided. | |||
If a stopTime is specified in a request without having specified a | If a <stopTime> is specified in a request without having specified | |||
startTime the following error is returned: | a <startTime>, the following error is returned: | |||
Tag: missing-element | Tag: missing-element | |||
Error-type: protocol | Error-type: protocol | |||
Severity: error | Severity: error | |||
Error-info: <badElement>: startTime | Error-info: <bad-element>: startTime | |||
Description: An expected element is missing. | Description: An expected element is missing. | |||
If the optional replay feature is requested but it is not | If the optional replay feature is requested but it is not | |||
supported by the NETCONF server, the following error is returned: | supported by the NETCONF server, the following error is returned: | |||
Tag: operation-failed | Tag: operation-failed | |||
Error-type: protocol | Error-type: protocol | |||
skipping to change at page 8, line 48 | skipping to change at page 9, line 4 | |||
Description: An expected element is missing. | Description: An expected element is missing. | |||
If the optional replay feature is requested but it is not | If the optional replay feature is requested but it is not | |||
supported by the NETCONF server, the following error is returned: | supported by the NETCONF server, the following error is returned: | |||
Tag: operation-failed | Tag: operation-failed | |||
Error-type: protocol | Error-type: protocol | |||
Severity: error | Severity: error | |||
Error-info: none | Error-info: none | |||
Description: Request could not be completed because the | Description: Request could not be completed because the | |||
requested operation failed for some reason not covered by any | requested operation failed for some reason not covered by any | |||
other error condition | other error condition | |||
2.1.1.1. Usage Example | 2.1.1.1. Usage Example | |||
The following demonstrates creating a simple subscription. More | ||||
complex examples can be found in section 5. | ||||
<netconf:rpc message-id="101" | <netconf:rpc message-id="101" | |||
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> | xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"/> | |||
<create-subscription | <create-subscription | |||
xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | |||
</create-subscription> | </create-subscription> | |||
</netconf:rpc> | </netconf:rpc> | |||
Figure 2 | ||||
2.2. Sending Event Notifications | 2.2. Sending Event Notifications | |||
Once the subscription has been set up, the NETCONF server sends the | Once the subscription has been set up, the NETCONF server sends the | |||
event notifications asynchronously over the connection. | event notifications asynchronously over the connection. | |||
2.2.1. <notification> | 2.2.1. <notification> | |||
Description: | Description: | |||
An event notification is sent to the client who initiated a | An event notification is sent to the client who initiated a | |||
<create-subscription> command asynchronously when an event of | <create-subscription> command asynchronously when an event of | |||
interest (i.e., meeting the specified filtering criteria) to them | interest (i.e., meeting the specified filtering criteria) has | |||
has occurred. An event notification is a complete and well-formed | occurred. An event notification is a complete and well-formed XML | |||
XML document. Note that <notification> is not an RPC method but | 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. | notification. | |||
Parameters: | Parameters: | |||
Contains notification-specific tagged content. The content of | eventTime | |||
the data tag is beyond the scope of this document. | ||||
The time the event was generated by the event source | ||||
Also contains notification-specific tagged content, if any. With | ||||
the exception of <eventTime>, the content of the notification is | ||||
beyond the scope of this document. | ||||
Response: | Response: | |||
No response. Not applicable. | No response. Not applicable. | |||
2.3. Terminating the Subscription | 2.3. Terminating the Subscription | |||
Closing of the event notification subscription can be done by | Closing of the event notification subscription can be done by | |||
terminating the NETCONF session ( <kill-session> ) or the underlying | terminating the NETCONF session ( <kill-session> ) or the underlying | |||
transport session. If a stop time is provided when the subscription | 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 | |||
is reached. In this case, the NETCONF session will still be an | reached. In this case, the NETCONF session will still be an active | |||
active session. | session. | |||
3. Supporting Concepts | 3. Supporting Concepts | |||
3.1. Capabilities Exchange | 3.1. Capabilities Exchange | |||
The ability to process and send event notifications is advertised | The ability to process and send event notifications is advertised | |||
during the capability exchange between the NETCONF client and server. | during the capability exchange between the NETCONF client and server. | |||
3.1.1. Capability Identifier | 3.1.1. Capability Identifier | |||
skipping to change at page 11, line 33 | skipping to change at page 11, line 33 | |||
<capability> | <capability> | |||
urn:ietf:params:netconf:capability:startup:1.0 | urn:ietf:params:netconf:capability:startup:1.0 | |||
</capability> | </capability> | |||
<capability> | <capability> | |||
urn:ietf:params:netconf:capability:notification:1.0 | urn:ietf:params:netconf:capability:notification:1.0 | |||
</capability> | </capability> | |||
</capabilities> | </capabilities> | |||
<session-id>4</session-id> | <session-id>4</session-id> | |||
</hello> | </hello> | |||
Figure 3 | ||||
3.2. Event Streams | 3.2. Event Streams | |||
An event stream is defined as a set of event notifications matching | An event stream is defined as a set of event notifications matching | |||
some forwarding criteria. | some forwarding criteria. | |||
The diagram depicted in Figure 2 illustrates the notification flow | Figure 2 illustrates the notification flow and concepts identified in | |||
and concepts identified in this document. The following is observed | this document. The following is observed from the diagram below: | |||
from the diagram below: System components (c1..cn) generate event | System components (c1..cn) generate event notifications which are | |||
notifications which are passed to a central component for | passed to a central component for classification and distribution. | |||
classification and distribution. The central component inspects each | The central component inspects each event notification and matches | |||
event notification and matches the event notification against the set | the event notification against the set of stream definitions. When a | |||
of stream definitions. When a match occurs, the event notification | match occurs, the event notification is considered to be a member of | |||
is considered to be a member of that event stream (stream 1..stream | that event stream (stream 1..stream n). An event notification may be | |||
n). An event notification may be part of multiple event streams. | part of multiple event streams. | |||
At some point after the NETCONF server receives the internal event | ||||
from a stream, it is converted to an appropriate XML encoding by the | ||||
server, and a <notification> element is ready to send to all NETCONF | ||||
sessions subscribed to that stream. | ||||
After generation of the <notification> element, access control is | ||||
applied by the server. If a session does not have permission to | ||||
receive the <notification>, then it is discarded for that session, | ||||
and processing of the internal event is completed for that session. | ||||
When a NETCONF client subscribes to a given event stream, user- | When a NETCONF client subscribes to a given event stream, user- | |||
defined filters, if applicable, are applied to the event stream and | defined filter elements, if applicable, are applied to the event | |||
matching event notifications are forwarded to the NETCONF server for | stream and matching event notifications are forwarded to the NETCONF | |||
distribution to subscribed NETCONF clients. For more information on | server for distribution to subscribed NETCONF clients. A filter is | |||
filters, see section 3.6. | transferred from the client to the server during the <create- | |||
subscription> operation and applied against each <notification> | ||||
element generated by the stream. For more information on filtering, | ||||
see section 3.6. | ||||
A notification logging service may also be available, in which case, | A notification logging service may also be available, in which case, | |||
the central component logs notifications. The NETCONF server may | the central component logs notifications. The NETCONF server may | |||
later retrieve logged notifications via the optional replay feature. | later retrieve logged notifications via the optional replay feature. | |||
For more information on replay, see section 3.3. | For more information on replay, see section 3.3. | |||
+----+ | +----+ | |||
| c1 |----+ available streams | | c1 |----+ available streams | |||
+----+ | +---------+ | +----+ | +---------+ | |||
+----+ | |central |-> stream 1 | +----+ | |central |-> stream 1 | |||
| c2 | +--->|event |-> stream 2 filter +-------+ | | c2 | +--->|event |-> stream 2 filter +-------+ | |||
+----+ | |processor|-> NETCONF stream ----->|netconf| | +----+ | |processor|-> NETCONF stream ----->|NETCONF| | |||
... | | |-> stream n |server | | ... | | |-> stream n |server | | |||
System | +---------+ +-------+ | System | +---------+ +-------+ | |||
Components| | /\ | Components| | /\ | |||
... | | || | ... | | || | |||
+----+ | | (------------) || | +----+ | | (------------) || | |||
| cn |----+ | (notification) || | | cn |----+ | (notification) || | |||
+----+ +-----> ( logging ) || | +----+ +-----> ( logging ) || | |||
( service ) || | ( service ) || | |||
(------------) || | (------------) || | |||
|| | || | |||
|| | || | |||
\/ | \/ | |||
+-------+ | +-------+ | |||
|netconf| | |NETCONF| | |||
|client | | |client | | |||
+-------+ | +-------+ | |||
Figure 4 | Figure 2 | |||
3.2.1. Event Stream Definition | 3.2.1. Event Stream Definition | |||
Event streams are predefined on the managed device. The | Event streams are predefined on the managed device. The | |||
configuration of event streams is outside the scope of this document. | configuration of event streams is outside the scope of this document. | |||
However, it is envisioned that event streams are either pre- | However, it is envisioned that event streams are either pre- | |||
established by the vendor (pre-configured) or user configurable | established by the vendor (pre-configured), user configurable (e.g., | |||
(e.g., part of the device's configuration) or both. Device vendors | part of the device's configuration) or both. Device vendors may | |||
may allow event stream configuration via NETCONF protocol (i.e., | allow event stream configuration via the NETCONF protocol (i.e., | |||
edit-config operation). | edit-config operation). | |||
3.2.2. Event Stream Content Format | 3.2.2. Event Stream Content Format | |||
The contents of all event streams made available to a NETCONF client | The contents of all event streams made available to a NETCONF client | |||
(i.e., the notification sent by the NETCONF server) must be encoded | (i.e., the notification sent by the NETCONF server) must be encoded | |||
in XML. | in XML. | |||
3.2.3. Default Event Stream | 3.2.3. Default Event Stream | |||
A NETCONF server implementation supporting the notification | A NETCONF server implementation supporting the notification | |||
capability must support the "NETCONF" notification event stream. | capability must support the "NETCONF" notification event stream. | |||
This stream contains all NETCONF XML event notifications supported by | This stream contains all NETCONF XML event notifications supported by | |||
the NETCONF server. The definition of the event notifications and | the NETCONF server. The exact string "NETCONF" is used during | |||
their contents for this event stream is outside the scope of this | advertisement of stream support during the <get> operation on | |||
<streams> and during the <create-subscription> operation. Definition | ||||
of the event notifications and their contents, beyond the inclusion | ||||
of <eventTime>, for this event stream is outside the scope of this | ||||
document. | document. | |||
3.2.4. Event Stream Sources | 3.2.4. Event Stream Sources | |||
With the exception of the default event stream (NETCONF | With the exception of the default event stream (NETCONF), | |||
notifications) specification of additional event stream sources | specification of additional event stream sources (e.g., SNMP, syslog) | |||
(e.g., SNMP, syslog, etc.) is outside the scope of this document. | is outside the scope of this document. NETCONF server | |||
NETCONF server implementations may leverage any desired event stream | implementations may leverage any desired event stream source in the | |||
source in the creation of supported event streams. | creation of supported event streams. | |||
3.2.5. Event Stream Discovery | 3.2.5. Event Stream Discovery | |||
A NETCONF client retrieves the list of supported event streams from a | A NETCONF client retrieves the list of supported event streams from a | |||
NETCONF server using the <get> RPC request. | NETCONF server using the <get> operation. | |||
3.2.5.1. Name Retrieval using <get> operation | 3.2.5.1. Name Retrieval using <get> operation | |||
The list of available event streams is retrieved by requesting the | The list of available event streams is retrieved by requesting the | |||
<eventStreams> subtree via a <get> operation. Available event | <streams> subtree via a <get> operation. Available event streams for | |||
streams for the requesting session are returned in the reply | the requesting session are returned in the reply containing the | |||
containing the <name> and <description> elements, where the <name> | <name> and <description> elements, where the <name> element is | |||
element is mandatory and its value is unique within the scope of a | mandatory, and its value is unique within the scope of a NETCONF | |||
NETCONF server. The returned list must only include the names of | server. An empty reply is returned if there are no available event | |||
those event streams for which the NETCONF session has sufficient | streams. | |||
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. | ||||
Example: Retrieving available event stream list using <get> | Additional information available about a stream include whether | |||
operation: | notification replay is available and if so, the timestamp of the | |||
earliest possible notification to replay. | ||||
The following example shows retrieving the list of available event | ||||
stream list using the <get> operation. | ||||
<rpc message-id="101" | <rpc message-id="101" | |||
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> | xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> | |||
<get> | <get> | |||
<filter type="subtree"> | <filter type="subtree"> | |||
<eventStreams xmlns="urn:ietf:params:xml:ns:netmod:notification"/> | <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification"> | |||
<streams/> | ||||
<netconf> | ||||
</filter> | </filter> | |||
</get> | </get> | |||
</rpc> | </rpc> | |||
Figure 5 | ||||
The NETCONF server returns a list of event streams available for | The NETCONF server returns a list of event streams available for | |||
subscription: NETCONF, SNMP, and syslog-critical in this example. | subscription: NETCONF, SNMP, and syslog-critical in this example. | |||
<rpc-reply message-id="101" | <rpc-reply message-id="101" | |||
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> | xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> | |||
<data> | <data> | |||
<eventStreams xmlns="urn:ietf:params:xml:ns:netmod:notification"> | <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification"> | |||
<streams> | ||||
<stream> | <stream> | |||
<name>NETCONF</name> | <name>NETCONF</name> | |||
<description>Default netconf event stream | <description>default NETCONF event stream | |||
</description> | </description> | |||
<replaySupport>true</replaySupport> | <replaySupport>true</replaySupport> | |||
<replayLogStartTime>2007-07-08T00:00:00Z</replayLogStartTime> | <replayLogCreationTime> | |||
2007-07-08T00:00:00Z | ||||
</replayLogCreationTime> | ||||
</stream> | </stream> | |||
<stream> | <stream> | |||
<name>SNMP</name> | <name>SNMP</name> | |||
<description>SNMP notifications</description> | <description>SNMP notifications</description> | |||
<replaySupport>false</replaySupport> | <replaySupport>false</replaySupport> | |||
</stream> | </stream> | |||
<stream> | <stream> | |||
<name>syslog-critical</name> | <name>syslog-critical</name> | |||
<description>Critical and higher severity | <description>Critical and higher severity | |||
</description> | </description> | |||
<replaySupport>true</replaySupport> | <replaySupport>true</replaySupport> | |||
<replayLogStartTime>2007-07-01T00:00:00Z</replayLogStartTime> | <replayLogCreationTime> | |||
2007-07-01T00:00:00Z | ||||
</replayLogCreationTime> | ||||
</stream> | </stream> | |||
</eventStreams> | </streams> | |||
</netconf> | ||||
</data> | </data> | |||
</rpc-reply> | </rpc-reply> | |||
Figure 6 | ||||
3.2.5.2. Event Stream Subscription | 3.2.5.2. Event Stream Subscription | |||
A NETCONF client may request from the NETCONF server the list of | A NETCONF client may request from the NETCONF server the list of | |||
event streams available to this session and then issue a <create- | event streams available to this session and then issue a <create- | |||
subscription> request with the desired event stream name. Omitting | subscription> request with the desired event stream name. Omitting | |||
the event stream name from the <create-subscription> request results | the event stream name from the <create-subscription> request results | |||
in subscription to the default NETCONF event stream. | in subscription to the default NETCONF event stream. | |||
3.2.5.2.1. Filtering Event Stream Contents | 3.2.5.2.1. Filtering Event Stream Contents | |||
The set of event notifications delivered in an event stream may be | The set of event notifications delivered in an event stream may be | |||
further refined by applying a user-specified filter at subscription | further refined by applying a user-specified filter supplied at | |||
creation time ( <create-subscription> ). This is a transient filter | subscription creation time ( <create-subscription> ). This is a | |||
associated with the event notification subscription and does not | transient filter associated with the event notification subscription | |||
modify the event stream configuration. | and does not modify the event stream configuration. The filter | |||
element is applied against the contents of the <notification> wrapper | ||||
and not the wrapper itself. See section 5 for examples. Either | ||||
subtree or XPATH filtering can be used. | ||||
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 | of the normal XPATH capability advertisement. If XPATH support is | |||
advertised via the XPATH capability then XPATH is supported for | advertised via the XPATH capability then XPATH is supported for | |||
notification filtering and if this capability is not advertised, then | notification filtering and if this capability is not advertised, | |||
XPATH is not supported for notification filtering. | XPATH is not supported for notification filtering. | |||
3.3. Notification Replay | 3.3. Notification Replay | |||
3.3.1. Overview | 3.3.1. Overview | |||
Replay is the ability to create an event subscription that will | Replay is the ability to create an event subscription that will | |||
resend recently generated notifications, or in some cases send them | resend recently generated notifications, or in some cases send them | |||
for the first time to a particular NETCONF client. These | for the first time to a particular NETCONF client. These | |||
notifications are sent the same way as normal notifications. | notifications are sent the same way as normal notifications. | |||
A replay of notifications is specified by including an optional | A replay of notifications is specified by including the optional | |||
parameter to the subscription command that indicates the start time | <startTime> parameter to the subscription command, which indicates | |||
of the replay. The end time is specified using the optional stopTime | the start time of the replay. The end time is specified using the | |||
parameter. If not present, notifications will continue to be sent | optional <stopTime> parameter. If not present, notifications will | |||
until the subscription is terminated. | continue to be sent until the subscription is terminated. | |||
A notification stream that supports replay is not expected to have an | A notification stream that supports replay is not expected to have an | |||
unlimited supply of saved notifications available to accommodate any | unlimited supply of saved notifications available to accommodate any | |||
replay request. | replay request. | |||
The actual number of stored notifications available for retrieval at | The actual number of stored notifications available for retrieval at | |||
any given time is a NETCONF server implementation specific matter. | any given time is a NETCONF server implementation specific matter. | |||
Control parameters for this aspect of the feature are outside the | Control parameters for this aspect of the feature are outside the | |||
scope of the current document. | scope of this document. | |||
Replay is dependent on a notification stream supporting some form of | Replay is dependent on a notification stream supporting some form of | |||
notification logging, although it puts no restrictions on the size or | 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> | not a stream supports replay can be discovered by doing a <get> | |||
operation on the eventStreams element of the Notification Management | operation on the <streams> element of the Notification Management | |||
Schema. This schema also provides the replayLogStartTime element to | Schema and looking at the value of the <replaySupport> object. This | |||
indicate the earliest available logged notification. | schema also provides the <replayLogCreationTime> element to indicate | |||
the earliest available logged notification. | ||||
3.3.2. Creating a Subscription with Replay | 3.3.2. Creating a Subscription with Replay | |||
This feature uses optional parameters to the <create-subscription> | This feature uses optional parameters to the <create-subscription> | |||
command called 'startTime' and 'stopTime'. 'startTime' identifies the | command called <startTime> and <stopTime>. <startTime> identifies the | |||
earliest date and time of interest for event notifications being | earliest date and time of interest for event notifications being | |||
replayed and also indicates that a subscription will be providing | replayed and also indicates that a subscription will be providing | |||
replay of notifications. Events generated before this time are not | replay of notifications. Events generated before this time are not | |||
matched. 'stopTime' specifies the latest date and time of interest | matched. <stopTime> specifies the latest date and time of interest | |||
for event notifications being replayed. If it is not present, then | for event notifications being replayed. If it is not present, then | |||
notifications will continue to be sent until the subscription is | notifications will continue to be sent until the subscription is | |||
terminated. | terminated. | |||
Note that startTime and stopTime are associated with the time an | Note that <startTime> and <stopTime> are associated with the time an | |||
event was generated by the system. | event was generated by the event source. | |||
A replayComplete notification is sent to indicate that all of the | A <replayComplete> notification is sent to indicate that all of the | |||
replay notifications have been sent. If this subscription has a stop | replay notifications have been sent. If this subscription has a stop | |||
time, then this session becomes a normal NETCONF session again. In | time, then this session becomes a normal NETCONF session again. When | |||
a <stopTime> has been specified, <notificationComplete> notification | ||||
is the last notification sent on the subscription before it | ||||
terminates and the NETCONF session returns to being a normal NETCONF | ||||
session. The NETCONF server will then accept <rpc> operations. In | ||||
the case of a subscription without a stop time, after the | the case of a subscription without a stop time, after the | |||
replayComplete notification has been sent, it can be expected that | <replayComplete> notification has been sent, it can be expected that | |||
any notifications generated since the start of the subscription | any notifications generated since the start of the subscription | |||
creation will be sent followed by notifications as they arise | creation will be sent, followed by notifications as they arise | |||
naturally within the system. | naturally within the system. | |||
3.3.3. Replay Complete Notification | The <replayComplete> and <notificationComplete> notifications cannot | |||
be filtered out. They will always be sent on a replay subscription | ||||
The replayComplete notification is the last notification sent over a | that specified a startTime and stopTime respectively. | |||
replay subscription. It indicates that replay is complete. After | ||||
this notification is received the subscription is terminated and the | ||||
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. | ||||
3.4. Notification Management Schema | 3.4. Notification Management Schema | |||
This Schema is used to learn about the event streams supported on the | This Schema is used to learn about the event streams supported on the | |||
system. It also contains the definition of the replayComplete, which | system. It also contains the definition of the <replayComplete> and | |||
is sent to indicate that an event replay has sent all applicable | <notificationComplete> notifications, which are sent to indicate that | |||
notifications." | an event replay has sent all applicable notifications and that the | |||
subscription has terminated, respectively. | ||||
<?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | |||
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" | <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" | |||
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" | xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" | |||
xmlns:ncEvent="urn:ietf:params:netconf:capability:notification:1.0" | xmlns:ncEvent="urn:ietf:params:netconf:capability:notification:1.0" | |||
xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification" | xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification" | |||
targetNamespace="urn:ietf:params:xml:ns:netmod:notification" | targetNamespace="urn:ietf:params:xml:ns:netmod:notification" | |||
elementFormDefault="qualified" | elementFormDefault="qualified" | |||
attributeFormDefault="unqualified"> | attributeFormDefault="unqualified" | |||
xml:lang="en" version="1.0"> | ||||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation xml:lang="en"> | <xs:documentation xml:lang="en"> | |||
A schema that can be used to learn about current | A schema that can be used to learn about current | |||
event streams. It also | event streams. It also contains the replayComplete | |||
contains the replayComplete notification. | and notificationComplete notification. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
<xs:import namespace="http://www.w3.org/XML/1998/namespace" | <xs:import namespace="http://www.w3.org/XML/1998/namespace" | |||
schemaLocation="http://www.w3.org/2001/xml.xsd"/> | schemaLocation="http://www.w3.org/2001/xml.xsd"/> | |||
<xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0" | <xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0" | |||
schemaLocation= | schemaLocation= | |||
"http://www.iana.org/assignments/xml-registry/schema/netconf.xsd"/> | "http://www.iana.org/assignments/xml-registry/schema/netconf.xsd"/> | |||
<xs:import namespace= | <xs:import namespace= | |||
"urn:ietf:params:netconf:capability:notification:1.0" | "urn:ietf:params:netconf:capability:notification:1.0" | |||
schemaLocation= | schemaLocation= | |||
"http://www.iana.org/assignments/xml-registry/schema/notification.xsd"/> | "http://www.iana.org/assignments/xml-registry/schema/notification.xsd"/> | |||
<!-- The above schemaLocation value is a placeholder and the actual | ||||
value will be assigned by IANA --> | ||||
<xs:element name="netconf" type="manageEvent:Netconf"/> | <xs:element name="netconf" type="manageEvent:Netconf"/> | |||
<xs:complexType name="Netconf"> | <xs:complexType name="Netconf"> | |||
<xs:sequence> | <xs:sequence> | |||
<xs:element name="eventStreams" > | <xs:element name="streams" > | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation> | <xs:documentation> | |||
The list of event streams supported by the | The list of event streams supported by the | |||
system. When a query is issued, the returned | system. When a query is issued, the returned | |||
set of streams is determined based on user | set of streams is determined based on user | |||
privileges. | privileges. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
<xs:complexType> | <xs:complexType> | |||
<xs:sequence minOccurs="0" maxOccurs="unbounded"> | <xs:sequence minOccurs="1" maxOccurs="unbounded"> | |||
<xs:element name="stream"> | <xs:element name="stream"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation> | <xs:documentation> | |||
Stream name and description. | Stream name, description and other information. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
<xs:complexType> | <xs:complexType> | |||
<xs:sequence> | <xs:sequence> | |||
<xs:element name="name" type="xs:string"/> | <xs:element name="name" | |||
type="ncEvent:streamNameType"> | ||||
<xs:annotation> | ||||
<xs:documentation> | ||||
The name of the event stream. If this is | ||||
the default NETCONF stream, this must have | ||||
the value "NETCONF". | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
</xs:element> | ||||
<xs:element name="description" | <xs:element name="description" | |||
type="xs:string"/> | type="xs:string"> | |||
<xs:annotation> | ||||
<xs:documentation> | ||||
A description of the event stream, including | ||||
such information as the type of events that | ||||
are sent over this stream. | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
</xs:element> | ||||
<xs:element name="replaySupport" | <xs:element name="replaySupport" | |||
type="xs:boolean"/> | type="xs:boolean"> | |||
<xs:element name="replayLogStartTime" | <xs:annotation> | |||
<xs:documentation> | ||||
An indication of whether or not event replay | ||||
is available on this stream. | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
</xs:element> | ||||
<xs:element name="replayLogCreationTime" | ||||
type="xs:dateTime" minOccurs="0"> | type="xs:dateTime" minOccurs="0"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation> | <xs:documentation> | |||
The start time of the log used to | The timestamp of the creation of the log | |||
support the replay function. This | used to support the replay function on | |||
this stream. | ||||
Note that this might be earlier then | ||||
the earliest available | ||||
notification in the log. This object | ||||
is updated if the log resets | ||||
for some reason. This | ||||
object MUST be present if replay is | object MUST be present if replay is | |||
supported. | supported. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
<xs:element name="replayLogAgedTime" | ||||
type="xs:dateTime" minOccurs="0"> | ||||
<xs:annotation> | ||||
<xs:documentation> | ||||
The timestamp of the last notification | ||||
aged out of the log. This | ||||
object MUST be present if replay is | ||||
supported and any notifications | ||||
have been aged out of the log. | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
</xs:element> | ||||
</xs:sequence> | </xs:sequence> | |||
</xs:complexType> | </xs:complexType> | |||
</xs:element> | </xs:element> | |||
</xs:sequence> | </xs:sequence> | |||
</xs:complexType> | </xs:complexType> | |||
</xs:element> | </xs:element> | |||
</xs:sequence> | </xs:sequence> | |||
</xs:complexType> | </xs:complexType> | |||
<xs:complexType name="ReplayCompleteNotificationType"> | <xs:complexType name="ReplayCompleteNotificationType"> | |||
skipping to change at page 18, line 46 | skipping to change at page 20, line 38 | |||
<xs:element name="replayComplete" | <xs:element name="replayComplete" | |||
type="manageEvent:ReplayCompleteNotificationType" | type="manageEvent:ReplayCompleteNotificationType" | |||
substitutionGroup="ncEvent:notificationContent"> | substitutionGroup="ncEvent:notificationContent"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation> | <xs:documentation> | |||
This notification is sent to signal the end of a replay | This notification is sent to signal the end of a replay | |||
portion of a subscription. | portion of a subscription. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | ||||
<xs:complexType name="NotificationCompleteNotificationType"> | ||||
<xs:complexContent> | ||||
<xs:extension base="ncEvent:NotificationContentType"/> | ||||
</xs:complexContent> | ||||
</xs:complexType> | ||||
<xs:element name="notificationComplete" | ||||
type="manageEvent:NotificationCompleteNotificationType" | ||||
substitutionGroup="ncEvent:notificationContent"> | ||||
<xs:annotation> | ||||
<xs:documentation> | ||||
This notification is sent to signal the end of a | ||||
notification subscription. It is sent in the case | ||||
that stopTime was specified during the creation of | ||||
the subscription. | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
</xs:element> | </xs:element> | |||
</xs:schema> | ||||
Figure 7 | </xs:schema> | |||
3.5. Subscriptions Data | 3.5. Subscriptions Data | |||
While it may be possible to retrieve information about subscriptions | Subscriptions are non-persistent state information and their lifetime | |||
via a get operation, subscriptions are not stored configuration. | is defined by their session or by the <stopTime> paramter. | |||
They are non-persistent state information and their lifetime is | ||||
defined by their session. | ||||
3.6. Filter Mechanics | 3.6. Filter Mechanics | |||
When multiple filter elements are specified, they are applied | When multiple filter elements are specified, they are applied | |||
collectively, so event notifications need to pass all specified | collectively, so event notifications need to pass all specified | |||
filters in order to be sent to the subscriber. If a filter element | filter elements in order to be sent to the subscriber. If a filter | |||
is specified to look for data of a particular value, and the data | element is specified to look for data of a particular value, and the | |||
item is not present within a particular event notification for its | data item is not present within a particular event notification for | |||
value to be checked against, the notification will be filtered out. | its value to be checked against, the notification will be filtered | |||
For example, if one were to check for 'severity=critical' in a | out. For example, if one were to check for 'severity=critical' in a | |||
configuration event notification where this field was not supported, | configuration event notification where this field was not supported, | |||
then the notification would be filtered out. | then the notification would be filtered out. | |||
The order that filter elements are applied does not matter since the | For subtree filtering, a non-empty node set means that the filter | |||
resulting set of notifications is the intersection of the set of | matches. For XPath filtering, the mechanisms defined in [XPATH] | |||
notifications that pass each filtering criteria. | should be used to convert the returned value to boolean. | |||
3.6.1. Filtering | 3.6.1. Filtering | |||
Filtering is explicitly stated when the event notification | Filtering is explicitly stated when the event notification | |||
subscription is created. This is specified via the 'filter' | subscription is created. This is specified via the 'filter' | |||
parameter. Filters only exist as parameters to the subscription. | parameter. A Filter only exist as a parameter to the subscription. | |||
3.7. Message Flow | 3.7. Message Flow | |||
The following figure depicts message flow between a NETCONF client | 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 | |||
the flow of notifications. It is possible that many rpc/rpc-reply | begin the flow of notifications. This subscription specified a | |||
sequences occur before the subscription is created or after a | <startTime>, so the server starts by replaying logged notifications. | |||
stopTime in a replay subscription, but this is not depicted in the | It is possible that many rpc/rpc-reply sequences occur before the | |||
figure. | subscription is created, but this is not depicted in the figure. | |||
C S | C S | |||
| | | | | | |||
| capability exchange | | | capability exchange | | |||
|-------------------------->| | |-------------------------->| | |||
|<------------------------->| | |<------------------------->| | |||
| | | | | | |||
| <create-subscription> | | | <create-subscription> | | |||
|-------------------------->| | |-------------------------->| | |||
|<--------------------------| | |<--------------------------| | |||
| <rpc-reply> | | | <rpc-reply> | | |||
| | | | | | |||
| <notification> | | | <notification> | | |||
|<--------------------------| | |<--------------------------| | |||
| | | | | | |||
| <notification> | | | <notification> | | |||
|<--------------------------| | |<--------------------------| | |||
| <notification> | (replayComplete) | ||||
|<--------------------------| | ||||
| | | | | | |||
| | | | | | |||
| | | | | | |||
| <notification> | | | <notification> | | |||
|<--------------------------| | |<--------------------------| | |||
| | | | | | |||
| | | | | | |||
| <notification> | | ||||
|<--------------------------| | ||||
| | | ||||
| | | ||||
Figure 8 | Figure 3 | |||
The following figure depicts message flow between a NETCONF client | ||||
(C) and NETCONF server (S) in order to create a subscription and | ||||
begin the flow of notifications. This subscription specified a | ||||
<startTime> and <stopTime> so it starts by replaying logged | ||||
notifications and then returns to be a normal command-response | ||||
NETCONF session after the <replayComplete> and <notificationComplete> | ||||
notifications are sent and it is available to process <rpc> requests. | ||||
It is possible that many rpc/rpc-reply sequences occur before the | ||||
subscription is created, but this is not depicted in the figure. | ||||
C S | ||||
| | | ||||
| capability exchange | | ||||
|-------------------------->| | ||||
|<------------------------->| | ||||
| | | ||||
| <create-subscription> | | ||||
|-------------------------->| | ||||
|<--------------------------| | ||||
| <rpc-reply> | | ||||
| | | ||||
| <notification> | | ||||
|<--------------------------| | ||||
| | | ||||
| <notification> | | ||||
|<--------------------------| | ||||
| <notification> | (replayComplete) | ||||
|<--------------------------| | ||||
| <notification> |(notificationComplete) | ||||
|<--------------------------| | ||||
| | | ||||
| | | ||||
| | | ||||
| <rpc> | | ||||
|-------------------------->| | ||||
|<--------------------------| | ||||
| <rpc-reply> | | ||||
| | | ||||
Figure 4 | ||||
4. XML Schema for Event Notifications | 4. XML Schema for Event Notifications | |||
The following [XML Schema] defines NETCONF Event Notifications. | The following [XML Schema] defines NETCONF Event Notifications. | |||
<?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | |||
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" | <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" | |||
xmlns="urn:ietf:params:netconf:capability:notification:1.0" | xmlns="urn:ietf:params:netconf:capability:notification:1.0" | |||
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" | xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" | |||
targetNamespace= | targetNamespace= | |||
skipping to change at page 22, line 17 | skipping to change at page 25, line 17 | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
<xs:element name="filter" | <xs:element name="filter" | |||
type="netconf:filterInlineType" | type="netconf:filterInlineType" | |||
minOccurs="0"> | minOccurs="0"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation> | <xs:documentation> | |||
An optional parameter that indicates | An optional parameter that indicates | |||
which subset of all possible events | 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 | parameter is the same as that of the | |||
filter parameter in the NETCONF | filter parameter in the NETCONF | |||
protocol operations. If not present, | protocol operations. If not present, | |||
all events not precluded by other | all events not precluded by other | |||
parameters will be sent. | parameters will be sent. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
<xs:element name="startTime" type="xs:dateTime" | <xs:element name="startTime" type="xs:dateTime" | |||
minOccurs="0" > | minOccurs="0" > | |||
skipping to change at page 22, line 48 | skipping to change at page 25, line 48 | |||
<xs:element name="stopTime" type="xs:dateTime" | <xs:element name="stopTime" type="xs:dateTime" | |||
minOccurs="0" > | minOccurs="0" > | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation> | <xs:documentation> | |||
An optional parameter used with the | An optional parameter used with the | |||
optional replay feature to indicate the | optional replay feature to indicate the | |||
newest notifications of interest. If | newest notifications of interest. If | |||
stop time is not present, the | stop time is not present, the | |||
notifications will continue until the | notifications will continue until the | |||
subscription is terminated. Must be used | subscription is terminated. Must be used | |||
with 'startTime'. | with startTime. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
</xs:sequence> | </xs:sequence> | |||
</xs:extension> | </xs:extension> | |||
</xs:complexContent> | </xs:complexContent> | |||
</xs:complexType> | </xs:complexType> | |||
<xs:simpleType name="streamNameType"> | <xs:simpleType name="streamNameType"> | |||
<xs:annotation> | <xs:annotation> | |||
skipping to change at page 23, line 25 | skipping to change at page 26, line 25 | |||
<xs:restriction base="xs:string"/> | <xs:restriction base="xs:string"/> | |||
</xs:simpleType> | </xs:simpleType> | |||
<xs:element name="create-subscription" | <xs:element name="create-subscription" | |||
type="createSubscriptionType" | type="createSubscriptionType" | |||
substitutionGroup="netconf:rpcOperation"> | substitutionGroup="netconf:rpcOperation"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation> | <xs:documentation> | |||
The command to create a notification subscription. It | The command to create a notification subscription. It | |||
takes as argument the name of the notification stream | takes as argument the name of the notification stream | |||
and filter or profile information. All of those options | and filter. Both of those options | |||
limit the content of the subscription. In addition, | limit the content of the subscription. In addition, | |||
there are two time-related parameters startTime and | there are two time-related parameters, startTime and | |||
stopTime which can be used to select the time interval | stopTime, which can be used to select the time interval | |||
of interest. | of interest to the notification replay feature. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
<!-- ************** One-way Operations ******************--> | <!-- ************** One-way Operations ******************--> | |||
<!-- <Notification> operation --> | <!-- <Notification> operation --> | |||
<xs:complexType name="NotificationContentType"/> | <xs:complexType name="NotificationContentType"/> | |||
<xs:element name="notificationContent" | <xs:element name="notificationContent" | |||
type="NotificationContentType" abstract="true"/> | type="NotificationContentType" abstract="true"/> | |||
<xs:complexType name="NotificationType"> | <xs:complexType name="NotificationType"> | |||
<xs:sequence> | <xs:sequence> | |||
<xs:element name="eventTime" type="xs:dateTime"> | ||||
<xs:annotation> | ||||
<xs:documentation> | ||||
The time the event was generated by the event source | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
</xs:element> | ||||
<xs:element ref="notificationContent"/> | <xs:element ref="notificationContent"/> | |||
</xs:sequence> | </xs:sequence> | |||
</xs:complexType> | </xs:complexType> | |||
<xs:element name="notification" type="NotificationType"/> | <xs:element name="notification" type="NotificationType"/> | |||
</xs:schema> | ||||
Figure 9 | </xs:schema> | |||
5. Filtering Examples | 5. Filtering Examples | |||
The following section provides examples to illustrate the various | The following section provides examples to illustrate the various | |||
methods of filtering content on an event notification subscription. | methods of filtering content on an event notification subscription. | |||
5.1. Subtree Filtering | In order to illustrate the use of filter expressions, it is necessary | |||
to assume some of the event notification content. The examples below | ||||
assume that the event notification schema definition has an <event> | ||||
element at the top level consisting of the event class (e.g., fault, | ||||
state, config), reporting entity and either severity or operational | ||||
state. | ||||
XML subtree filtering is not well suited for creating elaborate | Examples in this section are generated from the following fictional | |||
filter definitions given that it only supports equality comparisons | Schema. | |||
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 | <?xml version="1.0" encoding="UTF-8"?> | |||
to assume some of the event notification content. The examples | <xs:schema targetNamespace="http://example.com/event/1.0" | |||
herein assume that the event notification schema definition has an | xmlns="http://example.com/event/1.0" | |||
<events> element at the top level that contains one or more child | elementFormDefault="qualified" | |||
elements <eventEntry> consisting of the event class (e.g., fault, | xmlns:xs="http://www.w3.org/2001/XMLSchema" | |||
state, config, etc.) reporting entity and either severity or | xmlns:ncEvent="urn:ietf:params:netconf:capability:notification:1.0"> | |||
operational state. | ||||
Sample event list | <xs:import namespace= | |||
"urn:ietf:params:netconf:capability:notification:1.0" | ||||
schemaLocation= | ||||
"http://www.iana.org/assignments/xml-registry/schema/notification.xsd"/> | ||||
<xs:complexType name="eventType"> | ||||
<xs:complexContent> | ||||
<xs:extension base="ncEvent:NotificationContentType"> | ||||
<xs:sequence> | ||||
<xs:element name="eventClass" /> | ||||
<xs:element name="reportingEntity"> | ||||
<xs:complexType> | ||||
<xs:sequence> | ||||
<xs:any namespace="##any" | ||||
processContents="lax"/> | ||||
</xs:sequence> | ||||
</xs:complexType> | ||||
</xs:element> | ||||
<xs:choice> | ||||
<xs:element name="severity"/> | ||||
<xs:element name="operState"/> | ||||
</xs:choice> | ||||
</xs:sequence> | ||||
</xs:extension> | ||||
</xs:complexContent> | ||||
</xs:complexType> | ||||
<xs:element name="event" | ||||
type="eventType" | ||||
substitutionGroup="ncEvent:notificationContent"/> | ||||
</xs:schema> | ||||
The above fictional notification definition could result in the | ||||
following is a sample notification list, whihc is used in the | ||||
examples in this section. | ||||
<notification | ||||
xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | ||||
<eventTime>2007-07-08T00:01:00Z</eventTime> | ||||
<event xmlns="http://example.com/event/1.0"> | <event xmlns="http://example.com/event/1.0"> | |||
<eventClass>fault</eventClass> | <eventClass>fault</eventClass> | |||
<reportingEntity> | <reportingEntity> | |||
<card>Ethernet0</card> | <card>Ethernet0</card> | |||
</reportingEntity> | </reportingEntity> | |||
<severity>major</severity> | <severity>major</severity> | |||
</event> | </event> | |||
</notification> | ||||
<notification | ||||
xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | ||||
<eventTime>2007-07-08T00:02:00Z</eventTime> | ||||
<event xmlns="http://example.com/event/1.0"> | <event xmlns="http://example.com/event/1.0"> | |||
<eventClass>fault</eventClass> | <eventClass>fault</eventClass> | |||
<reportingEntity> | <reportingEntity> | |||
<card>Ethernet2</card> | <card>Ethernet2</card> | |||
</reportingEntity> | </reportingEntity> | |||
<severity>critical</severity> | <severity>critical</severity> | |||
</event> | </event> | |||
</notification> | ||||
<notification | ||||
xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | ||||
<eventTime>2007-07-08T00:04:00Z</eventTime> | ||||
<event xmlns="http://example.com/event/1.0"> | <event xmlns="http://example.com/event/1.0"> | |||
<eventClass>fault</eventClass> | <eventClass>fault</eventClass> | |||
<reportingEntity> | <reportingEntity> | |||
<card>ATM1</card> | <card>ATM1</card> | |||
</reportingEntity> | </reportingEntity> | |||
<severity>minor</severity> | <severity>minor</severity> | |||
</event> | </event> | |||
</notification> | ||||
<notification | ||||
xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | ||||
<eventTime>2007-07-08T00:10:00Z</eventTime> | ||||
<event xmlns="http://example.com/event/1.0"> | <event xmlns="http://example.com/event/1.0"> | |||
<eventClass>state</eventClass> | <eventClass>state</eventClass> | |||
<reportingEntity> | <reportingEntity> | |||
<card>Ethernet0</card> | <card>Ethernet0</card> | |||
</reportingEntity> | </reportingEntity> | |||
<operState>enabled</operState> | <operState>enabled</operState> | |||
</event> | </event> | |||
</notification> | ||||
Figure 10 | 5.1. Subtree Filtering | |||
The following example illustrates selecting events which have | XML subtree filtering is not well-suited for creating elaborate | |||
severities of critical, major, or minor (presumably fault events). | filter definitions given that it only supports equality comparisons | |||
The filtering criteria evaluation is as follows: | and application of the logical OR operators (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. | ||||
The following example illustrates how to select fault events which | ||||
have severities of critical, major, or minor. The filtering criteria | ||||
evaluation is as follows: | ||||
((severity=critical) | (severity=major) | (severity=minor)) | ((severity=critical) | (severity=major) | (severity=minor)) | |||
<netconf:rpc netconf:message-id="101" | <netconf:rpc netconf:message-id="101" | |||
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> | xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> | |||
<create-subscription | <create-subscription | |||
xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | |||
<filter netconf:type="subtree"> | <filter netconf:type="subtree"> | |||
<event xmlns="http://example.com/event/1.0"> | <event xmlns="http://example.com/event/1.0"> | |||
<eventClass>fault</eventClass> | <eventClass>fault</eventClass> | |||
<severity>critical</severity> | <severity>critical</severity> | |||
</event> | </event> | |||
<event xmlns="http://example.com/event/1.0"> | <event xmlns="http://example.com/event/1.0"> | |||
skipping to change at page 27, line 25 | skipping to change at page 32, line 42 | |||
<severity>major</severity> | <severity>major</severity> | |||
</event> | </event> | |||
<event xmlns="http://example.com/event/1.0"> | <event xmlns="http://example.com/event/1.0"> | |||
<eventClass>fault</eventClass> | <eventClass>fault</eventClass> | |||
<severity>minor</severity> | <severity>minor</severity> | |||
</event> | </event> | |||
</filter> | </filter> | |||
</create-subscription> | </create-subscription> | |||
</netconf:rpc> | </netconf:rpc> | |||
Figure 11 | The following example illustrates how to select state or config | |||
The following example illustrates selecting state or config | ||||
EventClasses or fault events that are related to card Ethernet0. The | EventClasses or fault events that are related to card Ethernet0. The | |||
filtering criteria evaluation is as follows: | filtering criteria evaluation is as follows: | |||
( state | config | fault & card=Ethernet0) | ( state | config | ( fault & ( card=Ethernet0))) | |||
<netconf:rpc netconf:message-id="101" | <netconf:rpc netconf:message-id="101" | |||
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> | xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> | |||
<create-subscription | <create-subscription | |||
xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | |||
<filter netconf:type="subtree"> | <filter netconf:type="subtree"> | |||
<event xmlns="http://example.com/event/1.0"> | <event xmlns="http://example.com/event/1.0"> | |||
<eventClass>fault</eventClass> | <eventClass>fault</eventClass> | |||
</event> | </event> | |||
<event xmlns="http://example.com/event/1.0"> | <event xmlns="http://example.com/event/1.0"> | |||
<eventClass>state</eventClass> | <eventClass>state</eventClass> | |||
skipping to change at page 28, line 30 | skipping to change at page 33, line 31 | |||
<reportingElement> | <reportingElement> | |||
<card>Ethernet0</card> | <card>Ethernet0</card> | |||
</reportingElement> | </reportingElement> | |||
</event> | </event> | |||
</filter> | </filter> | |||
</create-subscription> | </create-subscription> | |||
</netconf:rpc> | </netconf:rpc> | |||
5.2. XPATH filters | 5.2. XPATH filters | |||
The following [XPATH] example illustrates selecting fault EventClass | The following [XPATH] example illustrates how to select fault | |||
notifications that have severities of critical, major, or minor. The | EventClass notifications that have severities of critical, major, or | |||
filtering criteria evaluation is as follows: | minor. The filtering criteria evaluation is as follows: | |||
((fault) & ((severity=critical) | (severity=major) | (severity = | ((fault) & ((severity=critical) | (severity=major) | (severity = | |||
minor))) | minor))) | |||
<netconf:rpc netconf:message-id="101" | <netconf:rpc netconf:message-id="101" | |||
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> | xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> | |||
<create-subscription | <create-subscription | |||
xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | |||
<filter netconf:type="xpath" | <filter netconf:type="xpath" | |||
xmlns:ex="http://example.com/event/1.0" | xmlns:ex="http://example.com/event/1.0" | |||
select="/ex:event[ex:eventClass='fault' and | select="/ex:event[ex:eventClass='fault' and | |||
(ex:severity='minor' or ex:severity='major' | (ex:severity='minor' or ex:severity='major' | |||
or ex:severity='critical')]"/> | or ex:severity='critical')]"/> | |||
</create-subscription> | </create-subscription> | |||
</netconf:rpc> | </netconf:rpc> | |||
Figure 13 | The following example illustrates how to select state and config | |||
EventClasses or fault events of any severity that come from card | ||||
The following example illustrates selecting state and config | Ethernet0. The filtering criteria evaluation is as follows: | |||
EventClasses or fault events that have severities of critical, major, | ||||
or minor or come from card Ethernet0. The filtering criteria | ||||
evaluation is as follows: | ||||
(( state | config) & ((fault & severity=critical) | (fault & | (( state | config) & (fault & card=Ethernet0)) | |||
severity=major) | (fault & severity = minor) | (fault & | ||||
card=Ethernet0))) | ||||
<netconf:rpc netconf:message-id="101" | <netconf:rpc message-id="101" | |||
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> | xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> | |||
<create-subscription | <create-subscription | |||
xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | xmlns="urn:ietf:params:netconf:capability:notification:1.0"> | |||
<filter netconf:type="xpath" | <filter netconf:type="xpath" | |||
xmlns:ex="http://example.com/event/1.0" | xmlns:ex="http://example.com/event/1.0" | |||
select="/ex:event[ | select="/ex:event[ | |||
ex:eventClass='fault' and ex:severity='minor') or | (ex:eventClass='state' or ex:eventClass='config') and | |||
(ex:eventClass='fault' and ex:severity='major') or | ((ex:eventClass='fault' and ex:card='Ethernet0'))]"/> | |||
ex:eventClass='fault' and ex:severity='critical') or | ||||
(ex:eventClass='fault' and | ||||
ex:reportingElement/ex:card='Ethernet0') or | ||||
ex:eventClass='state' or | ||||
ex:eventClass='config']"/> | ||||
</create-subscription> | </create-subscription> | |||
</netconf:rpc> | </netconf:rpc> | |||
Figure 14 | ||||
6. Security Considerations | 6. Security Considerations | |||
The security considerations from the base [NETCONF] document apply | The security considerations from the base [NETCONF] document also | |||
also to the Notification capability. | apply to the Notification capability. | |||
The access control framework and the choice of transport will have a | The access control framework and the choice of transport will have a | |||
major impact on the security of the solution. | major impact on the security of the solution. | |||
The <notification> elements are never sent before the transport layer | The <notification> elements are never sent before the transport layer | |||
and the netconf layer (capabilities exchange) have been established, | and the NETCONF layer, including capabilities exchange, have been | |||
and the manager has been identified and authenticated. | established, and the manager has been identified and authenticated. | |||
It is recommended that care be taken to ensure the secure operation | It is recommended that care be taken to secure execution: | |||
of the following commands: | ||||
o <create-subscription> invocation | o <create-subscription> invocation | |||
o read-only data models | o <get> on read-only data models | |||
o read-write data models | ||||
o notification content | o <notification> content | |||
One issue related to the notifications draft is the transport of data | One potential security issue is the transport of data from non- | |||
from non-netconf streams, such as syslog and SNMP. This data may be | NETCONF streams, such as syslog and SNMP. This data may be more | |||
more vulnerable (or is not more vulnerable) when being transported | vulnerable (or less vulnerable) when being transported over NETCONF | |||
over netconf than when being transported using the protocol normally | than when being transported using the protocol normally used for | |||
used for transporting it, depending on the security credentials of | transporting it, depending on the security credentials of the two | |||
the two subsystems. The NETCONF server is responsible for providing | subsystems. The NETCONF server is responsible for applying access | |||
access control to stream content. | control to stream content. | |||
If a user does not have permission to view content via other NETCONF | The contents of notifications as well as the name of event streams | |||
operations it does not have permission to access that content via | may contain sensitive information and care should be taken to ensure | |||
Notifications. If a user is not permitted to view one element in the | that it is viewed only by authorized users. If a user does not have | |||
content of the notification, the notification is not sent to that | permission to view content via other NETCONF operations, it does not | |||
user. | 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 | If a subscription is created with a <stopTime>, the NETCONF session | |||
will return to being a normal command-response NETCONF session when | will return to being a normal command-response NETCONF session when | |||
the replay is completed. It is the responsibility of the NETCONF | 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. | |||
7. IANA Considerations | 7. IANA Considerations | |||
This document registers two URIs for the NETCONF XML namespace in the | This document registers three URIs for the NETCONF XML namespace in | |||
IETF XML registry [RFC3688]. | the IETF XML registry [RFC3688]. | |||
Following the format in RFC 3688, IANA has made the following | Following the format in RFC 3688, IANA has made the following | |||
registration. | registration. | |||
URI: urn:ietf:params:netconf:capability:notification:1.0 | URI: urn:ietf:params:netconf:capability:notification:1.0 | |||
URI: urn:ietf:params:xml:ns:netmod:notification | URI: urn:ietf:params:xml:ns:netmod:notification | |||
URI: urn:ietf:params:xml:ns:netconf:notification | ||||
Registrant Contact: The IESG. | Registrant Contact: The IESG. | |||
XML: N/A, the requested URI is an XML namespace. | XML: N/A, the requested URI is an XML namespace. | |||
8. Acknowledgements | 8. Acknowledgements | |||
Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing | Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing | |||
their input into the early work on this document. In addition, the | their input into the early work on this document. In addition, the | |||
editors would like to acknowledge input at the Vancouver editing | editors would like to acknowledge input at the Vancouver editing | |||
session from the following people: Orly Nicklass, James Balestriere, | session from the following people: Orly Nicklass, James Balestriere, | |||
Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, | Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, | |||
Dave Partain, Ray Atarashi and Dave Perkins and the following | Dave Partain, Ray Atarashi and David Perkins and the following | |||
additional people from the Montreal editing session: Balazs Lengyel, | additional people from the Montreal editing session: Balazs Lengyel, | |||
Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen, | Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen, | |||
Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig, | Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig, | |||
Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William | Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William | |||
Chow. | Chow. We would also like to thank Li Yan for his numerous reviews. | |||
9. Normative References | 9. Normative References | |||
[NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, | [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, | |||
December 2006. | December 2006. | |||
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision | ||||
3", RFC 2026, BCP 9, October 1996. | ||||
[RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements | [RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements | |||
Levels", RFC 2119, March 1997. | Levels", RFC 2119, March 1997. | |||
[RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", | ||||
RFC 2223, October 1997. | ||||
[RFC3688] Bradner, s., "The IETF XML Registry", RFC 3688, January | [RFC3688] Bradner, s., "The IETF XML Registry", RFC 3688, January | |||
2004. | 2004. | |||
[XML] World Wide Web Consortium, "Extensible Markup Language | [XML] World Wide Web Consortium, "Extensible Markup Language | |||
(XML) 1.0", W3C XML, February 1998, | (XML) 1.0", W3C XML, February 1998, | |||
<http://www.w3.org/TR/1998/REC-xml-19980210>. | <http://www.w3.org/TR/1998/REC-xml-19980210>. | |||
[XML Schema] | [XML Schema] | |||
Fallside, D. and P. Walmsley, "XML Schema Part 0: Primer | Fallside, D. and P. Walmsley, "XML Schema Part 0: Primer | |||
Second Edition", W3C XML Schema, October 2004. | Second Edition", W3C XML Schema, October 2004. | |||
skipping to change at page 34, line 37 | skipping to change at page 39, line 37 | |||
fixed this. | fixed this. | |||
9. On page 8, replaced "If the startTime specified is earlier then | 9. On page 8, replaced "If the startTime specified is earlier then | |||
the" with 'If the startTime specified is earlier than the" | the" with 'If the startTime specified is earlier than the" | |||
10. Updated some name spaces and schemaLocations as per Andy's June | 10. Updated some name spaces and schemaLocations as per Andy's June | |||
3rd email. | 3rd email. | |||
11. Added discussion of replayLogStartTime to draft in section 3.3.1 | 11. Added discussion of replayLogStartTime to draft in section 3.3.1 | |||
as follows "Whether or not a stream supports replay can be | as follows "Whether or not a stream supports replay can be | |||
discovered by doing a <get> operation on the eventStreams | discovered by doing a <get> operation on the <streams> elements | |||
elements of the Notification Management Schema. This schema | of the Notification Management Schema. This schema also | |||
also provides the replayLogStartTime element to indicate the | provides the replayLogStartTime element to indicate the earliest | |||
earliest available logged notification." | available logged notification." | |||
12. Removed most of the uses of the phrase 'Note that'. I kept two | 12. Removed most of the uses of the phrase 'Note that'. I kept two | |||
uses that prevent sentences from starting with either a lower | uses that prevent sentences from starting with either a lower | |||
case letter or an angle bracket. | case letter or an angle bracket. | |||
13. In section 3.6 replaced "it will be filtered out" with "the | 13. In section 3.6 replaced "it will be filtered out" with "the | |||
notification will be filtered out" | notification will be filtered out" | |||
14. In section 3.4, replaced "and the query" with "and to query" | 14. In section 3.4, replaced "and the query" with "and to query" | |||
skipping to change at page 37, line 5 | skipping to change at page 41, line 29 | |||
process RPC requests on the session associated with the | process RPC requests on the session associated with the | |||
subscription until the notification subscription is done and may | subscription until the notification subscription is done and may | |||
silently discard these requests." with "A NETCONF server is will | silently discard these requests." with "A NETCONF server is will | |||
not read RPC requests, by default, on the session associated | not read RPC requests, by default, on the session associated | |||
with the subscription until the notification subscription is | with the subscription until the notification subscription is | |||
done. | done. | |||
36. Updated the notification definition and the replyComplete | 36. Updated the notification definition and the replyComplete | |||
notification definition to use a substitution group. | notification definition to use a substitution group. | |||
A.2. Version -09 | ||||
1. In section 5.1 "logical OR operation" -> "application of the | ||||
logical OR operator" | ||||
2. In section 6 "ensure the secure operation of the following | ||||
commands" -> "secure execution" | ||||
3. Removed a couple remaining references to named profiles. | ||||
4. Updated name datatype in eventStreams element. | ||||
5. Modified the cardinality of eventStreams to reflect that there | ||||
will always be at least one event stream. | ||||
6. Fixed description of examples to remove reference to eventEntry, | ||||
which is no longer part of the actual example. | ||||
7. In examples, for consistency changed some references to | ||||
reportingElement to be reportingEntity | ||||
8. Fixed section 3.2, third pararaph to talk about filter elements | ||||
instead of filters. | ||||
9. Merge section 3.3.2 and section 3.3.3. Delete the first | ||||
paragraph in (old) section 3.3.3 since it both duplicates and | ||||
contradicts text in section 3.3.2 | ||||
10. In section 3.2.5.2.1, added clarification to first paragraph | ||||
that "Either subtree or XPATH filtering can be used. " | ||||
11. Removed discussion of not allowing the return of stream names | ||||
for which the user does not have permissions from the body of | ||||
the document to the security considerations section. | ||||
12. Fixed typos and did wordsmithing in various parts of the | ||||
document. | ||||
13. In section 2.1, explicitly stated that a subscription is bound | ||||
to a single stream for the lifetime of the subscription. | ||||
14. removed single quotes around some instances of stopTime and | ||||
startTime for consistency. When appropriate, put between angle | ||||
brackets. | ||||
15. In section 2.1.1, changed "Error-info: <badElement>: startTime" | ||||
to use bad-element. | ||||
16. In section 2.2.1, under the parameter tag, replaced "Contains | ||||
notification-specific tagged content." with "Contains | ||||
notification-specific tagged content, if any. " | ||||
17. Clarified some text in section 3.2, paragraph 3 around sending | ||||
of filters from client and the fitlers later being applied to | ||||
the notifications. | ||||
18. Fixed target namespace in section 4. | ||||
19. Added missing lang and version information to schema in section | ||||
3.4 | ||||
20. Clarified that the examples in section 5 all used the same | ||||
example event list. | ||||
21. Cleaned up security considerations section. | ||||
22. In section 3.4, clarified the definition of replayLogStart time | ||||
to be the timestamp of the earliest available notification in | ||||
the log used to support the replay function in the description | ||||
tag for the object definition. | ||||
23. In section 3.3.2, clarified that the time an event was generated | ||||
by the system means time an event was generated by the event | ||||
source. | ||||
24. In section 3.5, deleted discussion about possibly defining | ||||
subscriptions in XML Schema. | ||||
25. In section 3.6, deleted discussion about filter element | ||||
execution order not mattering. | ||||
26. Fixed examples in section 5 to add <netconf> tag and to make | ||||
other corrections | ||||
27. Added XML Schema definition for examples in section 5 and showed | ||||
the event list with <notification> wrappers. | ||||
28. Added <notificationComplete> notification | ||||
29. Removed support of startTime and stopTime in the future. | ||||
30. Replaced replayLogStartTime with replayLogCreationTime and | ||||
replayLogAgedTime. | ||||
Authors' Addresses | Authors' Addresses | |||
Sharon Chisholm | Sharon Chisholm | |||
Nortel | Nortel | |||
3500 Carling Ave | 3500 Carling Ave | |||
Nepean, Ontario K2H 8E9 | Nepean, Ontario K2H 8E9 | |||
Canada | Canada | |||
Email: schishol@nortel.com | Email: schishol@nortel.com | |||
End of changes. 135 change blocks. | ||||
330 lines changed or deleted | 608 lines changed or added | |||
This html diff was produced by rfcdiff 1.34. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |