--- 1/draft-ietf-netconf-notification-09.txt 2007-10-17 22:12:08.000000000 +0200 +++ 2/draft-ietf-netconf-notification-10.txt 2007-10-17 22:12:08.000000000 +0200 @@ -1,19 +1,18 @@ - Network Working Group S. Chisholm Internet-Draft Nortel Intended status: Standards Track H. Trevino -Expires: March 13, 2008 Cisco - September 10, 2007 +Expires: April 19, 2008 Cisco + October 17, 2007 NETCONF Event Notifications - draft-ietf-netconf-notification-09.txt + draft-ietf-netconf-notification-10.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,21 +23,21 @@ 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 March 13, 2008. + This Internet-Draft will expire on April 19, 2008. Copyright Notice Copyright (C) The IETF Trust (2007). Abstract This document defines mechanisms that provide an asynchronous message notification delivery service for the NETCONF protocol. This is an optional capability built on top of the base NETCONF definition. @@ -47,22 +46,22 @@ Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 4 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Event Notifications in NETCONF . . . . . . . . . . . . . . 6 2. Notification-Related Operations . . . . . . . . . . . . . . . 7 2.1. Subscribing to Receive Event Notifications . . . . . . . . 7 2.1.1. . . . . . . . . . . . . . . . . 7 - 2.2. Sending Event Notifications . . . . . . . . . . . . . . . 9 - 2.2.1. . . . . . . . . . . . . . . . . . . . . 9 + 2.2. Sending Event Notifications . . . . . . . . . . . . . . . 10 + 2.2.1. . . . . . . . . . . . . . . . . . . . . 10 2.3. Terminating the Subscription . . . . . . . . . . . . . . . 10 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 11 3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 11 3.1.1. Capability Identifier . . . . . . . . . . . . . . . . 11 3.1.2. Capability Example . . . . . . . . . . . . . . . . . . 11 3.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 11 3.2.1. Event Stream Definition . . . . . . . . . . . . . . . 13 3.2.2. Event Stream Content Format . . . . . . . . . . . . . 13 3.2.3. Default Event Stream . . . . . . . . . . . . . . . . . 13 3.2.4. Event Stream Sources . . . . . . . . . . . . . . . . . 13 @@ -72,51 +71,58 @@ 3.3.2. Creating a Subscription with Replay . . . . . . . . . 17 3.4. Notification Management Schema . . . . . . . . . . . . . . 17 3.5. Subscriptions Data . . . . . . . . . . . . . . . . . . . . 21 3.6. Filter Mechanics . . . . . . . . . . . . . . . . . . . . . 21 3.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 21 3.7. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 21 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 24 5. Filtering Examples . . . . . . . . . . . . . . . . . . . . . . 28 5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 32 5.2. XPATH filters . . . . . . . . . . . . . . . . . . . . . . 33 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 35 - 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 - 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 37 - 9. Normative References . . . . . . . . . . . . . . . . . . . . . 38 - Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 39 - A.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 39 - A.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . . 41 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 44 - Intellectual Property and Copyright Statements . . . . . . . . . . 45 + 6. Interleave Capability . . . . . . . . . . . . . . . . . . . . 35 + 6.1. Description . . . . . . . . . . . . . . . . . . . . . . . 35 + 6.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 35 + 6.3. Capability Identifier . . . . . . . . . . . . . . . . . . 35 + 6.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 35 + 6.5. Modifications to Existing Operations . . . . . . . . . . . 35 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 36 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 + 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 38 + 10. Normative References . . . . . . . . . . . . . . . . . . . . . 39 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 40 + A.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 40 + A.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . . 42 + A.3. Version -10 . . . . . . . . . . . . . . . . . . . . . . . 44 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 45 + Intellectual Property and Copyright Statements . . . . . . . . . . 46 1. Introduction [NETCONF] can be conceptually partitioned into four layers: Layer Example - +-------------+ +----------------------------------------+ + +-------------+ +-------------------------------------------+ | Content | | Configuration data | - +-------------+ +----------------------------------------+ + +-------------+ +-------------------------------------------+ | | +-------------+ +-------------------------------------------+ | Operations | | , | +-------------+ +-------------------------------------------+ | | | +-------------+ +-----------------------------+ | | RPC | | , | | +-------------+ +-----------------------------+ | | | | - +-------------+ +------------------------------------------+ + +-------------+ +-------------------------------------------+ | Transport | | BEEP, SSH, SSL, console | | Protocol | | | - +-------------+ +------------------------------------------+ + +-------------+ +-------------------------------------------+ Figure 1 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 memo defines the capabilities and operations necessary to support this service. 1.1. Definition of Terms @@ -202,26 +208,26 @@ server replies to indicate whether the subscription request was successful and, if it was successful, begins sending the event 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 terminates 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. - The NETCONF server MUST accept and process the close-session + The NETCONF server MUST accept and process the operation, even while the notification subscription is active. The NETCONF server MAY accept and process other commands, otherwise they will be rejected and the server MUST send a 'resource-denied' error. - An example of when other commands would be processed is if a separate - capability was advertised indicating support of this functionality. + A NETCONF server advertises support of the ability to process other + commands via the interleave capability. 2. Notification-Related Operations 2.1. Subscribing to Receive Event Notifications The event notification subscription is initiated by the NETCONF client and responded to by the NETCONF server. A subscription is bound to a single stream for the lifetime of the subscription. When the event notification subscription is created, the events of interest are specified. @@ -264,24 +270,22 @@ earlier than the log can support, the replay will begin with the earliest available notification. This parameter is of type dateTime. Stop Time: An optional parameter, , used with the optional replay feature to indicate the newest notifications of interest. If stop time is not present, the notifications will continue until the subscription is terminated. Must be used - with and be later than . A stop times that is later - than the current time, will be interpreted as being the time of - the subscription creation (current time). This parameter is of - type dateTime. + with and be later than . Values of in + the future are valid. This parameter is of type dateTime. Positive Response: If the NETCONF server can satisfy the request, the server sends an element. Negative Response: An element is included within the if the request cannot be completed for any reason. Subscription requests @@ -302,26 +306,54 @@ Description: An expected element is missing. If the optional replay feature is requested but it is not supported by the NETCONF server, the following error is returned: Tag: operation-failed Error-type: protocol Severity: error - Error-info: none + Error-info: none Description: Request could not be completed because the requested operation failed for some reason not covered by any other error condition + If a is requested which is earlier then the specified + , the following error is returned: + + Tag: bad-element + + Error-type: protocol + + Severity: error + + Error-info: : stopTime + + Description: An element value is not correct; e.g., wrong type, + out of range, pattern mismatch. + + If a is requested which is later then the current + time, the following error is returned: + + Tag: bad-element + + Error-type: protocol + + Severity: error + + Error-info: : startTime + + Description: An element value is not correct; e.g., wrong type, + out of range, pattern mismatch. + 2.1.1.1. Usage Example The following demonstrates creating a simple subscription. More complex examples can be found in section 5. @@ -353,26 +385,27 @@ Also contains notification-specific tagged content, if any. With the exception of , the content of the notification is beyond the scope of this document. Response: No response. Not applicable. 2.3. Terminating the Subscription - Closing of the event notification subscription can be done by + Closing of the event notification subscription can be done by using + the operation from the subscriptions session or terminating the NETCONF session ( ) or the underlying - transport session. If a stop time is provided when the subscription - is created, the subscription will terminate after the stop time is - reached. In this case, the NETCONF session will still be an active - session. + transport session from another session. If a stop time is provided + when the subscription is created, 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 @@ -460,32 +493,32 @@ Figure 2 3.2.1. Event Stream Definition Event streams are predefined on the managed device. The configuration of event streams is outside the scope of this document. However, it is envisioned that event streams are either pre- established by the vendor (pre-configured), user configurable (e.g., part of the device's configuration) or both. Device vendors may allow event stream configuration via the NETCONF protocol (i.e., - edit-config operation). + operation). 3.2.2. Event Stream Content Format The contents of all event streams made available to a NETCONF client - (i.e., the notification sent by the NETCONF server) must be encoded + (i.e., the notification sent by the NETCONF server) MUST be encoded in XML. 3.2.3. Default Event Stream A NETCONF server implementation supporting the notification - capability must support the "NETCONF" notification event stream. + capability MUST support the "NETCONF" notification event stream. This stream contains all NETCONF XML event notifications supported by the NETCONF server. The exact string "NETCONF" is used during advertisement of stream support during the operation on and during the operation. Definition of the event notifications and their contents, beyond the inclusion of , for this event stream is outside the scope of this document. 3.2.4. Event Stream Sources @@ -501,21 +534,21 @@ NETCONF server using the operation. 3.2.5.1. Name Retrieval using operation 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 the element is mandatory, and its value is unique within the scope of a NETCONF server. An empty reply is returned if there are no available event - streams. + streams, due to user-specified filters on the operation . Additional information available about a stream include whether notification replay is available and if so, the timestamp of the earliest possible notification to replay. The following example shows retrieving the list of available event stream list using the operation. @@ -814,21 +847,21 @@ the subscription. 3.5. Subscriptions Data Subscriptions are non-persistent state information and their lifetime - is defined by their session or by the paramter. + is defined by their session or by the parameter. 3.6. Filter Mechanics When multiple filter elements are specified, they are applied collectively, so event notifications need to pass all specified filter elements in order to be sent to the subscriber. If a filter element 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, the notification will be filtered out. For example, if one were to check for 'severity=critical' in a @@ -852,21 +885,21 @@ , so the server starts by replaying logged notifications. It is possible that many rpc/rpc-reply sequences occur before the subscription is created, but this is not depicted in the figure. C S | | | capability exchange | |-------------------------->| |<------------------------->| | | - | | + | | (startTime) |-------------------------->| |<--------------------------| | | | | | | |<--------------------------| | | | | |<--------------------------| | | (replayComplete) @@ -893,22 +926,22 @@ notifications are sent and it is available to process requests. It is possible that many rpc/rpc-reply sequences occur before the subscription is created, but this is not depicted in the figure. C S | | | capability exchange | |-------------------------->| |<------------------------->| | | - | | - |-------------------------->| + | | (startTime, + |-------------------------->| stopTime) |<--------------------------| | | | | | | |<--------------------------| | | | | |<--------------------------| | | (replayComplete) |<--------------------------| @@ -924,24 +957,24 @@ | | Figure 4 4. XML Schema for Event Notifications The following [XML Schema] defines NETCONF Event Notifications. @@ -1121,21 +1154,21 @@ The above fictional notification definition could result in the - following is a sample notification list, whihc is used in the + following is a sample notification list, which is used in the examples in this section. 2007-07-08T00:01:00Z fault Ethernet0 @@ -1186,21 +1219,22 @@ and application of the logical OR operators (e.g., in an event subtree give me all event notifications which have severity=critical or severity=major or severity=minor). Nevertheless, it may be used for defining simple event notification forwarding filters as shown below. The following example illustrates how to select fault events which have severities of critical, major, or minor. The filtering criteria evaluation is as follows: - ((severity=critical) | (severity=major) | (severity=minor)) + ((fault & severity=critical) | (fault & severity=major) | (fault & + severity=minor)) fault critical @@ -1221,33 +1255,30 @@ filtering criteria evaluation is as follows: ( state | config | ( fault & ( card=Ethernet0))) - fault - - state config fault - + Ethernet0 - + 5.2. XPATH filters The following [XPATH] example illustrates how to select fault EventClass notifications that have severities of critical, major, or minor. The filtering criteria evaluation is as follows: @@ -1259,39 +1290,83 @@ xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> + The following example illustrates how to select state and config EventClasses or fault events of any severity that come from card Ethernet0. The filtering criteria evaluation is as follows: - (( state | config) & (fault & card=Ethernet0)) + ( state | config | (fault & card=Ethernet0)) -6. Security Considerations +6. Interleave Capability + +6.1. Description + + The Interleave capability indicates that the NETCONF peer supports + the ability to interleave other NETCONF operations within a + Notification subscription. This means the NETCONF server is able to + receive, process and respond to NETCONF requests on a session with an + active notification subscription. + +6.2. Dependencies + + This capability is dependant on the notification capability being + supported. + +6.3. Capability Identifier + + The :interleave capability is identified by the following capability + string: + + urn:ietf:params:netconf:capability:interleave:1.0 + +6.4. New Operations + + None. + +6.5. Modifications to Existing Operations + + When a is sent while another subscription is + active on that session, the following error will be returned: + + Tag: operation-failed + + Error-type: protocol + + Severity: error + + Error-info: : startTime + + Description: Request could not be completed because the requested + operation failed for some reason not covered by any other error + condition. + +7. Security Considerations The security considerations from the base [NETCONF] document also apply to the Notification capability. The access control framework and the choice of transport will have a major impact on the security of the solution. The elements are never sent before the transport layer and the NETCONF layer, including capabilities exchange, have been established, and the manager has been identified and authenticated. @@ -1308,63 +1383,65 @@ NETCONF streams, such as syslog and SNMP. This data may be more vulnerable (or less vulnerable) when being transported over NETCONF than when being transported using the protocol normally used for transporting it, depending on the security credentials of the two subsystems. The NETCONF server is responsible for applying access control to stream content. The contents of notifications as well as the name of event streams may contain sensitive information and care should be taken to ensure that it is viewed only by authorized users. If a user does not have - permission to view content via other NETCONF operations, it does not - have permission to access that content via Notifications. If a user - is not permitted to view one element in the content of the - notification, the notification is not sent to that user. + permission to view content via other NETCONF operations, it must not + have access that content via Notifications. If a user is not + permitted to view one element in the content of the notification, the + notification is not sent to that user. If a subscription is created with a , the NETCONF session will return to being a normal command-response NETCONF session when the replay is completed. It is the responsibility of the NETCONF client to close this session when it is no longer of use. -7. IANA Considerations +8. IANA Considerations This document registers three URIs for the NETCONF XML namespace in the IETF XML registry [RFC3688]. Following the format in RFC 3688, IANA has made the following registration. URI: urn:ietf:params:netconf:capability:notification:1.0 URI: urn:ietf:params:xml:ns:netmod:notification - URI: urn:ietf:params:xml:ns:netconf:notification + URI: urn:ietf:params:xml:ns:netconf:notification:1.0 + + URI: urn:ietf:params:netconf:capability:interleave:1.0 Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace. -8. Acknowledgements +9. Acknowledgements 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 David Perkins and the following additional people from the Montreal editing session: Balazs Lengyel, Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen, Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig, Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William Chow. We would also like to thank Li Yan for his numerous reviews. -9. Normative References +10. Normative References [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006. [RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements Levels", RFC 2119, March 1997. [RFC3688] Bradner, s., "The IETF XML Registry", RFC 3688, January 2004. @@ -1449,27 +1526,27 @@ 21. In section 3.2.5.1, clarified that "value is unique" - within the scope of a NETCONF server. 22. In section 2.1.1, clarified that stopTime cannot preceded start time. 23. In section 2.1.1, in Start Time s/indicates/indicate/ 24. In section 2.1.1, in Filter: s/This is mutually exclusive/The filter parameter is mutually exclusive/ ("this" could refer to - the behavior described in the previous sentence.) + the behaviour described in the previous sentence.) 25. In section 1.4, third bullet, replaced "syslog and SNMP are rather constrained in terms of message sizes)" with (ie, not too short) - 26. In section 1.4, made all bullets start with capital leters. + 26. In section 1.4, made all bullets start with capital letters. 27. Added definition of Filter to section 1.1 28. In section 1.1, improved the definition of subscription with "An agreement and method to receive event notifications over a NETCONF session." 29. In section 1.1, in the definition of operation, added a reference to [NETCONF]. @@ -1516,21 +1593,21 @@ 5. Modified the cardinality of eventStreams to reflect that there will always be at least one event stream. 6. Fixed description of examples to remove reference to eventEntry, which is no longer part of the actual example. 7. In examples, for consistency changed some references to reportingElement to be reportingEntity - 8. Fixed section 3.2, third pararaph to talk about filter elements + 8. Fixed section 3.2, third paragraph to talk about filter elements instead of filters. 9. Merge section 3.3.2 and section 3.3.3. Delete the first paragraph in (old) section 3.3.3 since it both duplicates and contradicts text in section 3.3.2 10. In section 3.2.5.2.1, added clarification to first paragraph that "Either subtree or XPATH filtering can be used. " 11. Removed discussion of not allowing the return of stream names @@ -1548,21 +1625,21 @@ brackets. 15. In section 2.1.1, changed "Error-info: : startTime" to use bad-element. 16. In section 2.2.1, under the parameter tag, replaced "Contains notification-specific tagged content." with "Contains notification-specific tagged content, if any. " 17. Clarified some text in section 3.2, paragraph 3 around sending - of filters from client and the fitlers later being applied to + of filters from client and the filters later being applied to the notifications. 18. Fixed target namespace in section 4. 19. Added missing lang and version information to schema in section 3.4 20. Clarified that the examples in section 5 all used the same example event list. @@ -1589,20 +1666,33 @@ 27. Added XML Schema definition for examples in section 5 and showed the event list with wrappers. 28. Added notification 29. Removed support of startTime and stopTime in the future. 30. Replaced replayLogStartTime with replayLogCreationTime and replayLogAgedTime. +A.3. Version -10 + + 1. Changed the description of stopTime to allow stopTimes in the + future. + + 2. Added interleave capability + + 3. Clarified create-subscription error messages. + + 4. Corrected targetNamespace in Netconf Notification XSD + + 5. Fixed typos and made minor edits. + Authors' Addresses Sharon Chisholm Nortel 3500 Carling Ave Nepean, Ontario K2H 8E9 Canada Email: schishol@nortel.com