--- 1/draft-ietf-netconf-notification-05.txt 2007-02-21 17:12:31.000000000 +0100 +++ 2/draft-ietf-netconf-notification-06.txt 2007-02-21 17:12:31.000000000 +0100 @@ -1,19 +1,19 @@ Network Working Group S. Chisholm Internet-Draft Nortel Intended status: Standards Track H. Trevino -Expires: June 22, 2007 Cisco - December 19, 2006 +Expires: August 24, 2007 Cisco + February 20, 2007 NETCONF Event Notifications - draft-ietf-netconf-notification-05.txt + draft-ietf-netconf-notification-06.txt Status of this Memo By submitting this Internet-Draft, each author represents that any 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 aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that @@ -24,25 +24,25 @@ and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. - This Internet-Draft will expire on June 22, 2007. + This Internet-Draft will expire on August 24, 2007. Copyright Notice - Copyright (C) The Internet Society (2006). + Copyright (C) The IETF Trust (2007). Abstract This document defines mechanisms which provide an asynchronous message notification delivery service for the NETCONF protocol. This is an optional capability built on top of the base NETCONF definition. This document defines the capabilities and operations necessary to support this service. Table of Contents @@ -61,39 +61,39 @@ 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 10 3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 10 3.1.1. Capability Identifier . . . . . . . . . . . . . . . . 10 3.1.2. Capability Example . . . . . . . . . . . . . . . . . . 10 3.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 10 3.2.1. Event Stream Definition . . . . . . . . . . . . . . . 11 3.2.2. Event Stream Content Format . . . . . . . . . . . . . 11 3.2.3. Default Event Stream . . . . . . . . . . . . . . . . . 11 3.2.4. Event Stream Sources . . . . . . . . . . . . . . . . . 12 3.2.5. Event Stream Discovery . . . . . . . . . . . . . . . . 12 - 3.2.6. Event Stream Subscription . . . . . . . . . . . . . . 15 - 3.3. Subscriptions not Configuration Data . . . . . . . . . . . 15 - 3.4. Filter Dependencies . . . . . . . . . . . . . . . . . . . 15 - 3.4.1. Named Profiles . . . . . . . . . . . . . . . . . . . . 15 - 3.4.2. Filtering . . . . . . . . . . . . . . . . . . . . . . 16 - 3.5. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 16 - 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 17 - 5. Filtering examples . . . . . . . . . . . . . . . . . . . . . . 20 - 5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 20 - 5.2. XPATH filters . . . . . . . . . . . . . . . . . . . . . . 21 - 6. Notification Replay . . . . . . . . . . . . . . . . . . . . . 23 - 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 23 - 6.2. Creating a Subscription with Replay . . . . . . . . . . . 23 - 6.3. Replay Complete Notification . . . . . . . . . . . . . . . 24 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26 - 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27 - 9. Normative References . . . . . . . . . . . . . . . . . . . . . 28 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 - Intellectual Property and Copyright Statements . . . . . . . . . . 30 + 3.3. Notification Management Schema . . . . . . . . . . . . . . 13 + 3.4. Subscriptions not Configuration Data . . . . . . . . . . . 16 + 3.5. Filter Dependencies . . . . . . . . . . . . . . . . . . . 17 + 3.5.1. Named Profiles . . . . . . . . . . . . . . . . . . . . 17 + 3.5.2. Filtering . . . . . . . . . . . . . . . . . . . . . . 17 + 3.6. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 17 + 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 19 + 5. Filtering examples . . . . . . . . . . . . . . . . . . . . . . 22 + 5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 22 + 5.2. XPATH filters . . . . . . . . . . . . . . . . . . . . . . 25 + 6. Notification Replay . . . . . . . . . . . . . . . . . . . . . 27 + 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 6.2. Creating a Subscription with Replay . . . . . . . . . . . 27 + 6.3. Replay Complete Notification . . . . . . . . . . . . . . . 28 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 30 + 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 31 + 9. Normative References . . . . . . . . . . . . . . . . . . . . . 32 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33 + Intellectual Property and Copyright Statements . . . . . . . . . . 34 1. Introduction [NETCONF] can be conceptually partitioned into four layers: Layer Example +-------------+ +----------------------------------------+ | Content | | Configuration data | +-------------+ +----------------------------------------+ | | @@ -155,23 +155,23 @@ notifications to the NETCONF client as the events occur within the system. These event notifications will continue to be sent until either the NETCONF session is terminated or the subscription to terminate for some other reason. The event notification subscription allows a number of options to enable the NETCONF client to specify which events are of interest. These are specified when the subscription is created. An NETCONF server is not required to process RPC requests on the session associated with the subscription until the notification - subscription is done. A capability may be advertised to announce - that a server is able to process RPCs while a notification stream is - active on a session. + subscription is done and may silently discard these requests. A + capability may be advertised to announce that a server is able to + process RPCs while a notification stream is active on a session. 1.3. Motivation The motivation for this work is to enable the sending of asynchronous messages that are consistent with the data model (content) and security model used within a NETCONF implementation. 1.4. Requirements The following requirements have been addressed by the solution: @@ -274,38 +274,43 @@ Once the subscription has been set up, the NETCONF server sends the event notifications asynchronously along the connection. 2.2.1. Description: An event notification is sent to the initiator of a command asynchronously when an event of interest (i.e. meeting the specified filtering criteria) to them has - occurred. An event notification is a complete XML document. Note - that is not an RPC method but rather the top level - element identifying the one way message as a notification. + occurred. An event notification is a complete and well-formed XML + document. Note that is not an RPC method but + rather the top level element identifying the one way message as a + notification. Parameters: Data: Contains notification-specific tagged content. Response: No response. Not applicable. 2.3. Terminating the Subscription Closing of the event notification subscription can be done by - terminating the NETCONF session ( ). + terminating the NETCONF session ( ) or the underlying + transport session. If a stop time is provided when the subscription + is created, then the subscription will terminate after the stop time + is reached. In this case, the Netconf session will still be an + active session. 3. Supporting Concepts 3.1. Capabilities Exchange The ability to process and send event notifications is advertised during the capability exchange between the NETCONF client and server. 3.1.1. Capability Identifier @@ -409,25 +414,21 @@ The list of available event streams is retrieved by requesting the subtree via a operation. Available event streams for the requesting session are returned in the reply containing the and elements, where element is mandatory and its value is unique. The returned list must only include the names of those event streams for which the NETCONF session has sufficient privileges. The NETCONF session privileges are determined via access control mechanisms which are beyond the scope of this document. An empty reply is returned if there are no available event - streams. - - The list of all event streams configured on a device may be retrieved - over a NETCONF session with sufficient privileges (e.g. - administrator). The information is retrieved by requesting the + streams. The information is retrieved by requesting the subtree via a operation. Example: Retrieving available event stream list using operation: @@ -456,54 +457,61 @@ syslog-critical Critical and higher severity true -3.2.5.2. Stream Retrieval Schema +3.2.5.2. Event Stream Subscription + + A NETCONF client may request from the NETCONF server the list of + available event streams to this session and then issue a request with the desired event stream name. Omitting + the event stream name from the request results + in subscription to the default NETCONF event stream. + +3.2.5.2.1. Filtering Event Stream Contents + + The set of event notifications delivered in an event stream may be + further refined by applying a user-specified filter at subscription + creation time ( ). This is a transient filter + associated with the event notification subscription and does not + modify the event stream configuration. + +3.3. Notification Management Schema - Schema for event streams - - - - - NetconfNotificationSchema - - - 2006-09-06T09:30:47-05:00 - - IETF - - A schema that can be used to learn about current - event streams. - - - + event streams and to manage named profiles. + + schemaLocation="urn:ietf:params:xml:ns:netconf:base:1.0"/> + The list of event streams supported by the system. When a query is issued, the returned set of streams is determined based on user privileges @@ -511,88 +519,153 @@ Stream name and description - + - -3.2.6. Event Stream Subscription + + + + A named profile, which is a saved set of parameters + associated that may be associated with zero or more + active subscriptions. - A NETCONF client may request from the NETCONF server the list of - available event streams to this session and then issue a request with the desired event stream name. Omitting - the event stream name from the request results - in subscription to the default NETCONF event stream. + This object can be created, read, deleted and its + individual components can be modified. + + + + -3.2.6.1. Filtering Event Stream Contents + + + + The name associated with the profile. - The set of event notifications delivered in an event stream may be - further refined by applying a user-specified filter at subscription - creation time ( ). This is a transient filter - associated with the event notification subscription and does not - modify the event stream configuration. + This object is readable and modifiable. + + + -3.3. Subscriptions not Configuration Data + + + + The event stream associated with this named + profile. - While it is possible to retrieve information about subscriptions via - a get operation, subscriptions are not stored configuration. They - are non-persistent state information. In this respect, they are + This object is readable and modifiable. + + + + + + + + The filters associated with this named + profile. + + This object is readable and modifiable. + + + + + + + + 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. + + This object is read-only. + + + + + + + + + + + + + + + + +3.4. Subscriptions not Configuration Data + + While it may be possible to retrieve information about subscriptions + via a get operation, subscriptions are not stored configuration. + They are non-persistent state information. In this respect, they are comparable to NETCONF sessions. Named profiles, if used, are considered configuration data. -3.4. Filter Dependencies +3.5. Filter Dependencies Note that when multiple filters are specified, they are applied collectively, so event notifications need to pass all specified filters in order to be sent to the subscriber. If a filter is specified to look for data of a 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 'severity=critical' in a configuration event notification where this field was not supported, then the notification would be filtered out. Note that the order that filters are applied does not matter since the resulting set of notifications is the intersection of the set of notifications that pass each filtering criteria. -3.4.1. Named Profiles +3.5.1. Named Profiles A named profile is a filter that is created ahead of time and applied at the time an event notification subscription is created . Note that changes to the profile after the subscription has been created will have no effect on the subscription. Since named profiles exist outside of the subscription, they persist after the subscription has been torn down. -3.4.2. Filtering +3.5.2. Filtering Just-in-time filtering is explicitly stated when the event notification subscription is created. This is specified via the 'filter' parameter. Filters only exist as parameters to the subscription. -3.5. Message Flow - +3.6. Message Flow The following figure depicts message flow between a NETCONF client (C) and NETCONF server (S) in order create a subscription and begin the flow of notifications. C S | | | capability exchange | |-------------------------->| |<------------------------->| | | @@ -609,20 +682,22 @@ | | | | | | | | |<--------------------------| | | | | 4. XML Schema for Event Notifications + The following [XML Schema] defines Netconf Event Notifications. + @@ -754,29 +829,63 @@ XML subtree filtering is not well suited for creating elaborate filter definitions given that it only supports equality comparisons and logical OR operations (e.g. in an event subtree give me all event notifications which have severity=critical or severity=major or severity=minor). Nevertheless, it may be used for defining simple event notification forwarding filters as shown below. In order to illustrate the use of filter expressions it is necessary to assume some of the event notification content. The examples herein assume that the event notification schema definition has an - element identifying the event category (e.g. fault, - state, config, etc.) and events have a element. + element at the top level that contains one or more child + elements consisting of the event class (e.g. fault, + state, config, etc.) reporting entity and either severity or + operational state. + + Sample event list + + + + fault + + Ethernet0 + + major + + + fault + + Ethernet2 + + critical + + + fault + + ATM1 + + minor + + + state + + Ethernet0 + + enabled + + The following example illustrates selecting events which have severities of critical, major, or minor (presumably fault events). The filtering criteria evaluation is as follows: ((severity=critical) | (severity=major) | (severity=minor)) - critical major @@ -781,90 +890,96 @@ major minor - The following example illustrates selecting fault, state, config - EventClasses or events which are related to card Ethernet0. The + The following example illustrates selecting state or config + EventClasses or fault events that are related to card Ethernet0. The filtering criteria evaluation is as follows: - (fault | state | config | card=Ethernet0) - + ( state | config | fault & card=Ethernet0) + xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> - fault - - - state - - - config - - + + + fault + + + state + + + config + + + fault + Ethernet0 + + + 5.2. XPATH filters - The following example illustrates selecting fault EventClass - notifications that have severities of critical, major, or minor. In - this example, neb represents the namespace for the event definitions - schema. The filtering criteria evaluation is as follows: + The following [XPATH] example illustrates selecting fault EventClass + notifications that have severities of critical, major, or minor. The + filtering criteria evaluation is as follows: ((fault) & ((severity=critical) | (severity=major) | (severity = minor))) + xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> + select="event/eventClasses/fault' and + (event[severity='critical'] or + event[severity='major'] or + event[severity='minor')))"/> - The following example illustrates selecting fault, state and config - EventClasses which have severities of critical, major, or minor and - come from card Ethernet0. The filtering criteria evaluation is as - follows: + The following example illustrates selecting state and config + EventClasses or fault events that have severities of critical, major, + or minor or come from card Ethernet0. The filtering criteria + evaluation is as follows: - ((fault | state | config) & ((fault & severity=critical) | (fault & - severity=major) | (fault & severity = minor) | (card=Ethernet0))) + (( state | config) & ((fault & severity=critical) | (fault & + severity=major) | (fault & severity = minor) | (fault & + card=Ethernet0))) + xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> + select="((event[eventClasses/fault] or + event[eventClasses/state] or + event[eventClasses/config]) and + ((event[eventClasses/fault] and + event[severity='critical']) or + (event[eventClasses/fault] and + event[severity='major']) or + (event[eventClasses/fault] and + event[severity='minor']) or + event[eventClasses/fault/reportingElement/card='Ethernet0']))"/> 6. Notification Replay 6.1. Overview Replay is the ability to create an event subscription that will resend recently sent notifications. These notifications are sent the same way as normal notifications. @@ -906,54 +1021,63 @@ matched. 'stopTime' specifies the latest date and time of interest for event notifications being replayed. If it is not present, then notifications will continue to be sent until the subscription is terminated. Note that while a notification has three potential times associated it - the time it was generated, the time it was logged and the time it was sent out by the NETCONF server - the startTime and stopTime parameters are related to generation time. + In the event of an error with severity of warning, the subscription + will still be created. + Negative Response: An element is included in the if the startTime in replay request predates the oldest notification available to be replayed or if the stopTime is earlier then the startTime. Error-tag: start-time-too-early Error-type: protocol Error-severity: warning - Error-info: none + Error-info: : Timestamp of earliest event + available for replay Error-message: Start time predates oldest available notification to be replayed Error-tag: start-stop-time-mismatch Error-type: protocol - Error-severity: warning + Error-severity: error Error-info: none Error-message: stopTime predates startTime. 6.3. Replay Complete Notification The following notification is the last notification sent over a replay subscription. It indicates that replay is complete. This notification will only be sent if a 'stopTime' was specified when the - replay subscription was created. + replay subscription was created. After this notification is received + the subscription is terminated and the session becomes a normal + Netconf session. + + The replayCompleteNotifcation can not be filtered out. It will + always be sent on a relay subscription that specified a stop time. @@ -1015,21 +1139,21 @@ Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing their input into the early work on this document. In addition, the editors would like to acknowledge input at the Vancouver editing session from the following people: Orly Nicklass, James Balestriere, Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, Dave Partain, Ray Atarashi and Dave Perkins and the following additional people from the Montreal editing session: Balazs Lengyel, Phil Shafer, Rob Ennes, Andy Bierman, Dan Romascanu, Bert Wijnen, Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig, Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William - Chow + Chow. 9. Normative References [NETCONF] Enns, R., "NETCONF Configuration Protocol", ID draft-ietf-netconf-prot-12, February 2006. [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", RFC 2026, BCP 9, October 1996. [RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements @@ -1039,20 +1163,25 @@ RFC 2223, October 1997. [XML] World Wide Web Consortium, "Extensible Markup Language (XML) 1.0", W3C XML, February 1998, . [XML Schema] Fallside, D. and P. Walmsley, "XML Schema Part 0: Primer Second Edition", W3C XML Schema, October 2004. + [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) + Version 1.0", + W3C http://www.w3.org/TR/1999/REC-xpath-19991116, + November 1999. + Authors' Addresses Sharon Chisholm Nortel 3500 Carling Ave Nepean, Ontario K2H 8E9 Canada Email: schishol@nortel.com @@ -1060,32 +1189,32 @@ Cisco Suite 400 9155 E. Nichols Ave Englewood, CO 80112 USA Email: htrevino@cisco.com Full Copyright Statement - Copyright (C) The Internet Society (2006). + Copyright (C) The IETF Trust (2007). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, - INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE - INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in 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 made any independent effort to identify any such rights. Information