draft-ietf-netconf-notification-00.txt   draft-ietf-netconf-notification-01.txt 
Network Working Group S. Chisholm Network Working Group S. Chisholm
Internet-Draft K. Curran Internet-Draft K. Curran
Expires: July 12, 2006 Nortel Expires: October 30, 2006 Nortel
H. Trevino H. Trevino
Cisco Cisco
January 8, 2006 April 28, 2006
NETCONF Event Notifications NETCONF Event Notifications
draft-ietf-netconf-notification-00.txt draft-ietf-netconf-notification-01.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 36
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 July 12, 2006. This Internet-Draft will expire on October 30, 2006.
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
skipping to change at page 2, line 14 skipping to change at page 2, line 14
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
2. Event-Related Operations . . . . . . . . . . . . . . . . . . . 6 2. Event-Related Operations . . . . . . . . . . . . . . . . . . . 6
2.1 Subscribing to receive Events . . . . . . . . . . . . . . 6 2.1 Subscribing to receive Events . . . . . . . . . . . . . . 6
2.1.1 create-subscription . . . . . . . . . . . . . . . . . 6 2.1.1 create-subscription . . . . . . . . . . . . . . . . . 6
2.2 Sending Event Notifications . . . . . . . . . . . . . . . 7 2.2 Sending Event Notifications . . . . . . . . . . . . . . . 7
2.2.1 Events . . . . . . . . . . . . . . . . . . . . . . . . 7 2.2.1 Event Notification . . . . . . . . . . . . . . . . . . 7
2.3 Changing the Subscription . . . . . . . . . . . . . . . . 8 2.3 Changing the Subscription . . . . . . . . . . . . . . . . 8
2.3.1 modify-subscription . . . . . . . . . . . . . . . . . 9 2.3.1 modify-subscription . . . . . . . . . . . . . . . . . 9
2.4 Terminating the Subscription . . . . . . . . . . . . . . . 10 2.4 Terminating the Subscription . . . . . . . . . . . . . . . 10
2.4.1 cancel-subscription . . . . . . . . . . . . . . . . . 10 2.4.1 cancel-subscription . . . . . . . . . . . . . . . . . 10
3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 11 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 11
3.1 Capabilities Exchange . . . . . . . . . . . . . . . . . . 11 3.1 Capabilities Exchange . . . . . . . . . . . . . . . . . . 11
3.2 Querying Subscription Properties . . . . . . . . . . . . . 11 3.2 Querying Subscription Properties . . . . . . . . . . . . . 11
3.3 RPC One-way Messages . . . . . . . . . . . . . . . . . . . 14 3.3 One-way Notification Messages . . . . . . . . . . . . . . 16
3.4 User-Specified Filters . . . . . . . . . . . . . . . . . . 14 3.4 Filter Dependencies . . . . . . . . . . . . . . . . . . . 16
3.4.1 Named Profiles . . . . . . . . . . . . . . . . . . . . 15 3.4.1 Named Profiles . . . . . . . . . . . . . . . . . . . . 17
3.4.2 Filtering . . . . . . . . . . . . . . . . . . . . . . 15 3.4.2 Filtering . . . . . . . . . . . . . . . . . . . . . . 17
3.5 Event Classes . . . . . . . . . . . . . . . . . . . . . . 15 3.5 Event Classes . . . . . . . . . . . . . . . . . . . . . . 17
3.6 Defining Event Notifications . . . . . . . . . . . . . . . 16 3.6 Defining Event Notifications . . . . . . . . . . . . . . . 18
3.7 Interleaving Messages . . . . . . . . . . . . . . . . . . 16 3.7 Interleaving Messages . . . . . . . . . . . . . . . . . . 18
4. XML Schema for Event Notifications . . . . . . . . . . . . . . 18 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 20
5. Mapping to Application Protocols . . . . . . . . . . . . . . . 23 5. Mapping to Application Protocols . . . . . . . . . . . . . . . 24
5.1 SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.1 SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.2 BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.2 BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.2.1 One-way Messages in Beep . . . . . . . . . . . . . . . 24 5.2.1 One-way Notification Messages in Beep . . . . . . . . 25
5.3 SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.3 SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.3.1 A NETCONF over Soap over HTTP Example . . . . . . . . 25 5.3.1 A NETCONF over Soap over HTTP Example . . . . . . . . 26
6. Filtering examples . . . . . . . . . . . . . . . . . . . . . . 28 6. Filtering examples . . . . . . . . . . . . . . . . . . . . . . 29
6.1 Event Classes . . . . . . . . . . . . . . . . . . . . . . 28 6.1 Event Classes . . . . . . . . . . . . . . . . . . . . . . 29
6.2 Subtree Filtering . . . . . . . . . . . . . . . . . . . . 28 6.2 Subtree Filtering . . . . . . . . . . . . . . . . . . . . 29
6.3 XPATH filters . . . . . . . . . . . . . . . . . . . . . . 30 6.3 XPATH filters . . . . . . . . . . . . . . . . . . . . . . 31
7. Security Considerations . . . . . . . . . . . . . . . . . . . 32 7. Additional Capabilities . . . . . . . . . . . . . . . . . . . 33
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 7.1 Call-Home Notifications . . . . . . . . . . . . . . . . . 33
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 34 7.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . 33
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 7.1.2 Dependencies . . . . . . . . . . . . . . . . . . . . . 34
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 35 7.1.3 Capability Identifier . . . . . . . . . . . . . . . . 34
A. Potential Event Content . . . . . . . . . . . . . . . . . . . 36 8. Security Considerations . . . . . . . . . . . . . . . . . . . 37
A.1 Event Identifier . . . . . . . . . . . . . . . . . . . . . 36 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
A.2 Resource Instance . . . . . . . . . . . . . . . . . . . . 36 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 39
A.3 Event Time . . . . . . . . . . . . . . . . . . . . . . . . 36 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 39
A.4 Perceived Severity . . . . . . . . . . . . . . . . . . . . 36 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 40
A.5 Probable Cause . . . . . . . . . . . . . . . . . . . . . . 37 A. Design Alternatives . . . . . . . . . . . . . . . . . . . . . 41
A.6 Specific Problem . . . . . . . . . . . . . . . . . . . . . 37 A.1 Suspend And Resume . . . . . . . . . . . . . . . . . . . . 41
A.7 Trend Indication . . . . . . . . . . . . . . . . . . . . . 37 A.2 Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . 41
A.8 Additional Alarm Text . . . . . . . . . . . . . . . . . . 37 B. Event Notifications and Syslog . . . . . . . . . . . . . . . . 42
A.9 Threshold Identifier . . . . . . . . . . . . . . . . . . . 37 B.1 Leveraging Syslog Field Definitions . . . . . . . . . . . 42
A.10 Threshold Type . . . . . . . . . . . . . . . . . . . . . . 38 B.1.1 Field Mapping . . . . . . . . . . . . . . . . . . . . 43
A.11 Observed Value . . . . . . . . . . . . . . . . . . . . . . 38 B.1.2 Severity Mapping . . . . . . . . . . . . . . . . . . . 44
A.12 State Change Information . . . . . . . . . . . . . . . . . 38 B.2 Syslog within NETCONF Events . . . . . . . . . . . . . . . 44
B. Configuration Event Class Notifications . . . . . . . . . . . 39 B.2.1 Motivation . . . . . . . . . . . . . . . . . . . . . . 44
B.1 Types of Configuration Events . . . . . . . . . . . . . . 39 B.2.2 Embedding syslog messages in a NETCONF Event . . . . . 44
B.2 Config Event Notification Structure . . . . . . . . . . . 40 B.2.3 Supported Forwarding Options . . . . . . . . . . . . . 45
B.3 Configuration Event Content . . . . . . . . . . . . . . . 42 C. Example Configuration Notifications . . . . . . . . . . . . . 47
B.3.1 Target Datastore . . . . . . . . . . . . . . . . . . . 42 C.1 Types of Configuration Events . . . . . . . . . . . . . . 47
B.3.2 User Info . . . . . . . . . . . . . . . . . . . . . . 42 C.2 Config Event Notification Structure . . . . . . . . . . . 48
B.3.3 Data Source . . . . . . . . . . . . . . . . . . . . . 42 C.3 Configuration Event Content . . . . . . . . . . . . . . . 50
B.3.4 Operation . . . . . . . . . . . . . . . . . . . . . . 42 C.3.1 Target Datastore . . . . . . . . . . . . . . . . . . . 50
B.3.5 Context . . . . . . . . . . . . . . . . . . . . . . . 42 C.3.2 User Info . . . . . . . . . . . . . . . . . . . . . . 50
B.3.6 Entered Command . . . . . . . . . . . . . . . . . . . 43 C.3.3 Data Source . . . . . . . . . . . . . . . . . . . . . 50
B.3.7 New Config . . . . . . . . . . . . . . . . . . . . . . 43 C.3.4 Operation . . . . . . . . . . . . . . . . . . . . . . 50
B.3.8 Old Config . . . . . . . . . . . . . . . . . . . . . . 43 C.3.5 Context . . . . . . . . . . . . . . . . . . . . . . . 50
B.3.9 Non-netconf commands in configuration notifications . 43 C.3.6 Entered Command . . . . . . . . . . . . . . . . . . . 51
B.4 Design Alternative . . . . . . . . . . . . . . . . . . . . 43 C.3.7 New Config . . . . . . . . . . . . . . . . . . . . . . 51
B.4.1 Server Session Initiation . . . . . . . . . . . . . . 43 C.3.8 Old Config . . . . . . . . . . . . . . . . . . . . . . 51
B.4.2 Establishment . . . . . . . . . . . . . . . . . . . . 44 C.3.9 Non-netconf commands in configuration notifications . 51
B.4.3 Teardown . . . . . . . . . . . . . . . . . . . . . . . 44 Intellectual Property and Copyright Statements . . . . . . . . 52
B.4.4 Suspend And Resume . . . . . . . . . . . . . . . . . . 45
B.4.5 Lifecycle . . . . . . . . . . . . . . . . . . . . . . 45
C. NETCONF Event Notifications and Syslog . . . . . . . . . . . . 46
C.1 Leveraging Syslog Field Definitions . . . . . . . . . . . 46
C.1.1 Field Mapping . . . . . . . . . . . . . . . . . . . . 47
C.1.2 Severity Mapping . . . . . . . . . . . . . . . . . . . 48
C.2 Syslog within NETCONF Events . . . . . . . . . . . . . . . 48
C.2.1 Motivation . . . . . . . . . . . . . . . . . . . . . . 48
C.2.2 Embedding syslog messages in a NETCONF Event . . . . . 48
C.2.3 Supported Forwarding Options . . . . . . . . . . . . . 49
Intellectual Property and Copyright Statements . . . . . . . . 51
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> |
+-------------+ +-----------------------------+
| |
+-------------+ +-----------------------------+
| RPC | | <rpc>, <rpc-reply> |
+-------------+ +-----------------------------+
| | | |
+-------------+ +-----------------------------+ +-------------+ +-------------------------------------------+
| Operations | | <get-config>, <edit-config> <notification>|
+-------------+ +-------------------------------------------+
| | |
+-------------+ +-----------------------------+ |
| RPC | | <rpc>, <rpc-reply> | |
+-------------+ +-----------------------------+ |
| | |
+-------------+ +------------------------------------------+
| Application | | BEEP, SSH, SSL, console | | Application | | 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 application protocols. for the mapping to application protocols.
Figure 1 Figure 1
1.1 Definition of Terms 1.1 Definition of Terms
skipping to change at page 7, line 5 skipping to change at page 7, line 5
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. These filter parameters can
only be modified using the modify-subscription command. 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. If not present, no additional filtering will filter profile. The contents of the profile are specified in
be applied. If the separate definition of these filters is the provided XML Schema. If not present, no additional
updated, then these changes will be reflected in the filtered filtering will be applied. If the separate definition of these
events on this subscription. filters is updated, then these changes will be reflected in the
filtered events on this subscription.
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. request cannot be completed for any reason.
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, Notifications are tagged with event classes, subscription ID,
sequence number, and date and time. sequence number, and date and time.
2.2.1 Events 2.2.1 Event Notification
Events
<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 to subscription> command asynchronously when an event of interest
them has occurred. An event notification is a complete XML (i.e. meeting the specified filtering criteria) to them has
document. occurred. An event notification is a complete XML document.
Parameters: Parameters:
Event Classes: Event Classes:
The event class or classes associated with this event The event class or classes associated with this event
notification notification
Subscription Id: Subscription Id:
A unique identifier for this event subscription A unique identifier for this event subscription
skipping to change at page 8, line 33 skipping to change at page 8, line 33
Negative Response: Negative Response:
No response. No response.
2.2.1.1 Event Notification 2.2.1.1 Event Notification
The NETCONF Event notification structure is shown in the following The NETCONF Event notification structure is shown in the following
figure. figure.
_____________ ___________________________________________________________________
|RPC-Header|| || Notification Header || Data |
|__________||
|message-id||
|__________||
____________________________________________________________________
|| Event Header || Data |
||__________________________________________________________||______| ||__________________________________________________________||______|
|| subscriptionId| eventClasses| sequenceNumber| dataAndTime|| | || subscriptionId| eventClasses| sequenceNumber| dateAndTime|| |
||_______________|_____________|_______________|____________||______| ||_______________|_____________|_______________|____________||______|
2.3 Changing the Subscription 2.3 Changing the Subscription
After an event notification subscription has been established, the After an event notification subscription has been established, the
NETCONF client can initiate a request to change properties of the NETCONF client can initiate a request to change properties of the
event notification subscription. This prevents loss of event event notification subscription. This prevents loss of event
notifications that might otherwise occur during a tear down and notifications that might otherwise occur during a cancelling and
recreation of the event notification subscription. This command is recreation of the event notification subscription. This command is
responded to by the NETCONF server responded to by the NETCONF server
2.3.1 modify-subscription 2.3.1 modify-subscription
<modify-subscription> <modify-subscription>
Description: Description:
Change properties of the event notification subscription. Change properties of the event notification subscription.
skipping to change at page 9, line 38 skipping to change at page 9, line 36
An optional parameter that indicates which subset of all An optional parameter that indicates which subset of all
possible events that are of interest. The format is the same possible events that are of interest. The format is the same
filter used for other NETCONF commands. If not present, all filter used for other NETCONF commands. If not present, all
events not precluded by other parameters will be sent. These events not precluded by other parameters will be sent. These
filter parameters can only be modified using the modify- filter parameters can only be modified using the modify-
subscription command. subscription command.
Named Profile: Named Profile:
An optional parameter that points to separately defined filter An optional parameter that points to separately defined filter
profile. If not present, no additional filtering will be profile. The contents of the profile are specified in provided
XML Schema. If not present, no additional filtering will be
applied. If the separate definition of these filters is applied. If the separate definition of these filters is
updated, then these changes will be reflected in the events updated, then these changes will be reflected in the events
seen on this subscription. seen on this subscription.
Positive Response: Positive Response:
If the NETCONF server was able to satisfy the request, an <rpc- If the NETCONF server was able to satisfy the request, an <rpc-
reply> is sent that includes an <ok> element. reply> is sent that includes an <ok> element.
Negative Response: Negative Response:
skipping to change at page 10, line 23 skipping to change at page 10, line 23
NETCONF session may also be torn down for other reasons and this will NETCONF session may also be torn down for other reasons and this will
also result in the subscription being cancelled, but is not subjected also result in the subscription being cancelled, but is not subjected
to the behaviour of this command. to the behaviour of this command.
2.4.1 cancel-subscription 2.4.1 cancel-subscription
<cancel-subscription> <cancel-subscription>
Description: Description:
Tear down the event notification subscription. Stop and delete the event notification subscription.
Parameters: Parameters:
Subscription Id: Subscription Id:
A unique identifier for this event notification subscription. A unique identifier for this event notification subscription.
Positive Response: Positive Response:
If the NETCONF server was able to satisfy the request, an <rpc- If the NETCONF server was able to satisfy the request, an <rpc-
skipping to change at page 11, line 38 skipping to change at page 11, line 38
<session-id>4</session-id> <session-id>4</session-id>
</hello> </hello>
3.2 Querying Subscription Properties 3.2 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= xmlns:nsub="urn:ietf:params:xml:ns:netconf:subscription:1.0"
"urn:ietf:params:xml:ns:netconf:subscription:1.0" targetNamespace= "urn:ietf:params:xml:ns:netconf:subscription:1.0"
targetNamespace= xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"
"urn:ietf:params:xml:ns:netconf:subscription:1.0" xmlns:ncEvent= "urn:ietf:params:xml:ns:netconf:notification:1.0"
xmlns:netconf= xmlns:nm="urn:ietf:params:xml:ns:netconf:appInfo:1.0"
"urn:ietf:params:xml:ns:netconf:base:1.0" elementFormDefault="qualified" attributeFormDefault="unqualified"
xmlns:ncEvent= xml:lang="en">
"urn:ietf:params:xml:ns:netconf:notification:1.0" <xs:annotation>
elementFormDefault="qualified" <xs:documentation xml:lang="en">
attributeFormDefault="unqualified" xml:lang="en">
<annotation>
<documentation xml:lang="en">
Schema for reporting on Event Subscriptions Schema for reporting on Event Subscriptions
</documentation> </xs:documentation>
<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>NetConf State Schema</nm:Name> <nm:Name>NetConf State Schema</nm:Name>
<nm:LastUpdated>2005-11-30T09:30:47-05:00 <nm:LastUpdated>2006-04-30T09: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 NetConf Event subscriptions and creating named
profiles
</nm:Description> </nm:Description>
</nm:identity> </nm:identity>
</appinfo> </xs:appinfo>
</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:notification:1.0" namespace="urn:ietf:params:xml:ns:netconf:notifications:1.0"
schemaLocation="ietf-netconf-notification.xsd"/> schemaLocation="draft-ietf-netconf-notification-01.xsd"/>
<xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0" <xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
schemaLocation="draft-ietf-netconf-prot-09.xsd"/> schemaLocation="draft-ietf-netconf-prot-12.xsd"/>
<xs:element name="netconfSubscription"> <xs:element name="netconfSubscription">
<xs:annotation>
<xs:appinfo>
<nm:minAccess><read/></nm:minAccess>
<nm:maxAccess><read/></nm:maxAccess>
</xs:appinfo>
</xs:annotation>
<xs:complexType> <xs:complexType>
<xs:sequence maxOccurs="unbounded"> <xs:sequence maxOccurs="unbounded">
<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>
skipping to change at page 13, line 30 skipping to change at page 13, line 35
<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 name="namedProfile"
type="xs:string" 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. The named profile associated with this subscription. Note
Note that the contents of the named profile may have that the contents of the named profile may have changed
changed since it was last applied 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 has
not been modified since creation, this is the time of not been modified since creation, this is the time of
subscription creation. subscription creation.
</xs:documentation> </xs:documentation>
skipping to change at page 14, line 19 skipping to change at page 14, line 29
<xs:element name="lastSequenceNumber" <xs:element name="lastSequenceNumber"
type="xs:integer" minOccurs="0"> type="xs:integer" minOccurs="0">
<xs:annotation> <xs:annotation>
<xs:documentation xml:lang="en"> <xs:documentation xml:lang="en">
The sequence number of the last event notification sent to The sequence number of the last event notification sent to
this subscription this subscription
</xs:documentation> </xs:documentation>
</xs:annotation> </xs:annotation>
</xs:element> </xs:element>
<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:sequence>
</xs:complexType>
</xs:element>
<xs:element name="netconfSubscriptions">
<xs:complexType>
<xs:sequence>
<xs:element ref="nsub:netconfSubscription" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence> </xs:sequence>
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
<xs:element name="namedProfile">
<xs:annotation>
<xs:appinfo>
<nm:minAccess><read/></nm:minAccess>
<nm:maxAccess><read/> <write/> <create/> <delete/>
</nm:maxAccess>
</xs:appinfo>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<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"
type="netconf:filterInlineType" minOccurs="0">
<xs:annotation>
<xs:documentation xml:lang="en">
The filters associated with this named Profile.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="lastModified" type="xs:dateTime">
<xs:annotation>
<xs:documentation>
The timestamp of the last modification to this
named Profile. Note that modification of the
profile does not cause an immediate update
to all applicable subscription. Therefore, this
time should be compared with the last
modified time associated with the subscription.
If this time is earlier, then the subscription
is using the exact set of parameters associated
with this named profile. If this time is
later, then the subscription is using an earlier
version of this named profile and the exact
parameters may not match.
</xs:documentation>
<xs:appinfo>
<nm:minAccess><read/></nm:minAccess>
<nm:maxAccess><read/> </nm:maxAccess>
</xs:appinfo>
</xs:annotation>
</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:complexType>
</xs:element>
<xs:element name="namedProfiles">
<xs:complexType>
<xs:sequence>
<xs:element ref="nsub:namedProfile" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema> </xs:schema>
3.3 RPC One-way Messages 3.3 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 a order to support this model, this memo introduces the concept of
one-way RPC message. notifications, which are one-way messages.
The one-way RPC message is similar to the two-way RPC message, except A one-way message is similar to the two-way RPC message, except that
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 RPC will originate from the NETCONF server, and notification, this message will originate from the NETCONF server,
not the NETCONF client. and not the NETCONF client.
3.4 User-Specified Filters 3.4 Filter Dependencies
Note that when multiple filters are specified, they are applied Note that when multiple filters are specified (Event Class, in-line
collectively, so event notifications needs to pass all specified Filter, Named Profiles), they are applied collectively, so event
filters in order to be sent to the subscriber. If a filter is notifications needs to pass all specified filters in order to be sent
specified to look for data of a particular value, and the data item to the subscriber. If a filter is specified to look for data of a
is not present within a particular event for its value to be checked, particular value, and the data item is not present within a
particular event notification for its value to be checked against,
it will be filtered out. For example, if one were to check for it will be filtered out. For example, if one were to check for
'severity=critical' in a configuration event notification where this 'severity=critical' in a configuration event notification where this
field was not supported, then the notification would be filtered out. field was not supported, then the notification would be filtered out.
3.4.1 Named Profiles 3.4.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 or
modified. Note that changes to the profile after the subscription modified. Note that changes to the profile after the subscription
has been created will have no effect unless a modify subscription has been created will have no effect unless a modify subscription
command is issued. Since named profiles exist outside of the command is issued. Since named profiles exist outside of the
subscription, they persist after the subscription has been cancelled. subscription, they persist after the subscription has been cancelled.
3.4.2 Filtering 3.4.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. It can only be changed using notification subscription is created. These filters can only be
the modify subscription command. This is specified via the Filter changed using the modify subscription command. This is specified via
parameter. Filters only exist as parameters to the subscription. the Filter parameter. Filters only exist as parameters to the
subscription.
3.5 Event Classes 3.5 Event Classes
Events can be broadly classified into one more event classes. Each Events can be broadly classified into one more event classes. Each
event class identifies a set of event notifications which share event class identifies a set of event notifications which share
important characteristics, such being generated from similar events important characteristics, such being generated from similar events
or sharing much of the same content. or sharing much of the same content.
The initial set of event classes is fault, configuration, state, The initial set of event classes is fault, configuration, state,
audit, data, maintenance, metrics, security, information and audit, data, maintenance, metrics, security, information, heartbeat
heartbeat. and syslog.
A fault event notification is generated when a fault condition (error A fault event notification is generated when a fault condition (error
or warning) occurs. A fault event may result in an alarm. Examples or warning) occurs. A fault event may result in an alarm. Examples
of fault events could be a communications alarm, environmental alarm, of fault events could be a communications alarm, environmental alarm,
equipment alarm, processing error alarm, quality of service alarm, or equipment alarm, processing error alarm, quality of service alarm, or
a threshold crossing event. See RFC3877 and RFC2819 for more a threshold crossing event. See RFC3877 and RFC2819 for more
information. information.
A configuration event, alternatively known as an inventory event, is A configuration event, alternatively known as an inventory event, is
used to notify that hardware, software, or a service has been added/ used to notify that hardware, software, or a service has been added/
skipping to change at page 16, line 35 skipping to change at page 18, line 37
other event classes, with the exception that implementations may not other event classes, with the exception that implementations may not
want to include an event log, if supported. Although widely used want to include an event log, if supported. Although widely used
throughout the industry, no current corresponding work within the throughout the industry, no current corresponding work within the
IETF. However, other standards bodies such as the TeleManagement IETF. However, other standards bodies such as the TeleManagement
Forum have similar definitions. Forum have similar definitions.
An Information event is something that happens of interest which is An Information event is something that happens of interest which is
within the expected operational behaviour and not otherwise covered within the expected operational behaviour and not otherwise covered
by another class. by another class.
The syslog event class is used to indicate tunneled syslog content.
The content and format of the message will be compliant to syslog
standards.
3.6 Defining Event Notifications 3.6 Defining Event Notifications
Event Notifications are defined ahead of time by defining an XML Event Notifications are defined ahead of time by defining an XML
element and assigning it to particular event classes. This will be element and assigning it to particular event classes. This will be
done using an "eventClasses" attribute. done using an "eventClasses" attribute.
3.7 Interleaving Messages 3.7 Interleaving Messages
While each NETCONF message must be a complete XML document, the While each NETCONF message must be a complete XML document, the
design of the event system allows for the interleaving of complete design of the event system allows for the interleaving of complete
skipping to change at page 16, line 46 skipping to change at page 19, line 4
Event Notifications are defined ahead of time by defining an XML Event Notifications are defined ahead of time by defining an XML
element and assigning it to particular event classes. This will be element and assigning it to particular event classes. This will be
done using an "eventClasses" attribute. done using an "eventClasses" attribute.
3.7 Interleaving Messages 3.7 Interleaving Messages
While each NETCONF message must be a complete XML document, the While each NETCONF message must be a complete XML document, the
design of the event system allows for the interleaving of complete design of the event system allows for the interleaving of complete
asynchronous event notifications with complete synchronous messages. asynchronous event notifications with complete synchronous messages.
It is possible to still send command-response type messages such as It is possible to still send command-response type messages such as
<modify-subscription> while events are being generated. The only <modify-subscription> while events are being generated. The only
restriction is that each message must be complete restriction is that each message must be complete
The following sequence diagram demonstrates an example NETCONF The following sequence diagram demonstrates an example NETCONF
session where after basic session establishment and capability session where after basic session establishment and capability
exchange, NETCONF client (C), subscribes to receive event exchange, NETCONF client (C), subscribes to receive event
notifications. The NETCONF server (S), starts sending event notifications. The NETCONF server (S), starts sending event
notifications as events of interest happen within the system. The notifications as events of interest happen within the system. The
NETCONF client decides to change the characteristics of their event NETCONF client decides to change the characteristics of their event
subscription so sends a <modify-subscription> command. Before the subscription by sending a <modify-subscription> command. Before the
NETCONF server, receives this command, another event is generated and NETCONF server, receives this command, another event is generated and
the NETCONF server starts to send the event notification. The the NETCONF server starts to send the event notification. The
NETCONF server finishes sending this event notification before NETCONF server finishes sending this event notification before
processing the <modify-subscription> command and sending the reply. processing the <modify-subscription> command and sending the reply.
C S C S
| | | |
| capability exchange | | capability exchange |
|-------------------------->| |-------------------------->|
|<------------------------->| |<------------------------->|
skipping to change at page 21, line 21 skipping to change at page 23, line 21
</xs:sequence> </xs:sequence>
</xs:extension> </xs:extension>
</xs:complexContent> </xs:complexContent>
</xs:complexType> </xs:complexType>
<xs:element name="cancel-subscription" <xs:element name="cancel-subscription"
type="cancelSubscriptionType" type="cancelSubscriptionType"
substitutionGroup="netconf:rpcOperation"/> substitutionGroup="netconf:rpcOperation"/>
<!-- ************** One-way Operations ******************--> <!-- ************** One-way Operations ******************-->
<xs:complexType name="rpcOneWayType">
<xs:group ref="rpc-one-way"/>
<xs:attribute name="message-id" type="xs:string"
use="optional"/>
</xs:complexType>
<xs:group name="rpc-one-way">
<xs:sequence>
<xs:element name="data" type="netconf:dataInlineType"
minOccurs="0"/>
</xs:sequence>
</xs:group>
<!-- <!--
<Event> operation <Event> operation
--> -->
<xs:complexType name="NotificationType"> <xs:complexType name="NotificationType">
<xs:complexContent> <xs:complexContent>
<xs:extension base="rpcOneWayType">
<xs:sequence> <xs:sequence>
<xs:element name="subscription-id" <xs:element name="subscription-id"
type="SubscriptionID"/> type="SubscriptionID"/>
<xs:element name="event-classes" type="EventClasses"/> <xs:element name="event-classes" type="EventClasses"/>
<xs:element name="sequence-number" <xs:element name="sequence-number"
type="SequenceNumber"/> type="SequenceNumber"/>
<xs:element name="date-time" type="xs:dateTime"> <xs:element name="date-time" type="xs:dateTime">
<xs:annotation> <xs:annotation>
<xs:documentation> <xs:documentation>
The date and time that the event notification was The date and time that the event notification was
skipping to change at page 23, line 17 skipping to change at page 24, line 17
Currently, the NETCONF family of specification allows for running Currently, the NETCONF family of specification allows for running
NETCONF over a number of application protocols, some of which support NETCONF over a number of application 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 messages are supported as follows: Once the session has been One-way event messages are supported as follows: Once the session
established and capabilities have been exchanged, the server may send has been established and capabilities have been exchanged, the server
complete XML documents to the NETCONF client containing rpc-one-way may send complete XML documents to the NETCONF client containing
elements. No response is expected from the NETCONF client. notification elements. No response is expected from the NETCONF
client.
As the other examples in [NETCONF-SSH] illustrate, a special As the other examples in [NETCONF-SSH] illustrate, a special
character sequence, MUST be sent by both the client and the server character sequence, MUST be sent by both the client and the server
after each XML document in the NETCONF exchange. This character after each XML document in the NETCONF exchange. This character
sequence cannot legally appear in an XML document, so it can be sequence cannot legally appear in an XML document, so it can be
unambiguously used to identify the end of the current document in the unambiguously used to identify the end of the current document in the
event notification of an XML syntax or parsing error, allowing event notification of an XML syntax or parsing error, allowing
resynchronization of the NETCONF exchange. resynchronization of the 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 this: look like the following. Note the event notification contents
(delimited by <data> </data> tags) are not defined in this document
and are provided herein simply for illustration purposes:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<rpc-one-way message-id="105" <notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<notification>
<subscription-id>123456</subscription-id> <subscription-id>123456</subscription-id>
<event-class><configuration/><audit/></event-classes> <event-class><configuration/><audit/></event-classes>
<sequence-number>2</sequence-number> <sequence-number>2</sequence-number>
<date-time>2000-01-12T12:13:14Z</date-time> <date-time>2000-01-12T12:13:14Z</date-time>
<data> <data>
<user>Fred Flinstone</user> <user>Fred Flinstone</user>
<operation> <operation>
<edit-config> <edit-config>
<target> <target>
<running/> <running/>
skipping to change at page 24, line 32 skipping to change at page 25, line 31
<interface> <interface>
<name>Ethernet0/0</name> <name>Ethernet0/0</name>
<mtu>1500</mtu> <mtu>1500</mtu>
</interface> </interface>
</top> </top>
</config> </config>
</edit-config> </edit-config>
</operation> </operation>
</data> </data>
</notification> </notification>
</rpc-one-way>
]]> ]]>
]]> ]]>
5.2 BEEP 5.2 BEEP
Session establishment and two-way messages are based on the NETCONF Session establishment and two-way messages are based on the NETCONF
over BEEP transport mapping NETCONF-BEEP over BEEP transport mapping NETCONF-BEEP
5.2.1 One-way Messages in Beep 5.2.1 One-way Notification Messages in Beep
One-way messages can be supported either by mapping to the existing One-way notification messages can be supported either by mapping to
one-to-many BEEP construct or by creating a new one-to-none the existing one-to-many BEEP construct or by creating a new one-to-
construct. none construct.
This area is for future study. This area is for future study.
5.2.1.1 One-way messages via the One-to-many Construct 5.2.1.1 One-way messages via the One-to-many Construct
Messages in one-to-many exchanges: "rcp", "rpc-one-way", "rpc-reply" Messages in one-to-many exchanges: "rpc", "notification", "rpc-reply"
Messages in positive replies: "rpc-reply", "rpc-one-way" Messages in positive replies: "rpc-reply", "rpc-one-way"
5.2.1.2 One-way messages via the One-to-none Construct 5.2.1.2 One-way notification messages via the One-to-none Construct
Note that this construct would need to be added to an extension or Note that this construct would need to be added to an extension or
update to 'The Blocks Extensible Exchange Protocol Core' RFC 3080. update to 'The Blocks Extensible Exchange Protocol Core' RFC 3080.
MSG/NoANS: the client sends a "MSG" message, the server, sends no MSG/NoANS: the client sends a "MSG" message, the server, sends no
reply. reply.
In one-to-none exchanges, no reply to the "MSG" message is expected. In one-to-none exchanges, no reply to the "MSG" message is expected.
5.3 SOAP 5.3 SOAP
skipping to change at page 26, line 32 skipping to change at page 27, line 31
And then some time later And then some time later
S: HTTP/1.1 200 OK S: HTTP/1.1 200 OK
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: <rpc-one-way message-id="101" S: <notification
S: xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
S: <data>
S: <notification>
S: <subscriptionID>123456</subscriptionID> S: <subscriptionID>123456</subscriptionID>
S: <eventClass><configuration/><audit/></eventClass> S: <eventClass><configuration/><audit/></eventClass>
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: <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/>
skipping to change at page 27, line 11 skipping to change at page 28, line 7
S: <interface> S: <interface>
S: <name>Ethernet0/0</name> S: <name>Ethernet0/0</name>
S: <mtu>1500</mtu> S: <mtu>1500</mtu>
S: </interface> S: </interface>
S: </top> S: </top>
S: </config> S: </config>
S: </edit-config> S: </edit-config>
S: </operation> S: </operation>
S: </data> S: </data>
S: </notification> S: </notification>
S: </data>
S: </rpc-one-way>
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 Event Classes
skipping to change at page 32, line 5 skipping to change at page 33, line 5
/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. Security Considerations 7. Additional Capabilities
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.
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 initiates a session using a recognized
application protocol (SSH, Beep, SOAP, etc). In order to "activate"
this reverse behaviour 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.
2) Client and server are authenticated according to the underlying
application protocol (e.g. SSH, BEEP)
3) 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.3.1.1 New Data Model
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:nsub="urn:ietf:params:xml:ns:netconf:subscription:1.0"
targetNamespace=
"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:event: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
namespace="urn:ietf:params:xml:ns:netconf:subscription:1.0"
schemaLocation="urn:ietf:params:xml:ns:netconf:subscription:1.0"/>
<xs:element name="callHomeSubscription">
<xs:annotation>
<xs:appinfo>
<nm:minAccess><read/></nm:minAccess>
<nm:maxAccess><read/></nm:maxAccess>
</xs:appinfo>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="subscriber" type="xs:string">
<xs:annotation>
<xs:documentation>
This needs to be replaced with a more
prescriptive data type
</xs:documentation>
</xs:annotation>
</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">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Dormant"/>
<xs:enumeration value="Active"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
7.1.3.1.2 Modifications to Existing Operations
7.1.3.1.2.1 <create-subscription>
This capability adds a new attribute to the <create-subscription>
command. This attribute is
callHome:
An optional parameter that, when present, indicates whether this will
be a call-home Notification subscription. If not present, this will
be a normal subscription.
7.1.3.1.3 Interactions with Other Capabilities
It is only when these subscriptions move from the dormant state to
the active state that they have sessions associated with them. It is
only at this point that they show up in the active subscription list.
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
8. IANA Considerations 9. IANA Considerations
Event Classes will likely be an IANA-managed resource. The initial Event Classes will likely be an IANA-managed resource. The initial
set of values is defined in this specification. set of values is defined in this specification.
9. Acknowledgements 10. Acknowledgements
Thanks to Gilbert Gagnon and Greg Wilbur for providing their input Thanks to Gilbert Gagnon and Greg Wilbur for providing their input
into the early work on this document. In addition, the editors would into the early work on this document. In addition, the editors would
like to acknowledge input at the Vancouver editing session from the like to acknowledge input at the Vancouver editing session from the
following people: Orly Nicklass, James Bakstrieve, Yoshifumi following people: Orly Nicklass, James Bakstrieve, Yoshifumi
Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, Dave Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, Dave
Partain, Ray Atarashi and Dave Perkins. Partain, Ray Atarashi and Dave Perkins.
10. References 11. References
[NETCONF] Enns, R., "NETCONF Configuration Protocol", [NETCONF] Enns, R., "NETCONF Configuration Protocol",
ID draft-ietf-netconf-prot-06, April 2005. 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-05, March 2005. ID draft-ietf-netconf-beep-10, March 2006.
[NETCONF Datamodel] [NETCONF Datamodel]
Chisholm, S. and S. Adwankar, "Framework for NETCONF Chisholm, S. and S. Adwankar, "Framework for NETCONF
Content", ID draft-chisholm-netconf-model-04.txt, Content", ID draft-chisholm-netconf-model-05.txt,
October 2005. April 2006.
[NETCONF SOAP] [NETCONF SOAP]
Goddard, T., "Using the Network Configuration Protocol Goddard, T., "Using the Network Configuration Protocol
(NETCONF) Over the Simple Object Access Protocol (SOAP)", (NETCONF) Over the Simple Object Access Protocol (SOAP)",
ID draft-ietf-netconf-soap-05, April 2005. ID draft-ietf-netconf-soap-08, March 2006.
[NETCONF SSH] [NETCONF SSH]
Wasserman, M. and T. Goddard, "Using the NETCONF Wasserman, M. and T. Goddard, "Using the NETCONF
Configuration Protocol over Secure Shell (SSH)", Configuration Protocol over Secure Shell (SSH)",
ID draft-ietf-netconf-ssh-04.txt, April 2005. ID draft-ietf-netconf-ssh-06.txt, March 2006.
[URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396, Resource Identifiers (URI): Generic Syntax", RFC 2396,
August 1998. August 1998.
[XML] World Wide Web Consortium, "Extensible Markup Language [XML] World Wide Web Consortium, "Extensible Markup Language
(XML) 1.0", W3C XML, February 1998, (XML) 1.0", W3C XML, February 1998,
<http://www.w3.org/TR/1998/REC-xml-19980210>. <http://www.w3.org/TR/1998/REC-xml-19980210>.
[refs.RFC2026] [refs.RFC2026]
skipping to change at page 36, line 5 skipping to change at page 41, line 5
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. Potential Event Content Appendix A. Design Alternatives
This non-normative appendix explores possible content of event A.1 Suspend And Resume
notifications. It provides field descriptions and indicates their
applicability for the various event classes. Fields specific to
configuration events (configuration event class) are provided in
Appendix B.
A.1 Event Identifier 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.
A unique event identifier provided for event correlation purposes. The suspend and resume commands would allows a NETCONF client to
This field is used by management applications to identify events suspend event notification forwarding without removing the existing
which are generated for a single event occurrence via different subscription information. It could be used for both subscriptions
mechanisms (e.g. syslog, NETCONF). Ie, this event identifier could based on persistent and non-persistent subscription information.
be included as content in a syslog or SNMP message to indicate that Operations <suspend-subscription> and ><resume-subscription> are
all the messages were generated from the same source event. Event Id proposed for this purpose.
values may be re-used across re-boots.
Applicable event classes: All 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 Resource Instance A.2 Lifecycle
This field identifies the element/entity/object for which the event Configuration information associated with the event subscription
is applicable. (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).
Applicable event classes: All Appendix B. Event Notifications and Syslog
A.3 Event Time 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.
This field represents the time at which the action causing the The second part of the appendix describes an optional capability to
generation of the event has taken place. Event time field is embed an entire syslog message (hereafter referred to as syslog
composed of two parts: event generation time and event sysUpTime. message(s) to avoid confusion with the message field in syslog)
within a NETCONF event notification.
Event generation time follows the syslog TIMESTAMP format defined in B.1 Leveraging Syslog Field Definitions
draft-ietf-syslog-protocol-14.txt (derived from RFC3339 but with
additional restrictions). Event sysUpTime is of XML type integer
(0..4294967295) and it follows the same definition as sysUpTime
(TimeTicks) defined in RFC3418 - "The time (in hundredths of a
second) since the network management portion of the system was last
re-initialized).
Applicable event classes: All This section provides a semantic mapping between NETCONF event fields
and syslog message fields.
A.4 Perceived Severity -------------------------------------------------------------------
| PRI | HEADER | MESSAGE |
-------------------------------------------------------------------
| FACILITY | SEVERITY | TIMESTAMP | HOSTNAME | TAG CONTENT |
-------------------------------------------------------------------
Figure 2 - syslog message (RFC3164)
The severity of the alarm as determined by the alarm detection point -------------------------------------------------------------------
using the information it has available [RFC3877]. The values are | HEADER | STRUCTURED DATA | MESSAGE |
cleared, indeterminate, critical, major, minor and warning. -------------------------------------------------------------------
Figure 3 - syslog message (draft-ietf-syslog-protocol-14.txt)
Applicable event classes: fault HEADER (Version, Facility, Severity, Truncate, Flag, TimeStamp,
HostName, AppName, ProcId, MsgId)
A.5 Probable Cause STRUCTURED DATA (Zero or more Structured Data Elements - SDEs)
This field provides further information describing the cause of the MESSAGE ( Text message )
alarm . Allowed values for this field are the same as those listed
in RFC3877 and are derived from ITU X.733 and ITU M.3100.
Note that this concept is being evolved to be less linear, within the B.1.1 Field Mapping
ITU-T, in X.733.1, a protocol-neutral version of X.733. It may make
sense to consider alignment with this update on the concept of
probable cause, instead of the one in RFC3877 and X.733.
Applicable event classes: fault ------------------------------------------------------
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
------------------------------------------------------
A.6 Specific Problem Figure 4 - syslog to NETCONF Event field mapping
This parameter is optional. When present, it identifies further Notes:
refinements to the Probable cause of the alarm. This definition
follows ITU X.733
Applicable event classes: fault VERSION: Schema version is found in XML Schema namespace. However,
no correspondence to syslog.
A.7 Trend Indication FACILITY: No well defined semantics for this field. Therefore not
used at this time.
This parameter indicates the trend of the alarm against the managed TRUNCATE: Not applicable. NETCONF events must be complete XML
resource Allowed values for this field are as specified in RFC3877 documents therefore cannot be truncated.
and follow the ITU X.733 value definitions
Applicable event classes: fault TIME: TIMESTAMP in syslog ID is derived from RFC3339 but with
additional restrictions
A.8 Additional Alarm Text PROC-ID: No equivalent field
This parameter is provided to allow implementation to include a CONTENT: This is a free form text field with not defined semantics.
textual description of the alarm The contents of this field may be included in the AdditionalText
field.
Applicable event classes: fault B.1.2 Severity Mapping
A.9 Threshold Identifier The severity value mappings stated in (draft-ietf-syslog-protocol-14)
are used:
This field holds the identifier of the monitored variable for which ITU Perceived Severity syslog SEVERITY
the threshold was set. This is analogous to the alarmVariable Critical Alert
OBJECT-TYPE in RFC2819. Major Critical
Minor Error
Warning Warning
Indeterminate Notice
Cleared Notice
Applicable event classes: fault (useful for threshold crossing Figure 5. ITU Perceived Severity to syslog SEVERITY mapping.
alarms)
A.10 Threshold Type B.2 Syslog within NETCONF Events
This parameter is used to indicate the direction of the threshold B.2.1 Motivation
crossing: rising, falling, or clear.
Rising threshold type: This indicates that the value of a monitored The syslog protocol (RFC3164) is widely used by equipment vendors as
variable has crossed the set threshold in the upwards direction. a means to deliver event messages. Due to the widespread use of
Only sent to indicate a problem 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.
Falling threshold type: This indicates that the value of a monitored The information provided in this appendix describes a mechanism to
variable has crossed the set threshold in the downwards direction. leverage syslog messages for the purpose of complementing the
Only sent to indicate a problem. 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).
Clear threshold type: This indicates that the value of the monitored Covered herein is the syslog protocol as defined in RFC3164 and
variable for which a threshold alarm had been previously issued as a draft-ietf-syslog-protocol-14.txt.
result of crossing the set value either in the upwards or downwards
direction has been restored to a value within an acceptable range
(i.e. does not exceed the set threshold). Note that this differs
from RFC2819.
Applicable event classes: fault (useful in the case threshold B.2.2 Embedding syslog messages in a NETCONF Event
crossing alarms)
A.11 Observed Value 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.
The value of the monitored parameter (Threshold Identifier) for the ______________________________________________________
last sampling period. This parameter follows the alarmValue | NETCONF Event Header | Data |
definition in RFC2819. This field is in two parts - the value and |________________________ |___________________________|
the units of measure. | | Event Info |
|_________________________|___________________________|
|
v
____________________________
| Event Fields | SyslogInfo |
|___________________________|
Applicable event classes: fault (useful in the case threshold Figure 1 - Embedding syslog in a NETCONF Event Notifications
crossing alarms)
A.12 State Change Information B.2.3 Supported Forwarding Options
This parameter holds the name and values of the state attributes Three event forwarding options may be supported by the NETCONF
whose values have changed and are being reported. server: a) XML only (mandatory if NETCONF events capability is
supported) b) XML and syslog (Optional) c) syslog only (optional)
This is a parameter composed of three fields: Attribute Name, Old Note to the reader: Option "a" above refers to event notification
Value, and New Value. The definitions given in RFC4268 for state messages defined for use over the NETCONF protocol. While their use
attributes and values are being followed. 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.
Applicable event classes: state B.2.3.1 XML and Syslog option - Forwarding Behaviour
Appendix B. Configuration Event Class Notifications 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 This non-normative appendix provides a detailed description of a
configuration change event notification definition in support of the configuration change event notification definition in support of the
configuration operations, particularly those defined by the NETCONF configuration operations, particularly those defined by the NETCONF
protocol. protocol.
B.1 Types of Configuration Events C.1 Types of Configuration Events
Configuration event notifications include: Configuration event notifications include:
o All-triggered Configuration Events o All-triggered Configuration Events
o NETCONF-triggered Configuration Events o NETCONF-triggered Configuration Events
All-triggered Configuration events report on changes from the All-triggered Configuration events report on changes from the
perspective of the managed resource, rather than the commands which perspective of the managed resource, rather than the commands which
created the configuration change. They are reported regardless of created the configuration change. They are reported regardless of
skipping to change at page 40, line 23 skipping to change at page 48, line 23
* This is a data store level event generated following the * This is a data store level event generated following the
successful locking of a configuration data store. successful locking of a configuration data store.
o unlock-config event o unlock-config event
* This is a data store level event generated following the * This is a data store level event generated following the
successful release of a lock previously held on a configuration successful release of a lock previously held on a configuration
data store. data store.
B.2 Config Event Notification Structure C.2 Config Event Notification Structure
The table below lists the EventInfo parameters for a config event The table below lists the EventInfo parameters for a config event
notification. notification.
Nomenclature: Nomenclature:
O - This is marked optional field because it is implementation/ O - This is marked optional field because it is implementation/
notification category dependent. In some cases this may be user notification category dependent. In some cases this may be user
configurable. configurable.
skipping to change at page 42, line 5 skipping to change at page 50, line 5
----------------------------------------------------- -----------------------------------------------------
OldConfig O OldConfig O
----------------------------------------------------- -----------------------------------------------------
EventTime M EventTime M
----------------------------------------------------- -----------------------------------------------------
EventGenerationTime EventGenerationTime
----------------------------------------------------- -----------------------------------------------------
EventSysUpTime EventSysUpTime
----------------------------------------------------- -----------------------------------------------------
B.3 Configuration Event Content C.3 Configuration Event Content
The applicability of these fields to other event classes is for The applicability of these fields to other event classes is for
further study. further study.
B.3.1 Target Datastore C.3.1 Target Datastore
Target datastore refers to the data store (startup, candidate, Target datastore refers to the data store (startup, candidate,
running) which was modified by the management operation. running) which was modified by the management operation.
B.3.2 User Info C.3.2 User Info
This is used to convey information describing who originated the This is used to convey information describing who originated the
configuration event and the means for submitting the request. The configuration event and the means for submitting the request. The
user info field contains the following information: user info field contains the following information:
user Name: User id which was authorized to execute the associated user Name: User id which was authorized to execute the associated
management operation causing the generation of this event. management operation causing the generation of this event.
source Indicator: Indicates the method employed to initiate the source Indicator: Indicates the method employed to initiate the
management operation telnet, NETCONF, console, etc. management operation telnet, NETCONF, console, etc.
transaction Id: If available, this field contains a unique transaction Id: If available, this field contains a unique
identifier for the associated management operation. This is identifier for the associated management operation. This is
implementation dependent and may require additional information to implementation dependent and may require additional information to
be communicated between server and client. A possible option is be communicated between server and client. A possible option is
to make use of the message-id in the NETCONF rpc header to make use of the message-id in the NETCONF rpc header
B.3.3 Data Source C.3.3 Data Source
The data source is used, for example, in the copy configuration The data source is used, for example, in the copy configuration
command to indicated the source of information used in the copy command to indicated the source of information used in the copy
operation operation
Applicable Event Classes: configuration (useful for copy-config) Applicable Event Classes: configuration (useful for copy-config)
B.3.4 Operation C.3.4 Operation
Operation is used, for example, in the edit configuration command to Operation is used, for example, in the edit configuration command to
indicated the specific operation that has taken place - create, indicated the specific operation that has taken place - create,
delete, merge, replace. delete, merge, replace.
Applicable Event Classes: configuration (useful for edit-config) Applicable Event Classes: configuration (useful for edit-config)
B.3.5 Context C.3.5 Context
The configuration sub-mode under which the command was executed. The configuration sub-mode under which the command was executed.
Applicable Event Classes: configuration Applicable Event Classes: configuration
B.3.6 Entered Command C.3.6 Entered Command
The command entered and executed on the device. The command entered and executed on the device.
B.3.7 New Config C.3.7 New Config
The device's configuration following the successful execution of the The device's configuration following the successful execution of the
entered command. entered command.
Applicable Event Classes: configuration Applicable Event Classes: configuration
B.3.8 Old Config C.3.8 Old Config
The configuration prior to the execution of the entered command. The configuration prior to the execution of the entered command.
Applicable Event Classes: configuration Applicable Event Classes: configuration
B.3.9 Non-netconf commands in configuration notifications C.3.9 Non-netconf commands in configuration notifications
To support legacy implementations and for better integration with To support legacy implementations and for better integration with
other deployed solutions on the box, sending information via netconf other deployed solutions on the box, sending information via netconf
about configuration changes that were originated via other solutions, about configuration changes that were originated via other solutions,
such as command line interfaces is necessary. In order to do this, 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 the information in the message needs to be clearly tagged so that the
consumer of the information knows what to expect. In addition, the consumer of the information knows what to expect. In addition, the
creation of the subscription needs allow for the client to indicate creation of the subscription needs allow for the client to indicate
whether this non-XML formatted information is of interest whether this non-XML formatted information is of interest
skipping to change at page 43, line 47 skipping to change at page 52, line 5
in which it wants the NETCONF server to issue the event notifications in which it wants the NETCONF server to issue the event notifications
at subscription time by specifying the appropriate namespace under at subscription time by specifying the appropriate namespace under
the Filter parameter in the <create-subscription> operation. An the Filter parameter in the <create-subscription> operation. An
example is provided below: example is provided below:
<netconf:filter> <netconf:filter>
<data-format:config-format-xml <data-format:config-format-xml
xmlns="http://www.example.com/xmlnetevents"/> xmlns="http://www.example.com/xmlnetevents"/>
</netconf:filter> </netconf:filter>
B.4 Design Alternative
B.4.1 Server Session Initiation
Currently the NETCONF protocol requires session establishment to be
initiated by the NETCONF client. With the introduction of event
notifications in NETCONF as well deployments which might require the
"call-home" feature to get around firewall and/or NAT issues, the
ability for a NETCONF server to initiate sessions becomes important.
Other potential uses of this feature includes the following
deployment scenario: NE registration/auto-configuration. The device
is pre-configured with a target destination address (the management
station's address) where it needs to register and download its
configuration. When managing large numbers of devices (e.g. CPEs)
this also allows for increased scalability since the management
station does not need to maintain established sessions to all managed
devices.
This appendix proposes extensions to the event subscription session
establishment procedures and related operations to allow for server
session initiation.
Note that the security implications of this approach, compared with
more traditional, well understood models, is for further study.
The subscription information as described in the body of this
document indicates that it is transient in nature (i.e. it is not
persisted and it is only applicable through the life of the session).
This section describes additional functionality for persisting event
subscription information and allowing the NETCONF server (e.g.
network element) to initiate the event subscription session.
QUICK SUMMARY: The <create-subscription>, <cancel-subscription>,
<modify-subscription> operations would be used in same manner as
described in doc. It may use useful to allow a client and server to
re-establish an events subscription. This would result in another
capability to allow session initiation by the server.
B.4.2 Establishment
In order to establish an event subscription, a client must issue a
<create-subscription> message request. Upon a successful response
from the server (e.g. network element) the event subscription is
established. With this modified persistent version of the
subscription, the NETCONF server would maintain the subscription
information as part of its configuration.
B.4.3 Teardown
A event subscription is torn down when a) the client issues a
<cancel-subscription> message and it is successfully processed by
the server (i.e. the server issues a positive response) or b) the
NETCONF session carrying the event subscription goes down for any
reason.
If the subscription is not persistent, the user must create a new
subscription with the exact same parameters as the original session.
If instead, subscriptions were persistent, as part of the network
element's configuration, the client simply needs to re-establish the
session by specifying the subscription Id.
B.4.4 Suspend And Resume
Since the purpose of the <cancel-subscription> operation is to stop
event notification forwarding and due to its transient nature removes
all subscription configuration; a different mechanism might be needed
for shutting down the session but preserving the subscription
information thus allowing the NETCONF server to re-establish the
parameters and reproduce the subscription.
The suspend and resume commands would allows a NETCONF client to
suspend event notification forwarding without removing the existing
subscription information. Operations <suspend-subscription> and
><resume-subscription> are proposed for this purpose.
Since 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.
B.4.5 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 C. NETCONF 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.
C.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 )
C.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.
C.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 PerceivedSeverity to syslog SEVERITY mapping.
C.2 Syslog within NETCONF Events
C.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.
C.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 v
____________________________
| Event Fields | SyslogInfo |
|___________________________|
Figure 1 - Embedding syslog in a NETCONF Event Notifications
C.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.
C.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.
C.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 that type of event for which the event
notification is generated and lets the consumer of the message know
what to expect. NETCONF event notifications which only contain a
syslog message (Options b or c) must have the EventClass field set to
"information". [Editor's Note: This needs to be thought through. It
may not be the best option.] The NETCONF client parses the message
in the same manner as any other message, finds the normal fields
empty [Editor's Note: or not present?] and either proceeds to parse
the SyslogInfo field or hands the syslog message to the entity
responsible for processing syslog messages.
C.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.
C.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.
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. 123 change blocks. 
592 lines changed or deleted 647 lines changed or added

This html diff was produced by rfcdiff 1.29, available from http://www.levkowetz.com/ietf/tools/rfcdiff/