draft-ietf-netconf-notification-02.txt | draft-ietf-netconf-notification-03.txt | |||
---|---|---|---|---|
Network Working Group S. Chisholm | Network Working Group S. Chisholm | |||
Internet-Draft K. Curran | Internet-Draft Nortel | |||
Expires: December 23, 2006 Nortel | Expires: March 18, 2007 H. Trevino | |||
H. Trevino | ||||
Cisco | Cisco | |||
June 21, 2006 | September 14, 2006 | |||
NETCONF Event Notifications | NETCONF Event Notifications | |||
draft-ietf-netconf-notification-02.txt | draft-ietf-netconf-notification-03.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 36 | 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 December 23, 2006. | This Internet-Draft will expire on March 18, 2007. | |||
Copyright Notice | Copyright Notice | |||
Copyright (C) The Internet Society (2006). | Copyright (C) The Internet Society (2006). | |||
Abstract | Abstract | |||
This memo defines a framework for sending asynchronous messages, or | This memo defines a framework for sending asynchronous messages, or | |||
event notifications in NETCONF. It defines both the operations | event notifications in NETCONF. It defines both the operations | |||
necessary to support this concept, and also discusses implications | necessary to support this concept, and also discusses implications | |||
for the mapping to transport protocols. | for the mapping to transport protocols. | |||
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 Event Notifications in NETCONF . . . . . . . . . . . . . . 5 | 1.2 Event Notifications in NETCONF . . . . . . . . . . . . . . 5 | |||
1.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 | 1.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
1.4 Requirements . . . . . . . . . . . . . . . . . . . . . . . 5 | 1.4 Requirements . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
1.5 Architecture . . . . . . . . . . . . . . . . . . . . . . . 7 | 2. Notification-Related Operations . . . . . . . . . . . . . . . 7 | |||
2. Event-Related Operations . . . . . . . . . . . . . . . . . . . 8 | 2.1 Subscribing to receive Event Notifications . . . . . . . . 7 | |||
2.1 Subscribing to receive Events . . . . . . . . . . . . . . 8 | 2.1.1 create-subscription . . . . . . . . . . . . . . . . . 7 | |||
2.1.1 create-subscription . . . . . . . . . . . . . . . . . 8 | 2.2 Sending Event Notifications . . . . . . . . . . . . . . . 8 | |||
2.2 Sending Event Notifications . . . . . . . . . . . . . . . 9 | 2.2.1 Event Notification . . . . . . . . . . . . . . . . . . 8 | |||
2.2.1 Event Notification . . . . . . . . . . . . . . . . . . 9 | 2.3 Terminating the Subscription . . . . . . . . . . . . . . . 9 | |||
2.3 Changing the Subscription . . . . . . . . . . . . . . . . 10 | 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 10 | |||
2.3.1 modify-subscription . . . . . . . . . . . . . . . . . 10 | 3.1 Capabilities Exchange . . . . . . . . . . . . . . . . . . 10 | |||
2.4 Terminating the Subscription . . . . . . . . . . . . . . . 11 | 3.2 Event Streams . . . . . . . . . . . . . . . . . . . . . . 10 | |||
2.4.1 cancel-subscription . . . . . . . . . . . . . . . . . 12 | 3.2.1 Event Stream Definition . . . . . . . . . . . . . . . 11 | |||
3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 13 | 3.2.2 Event Stream Content Format . . . . . . . . . . . . . 11 | |||
3.1 Capabilities Exchange . . . . . . . . . . . . . . . . . . 13 | 3.2.3 Default Event Stream . . . . . . . . . . . . . . . . . 11 | |||
3.2 Subscriptions and Datastores . . . . . . . . . . . . . . . 13 | 3.2.4 Event Stream Sources . . . . . . . . . . . . . . . . . 12 | |||
3.3 Querying Subscription Properties . . . . . . . . . . . . . 13 | 3.2.5 Event Stream Discovery . . . . . . . . . . . . . . . . 12 | |||
3.4 One-way Notification Messages . . . . . . . . . . . . . . 18 | 3.2.6 Event Stream Subscription . . . . . . . . . . . . . . 17 | |||
3.5 Filter Dependencies . . . . . . . . . . . . . . . . . . . 19 | 3.3 Subscriptions and Datastores . . . . . . . . . . . . . . . 17 | |||
3.5.1 Named Profiles . . . . . . . . . . . . . . . . . . . . 19 | 3.4 Querying Subscription Properties . . . . . . . . . . . . . 18 | |||
3.5.2 Filtering . . . . . . . . . . . . . . . . . . . . . . 19 | 3.5 One-way Notification Messages . . . . . . . . . . . . . . 22 | |||
3.6 Event Classes . . . . . . . . . . . . . . . . . . . . . . 19 | 3.6 Filter Dependencies . . . . . . . . . . . . . . . . . . . 22 | |||
3.6.1 Initial Set of Event Classes . . . . . . . . . . . . . 20 | 3.6.1 Named Profiles . . . . . . . . . . . . . . . . . . . . 23 | |||
3.7 Defining Event Notifications . . . . . . . . . . . . . . . 21 | 3.6.2 Filtering . . . . . . . . . . . . . . . . . . . . . . 23 | |||
3.8 Interleaving Messages . . . . . . . . . . . . . . . . . . 21 | 3.7 Message Flow . . . . . . . . . . . . . . . . . . . . . . . 23 | |||
4. XML Schema for Event Notifications . . . . . . . . . . . . . . 23 | 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 25 | |||
5. Mapping to Transport Protocols . . . . . . . . . . . . . . . . 27 | 5. Mapping to Transport Protocols . . . . . . . . . . . . . . . . 27 | |||
5.1 SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 | 5.1 SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 | |||
5.2 BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 | 5.2 BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
5.2.1 One-way Notification Messages in Beep . . . . . . . . 28 | 5.2.1 One-way Notification Messages in Beep . . . . . . . . 28 | |||
5.3 SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 | 5.3 SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 | |||
5.3.1 A NETCONF over Soap over HTTP Example . . . . . . . . 29 | 5.3.1 A NETCONF over Soap over HTTP Example . . . . . . . . 29 | |||
6. Filtering examples . . . . . . . . . . . . . . . . . . . . . . 32 | 6. Filtering examples . . . . . . . . . . . . . . . . . . . . . . 32 | |||
6.1 Event Classes . . . . . . . . . . . . . . . . . . . . . . 32 | 6.1 Subtree Filtering . . . . . . . . . . . . . . . . . . . . 32 | |||
6.2 Subtree Filtering . . . . . . . . . . . . . . . . . . . . 32 | 6.2 XPATH filters . . . . . . . . . . . . . . . . . . . . . . 33 | |||
6.3 XPATH filters . . . . . . . . . . . . . . . . . . . . . . 34 | 7. Notification Replay Capability . . . . . . . . . . . . . . . . 35 | |||
7. Additional Capabilities . . . . . . . . . . . . . . . . . . . 36 | 7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 35 | |||
7.1 Call-Home Notifications . . . . . . . . . . . . . . . . . 36 | 7.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . 35 | |||
7.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . 36 | 7.3 Capability Identifier . . . . . . . . . . . . . . . . . . 35 | |||
7.1.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 37 | 7.4 New Operations . . . . . . . . . . . . . . . . . . . . . . 35 | |||
7.1.3 Capability Identifier . . . . . . . . . . . . . . . . 37 | 7.5 Modifications to Existing Operations . . . . . . . . . . . 36 | |||
8. Security Considerations . . . . . . . . . . . . . . . . . . . 41 | 7.5.1 create-subscription . . . . . . . . . . . . . . . . . 36 | |||
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 | 7.5.2 Interactions with Other Capabilities . . . . . . . . . 36 | |||
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 43 | 8. Security Considerations . . . . . . . . . . . . . . . . . . . 37 | |||
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 | 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 38 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 44 | 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 | |||
A. Design Alternatives . . . . . . . . . . . . . . . . . . . . . 45 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 39 | |||
A.1 Suspend And Resume . . . . . . . . . . . . . . . . . . . . 45 | Intellectual Property and Copyright Statements . . . . . . . . 40 | |||
A.2 Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . 45 | ||||
B. Event Notifications and Syslog . . . . . . . . . . . . . . . . 46 | ||||
B.1 Leveraging Syslog Field Definitions . . . . . . . . . . . 46 | ||||
B.1.1 Field Mapping . . . . . . . . . . . . . . . . . . . . 47 | ||||
B.1.2 Severity Mapping . . . . . . . . . . . . . . . . . . . 48 | ||||
B.2 Syslog within NETCONF Events . . . . . . . . . . . . . . . 48 | ||||
B.2.1 Motivation . . . . . . . . . . . . . . . . . . . . . . 48 | ||||
B.2.2 Embedding syslog messages in a NETCONF Event . . . . . 48 | ||||
B.2.3 Supported Forwarding Options . . . . . . . . . . . . . 49 | ||||
C. Example Configuration Notifications . . . . . . . . . . . . . 51 | ||||
C.1 Types of Configuration Events . . . . . . . . . . . . . . 51 | ||||
C.2 Config Event Notification Structure . . . . . . . . . . . 52 | ||||
C.3 Configuration Event Content . . . . . . . . . . . . . . . 54 | ||||
C.3.1 Target Datastore . . . . . . . . . . . . . . . . . . . 54 | ||||
C.3.2 User Info . . . . . . . . . . . . . . . . . . . . . . 54 | ||||
C.3.3 Data Source . . . . . . . . . . . . . . . . . . . . . 54 | ||||
C.3.4 Operation . . . . . . . . . . . . . . . . . . . . . . 54 | ||||
C.3.5 Context . . . . . . . . . . . . . . . . . . . . . . . 54 | ||||
C.3.6 Entered Command . . . . . . . . . . . . . . . . . . . 55 | ||||
C.3.7 New Config . . . . . . . . . . . . . . . . . . . . . . 55 | ||||
C.3.8 Old Config . . . . . . . . . . . . . . . . . . . . . . 55 | ||||
C.3.9 Non-netconf commands in configuration notifications . 55 | ||||
D. IP Address Schema . . . . . . . . . . . . . . . . . . . . . . 56 | ||||
Intellectual Property and Copyright Statements . . . . . . . . 58 | ||||
1. Introduction | 1. Introduction | |||
NETCONF [NETCONF-PROTO] can be conceptually partitioned into four | NETCONF [NETCONF-PROTO] can be conceptually partitioned into four | |||
layers: | layers: | |||
Layer Example | Layer Example | |||
+-------------+ +----------------------------------------+ | +-------------+ +----------------------------------------+ | |||
| Content | | Configuration data | | | Content | | Configuration data | | |||
+-------------+ +----------------------------------------+ | +-------------+ +----------------------------------------+ | |||
| | | | | | |||
+-------------+ +-------------------------------------------+ | +-------------+ +-------------------------------------------+ | |||
| Operations | | <get-config>, <edit-config> <notification>| | | Operations | | <get-config>, <edit-config> <notification>| | |||
+-------------+ +-------------------------------------------+ | +-------------+ +-------------------------------------------+ | |||
| | | | | | | | |||
+-------------+ +-----------------------------+ | | +-------------+ +-----------------------------+ | | |||
| RPC | | <rpc>, <rpc-reply> | | | | RPC | | <rpc>, <rpc-reply> | | | |||
+-------------+ +-----------------------------+ | | +-------------+ +-----------------------------+ | | |||
| | | | | | | | |||
+-------------+ +------------------------------------------+ | +-------------+ +------------------------------------------+ | |||
| Application | | BEEP, SSH, SSL, console | | | Transport | | BEEP, SSH, SSL, console | | |||
| Protocol | | | | | Protocol | | | | |||
+-------------+ +------------------------------------------+ | +-------------+ +------------------------------------------+ | |||
This document defines a framework for sending asynchronous messages, | This document defines a framework for sending asynchronous messages, | |||
or event notifications in NETCONF. It defines both the operations | or event notifications in NETCONF. It defines both the operations | |||
necessary to support this concept, and also discusses implications | necessary to support this concept, and also discusses implications | |||
for the mapping to transport protocols. | for the mapping to transport protocols. | |||
Figure 1 | Figure 1 | |||
skipping to change at page 5, line 5 | skipping to change at page 5, line 5 | |||
Element: An XML Element[XML]. | Element: An XML Element[XML]. | |||
Managed Entity: A node, which supports NETCONF[NETCONF-PROTO] and has | Managed Entity: A node, which supports NETCONF[NETCONF-PROTO] and has | |||
access to management instrumentation. This is also known as the | access to management instrumentation. This is also known as the | |||
NETCONF server. | NETCONF server. | |||
Managed Object: A collection of one of more Elements that define an | Managed Object: A collection of one of more Elements that define an | |||
abstract thing of interest. | abstract thing of interest. | |||
Subscription: A concept related to the delivery of notifications (if | ||||
any to send) involving destination and selection of notifications. | ||||
It is bound to the lifetime of a session. | ||||
1.2 Event Notifications in NETCONF | 1.2 Event Notifications in NETCONF | |||
An event is something that happens which may be of interest - a | An event is something that happens which may be of interest - a | |||
configuration change, a fault, a change in status, crossing 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 a | this results in an asynchronous message, sometimes referred to as a | |||
notification or event notification, being sent out to interested | notification or event notification, being sent out to interested | |||
parties to notify them that this event has occurred. | parties to notify them that this event has occurred. | |||
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 an explicit command to | either the NETCONF session is terminated or some event, outside the | |||
cancel the subscription is sent. The event notification subscription | scope of this specification, causes the subscription to terminate. | |||
allows a number of options to enable the NETCONF client to specify | The event notification subscription allows a number of options to | |||
which events are of interest. These are specified when the | enable the NETCONF client to specify which events are of interest. | |||
subscription is created, but can be modified later using a modify | These are specified when the subscription is created. | |||
subscription command. | ||||
An agent is not required to process RPC requests until the | ||||
notification stream is done. A capability may be defined to announce | ||||
that a server is able to process RPCs while a notification stream is | ||||
active on a session. | ||||
1.3 Motivation | 1.3 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. | |||
1.4 Requirements | 1.4 Requirements | |||
The requirements for this solution are as follows: | The requirements for this solution are as follows: | |||
o Initial release should ensure it supports notification in support | o Initial release should ensure it supports notification in support | |||
of configuration operations | of configuration operations | |||
o Data content must be use the same data model as used in | o Data content must not preclude the use of the same data model as | |||
configuration | used in configuration | |||
o solution should support structured hierarchical data | ||||
o solution should be able to carry configuration fragments | ||||
o solution should support a reasonable message size limit (syslog | o solution should support a reasonable message size limit (syslog | |||
and SNMP are rather constrained in terms of message sizes) | and SNMP are rather constrained in terms of message sizes) | |||
o solution should provide reliable delivery of notifications | o solution should provide reliable delivery of notifications | |||
o solution should support preconfigured notification destinations | ||||
o solution should support agent initiated connections | o solution should support agent initiated connections | |||
o solution should provide a subscription mechanism | o solution should provide a subscription mechanism (An agent does | |||
not send notifications before asked to do so and the manager | ||||
o solution should support multiple subscriptions | initiates the flow of notifications) | |||
o solution should provide a filtering mechanism | o solution should provide a filtering mechanism | |||
o solution should support notification names | ||||
o solution should support notification timestamps | ||||
o solution should support notification classes | ||||
o solution should support notification info | ||||
o solution should provide the ability to specify the content of | ||||
notifications to ensure predictability | ||||
o solution should send sufficient information in a notification so | o solution should send sufficient information in a notification so | |||
that it can be analyzed independent of the transport mechanism | that it can be analyzed independent of the transport mechanism | |||
(data content fully describes a notification; protocol information | ||||
o solution should allow notifications to refer to prior | is not needed to understand a notification) | |||
configuration change RPCs | ||||
o solution should not bind subscriptions to a connection | o solution should not bind subscriptions to a connection | |||
o channels for configuration change notifications should share fate | o channels for configuration change notifications should share fate | |||
with a session that includes a configuration channel | with a session that includes a configuration channel | |||
o solution should support replay of locally logged notifications | o solution should support replay of locally logged notifications | |||
o solution should support message chunking capability in cases | 2. Notification-Related Operations | |||
channels carry mixed RPCs | ||||
o solution should scale to 30.000-100.000 nodes which may emit | ||||
notifications | ||||
o solution should scale to order 30.000-100.000 nodes to send | ||||
notifications [BL] | ||||
See also the external website tracking requirements at | ||||
http://www.eecs.iu-bremen.de/wiki/index.php/Netconf_notifications | ||||
1.5 Architecture | ||||
[Editor's Note: add pointers to the various architecture discussions | ||||
in the document and identify what people view to be gaps in | ||||
architecture discussion. The following may not be what people were | ||||
looking for in this section, but should at least give people | ||||
something to discuss] | ||||
The following figure illustrates that the netconf implementation | ||||
leverages protocol-neutral event management software within the box | ||||
rather then re-invent everything in Netconf specific methods. The | ||||
netconf client understands which notifications are of interest to it | ||||
and creates a subscription that meets its requirements. The network | ||||
elements accepts the subscription requests and creates a temporary | ||||
subscription to meet those needs. | ||||
---------------------------------------------- | ||||
| Network Element | | ||||
| ------------ | | ||||
| | Alarm | | | ||||
| | Management | -------------- | -------------- | ||||
| ------------ |--->|Netconf Stack |<---------->| Netconf | | ||||
| | | | | | | | | ||||
| | | -------------- | --->| Client | | ||||
| V | | | -------------- | ||||
| ------------ | | | | ||||
| | Event |--->| ------------------ | | | ||||
| | Management | | |Other Protocols | | | | ||||
| ------------ |--->| | | | | ||||
| ------------------ | | | ||||
|--------------------------------------------- | | ||||
| | ||||
---------------------------------------------- | | ||||
| Network Element | | | ||||
| ------------ | | | ||||
| | Alarm | | | | ||||
| | Management | -------------- | | | ||||
| ------------ |--->|Netconf Stack |<-------| | ||||
| | | | | | | ||||
| | | -------------- | | ||||
| V | | | ||||
| ------------ | | | ||||
| | Event |--->| ------------------ | | ||||
| | Management | | |Other Protocols | | | ||||
| ------------ |--->| | | | ||||
| ------------------ | | ||||
|-------------------------------------------- | ||||
2. Event-Related Operations | ||||
2.1 Subscribing to receive Events | 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. When the event | |||
notification subscription is created, the events of interest are | notification subscription is created, the events of interest are | |||
specified. | specified. | |||
It is possible to create more than one event notification | ||||
subscription on a single underlying connection. Each event | ||||
notification subscription therefore has its own unique identifier. | ||||
Content for an event notification subscription can be selected by | Content for an event notification subscription can be selected by | |||
specifying which event classes are of interest and /or by applying | applying user-specified filters. | |||
user-specified filters. | ||||
2.1.1 create-subscription | 2.1.1 create-subscription | |||
<create-subscription> | <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 <cancel-subscription > command is sent. | command until the NETCONF session terminates or some event, | |||
outside the scope of this specification, causes the subscription | ||||
to terminate. | ||||
Parameters: | Parameters: | |||
Event Classes: | Stream: | |||
An optional parameter that indicates which event classes are of | An optional parameter that indicates which stream(s) of events | |||
interest. If not present, events of all classes will be sent. | are of interest. If not present, then events in the default | |||
NETCONF stream will be sent. | ||||
Filter: | Filter: | |||
An optional parameter that indicates which subset of all | An optional parameter that indicates which subset of all | |||
possible events are of interest. The format of this parameter | possible events are of interest. The format of this parameter | |||
is the same as that of the filter parameter in the NETCONF | is the same as that of the filter parameter in the NETCONF | |||
protocol operations. If not present, all events not precluded | protocol operations. If not present, all events not precluded | |||
by other parameters will be sent. These filter parameters can | by other parameters will be sent. | |||
only be modified using the modify-subscription command. | ||||
Named Profile | Named Profile | |||
An optional parameter that points to a separately defined | An optional parameter that points to a separately defined | |||
filter profile. The contents of the profile are specified in | filter profile. The contents of the profile are specified in | |||
the provided XML Schema. If not present, no additional | the provided XML Schema. If not present, no additional | |||
filtering will be applied. Note that changes to the profile | filtering will be applied. Note that changes to the profile | |||
after the subscription has been created will have no effect | after the subscription has been created will have no effect. | |||
unless a modify subscription command is issued. | ||||
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 | |||
<rpc-reply> element containing a <data> element containing the | <rpc-reply> element containing a <data> element containing the | |||
subscription ID. | subscription ID. | |||
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 is provided. | name of a non-existent profile or stream is provided. | |||
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 along the connection. | event notifications asynchronously along the connection. | |||
Notifications are tagged with event classes, subscription ID, | ||||
sequence number, and date and time. | ||||
2.2.1 Event Notification | 2.2.1 Event Notification | |||
<notification> | <notification> | |||
Description: | Description: | |||
An event notification is sent to the initiator of an <create- | An event notification is sent to the initiator of an <create- | |||
subscription> command asynchronously when an event of interest | subscription> command asynchronously when an event of interest | |||
(i.e. meeting the specified filtering criteria) to them has | (i.e. meeting the specified filtering criteria) to them has | |||
occurred. An event notification is a complete XML document. | occurred. An event notification is a complete XML document. | |||
Parameters: | Parameters: | |||
Event Classes: | ||||
The event class or classes associated with this event | ||||
notification | ||||
Subscription Id: | Subscription Id: | |||
A unique identifier for this event subscription | A unique identifier for this event subscription | |||
Sequence Number: | ||||
A sequentially increasing number to uniquely identify event | ||||
notifications for this subscription. It starts at 0, always | ||||
increases by just one and rolls back to 0 after its maximum | ||||
value is reached. | ||||
Date and Time: | ||||
The date and time that the event notification was sent by the | ||||
NETCONF server. | ||||
Data: | Data: | |||
Contains event class and notification-specific tagged content. | Contains notification-specific tagged content. | |||
Positive Response: | Positive Response: | |||
No response. | No response. | |||
Negative Response: | Negative Response: | |||
No response. | No response. | |||
2.3 Changing the Subscription | 2.3 Terminating the Subscription | |||
After an event notification subscription has been established, the | Closing of the event notification subscription is done by terminating | |||
NETCONF client can initiate a request to change properties of the | the Netconf session ( <kill-session> )or via some action outside the | |||
event notification subscription. This prevents loss of event | scope of this specification. | |||
notifications that might otherwise occur during a cancelling and | ||||
recreation of the event notification subscription. This operation is | ||||
responded to by the NETCONF server | ||||
2.3.1 modify-subscription | 3. Supporting Concepts | |||
<modify-subscription> | 3.1 Capabilities Exchange | |||
Description: | The ability to process and send event notifications is advertised | |||
during the capability exchange between the NETCONF client and server. | ||||
Change properties of the event notification subscription. | "urn:ietf:params:xml:ns:netconf:notification:1.0" | |||
Parameters: | For Example | |||
Subscription Id: | <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> | |||
<capabilities> | ||||
<capability> | ||||
urn:ietf:params:xml:ns:netconf:base:1.0 | ||||
</capability> | ||||
<capability> | ||||
urn:ietf:params:xml:ns:netconf:capability:startup:1.0 | ||||
</capability> | ||||
<capability> | ||||
urn:ietf:params:xml:ns:netconf:notification:1.0 | ||||
</capability> | ||||
</capabilities> | ||||
<session-id>4</session-id> | ||||
</hello> | ||||
A unique identifier for this event subscription. | 3.2 Event Streams | |||
Event Classes: | An event stream is defined herein as a set of event notifications | |||
matching some forwarding criteria. | ||||
An optional parameter that indicates which Event Classes are of | System components generate event notifications which are passed to a | |||
interest. If not present, events of all classes will be sent. | central component for classification and distribution. The central | |||
component inspects each event notification and matches the event | ||||
notification against the set of stream definitions. When a match | ||||
occurs, the event notification is considered to be a member of that | ||||
event stream. An event notification may be part of multiple event | ||||
streams. | ||||
Filter: | When a NETCONF client subscribes to a given event stream, user- | |||
defined filters, if applicable, are applied to the event stream and | ||||
matching event notifications are forwarded to the NETCONF server for | ||||
distribution to subscribed NETCONF clients. | ||||
An optional parameter that indicates which subset of all | +----+ | |||
possible events that are of interest. The format is the same | | c1 |---+ available streams | |||
filter used for other NETCONF commands. If not present, all | +----+ | +---------+ | |||
events not precluded by other parameters will be sent. These | +----+ | |central |-> stream 1 | |||
filter parameters can only be modified using the modify- | | c2 | +--->|event |-> stream 2 filter +-------+ | |||
subscription command. | +----+ | |processor|-> netconf stream --->|netconf| | |||
... | | |-> stream n |server | see | ||||
System | +---------+ +-------+ below | ||||
Components| | // | ||||
... | | // | ||||
+----+ | | (------------) | ||||
| cn |---+ | (notification) | ||||
+----+ +-----> ( logging ) | ||||
( service ) | ||||
(------------) | ||||
Named Profile: | +-------+ +-------+ | |||
|netconf|<--->|netconf| | ||||
-> |server | |client | | ||||
+-------+ +-------+ | ||||
An optional parameter that points to separately defined filter | 3.2.1 Event Stream Definition | |||
profile. The contents of the profile are specified in provided | ||||
XML Schema. If not present, no additional filtering will be | ||||
applied. Note that changes to the profile after the | ||||
subscription has been created will have no effect unless a | ||||
modify subscription command is issued. | ||||
Positive Response: | Event streams are pre-defined on the managed device. The | |||
configuration of event streams is outside the scope of this document. | ||||
However, it is envisioned that event streams are either pre- | ||||
established by the vendor (pre-configured) or user configurable (e.g. | ||||
part of the device's configuration) or both. Device vendors may | ||||
allow event stream configuration via NETCONF protocol (i.e. edit- | ||||
config operation) | ||||
If the NETCONF server was able to satisfy the request, an <rpc- | 3.2.2 Event Stream Content Format | |||
reply> is sent that includes an <ok> element. | ||||
Negative Response: | The contents of all event streams made available to a NETCONF client | |||
(i.e. the notification sent by the NETCONF server) must be encoded in | ||||
XML. | ||||
An <rpc-error> element is included within the <rpc-reply> if the | 3.2.3 Default Event Stream | |||
request cannot be completed for any reason. Subscription requests | ||||
will fail if a filter with invalid syntax is provided or if the | ||||
name of a non-existent profile is provided. | ||||
2.4 Terminating the Subscription | A NETCONF server implementation supporting the notification | |||
capability must support the "NETCONF" notification event stream. | ||||
This stream contains all NETCONF XML event notifications supported by | ||||
the NETCONF server. The definition of the event notification and | ||||
their contents for this event stream is outside the scope of this | ||||
document. | ||||
Closing of the event notification subscription is initiated by the | 3.2.4 Event Stream Sources | |||
NETCONF client. The specific subscription to be closed is specified | ||||
using a subscription ID. The NETCONF server responds. Note that the | ||||
NETCONF session may also be torn down for other reasons and this will | ||||
also result in the subscription being cancelled, but is not subjected | ||||
to the behaviour of this operation. | ||||
2.4.1 cancel-subscription | With the exception of the default event stream (NETCONF | |||
notifications) specification of additional event stream sources (e.g. | ||||
SNMP, syslog, etc.) is outside the scope of this document. NETCONF | ||||
server implementations may leverage any desired event stream source | ||||
in the creation of supported event streams. | ||||
<cancel-subscription> | 3.2.5 Event Stream Discovery | |||
Description: | A NETCONF client retrieves the list of supported event streams from a | |||
NETCONF server using the <get> or <get-config> RPC request. | ||||
Stop and delete the event notification subscription. | 3.2.5.1 Name Retrieval using get, get-config RPC | |||
Parameters: | The list of available event streams is retrieved by requesting the | |||
<eventStreams> subtree via a <get> or <get-config> operation. | ||||
Available event streams for the requesting session are returned in | ||||
the reply containing <name> and <description> elements, where | ||||
<name> element is mandatory and its value is unique [Editor's Note: | ||||
should we then define it as a key?]. The returned list must only | ||||
include the names of those event streams for which the NETCONF | ||||
sessions has sufficient privileges. The NETCONF session privileges | ||||
are determined via access control mechanisms which are beyond the | ||||
scope of this document. An empty reply is returned if there are no | ||||
available event streams. | ||||
Subscription Id: | Retrieving available event stream list using <get-config> operation: | |||
A unique identifier for this event notification subscription. | <get-config> | |||
<source> | ||||
<running/> | ||||
</source> | ||||
<filter type="subtree"> | ||||
<top xmlns="http://example.com/schema/1.2/config"> | ||||
<sessionEventStream> | ||||
<eventStreams/> | ||||
</sessionEventStream> | ||||
</top> | ||||
</filter> | ||||
</get-config> | ||||
</rpc> | ||||
Positive Response: | <rpc-reply message-id="101" | |||
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> | ||||
<data> | ||||
<top xmlns="http://example.com/schema/1.2/config"> | ||||
<sessionEventStream> | ||||
<eventStreams> | ||||
<stream> | ||||
<name>NETCONF</name> | ||||
<description>Default netconf event stream | ||||
</description> | ||||
</stream> | ||||
<stream> | ||||
<name>snmp</name> | ||||
<description>SNMP notifications</description> | ||||
</stream> | ||||
<stream> | ||||
<name>syslog-critical</name> | ||||
<description>Critical and higher severity | ||||
</description> | ||||
</stream> | ||||
</sessionEventStreams> | ||||
</eventStreams> | ||||
</top> | ||||
</data> | ||||
</rpc-reply> | ||||
Retrieving available event stream list using <get> operation: | ||||
If the NETCONF server was able to satisfy the request, an <rpc- | <get> | |||
reply> is sent that includes an <ok> element. | <filter type="subtree"> | |||
<top xmlns="http://example.com/schema/1.2/config"> | ||||
<sessionEventStreams> | ||||
<eventStreams/> | ||||
</sessionEventStreams> | ||||
</top> | ||||
</filter> | ||||
</get> | ||||
</rpc> | ||||
Negative Response: | <rpc-reply message-id="101" | |||
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> | ||||
<data> | ||||
<top xmlns="http://example.com/schema/1.2/config"> | ||||
<sessionEventStreams> | ||||
<eventStreams> | ||||
<stream> | ||||
<name>NETCONF</name> | ||||
<description>Default netconf event stream | ||||
</description> | ||||
</stream> | ||||
<stream> | ||||
<name>snmp</name> | ||||
<description>SNMP notifications</description> | ||||
</stream> | ||||
<stream> | ||||
<name>syslog-critical</name> | ||||
<description>Critical and higher severity | ||||
</description> | ||||
</stream> | ||||
</eventStreams> | ||||
</sessionEventStreams> | ||||
</top> | ||||
</data> | ||||
</rpc-reply> | ||||
An <rpc-error> element is included within the <rpc-reply> if the | 3.2.5.2 Device Supported Event Streams (System) | |||
request cannot be completed for any reason. | ||||
3. Supporting Concepts | The list of all event streams configured on a device may be retrieved | |||
over a NETCONF session with sufficient privileges (e.g. | ||||
administrator). The information is retrieved by requesting the | ||||
<systemEventStreams> subtree via a <get> or <get-config> | ||||
operation. | ||||
3.1 Capabilities Exchange | <get-config> | |||
<source> | ||||
<running/> | ||||
</source> | ||||
<filter type="subtree"> | ||||
<top xmlns="http://example.com/schema/1.2/config"> | ||||
<systemEventStreams/> | ||||
</top> | ||||
</filter> | ||||
</get-config> | ||||
</rpc> | ||||
The ability to process and send event notifications is advertised | <rpc-reply message-id="101" | |||
during the capability exchange between the NETCONF client and server. | xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> | |||
<data> | ||||
<top xmlns="http://example.com/schema/1.2/config"> | ||||
<systemEventStreams> | ||||
<stream> | ||||
<name>NETCONF</name> | ||||
<description>Default netconf event stream | ||||
</description> | ||||
</stream> | ||||
<stream> | ||||
<name>snmp</name> | ||||
<description>SNMP notifications | ||||
</description> | ||||
</stream> | ||||
<stream> | ||||
<name>syslog-critical</name> | ||||
<description>Critical and higher severity | ||||
</description> | ||||
</stream> | ||||
</systemEventStreams> | ||||
</top> | ||||
</data> | ||||
</rpc-reply> | ||||
"urn:ietf:params:xml:ns:netconf:notification:1.0" | 3.2.5.3 Stream Retrieval Schema | |||
<?xml version="1.0" encoding="UTF-8"?> | ||||
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" | ||||
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" | ||||
elementFormDefault="qualified" | ||||
attributeFormDefault="unqualified"> | ||||
<xs:annotation> | ||||
<xs:documentation xml:lang="en"> | ||||
Schema for event streams | ||||
</xs:documentation> | ||||
<xs:appinfo> | ||||
<nm:identity | ||||
xmlns:nm="urn:ietf:params:xml:ns:netmod:base:1.0"> | ||||
<nm:Name> | ||||
NetconfNotificationSchema | ||||
</nm:Name> | ||||
<nm:LastUpdated> | ||||
2006-09-06T09:30:47-05:00 | ||||
</nm:LastUpdated> | ||||
<nm:Organization>IETF | ||||
</nm:Organization> | ||||
<nm:Description> | ||||
A schema that can be used to learn about current | ||||
NetConf Event subscriptions and creating named | ||||
profiles | ||||
</nm:Description> | ||||
</nm:identity> | ||||
</xs:appinfo> | ||||
</xs:annotation> | ||||
For Example | <xs:import namespace="http://www.w3.org/XML/1998/namespace" | |||
schemaLocation="http://www.w3.org/2001/xml.xsd"/> | ||||
<xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0" | ||||
schemaLocation="./draft-ietf-netconf-prot-12.xsd"/> | ||||
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> | <xs:element name="sessionEventStreams"> | |||
<capabilities> | <xs:annotation> | |||
<capability> | <xs:documentation> | |||
urn:ietf:params:xml:ns:netconf:base:1.0 | The list of event streams supported by the system. | |||
</capability> | When a query is issued, the returned set of streams is | |||
<capability> | determined based on user privileges | |||
urn:ietf:params:xml:ns:netconf:capability:startup:1.0 | </xs:documentation> | |||
</capability> | </xs:annotation> | |||
<capability> | <xs:complexType> | |||
urn:ietf:params:xml:ns:netconf:notification:1.0 | <xs:sequence maxOccurs="unbounded"> | |||
</capability> | <xs:element name="stream"> | |||
</capabilities> | <xs:annotation> | |||
<session-id>4</session-id> | <xs:documentation> | |||
</hello> | Stream name and description | |||
</xs:documentation> | ||||
</xs:annotation> | ||||
<xs:complexType> | ||||
<xs:sequence> | ||||
<xs:element name="name" type="xs:string"/> | ||||
<xs:element name="description" type="xs:string"/> | ||||
</xs:sequence> | ||||
</xs:complexType> | ||||
</xs:element> | ||||
</xs:sequence> | ||||
</xs:complexType> | ||||
</xs:element> | ||||
</xs:schema> | ||||
3.2 Subscriptions and Datastores | 3.2.6 Event Stream Subscription | |||
Subscriptions are like Netconf sessions in that they don't exist | A NETCONF client may request from the NETCONF server the list of | |||
Netconf datastores. The two exceptions to this are named profiles | available event streams to this session and then issue a <create- | |||
and the optional call-home notification feature. | subscription> request with the desired event stream name. Omitting | |||
the event stream name from the <create-subscription> request results | ||||
in subscription to the default NETCONF event stream. | ||||
3.3 Querying Subscription Properties | 3.2.6.1 Filtering Event Stream Contents | |||
The set of event notifications delivered in an event stream may be | ||||
further refined by applying a user-specified filter at subscription | ||||
creation time ( <create-subscription> ). This is a transient filter | ||||
associated with the event notification subscription and does not | ||||
modify the event stream configuration. | ||||
3.2.6.2 Subscription to Multiple Event Streams | ||||
Multiple event streams may be configured on a device and a NETCONF | ||||
client may subscribe to one or more of the available event streams. | ||||
A NETCONF client subscribing to multiple event streams must do so by | ||||
either establishing a new NETCONF session or opening a new channel on | ||||
an existing NETCONF session. | ||||
3.3 Subscriptions and Datastores | ||||
Subscriptions are like NETCONF sessions in that they don't exist in | ||||
NETCONF datastores. The exception to this is the named profiles | ||||
feature. | ||||
3.4 Querying Subscription Properties | ||||
The following Schema can be used to retrieve information about active | The following Schema can be used to retrieve information about active | |||
event notification subscriptions | event notification subscriptions | |||
<xs:schema | <xs:schema | |||
xmlns:xs="http://www.w3.org/2001/XMLSchema" | xmlns:xs="http://www.w3.org/2001/XMLSchema" | |||
xmlns:nsub="urn:ietf:params:xml:ns:netconf:subscription:1.0" | xmlns:nsub="urn:ietf:params:xml:ns:netconf:subscription:1.0" | |||
targetNamespace= "urn:ietf:params:xml:ns:netconf:subscription:1.0" | targetNamespace= "urn:ietf:params:xml:ns:netconf:subscription:1.0" | |||
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:xml:ns:netconf:notification:1.0" | xmlns:ncEvent= "urn:ietf:params:xml:ns:netconf:notification:1.0" | |||
skipping to change at page 14, line 14 | skipping to change at page 18, line 29 | |||
elementFormDefault="qualified" attributeFormDefault="unqualified" | elementFormDefault="qualified" attributeFormDefault="unqualified" | |||
xml:lang="en"> | xml:lang="en"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation xml:lang="en"> | <xs:documentation xml:lang="en"> | |||
Schema for reporting on Event Subscriptions | Schema for reporting on Event Subscriptions | |||
</xs:documentation> | </xs:documentation> | |||
<xs:appinfo> | <xs:appinfo> | |||
<nm:identity | <nm:identity | |||
xmlns:nm="urn:ietf:params:xml:ns:netmod:base:1.0"> | xmlns:nm="urn:ietf:params:xml:ns:netmod:base:1.0"> | |||
<nm:Name>NetconfNotificationSchema</nm:Name> | <nm:Name>NetconfNotificationSchema</nm:Name> | |||
<nm:LastUpdated>2006-04-30T09:30:47-05:00 | <nm:LastUpdated>2006-09-13T09:30:47-05:00 | |||
</nm:LastUpdated> | </nm:LastUpdated> | |||
<nm:Organization>IETF</nm:Organization> | <nm:Organization>IETF</nm:Organization> | |||
<nm:Description> | <nm:Description> | |||
A schema that can be used to learn about current | A schema that can be used to learn about current | |||
NetConf Event subscriptions and creating named | NetConf Event subscriptions and creating named | |||
profiles | profiles | |||
</nm:Description> | </nm:Description> | |||
</nm:identity> | </nm:identity> | |||
</xs:appinfo> | </xs:appinfo> | |||
</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 | <xs:import | |||
namespace="urn:ietf:params:xml:ns:netconf:notifications:1.0" | namespace="urn:ietf:params:xml:ns:netconf:notification:1.0" | |||
schemaLocation="draft-ietf-netconf-notification-01.xsd"/> | schemaLocation= | |||
"urn:ietf:params:xml:ns:netconf:notification:1.0"/> | ||||
<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="draft-ietf-netconf-prot-12.xsd"/> | schemaLocation="urn:ietf:params:xml:ns:netconf:base:1.0"/> | |||
<!-- Associations --> | ||||
<xs:element name="associatedNamedProfile" type="xs:string"/> | ||||
<xs:element name="relationships"> | ||||
<xs:keyref name="subscriptionToNamedProfile" | ||||
refer="nsub:namedProfileKey"> | ||||
<xs:selector xpath=".//netconfSubscription"/> | ||||
<xs:field xpath="nsub:associatedNamedProfile"/> | ||||
</xs:keyref> | ||||
<!-- Keys --> | ||||
<xs:key name="namedProfileKey"> | ||||
<xs:selector xpath=".//namedProfile"/> | ||||
<xs:field xpath="name"/> | ||||
</xs:key> | ||||
</xs:element> | ||||
<xs:element name="netconfSubscription"> | <xs:element name="netconfSubscription"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:appinfo> | <xs:appinfo> | |||
<nm:minAccess><read/></nm:minAccess> | <nm:minAccess><read/></nm:minAccess> | |||
<nm:maxAccess><read/></nm:maxAccess> | <nm:maxAccess><read/></nm:maxAccess> | |||
</xs:appinfo> | </xs:appinfo> | |||
</xs:annotation> | </xs:annotation> | |||
<xs:complexType> | <xs:complexType> | |||
<xs:sequence maxOccurs="unbounded"> | <xs:sequence > | |||
<xs:element name="session-id" | <xs:element name="session-id" | |||
type="netconf:SessionId" > | type="netconf:SessionId" > | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation xml:lang="en"> | <xs:documentation xml:lang="en"> | |||
The session id associated with this subscription. | The session id associated with this subscription. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
<xs:element name="subscriptionID" | <xs:element name="subscriptionID" | |||
type="ncEvent:SubscriptionID" > | type="ncEvent:SubscriptionID" > | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation xml:lang="en"> | <xs:documentation xml:lang="en"> | |||
The subscription id associated with this subscription. | The subscription id associated with this | |||
</xs:documentation> | subscription. | |||
</xs:annotation> | ||||
</xs:element> | ||||
<xs:element name="eventClasses"> | ||||
<xs:annotation> | ||||
<xs:documentation xml:lang="en"> | ||||
The event classes associated with this subscription. | ||||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
<xs:complexType> | ||||
<xs:sequence minOccurs="0" maxOccurs="unbounded"> | ||||
<xs:element ref="ncEvent:EventClass"/> | ||||
</xs:sequence> | ||||
</xs:complexType> | ||||
</xs:element> | </xs:element> | |||
<xs:element name="filter" | <xs:element name="filter" | |||
type="netconf:filterInlineType" minOccurs="0"> | type="netconf:filterInlineType" minOccurs="0"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation xml:lang="en"> | <xs:documentation xml:lang="en"> | |||
The filters associated with this subscription. | The filters associated with this subscription. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
<xs:element name="namedProfile" | <xs:element ref="nsub:associatedNamedProfile" minOccurs="0"> | |||
type="xs:string" minOccurs="0"> | ||||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation xml:lang="en"> | <xs:documentation xml:lang="en"> | |||
The named profile associated with this subscription. Note | The named profile associated with this subscription. | |||
that the contents of the named profile may have changed | Note that the contents of the named profile may | |||
since it was last applied. | have changed since it was last applied. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
<xs:keyref name="namedProfileKeyRef" | ||||
refer="nsub:namedProfileKey"> | ||||
<xs:selector xpath=".//namedProfile"/> | ||||
<xs:field xpath="namedProfile"/> | ||||
</xs:keyref> | ||||
</xs:element> | </xs:element> | |||
<xs:element name="lastModified" | <xs:element name="lastModified" | |||
type="xs:dateTime" > | type="xs:dateTime" > | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation xml:lang="en"> | <xs:documentation xml:lang="en"> | |||
The last time this subscription was modified. If it has | The last time this subscription was modified. If it | |||
not been modified since creation, this is the time of | has not been modified since creation, this is the | |||
subscription creation. | time of subscription creation. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
<xs:element name="messagesSent" | <xs:element name="messagesSent" | |||
type="xs:integer" minOccurs="0"> | type="xs:integer" minOccurs="0"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation xml:lang="en"> | <xs:documentation xml:lang="en"> | |||
A count of event notifications sent along this connection | A count of event notifications sent along | |||
since the subscription was created. | this connection since the subscription was | |||
created. | ||||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
<xs:element name="lastSequenceNumber" | ||||
type="xs:integer" minOccurs="0"> | ||||
<xs:annotation> | ||||
<xs:documentation xml:lang="en"> | ||||
The sequence number of the last event notification sent to | ||||
this subscription | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
</xs:element> | ||||
<xs:element name="key"> | <xs:element name="key"> | |||
<xs:key name="uniqueSubscription"> | <xs:key name="uniqueSubscription"> | |||
<xs:selector xpath=".//subscription"/> | <xs:selector xpath=".//subscription"/> | |||
<xs:field xpath="session-id"/> | <xs:field xpath="session-id"/> | |||
<xs:field xpath="subscriptionID"/> | <xs:field xpath="subscriptionID"/> | |||
</xs:key> | </xs:key> | |||
</xs:element> | </xs:element> | |||
</xs:sequence> | </xs:sequence> | |||
</xs:complexType> | </xs:complexType> | |||
</xs:element> | </xs:element> | |||
<xs:element name="netconfSubscriptions"> | <xs:element name="netconfSubscriptions"> | |||
<xs:complexType> | <xs:complexType> | |||
<xs:sequence> | <xs:sequence> | |||
<xs:element ref="nsub:netconfSubscription" minOccurs="0" | <xs:element ref="nsub:netconfSubscription" | |||
minOccurs="0" | ||||
maxOccurs="unbounded" /> | maxOccurs="unbounded" /> | |||
</xs:sequence> | </xs:sequence> | |||
</xs:complexType> | </xs:complexType> | |||
</xs:element> | </xs:element> | |||
<xs:element name="namedProfile"> | <xs:element name="namedProfile"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:appinfo> | <xs:appinfo> | |||
<nm:minAccess><read/></nm:minAccess> | <nm:minAccess><read/></nm:minAccess> | |||
<nm:maxAccess><read/> <write/> <create/> <delete/> | <nm:maxAccess><read/> <write/> <create/> <delete/> | |||
</nm:maxAccess> | </nm:maxAccess> | |||
</xs:appinfo> | </xs:appinfo> | |||
</xs:annotation> | </xs:annotation> | |||
<xs:complexType> | <xs:complexType> | |||
<xs:sequence> | <xs:sequence> | |||
<xs:element name="name"/> | <xs:element name="name"/> | |||
<xs:element name="eventClasses"> | ||||
<xs:annotation> | ||||
<xs:documentation xml:lang="en"> | ||||
The event classes associated with this named | ||||
Profile. | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
<xs:complexType> | ||||
<xs:sequence minOccurs="0" maxOccurs="unbounded"> | ||||
<xs:element ref="ncEvent:EventClass"/> | ||||
</xs:sequence> | ||||
</xs:complexType> | ||||
</xs:element> | ||||
<xs:element name="filter" | <xs:element name="filter" | |||
type="netconf:filterInlineType" minOccurs="0"> | type="netconf:filterInlineType" minOccurs="0"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation xml:lang="en"> | <xs:documentation xml:lang="en"> | |||
The filters associated with this named Profile. | The filters associated with this named | |||
profile. | ||||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
<xs:element name="lastModified" type="xs:dateTime"> | <xs:element name="lastModified" type="xs:dateTime"> | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation> | <xs:documentation> | |||
The timestamp of the last modification to this | The timestamp of the last modification to this | |||
named Profile. Note that modification of the | named Profile. Note that modification of the | |||
profile does not cause an immediate update | profile does not cause an immediate update | |||
skipping to change at page 18, line 15 | skipping to change at page 22, line 12 | |||
later, then the subscription is using an earlier | later, then the subscription is using an earlier | |||
version of this named profile and the exact | version of this named profile and the exact | |||
parameters may not match. | parameters may not match. | |||
</xs:documentation> | </xs:documentation> | |||
<xs:appinfo> | <xs:appinfo> | |||
<nm:minAccess><read/></nm:minAccess> | <nm:minAccess><read/></nm:minAccess> | |||
<nm:maxAccess><read/> </nm:maxAccess> | <nm:maxAccess><read/> </nm:maxAccess> | |||
</xs:appinfo> | </xs:appinfo> | |||
</xs:annotation> | </xs:annotation> | |||
</xs:element> | </xs:element> | |||
<xs:element name="key"> | ||||
<xs:key name="namedProfileKey"> | ||||
<xs:selector xpath="*/name" /> | ||||
<xs:field xpath="name" /> | ||||
</xs:key> | ||||
</xs:element> | ||||
</xs:sequence> | </xs:sequence> | |||
</xs:complexType> | </xs:complexType> | |||
</xs:element> | </xs:element> | |||
<xs:element name="namedProfiles"> | <xs:element name="namedProfiles"> | |||
<xs:complexType> | <xs:complexType> | |||
<xs:sequence> | <xs:sequence> | |||
<xs:element ref="nsub:namedProfile" minOccurs="0" | <xs:element ref="nsub:namedProfile" minOccurs="0" | |||
maxOccurs="unbounded" /> | maxOccurs="unbounded" /> | |||
</xs:sequence> | </xs:sequence> | |||
skipping to change at page 18, line 34 | skipping to change at page 22, line 24 | |||
</xs:element> | </xs:element> | |||
<xs:element name="namedProfiles"> | <xs:element name="namedProfiles"> | |||
<xs:complexType> | <xs:complexType> | |||
<xs:sequence> | <xs:sequence> | |||
<xs:element ref="nsub:namedProfile" minOccurs="0" | <xs:element ref="nsub:namedProfile" minOccurs="0" | |||
maxOccurs="unbounded" /> | maxOccurs="unbounded" /> | |||
</xs:sequence> | </xs:sequence> | |||
</xs:complexType> | </xs:complexType> | |||
</xs:element> | </xs:element> | |||
</xs:schema> | </xs:schema> | |||
3.4 One-way Notification Messages | 3.5 One-way Notification Messages | |||
In order to support the concept that each individual event | In order to support the concept that each individual event | |||
notification is a well-defined XML-document that can be processed | notification is a well-defined XML-document that can be processed | |||
without waiting for all events to come in, it makes sense to define | without waiting for all events to come in, it makes sense to define | |||
events, not as an endless reply to a subscription command, but as | events, not as an endless reply to a subscription command, but as | |||
independent messages that originate from the NETCONF server. In | independent messages that originate from the NETCONF server. In | |||
order to support this model, this memo introduces the concept of | order to support this model, this memo introduces the concept of | |||
notifications, which are one-way messages. | notifications, which are one-way messages. | |||
A one-way message is similar to the two-way RPC message, except that | A one-way message is similar to the two-way RPC message, except that | |||
no response is expected to the command. In the case of event | no response is expected to the command. In the case of event | |||
notification, this message will originate from the NETCONF server, | notification, this message will originate from the NETCONF server, | |||
and not the NETCONF client. | and not the NETCONF client. | |||
3.5 Filter Dependencies | 3.6 Filter Dependencies | |||
Note that when multiple filters are specified (Event Class, in-line | Note that when multiple filters are specified (in-line Filter, Named | |||
Filter, Named Profiles), they are applied collectively, so event | Profiles), they are applied collectively, so event notifications need | |||
notifications needs to pass all specified filters in order to be sent | to pass all specified filters in order to be sent to the subscriber. | |||
to the subscriber. If a filter is specified to look for data of a | If a filter is specified to look for data of a particular value, and | |||
particular value, and the data item is not present within a | the data item is not present within a particular event notification | |||
particular event notification for its value to be checked against, | for its value to be checked against, it will be filtered out. For | |||
it will be filtered out. For example, if one were to check for | example, if one were to check for 'severity=critical' in a | |||
'severity=critical' in a configuration event notification where this | configuration event notification where this field was not supported, | |||
field was not supported, then the notification would be filtered out. | then the notification would be filtered out. | |||
3.5.1 Named Profiles | Note that the order that filters are applied does not matter since | |||
the resulting set of notifications is the intersection of the set of | ||||
notifications that pass each filtering criteria. | ||||
3.6.1 Named Profiles | ||||
A named profile is a filter that is created ahead of time and applied | A named profile is a filter that is created ahead of time and applied | |||
at the time an event notification subscription is created or | at the time an event notification subscription is created . Note | |||
modified. Note that changes to the profile after the subscription | that changes to the profile after the subscription has been created | |||
has been created will have no effect unless a modify subscription | will have no effect on the subscription. Since named profiles exist | |||
command is issued. Since named profiles exist outside of the | outside of the subscription, they persist after the subscription has | |||
subscription, they persist after the subscription has been cancelled. | been torn down. | |||
3.5.2 Filtering | 3.6.2 Filtering | |||
Just-in-time filtering is explicitly stated when the event | Just-in-time filtering is explicitly stated when the event | |||
notification subscription is created. These filters can only be | notification subscription is created. This is specified via the | |||
changed using the modify subscription command. This is specified via | Filter parameter. Filters only exist as parameters to the | |||
the Filter parameter. Filters only exist as parameters to the | ||||
subscription. | subscription. | |||
3.6 Event Classes | 3.7 Message Flow | |||
The following figure depicts message flow between a Netconf client | ||||
Events can be classified into one more event classes. Each event | (C) and Netconf server (S) in order create a subscription and begin | |||
class identifies a set of event notifications which | the flow of notifications. | |||
share similar content | ||||
are generated from similar events | ||||
The initial set of event classes is configuration, fault, state, | ||||
audit, data, maintenance, metrics, security, information, heartbeat | ||||
and syslogTunnel. See the IANA Considerations section for | ||||
information on defining new event classes. | ||||
All events shall carry the following data: list of event class, | ||||
timestamp and sequence number of the notification. They may also | ||||
carry additional data. | ||||
___________________________________________________________________ | ||||
|| Notification Header || Data | | ||||
||__________________________________________________________||______| | ||||
|| subscriptionId| eventClasses| sequenceNumber| dateAndTime|| | | ||||
||_______________|_____________|_______________|____________||______| | ||||
3.6.1 Initial Set of Event Classes | ||||
A configuration event, alternatively known as an inventory event, is | ||||
used to indicate that hardware, software, or a service has been | ||||
added, changed or removed. In keeping aligned with NETCONF protocol | ||||
operations, configuration events may included copy configuration | ||||
event, delete configuration event, or the edit configuration event | ||||
(create, delete, merge, replace). As configuration notifications | ||||
could potentially carry huge amounts of data in order to properly | ||||
support functions such as security audit logs, so it is expected that | ||||
netconf clients will engineer their subscriptions to meet their needs | ||||
and to not overwhelm their capacity to process and store event | ||||
notifications. Examples include hardware board removed, software | ||||
module loaded or DNS server reconfigured. Changes are reported to | ||||
all subscribed clients, not just to those clients whose actions | ||||
triggered the changes. | ||||
A fault event notification is generated when a fault condition (error | ||||
or warning) occurs. A fault event may result in an alarm. Examples | ||||
of fault events could be a communications alarm, environmental alarm, | ||||
equipment alarm, processing error alarm, quality of service alarm, or | ||||
a threshold crossing event. See RFC3877 and RFC2819 for more | ||||
information. The fault notification should carry the following data: | ||||
severity, event source, probable cause, specific problem, additional | ||||
information. | ||||
A state event indicates a change from one state to another, where a | ||||
state is a condition or stage in the existence of a managed entity. | ||||
State change events are seen in many specifications. For Entity | ||||
state changes, see [Entity-State-MIB] for more information. The | ||||
notification shall identify the object who's state changed and the | ||||
new state. Internal states of a node are important for supervision | ||||
purposes and also effect how a node can be configured. | ||||
Audit events provide event of very specific actions within a managed | ||||
device. In isolation an audit events provides very limited data. A | ||||
collection of audit information forms an audit trail. | ||||
A data dump event is an asynchronous event containing information | ||||
about a system, its configuration, state, etc. | ||||
A maintenance event signals the beginning, process or end of an | ||||
action either generated by a manual or automated maintenance action. | ||||
If the maintenance event is a direct result of a configuration | ||||
management operation on this Netconf session then an rpc-reply | ||||
notification should be used. This event class is intended instead | ||||
for reporting on scheduled maintenance activities. Expected data | ||||
includes a description of the maintenance process, the stage the | ||||
process has reached, the manual action, automatic process that | ||||
triggered the notification. Examples include automatic backup | ||||
completed. | ||||
A metrics event contains a metric or a collection of metrics. This | ||||
includes performance metrics. | ||||
A heart beat event is sent periodically to enable testing that the | ||||
communications channel is still functional. It behaves much like the | ||||
other event classes, with the exception that implementations may not | ||||
want to include an event log, if supported. Although widely used | ||||
throughout the industry, no current corresponding work within the | ||||
IETF. However, other standards bodies such as the TeleManagement | ||||
Forum have similar definitions. | ||||
An Information event is something that happens of interest which is | ||||
within the expected operational behaviour and not otherwise covered | ||||
by another class. | ||||
syslogTunnel event is when syslog content is sent, unmodified, within | ||||
a Netconf event Notification. See appendix X.X for more | ||||
information.. | ||||
3.7 Defining Event Notifications | ||||
Event Notifications are defined ahead of time by defining an XML | ||||
element and assigning it to particular event classes. This will be | ||||
done using an "eventClasses" attribute. | ||||
3.8 Interleaving Messages | ||||
While each NETCONF message must be a complete XML document, the | ||||
design of the event system allows for the interleaving of complete | ||||
asynchronous event notifications with complete synchronous messages. | ||||
It is possible to still send command-response type messages such as | ||||
<modify-subscription> while events are being generated. The only | ||||
restriction is that each message must be complete | ||||
The following sequence diagram demonstrates an example NETCONF | ||||
session where after basic session establishment and capability | ||||
exchange, NETCONF client (C), subscribes to receive event | ||||
notifications. The NETCONF server (S), starts sending event | ||||
notifications as events of interest happen within the system. The | ||||
NETCONF client decides to change the characteristics of their event | ||||
subscription by sending a <modify-subscription> command. Before the | ||||
NETCONF server, receives this command, another event is generated and | ||||
the NETCONF server starts to send the event notification. The | ||||
NETCONF server finishes sending this event notification before | ||||
processing the <modify-subscription> command and sending the reply. | ||||
C S | C S | |||
| | | | | | |||
| capability exchange | | | capability exchange | | |||
|-------------------------->| | |-------------------------->| | |||
|<------------------------->| | |<------------------------->| | |||
| | | | | | |||
| <create-subscription> | | | <create-subscription> | | |||
|-------------------------->| | |-------------------------->| | |||
|<--------------------------| | |<--------------------------| | |||
| <rpc-reply> | | ||||
| | | | | | |||
| <notification> | | | <notification> | | |||
|<--------------------------| | |<--------------------------| | |||
| | | | | | |||
| <notification> | | | <notification> | | |||
|<--------------------------| | |<--------------------------| | |||
| | | | | | |||
| <modify-subscription> | | | | | |||
|-------------------------->| (buffered) | | | | |||
| <notification> | | | <notification> | | |||
|<--------------------------| | |<--------------------------| | |||
| <rpc-reply> | | | | | |||
|<--------------------------| | | | | |||
4. XML Schema for Event Notifications | 4. XML Schema for 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:xml:ns:netconf:notification:1.0" | xmlns="urn:ietf:params:xml:ns:netconf: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="urn:ietf:params:xml:ns:netconf:notification:1.0" | targetNamespace="urn:ietf:params:xml:ns:netconf:notification:1.0" | |||
elementFormDefault="qualified" | elementFormDefault="qualified" | |||
attributeFormDefault="unqualified" | attributeFormDefault="unqualified" | |||
skipping to change at page 24, line 8 | skipping to change at page 26, line 8 | |||
<xs:annotation> | <xs:annotation> | |||
<xs:documentation> | <xs:documentation> | |||
A monotonically increasing integer. Starts at 0. | A monotonically increasing integer. Starts at 0. | |||
Always increases by just one. Roll back to 0 after maximum | Always increases by just one. Roll back to 0 after maximum | |||
value is reached. | value is reached. | |||
</xs:documentation> | </xs:documentation> | |||
</xs:annotation> | </xs:annotation> | |||
<xs:restriction base="xs:integer"/> | <xs:restriction base="xs:integer"/> | |||
</xs:simpleType> | </xs:simpleType> | |||
<xs:complexType name="EventClassType"/> | ||||
<xs:element name="EventClass" | ||||
type="EventClassType" abstract="true"/> | ||||
<xs:element name="fault" type="EventClassType" | ||||
substitutionGroup="EventClass"/> | ||||
<xs:element name="information" type="EventClassType" | ||||
substitutionGroup="EventClass"/> | ||||
<xs:element name="state" type="EventClassType" | ||||
substitutionGroup="EventClass"/> | ||||
<xs:element name="configuration" type="EventClassType" | ||||
substitutionGroup="EventClass"/> | ||||
<xs:element name="data" type="EventClassType" | ||||
substitutionGroup="EventClass"/> | ||||
<xs:element name="maintenance" type="EventClassType" | ||||
substitutionGroup="EventClass"/> | ||||
<xs:element name="metrics" type="EventClassType" | ||||
substitutionGroup="EventClass"/> | ||||
<xs:element name="security" type="EventClassType" | ||||
substitutionGroup="EventClass"/> | ||||
<xs:element name="heartbeat" type="EventClassType" | ||||
substitutionGroup="EventClass"/> | ||||
<xs:complexType name="EventClasses"> | ||||
<xs:sequence maxOccurs="unbounded"> | ||||
<xs:element ref="EventClasses" /> | ||||
</xs:sequence> | ||||
</xs:complexType> | ||||
<!-- ************** Symmetrical Operations ********************--> | <!-- ************** Symmetrical Operations ********************--> | |||
<!-- | <!-- | |||
<create-subscription> operation | <create-subscription> operation | |||
--> | --> | |||
<xs:complexType name="createSubscriptionType"> | <xs:complexType name="createSubscriptionType"> | |||
<xs:complexContent> | <xs:complexContent> | |||
<xs:extension base="netconf:rpcOperationType"> | <xs:extension base="netconf:rpcOperationType"> | |||
<xs:sequence> | <xs:sequence> | |||
<xs:element name="event-classes" | ||||
minOccurs="0"> | ||||
<xs:complexType> | ||||
<xs:complexContent> | ||||
<xs:extension base="EventClasses"/> | ||||
</xs:complexContent> | ||||
</xs:complexType> | ||||
</xs:element> | </xs:element> | |||
<xs:element name="filter" | <xs:element name="filter" | |||
type="netconf:filterInlineType" minOccurs="0"/> | type="netconf:filterInlineType" minOccurs="0"/> | |||
<xs:element name="named-profile" | <xs:element name="named-profile" | |||
type="xs:string" minOccurs="0"/> | type="xs:string" minOccurs="0"/> | |||
<xs:element name="startTime" type="xs:dateTime" | ||||
minOccurs="0" /> | ||||
</xs:sequence> | </xs:sequence> | |||
</xs:extension> | </xs:extension> | |||
</xs:complexContent> | </xs:complexContent> | |||
</xs:complexType> | </xs:complexType> | |||
<xs:element name="create-subscription" | <xs:element name="create-subscription" | |||
type="createSubscriptionType" | type="createSubscriptionType" | |||
substitutionGroup="netconf:rpcOperation"/> | substitutionGroup="netconf:rpcOperation"/> | |||
<!-- | ||||
<modify-subscription> operation | ||||
--> | ||||
<xs:complexType name="modifySubscriptionType"> | ||||
<xs:complexContent> | ||||
<xs:extension base="netconf:rpcOperationType"> | ||||
<xs:sequence> | ||||
<xs:element name="subscription-id" | ||||
type="SubscriptionID" /> | ||||
<xs:element name="event-classes" | ||||
minOccurs="0"> | ||||
<xs:complexType> | ||||
<xs:complexContent> | ||||
<xs:extension base="EventClasses"/> | ||||
</xs:complexContent> | ||||
</xs:complexType> | ||||
</xs:element> | ||||
<xs:element name="filter" | ||||
type="netconf:filterInlineType" | ||||
minOccurs="0"/> | ||||
<xs:element name="named-profile" | ||||
type="xs:string" minOccurs="0"/> | ||||
</xs:sequence> | ||||
</xs:extension> | ||||
</xs:complexContent> | ||||
</xs:complexType> | ||||
<xs:element name="modify-subscription" | ||||
type="modifySubscriptionType" | ||||
substitutionGroup="netconf:rpcOperation"/> | ||||
<!-- | ||||
<cancel-subscription> operation | ||||
--> | ||||
<xs:complexType name="cancelSubscriptionType"> | ||||
<xs:complexContent> | ||||
<xs:extension base="netconf:rpcOperationType"> | ||||
<xs:sequence> | ||||
<xs:element name="subscription-id" | ||||
type="SubscriptionID" /> | ||||
</xs:sequence> | ||||
</xs:extension> | ||||
</xs:complexContent> | ||||
</xs:complexType> | ||||
<xs:element name="cancel-subscription" | ||||
type="cancelSubscriptionType" | ||||
substitutionGroup="netconf:rpcOperation"/> | ||||
<!-- ************** One-way Operations ******************--> | <!-- ************** One-way Operations ******************--> | |||
<!-- | <!-- | |||
<Event> operation | <Event> operation | |||
--> | --> | |||
<xs:complexType name="NotificationType"> | <xs:complexType name="NotificationType"> | |||
<xs:sequence> | <xs:sequence> | |||
<xs:element name="subscriptionId" type="SubscriptionID" /> | <xs:element name="subscriptionId" type="SubscriptionID" /> | |||
<xs:element name="eventClasses" type="EventClasses" /> | ||||
<xs:element name="sequenceNumber" type="SequenceNumber" /> | ||||
<xs:element name="dateAndTime" type="xs:dateTime"> | ||||
<xs:annotation> | ||||
<xs:documentation> | ||||
The date and time that the notification was sent | ||||
by the netconf server. | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
</xs:element> | ||||
</xs:sequence> | </xs:sequence> | |||
</xs:complexType> | </xs:complexType> | |||
<xs:element name="notification" type="NotificationType"/> | <xs:element name="notification" type="NotificationType"/> | |||
</xs:schema> | </xs:schema> | |||
5. Mapping to Transport Protocols | 5. Mapping to Transport Protocols | |||
Currently, the NETCONF family of specification allows for running | Currently, the NETCONF family of specification allows for running | |||
NETCONF over a number of transport protocols, some of which support | NETCONF over a number of transport protocols, some of which support | |||
multiple configurations. Some of these options will be better suited | multiple configurations. Some of these options will be better suited | |||
for supporting event notifications then others. | for supporting event notifications then others. | |||
5.1 SSH | 5.1 SSH | |||
Session establishment and two-way messages are based on the NETCONF | Session establishment and two-way messages are based on the NETCONF | |||
over SSH transport mapping [NETCONF-SSH] | over SSH transport mapping [NETCONF-SSH] | |||
One-way event messages are supported as follows: Once the session | One-way event messages are supported as follows: Once the session has | |||
has been established and capabilities have been exchanged, the server | been established and capabilities have been exchanged, the server may | |||
may send complete XML documents to the NETCONF client containing | send complete XML documents to the NETCONF client containing | |||
notification elements. No response is expected from the NETCONF | notification elements. No response is expected from the NETCONF | |||
client. | client. | |||
As the other examples in [NETCONF-SSH] illustrate, a special | As the examples in [NETCONF-SSH] illustrate, a special character | |||
character sequence, MUST be sent by both the client and the server | sequence, MUST be sent by both the client and the server after each | |||
after each XML document in the NETCONF exchange. This character | XML document in the NETCONF exchange. This character sequence cannot | |||
sequence cannot legally appear in an XML document, so it can be | legally appear in an XML document, so it can be unambiguously used to | |||
unambiguously used to identify the end of the current document in the | identify the end of the current document in the event notification of | |||
event notification of an XML syntax or parsing error, allowing | an XML syntax or parsing error, allowing resynchronization of the | |||
resynchronization of the NETCONF exchange. | NETCONF exchange. | |||
The NETCONF over SSH session to receive an event notification might | The NETCONF over SSH session to receive an event notification might | |||
look like the following. Note the event notification contents | look like the following. Note the event notification contents | |||
(delimited by <data> </data> tags) are not defined in this document | (delimited by <data> </data> tags) are not defined in this document | |||
and are provided herein simply for illustration purposes: | and are provided herein simply for illustration purposes: | |||
<?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | |||
<notification | <notification | |||
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | |||
<subscription-id>123456</subscription-id> | <subscription-id>123456</subscription-id> | |||
<data> | ||||
<eventClasses><configuration/><audit/></eventClasses> | <eventClasses><configuration/><audit/></eventClasses> | |||
<sequenceNumber>2</sequenceNumber> | <sequenceNumber>2</sequenceNumber> | |||
<dateAndTime>2000-01-12T12:13:14Z</dateAndTime> | <dateAndTime>2000-01-12T12:13:14Z</dateAndTime> | |||
<data> | ||||
<user>Fred Flinstone</user> | <user>Fred Flinstone</user> | |||
<operation> | <operation> | |||
<edit-config> | <edit-config> | |||
<target> | <target> | |||
<running/> | <running/> | |||
</target> | </target> | |||
<config> | <config> | |||
<top xmlns="http://example.com/schema/1.2/config"> | <top xmlns="http://example.com/schema/1.2/config"> | |||
<interface> | <interface> | |||
<name>Ethernet0/0</name> | <name>Ethernet0/0</name> | |||
skipping to change at page 30, line 34 | skipping to change at page 30, line 34 | |||
S: Content-Type: application/soap+xml; charset=utf-8 | S: Content-Type: application/soap+xml; charset=utf-8 | |||
S: Content-Length: 917 | S: Content-Length: 917 | |||
S: | S: | |||
S: <?xml version="1.0" encoding="UTF-8"?> | S: <?xml version="1.0" encoding="UTF-8"?> | |||
S: <soapenv:Envelope | S: <soapenv:Envelope | |||
S: xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> | S: xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> | |||
S: <soapenv:Body> | S: <soapenv:Body> | |||
S: <notification | S: <notification | |||
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | |||
S: <subscriptionID>123456</subscriptionID> | S: <subscriptionID>123456</subscriptionID> | |||
S: <data> | ||||
S: <eventClasses><configuration/><audit/></eventClasses> | S: <eventClasses><configuration/><audit/></eventClasses> | |||
S: <sequenceNumber>2</sequenceNumber> | S: <sequenceNumber>2</sequenceNumber> | |||
S: <dateAndTime>2000-01-12T12:13:14Z</dateAndTime> | S: <dateAndTime>2000-01-12T12:13:14Z</dateAndTime> | |||
S: <data> | ||||
S: <user>Fred Flinstone</user> | S: <user>Fred Flinstone</user> | |||
S: <operation> | S: <operation> | |||
S: <edit-config> | S: <edit-config> | |||
S: <target> | S: <target> | |||
S: <running/> | S: <running/> | |||
S: </target> | S: </target> | |||
S: <config> | S: <config> | |||
S: <top xmlns="http://example.com/schema/1.2/config"> | S: <top xmlns="http://example.com/schema/1.2/config"> | |||
S: <interface> | S: <interface> | |||
S: <name>Ethernet0/0</name> | S: <name>Ethernet0/0</name> | |||
skipping to change at page 32, line 10 | skipping to change at page 32, line 10 | |||
S: </data> | S: </data> | |||
S: </notification> | S: </notification> | |||
S: </soapenv:Body> | S: </soapenv:Body> | |||
S: </soapenv:Envelope> | S: </soapenv:Envelope> | |||
6. Filtering examples | 6. 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. | |||
6.1 Event Classes | 6.1 Subtree Filtering | |||
The following example illustrates selecting all event notifications | ||||
for EventClasses fault, state or config | ||||
<rpc message-id="101" | ||||
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | ||||
<create-subscription> | ||||
<eventClasses> | ||||
<fault/> | ||||
<state/> | ||||
<config/> | ||||
</eventClasses> | ||||
</create-subscription> | ||||
</rpc> | ||||
6.2 Subtree Filtering | ||||
XML subtree filtering is not well suited for creating elaborate | XML subtree filtering is not well suited for creating elaborate | |||
filter definitions given that it only supports equality comparisons | filter definitions given that it only supports equality comparisons | |||
(e.g. in the event subtree give me all event notifications which have | and logical OR operations (e.g. in an event subtree give me all event | |||
severity=critical or severity=major or severity=minor). | notifications which have severity=critical or severity=major or | |||
Nevertheless, it may be used for defining simple notification | severity=minor). Nevertheless, it may be used for defining simple | |||
forwarding filters as shown below. | event notification forwarding filters as shown below. | |||
The following example illustrates selecting fault EventClass which | In order to illustrate the use of filter expressions it is necessary | |||
have severities of critical, major, or minor. The filtering criteria | to assume some of the event notification content (only for example | |||
evaluation is as follows: | purposes). The examples herein assume that the event notification | |||
schema definition has an <eventClasses> element identifying the | ||||
event category (e.g. fault, state, config, etc.) and events have a | ||||
<severity> element | ||||
The following example illustrates selecting events which have | ||||
severities of critical, major, or minor (presumably fault events). | ||||
The filtering criteria evaluation is as follows: | ||||
((severity=critical) | (severity=major) | (severity=minor)) | ||||
((fault) & ((severity=critical) | (severity=major) | (severity = | ||||
minor))) | ||||
<rpc message-id="101" | <rpc message-id="101" | |||
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | |||
<create-subscription> | <create-subscription> | |||
<eventClasses> | ||||
<fault/> | ||||
</eventClasses> | ||||
<netconf:filter type="subtree"> | <netconf:filter type="subtree"> | |||
<neb | <neb | |||
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | |||
<event> | <event> | |||
<severity>critical</severity> | <severity>critical</severity> | |||
</event> | </event> | |||
<event> | <event> | |||
<severity>major</severity> | <severity>major</severity> | |||
</event> | </event> | |||
<event> | <event> | |||
skipping to change at page 33, line 26 | skipping to change at page 33, line 4 | |||
<event> | <event> | |||
<severity>major</severity> | <severity>major</severity> | |||
</event> | </event> | |||
<event> | <event> | |||
<severity>minor</severity> | <severity>minor</severity> | |||
</event> | </event> | |||
</neb> | </neb> | |||
</netconf:filter> | </netconf:filter> | |||
</create-subscription> | </create-subscription> | |||
</rpc> | </rpc> | |||
The following example illustrates selecting fault, state, config | The following example illustrates selecting fault, state, config | |||
EventClasses which have severities of critical, major, or minor and | EventClasses or events which are related to card Ethernet0. The | |||
come from card Ethernet0. The filtering criteria evaluation is as | filtering criteria evaluation is as follows: | |||
follows: | ||||
(fault | state | config | card=Ethernet0) | ||||
((fault | state | config) & ((fault & severity=critical) | (fault & | ||||
severity=major) | (fault & severity = minor) | (card=Ethernet0))) | ||||
<rpc message-id="101" | <rpc message-id="101" | |||
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | |||
<create-subscription> | <create-subscription> | |||
<eventClasses> | ||||
<fault/> | ||||
<state/> | ||||
<config/> | ||||
</eventClasses> | ||||
<netconf:filter type="subtree"> | <netconf:filter type="subtree"> | |||
<neb | <neb | |||
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | |||
<event> | <event> | |||
<eventClasses>fault</eventClasses> | <eventClasses>fault</eventClasses> | |||
<severity>critical</severity> | ||||
</event> | </event> | |||
<event> | <event> | |||
<eventClasses>fault</eventClasses> | <eventClasses>state</eventClasses> | |||
<severity>major</severity> | ||||
</event> | </event> | |||
<event> | <event> | |||
<eventClasses>fault</eventClasses> | <eventClasses>config</eventClasses> | |||
<severity>minor</severity> | ||||
</event> | </event> | |||
<event> | <event> | |||
<card>Ethernet0</card> | <card>Ethernet0</card> | |||
</event> | </event> | |||
</neb> | </neb> | |||
</netconf:filter> | </netconf:filter> | |||
</create-subscription> | </create-subscription> | |||
</rpc> | </rpc> | |||
6.3 XPATH filters | 6.2 XPATH filters | |||
The following example illustrates selecting fault EventClass which | The following example illustrates selecting fault EventClass | |||
have severities of critical, major, or minor. The filtering criteria | notifications that have severities of critical, major, or minor. The | |||
evaluation is as follows: | filtering criteria evaluation is as follows: | |||
((fault) & ((severity=critical) | (severity=major) | (severity = | ((fault) & ((severity=critical) | (severity=major) | (severity = | |||
minor))) | minor))) | |||
<rpc message-id="101" | <rpc message-id="101" | |||
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | |||
<create-subscription> | <create-subscription> | |||
<eventClasses> | ||||
<fault/> | ||||
</eventClasses> | ||||
<netconf:filter type="xpath"> | <netconf:filter type="xpath"> | |||
(/event[eventClasses/fault] and | (/event[eventClasses/fault] and | |||
(/event[severity="critical"] or | (/event[severity="critical"] or | |||
/event[severity="major"] or /event[severity="minor"])) | /event[severity="major"] or /event[severity="minor"])) | |||
</netconf:filter> | </netconf:filter> | |||
</create-subscription> | </create-subscription> | |||
</rpc> | </rpc> | |||
The following example illustrates selecting fault, state, config | The following example illustrates selecting fault, state and config | |||
EventClasses which have severities of critical, major, or minor and | EventClasses which have severities of critical, major, or minor and | |||
come from card Ethernet0. The filtering criteria evaluation is as | come from card Ethernet0. The filtering criteria evaluation is as | |||
follows: | follows: | |||
((fault | state | config) & ((fault & severity=critical) | (fault & | ((fault | state | config) & ((fault & severity=critical) | (fault & | |||
severity=major) | (fault & severity = minor) | (card=Ethernet0))) | severity=major) | (fault & severity = minor) | (card=Ethernet0))) | |||
<rpc message-id="101" | <rpc message-id="101" | |||
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> | |||
<create-subscription> | <create-subscription> | |||
<eventClasses> | ||||
<fault/> | ||||
<state/> | ||||
<config/> | ||||
</eventClasses> | ||||
<netconf:filter type="xpath"> | <netconf:filter type="xpath"> | |||
((/event[eventClasses/fault] or | ((/event[eventClasses/fault] or | |||
/event[eventClasses/state] or | /event[eventClasses/state] or | |||
/event[eventClasses/config]) and | /event[eventClasses/config]) and | |||
( (/event[eventClasses/fault] and | ( (/event[eventClasses/fault] and | |||
/event[severity="critical"]) or | /event[severity="critical"]) or | |||
(/event[eventClasses/fault] and | (/event[eventClasses/fault] and | |||
/event[severity="major"]) or | /event[severity="major"]) or | |||
(/event[eventClasses/fault] and | (/event[eventClasses/fault] and | |||
/event[severity="minor"]) or | /event[severity="minor"]) or | |||
/event[card="Ethernet0"])) | /event[card="Ethernet0"])) | |||
</netconf:filter> | </netconf:filter> | |||
</create-subscription> | </create-subscription> | |||
</rpc> | </rpc> | |||
7. Additional Capabilities | 7. Notification Replay Capability | |||
7.1 Call-Home Notifications | ||||
7.1.1 Overview | ||||
Call-Home Notifications are an alternative model for providing | ||||
notifications that may be preferred for two particular use cases. | ||||
The first use case is NAT traversal as in this model, the Netconf | ||||
server initiates the Notification session. The second use case is | ||||
when a manager has a large number of low-priority devices that it | ||||
only wants to deal with when there a known issue. While this risks | ||||
loss of information, for this particular use case, this is not | ||||
considered an issue. The Call-home-Notification feature supports the | ||||
concept of a short-lived notification session that only exists when | ||||
there is something to report. | ||||
In this feature, a subscription consists of a named profile, and an | ||||
association with a Netconf client. Unlike normal subscriptions, | ||||
which only exist when they are active, these subscriptions live while | ||||
both dormant and active. When an event of interest happens on the | ||||
managed resource, the Netconf server checks the list of dormant | ||||
subscriptions and if the filtering parameters in the subscription | ||||
indicate interest in the Notification resulting from the event, then | ||||
the Netconf server initiates the connection to the specific Netconf | ||||
client and sends the Notification. When the Notification has been | ||||
sent, the connection is terminated. | ||||
A subscription is active when it is currently session between the | ||||
Netconf client and server related to this subscription on which | ||||
Notifications can be sent. A subscription is dormant when there is | ||||
currently no session set up between the Netconf client and server | ||||
related to this notification subscription. | ||||
7.1.1.1 Session Lifecycle | ||||
In order to avoid situations in which a sessions is continuously | ||||
setup and torn down, an inactivity timer is configured on the server. | ||||
The timeout interval value is the same for all sessions (i.e. system | ||||
wide) and each session has its own timer. Upon expiration of the | ||||
inactivity timer, the connection is terminated, otherwise if activity | ||||
is detected, the timer is reset. | ||||
[Editor's note: alternatives here were to either create and tear down | ||||
the session for each notification received or to have the server | ||||
somehow figure out that there are more notifications coming soon | ||||
after it has sent a notification and therefore keeps the connection | ||||
up.] | ||||
The session establishment procedure is as follows: | ||||
1) The NETCONF server checks to ensure there isn't already a suitable | ||||
notification session open. | ||||
2) The NETCONF server initiates a session using a recognized | ||||
transport protocol (SSH, Beep, SOAP, etc). In order to "activate" | ||||
this reverse behavior a new SSH subsystem may need to be defined. | ||||
This is for further study. In addition, the NE hosting the NETCONF | ||||
server must support both client and server modes in the case of SSH. | ||||
3) Client and server are authenticated according to the underlying | ||||
transport protocol (e.g. SSH, BEEP) | ||||
4) If using BEEP, as described in [NETCONF-BEEP] either party may | ||||
initiate the BEEP session. Once this occurs, the assumption is that | ||||
both parties know their roles. At this point, the NETCONF client, | ||||
initiates NETCONF session establishment whether running SSH or BEEP. | ||||
7.1.2 Dependencies | ||||
This feature is dependant on the named profiles concept from the | ||||
normal subscription method as well as the definition of | ||||
<notification>. | ||||
It also uses the same <notification> | ||||
7.1.3 Capability Identifier | ||||
urn:ietf:params:xml:ns:netconf:callHomeNotification:1.0 | ||||
7.1.3.1 New Operations | 7.1 Overview | |||
7.1.3.1.1 New Data Model | Replay is the ability to create an event subscription that will | |||
resend recently sent notifications. These notifications are sent the | ||||
same way as normal notifications. | ||||
<xs:schema | A replay of notifications is specified by including an optional | |||
xmlns:xs="http://www.w3.org/2001/XMLSchema" | parameter to the subscription command that indicates the start time | |||
xmlns:nsub="urn:ietf:params:xml:ns:netconf:subscription:1.0" | of the replay. The end time of the replay is implicitly defined to | |||
targetNamespace= | be the time the replay request was initiated. | |||
"urn:ietf:params:xml:ns:netconf:callHomeSubscription:1.0" | ||||
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" | ||||
xmlns:ncEvent= "urn:ietf:params:xml:ns:netconf:notification:1.0" | ||||
xmlns:nm="urn:ietf:params:xml:ns:netconf:appInfo:1.0" | ||||
elementFormDefault="qualified" | ||||
attributeFormDefault="unqualified" xml:lang="en"> | ||||
<xs:annotation> | ||||
<xs:documentation xml:lang="en"> | ||||
Schema for reporting on dormant Call-Home Notification | ||||
Subscriptions | ||||
</xs:documentation> | ||||
<xs:appinfo> | ||||
<nm:identity | ||||
xmlns:nm="urn:ietf:params:xml:ns:netmod:base:1.0"> | ||||
<nm:Name>NetConfCallHomeSchema</nm:Name> | ||||
<nm:LastUpdated>2006-04-30T09:30:47-05:00 | ||||
</nm:LastUpdated> | ||||
<nm:Organization>IETF</nm:Organization> | ||||
<nm:Description> | ||||
A schema that can be used to learn about callHome | ||||
Notification subscriptions | ||||
</nm:Description> | ||||
</nm:identity> | ||||
</xs:appinfo> | ||||
</xs:annotation> | ||||
<xs:import | An implementation that supports replay is not expected to have an | |||
namespace="urn:ietf:params:xml:ns:netconf:subscription:1.0" | unlimited supply of saved notifications available to accommodate any | |||
schemaLocation="urn:ietf:params:xml:ns:netconf:subscription:1.0"/> | replay request. If a client requests a replay of notifications that | |||
predate the oldest notification available, then the NETCONF server | ||||
must return an warning message in the RPC reply and start replaying | ||||
the notifications it does have available, within the other | ||||
constraints, such as filtering, that the client has provided. | ||||
<xs:element name="callHomeSubscription"> | The actual number of stored notifications available for retrieval at | |||
<xs:annotation> | any given time is an agent implementation specific matter. Control | |||
<xs:appinfo> | parameters for this aspect of the feature are outside the scope of | |||
<nm:minAccess><read/></nm:minAccess> | the current work. | |||
<nm:maxAccess><read/></nm:maxAccess> | ||||
</xs:appinfo> | ||||
</xs:annotation> | ||||
<xs:complexType> | ||||
<xs:sequence> | ||||
<xs:element name="subscriber" > | ||||
<xs:annotation> | ||||
<xs:documentation> | ||||
The Netconf client that is subscribed to | ||||
receive these notifications as part of | ||||
the call-home subscription. | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
<xs:complexType> | ||||
<xs:sequence> | ||||
<xs:element type="ip:IPAddressOrSysname" | ||||
name="iPAddressOrSysname"/> | ||||
<xs:element type="xs:integer" name="port"/> | ||||
</xs:sequence> | ||||
</xs:complexType> | ||||
</xs:element> | ||||
<xs:element name="namedProfile" | ||||
type="xs:string" minOccurs="0"> | ||||
<xs:annotation> | ||||
<xs:documentation xml:lang="en"> | ||||
The named profile associated with this | ||||
subscription. Note that the | ||||
contents of the named profile may have | ||||
changed since it was last applied | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
<xs:keyref refer="nsub:namedProfileKey" | ||||
name="namedProfileKeyRef"> | ||||
<xs:selector xpath=".//namedProfile"> | ||||
</xs:selector> | ||||
<xs:field xpath="namedProfile"></xs:field> | ||||
</xs:keyref> | ||||
</xs:element> | ||||
<xs:element name="status"> | A given subscription is either a replay subscription or a normal | |||
<xs:simpleType> | subscription, which sends event notifications as they happen. A | |||
<xs:restriction base="xs:string"> | replay subscription terminates once the it has completed replaying | |||
<xs:enumeration value="Dormant"/> | past events. | |||
<xs:enumeration value="Active"/> | ||||
</xs:restriction> | 7.2 Dependencies | |||
</xs:simpleType> | ||||
</xs:element> | This capability is dependent on the notification capability being | |||
supported. It also requires that the device support some form of | ||||
notification logging, although it puts no restrictions on the size or | ||||
form of the log. | ||||
</xs:sequence> | 7.3 Capability Identifier | |||
</xs:complexType> | ||||
</xs:element> | The Event Notification Replay capability is identified by following | |||
capability string: | ||||
</xs:schema> | http://ietf.org/netconf/notificationReplay/1.0 | |||
7.1.3.1.2 Modifications to Existing Operations | 7.4 New Operations | |||
7.1.3.1.2.1 <create-subscription> | None | |||
This capability adds a new attribute to the <create-subscription> | 7.5 Modifications to Existing Operations | |||
command. This attribute is | ||||
callHome: | 7.5.1 create-subscription | |||
An optional parameter that, when present, indicates whether this will | This capability adds an optional parameter to the <create- | |||
be a call-home Notification subscription. If not present, this will | subscription> command called 'startTime'. This identifies the | |||
be a normal subscription. | earliest date and time of interest for event notifications being | |||
replayed. Events generated before this time are not matched. | ||||
7.1.3.1.3 Interactions with Other Capabilities | 7.5.2 Interactions with Other Capabilities | |||
It is only when these subscriptions move from the dormant state to | [Edtitor's Note: If this capability does not interact with other | |||
the active state that they have sessions associated with them. It is | capabilities, this section may be omitted.] | |||
only at this point that they show up in the active subscription list. | ||||
8. Security Considerations | 8. Security Considerations | |||
To be determined once specific aspects of this solution are better | To be determined once specific aspects of this solution are better | |||
understood. In particular, the access control framework and the | understood. In particular, the access control framework and the | |||
choice of transport will have a major impact on the security of the | choice of transport will have a major impact on the security of the | |||
solution | solution | |||
9. IANA Considerations | 9. Acknowledgements | |||
Event Classes will likely be an IANA-managed resource. The initial | ||||
set of values is defined in this specification. | ||||
In order for new event classes to be allocated, the following | ||||
requirements must be met: | ||||
o There must be working group consensus to add the new class | ||||
o A detailed description of its purpose in the netconf protocol must | ||||
be provided | ||||
o A detailed description of all manager and agent implementation | ||||
requirements associated with the event class must be provided | ||||
o The description must make clear to developers how to determine | ||||
when it is appropriate to choose this event classification for a | ||||
new notification type | ||||
list | ||||
10. Acknowledgements | ||||
Thanks to Gilbert Gagnon and Greg Wilbur for providing their input | Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing | |||
into the early work on this document. In addition, the editors would | their input into the early work on this document. In addition, the | |||
like to acknowledge input at the Vancouver editing session from the | editors would like to acknowledge input at the Vancouver editing | |||
following people: Orly Nicklass, James Bakstrieve, Yoshifumi | session from the following people: Orly Nicklass, James Balestriere, | |||
Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, Dave | Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, | |||
Partain, Ray Atarashi and Dave Perkins. In addition, they would like | Dave Partain, Ray Atarashi and Dave Perkins and the following | |||
to thank Balazs Lengyel his contributions to the event class text. | additional people from the Montreal editing session: Balazs Lengyel, | |||
Phil Shafer, Rob Ennes, Andy Bierman, Dan Romascanu, Bert Wijnen, | ||||
Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent | ||||
Cridlig, Martin Bjorklund, Olivier Festor, Radu State, Brian | ||||
Trammell, William Chow | ||||
11. References | 10. References | |||
[NETCONF] Enns, R., "NETCONF Configuration Protocol", | [NETCONF] Enns, R., "NETCONF Configuration Protocol", | |||
ID draft-ietf-netconf-prot-12, February 2006. | ID draft-ietf-netconf-prot-12, February 2006. | |||
[NETCONF BEEP] | [NETCONF BEEP] | |||
Lear, E. and K. Crozier, "Using the NETCONF Protocol over | Lear, E. and K. Crozier, "Using the NETCONF Protocol over | |||
Blocks Extensible Exchange Protocol (BEEP)", | Blocks Extensible Exchange Protocol (BEEP)", | |||
ID draft-ietf-netconf-beep-10, March 2006. | ID draft-ietf-netconf-beep-10, March 2006. | |||
[NETCONF Datamodel] | [NETCONF Datamodel] | |||
skipping to change at page 44, line 25 | skipping to change at page 39, line 29 | |||
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 | |||
Kim Curran | ||||
Nortel | ||||
3500 Carling Ave | ||||
Nepean, Ontario K2H 8E9 | ||||
Canada | ||||
Email: kicurran@nortel.com | ||||
Hector Trevino | Hector Trevino | |||
Cisco | Cisco | |||
Suite 400 | Suite 400 | |||
9155 E. Nichols Ave | 9155 E. Nichols Ave | |||
Englewood, CO 80112 | Englewood, CO 80112 | |||
USA | USA | |||
Email: htrevino@cisco.com | Email: htrevino@cisco.com | |||
Appendix A. Design Alternatives | ||||
A.1 Suspend And Resume | ||||
The purpose of the <cancel-subscription> operation is to stop event | ||||
notification forwarding and since the notification subscription is | ||||
transient the operation naturally removes all subscription | ||||
configuration; For this reasons, a different mechanism might be | ||||
needed for shutting down the notification session but preserving the | ||||
subscription information thus allowing the NETCONF server to re- | ||||
establish the parameters and reproduce the notification subscription. | ||||
The suspend and resume commands would allows a NETCONF client to | ||||
suspend event notification forwarding without removing the existing | ||||
subscription information. It could be used for both subscriptions | ||||
based on persistent and non-persistent subscription information. | ||||
Operations <suspend-subscription> and ><resume-subscription> are | ||||
proposed for this purpose. | ||||
If event subscription information is now persistent, unsolicited | ||||
session termination (i.e. other than <cancel-subscription)) is | ||||
treated as if a <suspend-subscription> command was issued. Event | ||||
forwarding is resumed by sending a <resume-subscription> to the | ||||
NETCONF server on a new connection. | ||||
A.2 Lifecycle | ||||
Configuration information associated with the event subscription | ||||
(event classes and filters) could persist beyond the life of the | ||||
event subscription session. (i.e. it is maintained by the network | ||||
element as part of its configuration). This configuration | ||||
information is subject to the behaviour of the datastore it resides | ||||
in and may or may not persist across re-boots (e.g. it could be part | ||||
of the running configuration but not the startup configuration). | ||||
Appendix B. Event Notifications and Syslog | ||||
This appendix describes the mapping between syslog message fields and | ||||
NETCONF event notification fields. The purpose of this mapping is to | ||||
provide an unambiguous mapping to enable consistent multi-protocol | ||||
implementations as well as to enable future migration. | ||||
The second part of the appendix describes an optional capability to | ||||
embed an entire syslog message (hereafter referred to as syslog | ||||
message(s) to avoid confusion with the message field in syslog) | ||||
within a NETCONF event notification. | ||||
B.1 Leveraging Syslog Field Definitions | ||||
This section provides a semantic mapping between NETCONF event fields | ||||
and syslog message fields. | ||||
------------------------------------------------------------------- | ||||
| PRI | HEADER | MESSAGE | | ||||
------------------------------------------------------------------- | ||||
| FACILITY | SEVERITY | TIMESTAMP | HOSTNAME | TAG CONTENT | | ||||
------------------------------------------------------------------- | ||||
Figure 2 - syslog message (RFC3164) | ||||
------------------------------------------------------------------- | ||||
| HEADER | STRUCTURED DATA | MESSAGE | | ||||
------------------------------------------------------------------- | ||||
Figure 3 - syslog message (draft-ietf-syslog-protocol-14.txt) | ||||
HEADER (Version, Facility, Severity, Truncate, Flag, TimeStamp, | ||||
HostName, AppName, ProcId, MsgId) | ||||
STRUCTURED DATA (Zero or more Structured Data Elements - SDEs) | ||||
MESSAGE ( Text message ) | ||||
B.1.1 Field Mapping | ||||
------------------------------------------------------ | ||||
RFC3164 Syslog ID NETCONF Event | ||||
------------------------------------------------------ | ||||
VERSION | ||||
------------------------------------------------------ | ||||
FACILITY FACILITY | ||||
------------------------------------------------------ | ||||
SEVERITY SEVERITY PerceivedSeverity | ||||
------------------------------------------------------ | ||||
TRUNCATE FLAG | ||||
------------------------------------------------------ | ||||
TIMESTAMP TIMESTAMP EventTime | ||||
------------------------------------------------------ | ||||
HOSTNAME HOSTNAME EventOrigin | ||||
------------------------------------------------------ | ||||
TAG APP-NAME EventOrigin | ||||
------------------------------------------------------ | ||||
PROC-ID | ||||
------------------------------------------------------ | ||||
MSG-ID | ||||
------------------------------------------------------ | ||||
CONTENT CONTENT AdditionalText | ||||
------------------------------------------------------ | ||||
Figure 4 - syslog to NETCONF Event field mapping | ||||
Notes: | ||||
VERSION: Schema version is found in XML Schema namespace. However, | ||||
no correspondence to syslog. | ||||
FACILITY: No well defined semantics for this field. Therefore not | ||||
used at this time. | ||||
TRUNCATE: Not applicable. NETCONF events must be complete XML | ||||
documents therefore cannot be truncated. | ||||
TIME: TIMESTAMP in syslog ID is derived from RFC3339 but with | ||||
additional restrictions | ||||
PROC-ID: No equivalent field | ||||
CONTENT: This is a free form text field with not defined semantics. | ||||
The contents of this field may be included in the AdditionalText | ||||
field. | ||||
B.1.2 Severity Mapping | ||||
The severity value mappings stated in (draft-ietf-syslog-protocol-14) | ||||
are used: | ||||
ITU Perceived Severity syslog SEVERITY | ||||
Critical Alert | ||||
Major Critical | ||||
Minor Error | ||||
Warning Warning | ||||
Indeterminate Notice | ||||
Cleared Notice | ||||
Figure 5. ITU Perceived Severity to syslog SEVERITY mapping. | ||||
B.2 Syslog within NETCONF Events | ||||
B.2.1 Motivation | ||||
The syslog protocol (RFC3164) is widely used by equipment vendors as | ||||
a means to deliver event messages. Due to the widespread use of | ||||
syslog as well as a potential phased availability and coverage of | ||||
NETCONF events by equipment vendors, it is envisioned that users will | ||||
also follow a phased migration. As a way to facilitate migration and | ||||
at the same time allow equipment vendors to provide comprehensive | ||||
event coverage over a NETCONF event subscription session, syslog | ||||
messages could be embedded in their entirety within the body of a | ||||
NETCONF event notification. | ||||
The information provided in this appendix describes a mechanism to | ||||
leverage syslog messages for the purpose of complementing the | ||||
available NETCONF event notification set. The intent is to promote | ||||
the use of the NETCONF interface and not to simply provide a wrapper | ||||
and additional delivery mechanism for syslog messages. NETCONF | ||||
events are intended to be well defined and structured, therefore | ||||
providing an advantage over the unstructured and often times | ||||
arbitrarily defined syslog messages (i.e. the message field). | ||||
Covered herein is the syslog protocol as defined in RFC3164 and | ||||
draft-ietf-syslog-protocol-14.txt. | ||||
B.2.2 Embedding syslog messages in a NETCONF Event | ||||
When event notifications are supported, the default behaviour for a | ||||
NETCONF server is to send NETCONF event notifications over an | ||||
established event subscription. As an option, the NETCONF server may | ||||
embed a syslog message in its entirety (e.g. RFC3164 - PRI, Header, | ||||
and Message fields), placing it within the Event Info field | ||||
(SyslogInfo sub-field) - see Figure 1. | ||||
______________________________________________________ | ||||
| NETCONF Event Header | Data | | ||||
|________________________ |___________________________| | ||||
| | Event Info | | ||||
|_________________________|___________________________| | ||||
| | ||||
v | ||||
____________________________ | ||||
| Event Fields | SyslogInfo | | ||||
|___________________________| | ||||
Figure 1 - Embedding syslog in a NETCONF Event Notifications | ||||
B.2.3 Supported Forwarding Options | ||||
Three event forwarding options may be supported by the NETCONF | ||||
server: a) XML only (mandatory if NETCONF events capability is | ||||
supported) b) XML and syslog (Optional) c) syslog only (optional) | ||||
Note to the reader: Option "a" above refers to event notification | ||||
messages defined for use over the NETCONF protocol. While their use | ||||
is not necessarily limited to NETCONF protocol, they are referred to | ||||
as "NETCONF XML-event" in the remainder of this section simply to | ||||
avoid ambiguity. | ||||
B.2.3.1 XML and Syslog option - Forwarding Behaviour | ||||
It is possible, due to coverage, for a given NETCONF implementation | ||||
to not support a comprehensive set of NETCONF event notifications. | ||||
Therefore, it is possible for a given event to trigger the generation | ||||
of a syslog message without a NETCONF-aware counterpart. In such | ||||
situations, the NETCONF server could form a NETCONF event | ||||
notification, embed the syslog message in the SyslogInfo field and | ||||
forward the NETCONF event notifications to all subscribed | ||||
destinations. Otherwise, both NETCONF event and syslog messages must | ||||
be included in the Event Info field. | ||||
B.2.3.2 Event Class Identification | ||||
The event class field is found in the NETCONF event header | ||||
information as described in the main body of this document. It | ||||
conveys information describing what type of event for which the event | ||||
notification is generated and lets the consumer of the message know | ||||
what sort of content to expect. NETCONF event notifications which | ||||
only contain a syslog message (Options c) must have the EventClass | ||||
field set to "syslog". The NETCONF client parses the message in the | ||||
same manner as any other message, finds the normal fields (ie, XML- | ||||
marked content) not present and either proceeds to parse the | ||||
SyslogInfo field or hands the syslog message to the entity | ||||
responsible for processing syslog messages. | ||||
B.2.3.3 Event Subscription Options | ||||
A NETCONF client may request subscription to options b) XML and | ||||
syslog or c) syslog only listed in "Supported Forwarding Options" at | ||||
subscription time via the user-specified filter. The FILTER or NAMED | ||||
FILTER parameter in <create-subscription>. As previously indicated, | ||||
the default behaviour is to forward NETCONF XML only event | ||||
notifications. [Editor's Note: How is this done exactly?] | ||||
B.2.3.4 Supported Forwarding Option Discovery | ||||
A potential means for a NETCONF server to convey its feature set | ||||
support is via capabilities. However, in this particular case, the | ||||
event content is not a protocol feature therefore other means are | ||||
needed. A future version of this document will address this issue. | ||||
Appendix C. Example Configuration Notifications | ||||
This non-normative appendix provides a detailed description of a | ||||
configuration change event notification definition in support of the | ||||
configuration operations, particularly those defined by the NETCONF | ||||
protocol. | ||||
C.1 Types of Configuration Events | ||||
Configuration event notifications include: | ||||
o All-triggered Configuration Events | ||||
o NETCONF-triggered Configuration Events | ||||
All-triggered Configuration events report on changes from the | ||||
perspective of the managed resource, rather than the commands which | ||||
created the configuration change. They are reported regardless of | ||||
what specific method was used to initiate the change. They indicate | ||||
that a change has occurred around hardware, software, services or | ||||
other managed resources within a system. Specific events includes | ||||
o Resource Added | ||||
o Resource Removed | ||||
o Resource Modified | ||||
NETCONF-triggered events are those which correspond to the execution | ||||
of explicit NETCONF operations. These include: | ||||
o copy-config event | ||||
* This is a data store level event generated following the | ||||
successful completion of a copy-config operation. This | ||||
represents the creation of a new configuration file or | ||||
replacement of an existing one. | ||||
o delete-config event | ||||
* This is a data store level event generated following the | ||||
successful completion of a delete-config operation. This | ||||
represents the deletion of a configuration file. | ||||
o edit-config event | ||||
* This is an event generated following a change in configuration | ||||
due to an edit-config operation, e.g., due to the completion of | ||||
an edit-config operation which successfully changed some part | ||||
of the configuration. See edit-config error-options (stop-on- | ||||
error, ignore-error, rollback-on-error) The contents of this | ||||
event are dependent on the type of operation performed: edit- | ||||
config (merge, replace, delete, create). This event is not | ||||
intended to report completely unsuccessful configuration | ||||
operations. | ||||
o lock-config event | ||||
* This is a data store level event generated following the | ||||
successful locking of a configuration data store. | ||||
o unlock-config event | ||||
* This is a data store level event generated following the | ||||
successful release of a lock previously held on a configuration | ||||
data store. | ||||
C.2 Config Event Notification Structure | ||||
The table below lists the EventInfo parameters for a config event | ||||
notification. | ||||
Nomenclature: | ||||
O - This is marked optional field because it is implementation/ | ||||
notification category dependent. In some cases this may be user | ||||
configurable. | ||||
M - This is a mandatory field that must be included. Dependency on | ||||
event class may exist as noted below | ||||
----------------------------------------------------- | ||||
Parameter Name Restrictions | ||||
----------------------------------------------------- | ||||
EventInfo | ||||
----------------------------------------------------- | ||||
EventID O | ||||
----------------------------------------------------- | ||||
ResourceInstance M | ||||
----------------------------------------------------- | ||||
ConfigChangeType M | ||||
----------------------------------------------------- | ||||
TargetDataStore M | ||||
----------------------------------------------------- | ||||
UserInfo O | ||||
----------------------------------------------------- | ||||
UserName | ||||
----------------------------------------------------- | ||||
SourceIndicator | ||||
----------------------------------------------------- | ||||
TransactionId | ||||
----------------------------------------------------- | ||||
CopyConfigInfo -- copy-config only | ||||
----------------------------------------------------- | ||||
DataSource M | ||||
----------------------------------------------------- | ||||
EditConfigInfo -- edit-config only | ||||
----------------------------------------------------- | ||||
EventTime M | ||||
----------------------------------------------------- | ||||
Context O | ||||
----------------------------------------------------- | ||||
EnteredCommand M | ||||
----------------------------------------------------- | ||||
NewConfig M | ||||
----------------------------------------------------- | ||||
MergeReplaceInfo | ||||
----------------------------------------------------- | ||||
OldConfig O | ||||
----------------------------------------------------- | ||||
EventTime M | ||||
----------------------------------------------------- | ||||
EventGenerationTime | ||||
----------------------------------------------------- | ||||
EventSysUpTime | ||||
----------------------------------------------------- | ||||
C.3 Configuration Event Content | ||||
The applicability of these fields to other event classes is for | ||||
further study. | ||||
C.3.1 Target Datastore | ||||
Target datastore refers to the data store (startup, candidate, | ||||
running) which was modified by the management operation. | ||||
C.3.2 User Info | ||||
This is used to convey information describing who originated the | ||||
configuration event and the means for submitting the request. The | ||||
user info field contains the following information: | ||||
user Name: User id which was authorized to execute the associated | ||||
management operation causing the generation of this event. | ||||
source Indicator: Indicates the method employed to initiate the | ||||
management operation telnet, NETCONF, console, etc. | ||||
transaction Id: If available, this field contains a unique | ||||
identifier for the associated management operation. This is | ||||
implementation dependent and may require additional information to | ||||
be communicated between server and client. A possible option is | ||||
to make use of the message-id in the NETCONF rpc header | ||||
C.3.3 Data Source | ||||
The data source is used, for example, in the copy configuration | ||||
command to indicated the source of information used in the copy | ||||
operation | ||||
Applicable Event Classes: configuration (useful for copy-config) | ||||
C.3.4 Operation | ||||
Operation is used, for example, in the edit configuration command to | ||||
indicated the specific operation that has taken place - create, | ||||
delete, merge, replace. | ||||
Applicable Event Classes: configuration (useful for edit-config) | ||||
C.3.5 Context | ||||
The configuration sub-mode under which the command was executed. | ||||
Applicable Event Classes: configuration | ||||
C.3.6 Entered Command | ||||
The command entered and executed on the device. | ||||
C.3.7 New Config | ||||
The device's configuration following the successful execution of the | ||||
entered command. | ||||
Applicable Event Classes: configuration | ||||
C.3.8 Old Config | ||||
The configuration prior to the execution of the entered command. | ||||
Applicable Event Classes: configuration | ||||
C.3.9 Non-netconf commands in configuration notifications | ||||
To support legacy implementations and for better integration with | ||||
other deployed solutions on the box, sending information via netconf | ||||
about configuration changes that were originated via other solutions, | ||||
such as command line interfaces is necessary. In order to do this, | ||||
the information in the message needs to be clearly tagged so that the | ||||
consumer of the information knows what to expect. In addition, the | ||||
creation of the subscription needs allow for the client to indicate | ||||
whether this non-XML formatted information is of interest | ||||
The latter is done by identifying the XML namespace under which the | ||||
data syntax/schema is defined. A NETCONF client requests the format | ||||
in which it wants the NETCONF server to issue the event notifications | ||||
at subscription time by specifying the appropriate namespace under | ||||
the Filter parameter in the <create-subscription> operation. An | ||||
example is provided below: | ||||
<netconf:filter> | ||||
<data-format:config-format-xml | ||||
xmlns="http://www.example.com/xmlnetevents"/> | ||||
</netconf:filter> | ||||
Appendix D. IP Address Schema | ||||
<?xml version="1.0" encoding="UTF-8"?> | ||||
<!-- IETF Netconf Working Group | ||||
http://www.ietf.org/html.charters/netconf-charter.html | ||||
--> | ||||
<xs:schema elementFormDefault="qualified" | ||||
attributeFormDefault="unqualified" version="0.2" | ||||
xmlns:xs="http://www.w3.org/2001/XMLSchema" | ||||
xmlns="urn:ietf:params:xml:ns:netmod:ipAddress:1.0" | ||||
targetNamespace="urn:ietf:params:xml:ns:netmod:ipAddress:1.0"> | ||||
<xs:simpleType name = "ipV4Addr"> | ||||
<xs:annotation> | ||||
<xs:documentation> | ||||
An IP version 4 address in dotted notation decimal. | ||||
Example: 15.13.120.22 | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
<xs:restriction base = "xs:string"> | ||||
<xs:pattern value = | ||||
"[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}"/> | ||||
</xs:restriction> | ||||
</xs:simpleType> | ||||
<xs:simpleType name = "ipV6Addr"> | ||||
<xs:annotation> | ||||
<xs:documentation> | ||||
An IP version 6 address in colon separated 2 byte | ||||
block hexadecimal notation. | ||||
Example: FEDC:AB19:12FE:0234:98EF:1178:8891:CAFF | ||||
</xs:documentation> | ||||
</xs:annotation> | ||||
<xs:restriction base = "xs:string"> | ||||
<xs:pattern value = | ||||
"[0-9a-fA-F]{4}:[0-9a-fA-F]{4}:[0-9a-fA-F]{4}: | ||||
[0-9a-fA-F]{4}:[0-9a-fA-F]{4}: | ||||
[0-9a-fA-F]{4}:[0-9a-fA-F]{4}:[0-9a-fA-F]{4}"/> | ||||
</xs:restriction> | ||||
</xs:simpleType> | ||||
<xs:complexType name="IPAddressOrSysname"> | ||||
<xs:choice> | ||||
<xs:element name="ipv4Address" type="ipV4Addr"/> | ||||
<xs:element name="ipv6Address" type="ipV6Addr"/> | ||||
<xs:element name="sysName" type="xs:string"/> | ||||
</xs:choice> | ||||
</xs:complexType> | ||||
</xs:schema> | ||||
Intellectual Property Statement | Intellectual Property Statement | |||
The IETF takes no position regarding the validity or scope of any | The IETF takes no position regarding the validity or scope of any | |||
Intellectual Property Rights or other rights that might be claimed to | Intellectual Property Rights or other rights that might be claimed to | |||
pertain to the implementation or use of the technology described in | pertain to the implementation or use of the technology described in | |||
this document or the extent to which any license under such rights | this document or the extent to which any license under such rights | |||
might or might not be available; nor does it represent that it has | might or might not be available; nor does it represent that it has | |||
made any independent effort to identify any such rights. Information | made any independent effort to identify any such rights. Information | |||
on the procedures with respect to rights in RFC documents can be | on the procedures with respect to rights in RFC documents can be | |||
found in BCP 78 and BCP 79. | found in BCP 78 and BCP 79. | |||
End of changes. 151 change blocks. | ||||
1373 lines changed or deleted | 556 lines changed or added | |||
This html diff was produced by rfcdiff 1.32. The latest version is available from http://www.levkowetz.com/ietf/tools/rfcdiff/ |