--- 1/draft-ietf-netconf-notification-03.txt 2006-10-24 01:12:29.000000000 +0200 +++ 2/draft-ietf-netconf-notification-04.txt 2006-10-24 01:12:29.000000000 +0200 @@ -1,19 +1,19 @@ Network Working Group S. Chisholm Internet-Draft Nortel -Expires: March 18, 2007 H. Trevino - Cisco - September 14, 2006 +Intended status: Standards Track H. Trevino +Expires: April 25, 2007 Cisco + October 22, 2006 NETCONF Event Notifications - draft-ietf-netconf-notification-03.txt + draft-ietf-netconf-notification-04.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,136 +24,141 @@ 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 18, 2007. + This Internet-Draft will expire on April 25, 2007. Copyright Notice Copyright (C) The Internet Society (2006). Abstract - This memo defines a framework for sending asynchronous messages, or - event notifications in NETCONF. It defines both the operations - necessary to support this concept, and also discusses implications - for the mapping to transport protocols. + 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, operations, + transport mappings, and data models necessary to support this + service. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1.1 Definition of Terms . . . . . . . . . . . . . . . . . . . 4 - 1.2 Event Notifications in NETCONF . . . . . . . . . . . . . . 5 - 1.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 - 1.4 Requirements . . . . . . . . . . . . . . . . . . . . . . . 5 + 1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 4 + 1.2. Event Notifications in NETCONF . . . . . . . . . . . . . . 5 + 1.3. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 + 1.4. Requirements . . . . . . . . . . . . . . . . . . . . . . . 5 2. Notification-Related Operations . . . . . . . . . . . . . . . 7 - 2.1 Subscribing to receive Event Notifications . . . . . . . . 7 - 2.1.1 create-subscription . . . . . . . . . . . . . . . . . 7 - 2.2 Sending Event Notifications . . . . . . . . . . . . . . . 8 - 2.2.1 Event Notification . . . . . . . . . . . . . . . . . . 8 - 2.3 Terminating the Subscription . . . . . . . . . . . . . . . 9 + 2.1. Subscribing to receive Event Notifications . . . . . . . . 7 + 2.1.1. . . . . . . . . . . . . . . . . 7 + 2.1.2. Filter Dependencies . . . . . . . . . . . . . . . . . 8 + 2.2. Sending Event Notifications . . . . . . . . . . . . . . . 8 + 2.2.1. . . . . . . . . . . . . . . . . . . . . 8 + 2.3. Terminating the Subscription . . . . . . . . . . . . . . . 9 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 10 - 3.1 Capabilities Exchange . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . 17 - 3.3 Subscriptions and Datastores . . . . . . . . . . . . . . . 17 - 3.4 Querying Subscription Properties . . . . . . . . . . . . . 18 - 3.5 One-way Notification Messages . . . . . . . . . . . . . . 22 - 3.6 Filter Dependencies . . . . . . . . . . . . . . . . . . . 22 - 3.6.1 Named Profiles . . . . . . . . . . . . . . . . . . . . 23 - 3.6.2 Filtering . . . . . . . . . . . . . . . . . . . . . . 23 - 3.7 Message Flow . . . . . . . . . . . . . . . . . . . . . . . 23 - 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 25 - 5. Mapping to Transport Protocols . . . . . . . . . . . . . . . . 27 - 5.1 SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 - 5.2 BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 - 5.2.1 One-way Notification Messages in Beep . . . . . . . . 28 - 5.3 SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 - 5.3.1 A NETCONF over Soap over HTTP Example . . . . . . . . 29 - 6. Filtering examples . . . . . . . . . . . . . . . . . . . . . . 32 - 6.1 Subtree Filtering . . . . . . . . . . . . . . . . . . . . 32 - 6.2 XPATH filters . . . . . . . . . . . . . . . . . . . . . . 33 - 7. Notification Replay Capability . . . . . . . . . . . . . . . . 35 - 7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 35 - 7.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . 35 - 7.3 Capability Identifier . . . . . . . . . . . . . . . . . . 35 - 7.4 New Operations . . . . . . . . . . . . . . . . . . . . . . 35 - 7.5 Modifications to Existing Operations . . . . . . . . . . . 36 - 7.5.1 create-subscription . . . . . . . . . . . . . . . . . 36 - 7.5.2 Interactions with Other Capabilities . . . . . . . . . 36 - 8. Security Considerations . . . . . . . . . . . . . . . . . . . 37 - 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 38 - 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 39 - Intellectual Property and Copyright Statements . . . . . . . . 40 + 3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 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. Querying Subscription Properties . . . . . . . . . . . . . 16 + 3.5. Filter Dependencies . . . . . . . . . . . . . . . . . . . 20 + 3.5.1. Named Profiles . . . . . . . . . . . . . . . . . . . . 21 + 3.5.2. Filtering . . . . . . . . . . . . . . . . . . . . . . 21 + 3.6. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 21 + 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 23 + 5. Mapping to Transport Protocols . . . . . . . . . . . . . . . . 25 + 5.1. SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 5.2. BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 + 5.2.1. One-way Notification Messages in Beep . . . . . . . . 26 + 5.3. SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 5.3.1. A NETCONF over Soap over HTTP Example . . . . . . . . 27 + 6. Filtering examples . . . . . . . . . . . . . . . . . . . . . . 30 + 6.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 30 + 6.2. XPATH filters . . . . . . . . . . . . . . . . . . . . . . 31 + 7. Notification Replay Capability . . . . . . . . . . . . . . . . 33 + 7.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 33 + 7.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 33 + 7.3. Capability Identifier . . . . . . . . . . . . . . . . . . 33 + 7.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 34 + 7.5. Modifications to Existing Operations . . . . . . . . . . . 34 + 7.5.1. create-subscription . . . . . . . . . . . . . . . . . 34 + 7.5.2. Interactions with Other Capabilities . . . . . . . . . 34 + 7.6. Replay Complete Notification . . . . . . . . . . . . . . . 34 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 36 + 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 37 + 10. Normative References . . . . . . . . . . . . . . . . . . . . . 38 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 39 + Intellectual Property and Copyright Statements . . . . . . . . . . 40 1. Introduction - NETCONF [NETCONF-PROTO] can be conceptually partitioned into four - layers: + [NETCONF] can be conceptually partitioned into four layers: Layer Example +-------------+ +----------------------------------------+ | Content | | Configuration data | +-------------+ +----------------------------------------+ | | +-------------+ +-------------------------------------------+ | Operations | | , | +-------------+ +-------------------------------------------+ | | | +-------------+ +-----------------------------+ | | RPC | | , | | +-------------+ +-----------------------------+ | | | | +-------------+ +------------------------------------------+ | Transport | | BEEP, SSH, SSL, console | | Protocol | | | +-------------+ +------------------------------------------+ - This document defines a framework for sending asynchronous messages, - or event notifications in NETCONF. It defines both the operations - necessary to support this concept, and also discusses implications - for the mapping to transport protocols. + 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, operations, + transport mappings, and data models necessary to support this + service. Figure 1 -1.1 Definition of Terms +1.1. Definition of Terms The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in RFC 2119 [3]. - - Element: An XML Element[XML]. + document are to be interpreted as described in [RFC2119]. - Managed Entity: A node, which supports NETCONF[NETCONF-PROTO] and has - access to management instrumentation. This is also known as the - NETCONF server. + Element: An [XML] Element. Managed Object: A collection of one of more Elements that define an abstract thing of interest. Subscription: A concept related to the delivery of notifications (if any to send) involving destination and selection of notifications. It is bound to the lifetime of a session. -1.2 Event Notifications in NETCONF + Operation: This term is used to refer to NETCONF protocol + operations. Specifically within this document, operation refers + to NETCONF protocol operations defined in support of NETCONF + notifications. + +1.2. Event Notifications in NETCONF An event is something that happens which may be of interest - a configuration change, a fault, a change in status, crossing a threshold, or an external input to the system, for example. Often this results in an asynchronous message, sometimes referred to as a notification or event notification, being sent out to interested parties to notify them that this event has occurred. This memo defines a mechanism whereby the NETCONF client indicates interest in receiving event notifications from a NETCONF server by @@ -161,193 +166,193 @@ 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 some event, outside the scope of this specification, causes the subscription to terminate. 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 agent is not required to process RPC requests until the - notification stream is done. A capability may be defined to announce - that a server is able to process RPCs while a notification stream is - active on a session. + An NETCONF server is not required to process RPC requests on the + session associated with the subscription until the notification + stream 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. -1.3 Motivation +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 +1.4. Requirements - The requirements for this solution are as follows: + The following requirements have been addressed by the solution: o Initial release should ensure it supports notification in support of configuration operations o Data content must not preclude the use of the same data model as used in configuration o solution should support a reasonable message size limit (syslog and SNMP are rather constrained in terms of message sizes) o solution should provide reliable delivery of notifications - o solution should support agent initiated connections - - o solution should provide a subscription mechanism (An agent does - not send notifications before asked to do so and the manager - initiates the flow of notifications) + o solution should provide a subscription mechanism (A NETCONF server + does not send notifications before asked to do so and the NETCONF + client initiates the flow of notifications) - o solution should provide a filtering mechanism + o solution should provide a filtering mechanism within the Netconf + server o solution should send sufficient information in a notification so that it can be analyzed independent of the transport mechanism (data content fully describes a notification; protocol information is not needed to understand a notification) - o solution should not bind subscriptions to a connection - - o channels for configuration change notifications should share fate - with a session that includes a configuration channel - o solution should support replay of locally logged notifications 2. Notification-Related Operations -2.1 Subscribing to receive Event Notifications +2.1. Subscribing to receive Event Notifications The event notification subscription is initiated by the NETCONF client and responded to by the NETCONF server. When the event notification subscription is created, the events of interest are specified. Content for an event notification subscription can be selected by applying user-specified filters. -2.1.1 create-subscription - - +2.1.1. Description: This operation initiates an event notification subscription which will send asynchronous event notifications to the initiator of the command until the NETCONF session terminates or some event, outside the scope of this specification, causes the subscription to terminate. Parameters: - Stream: + Streams: An optional parameter that indicates which stream(s) of events are of interest. If not present, then events in the default NETCONF stream will be sent. Filter: An optional parameter that indicates which subset of all possible events are of interest. The format of this parameter is the same as that of the filter parameter in the NETCONF protocol operations. If not present, all events not precluded by other parameters will be sent. - Named Profile + Named Profile: An optional parameter that points to a separately defined filter profile. The contents of the profile are specified in - the provided XML Schema. If not present, no additional + the provided [XML Schema]. If not present, no additional filtering will be applied. Note that changes to the profile after the subscription has been created will have no effect. + Start Time: + + A parameter used with the optional replay capability to signals + that this is a replay subscription and that the replay should + start at the time specified. If start time is not present, + this is not a replay subscription. Stop time for replay is + implicitly defined to be the time the create-subscription + command was received by the Netconf server. + Positive Response: If the NETCONF server can satisfy the request, the server sends an - element containing a element containing the - subscription ID. + element. Negative Response: An element is included within the if the request cannot be completed for any reason. Subscription requests will fail if a filter with invalid syntax is provided or if the name of a non-existent profile or stream is provided. -2.2 Sending Event Notifications +2.1.2. Filter Dependencies + + When multiple filters are specified (in-line Filter, Named Profiles), + they are applied collectively (i.e. logical AND operation). That is, + event notifications must pass all specified filters in order to be + sent to the subscriber. + +2.2. Sending Event Notifications Once the subscription has been set up, the NETCONF server sends the event notifications asynchronously along the connection. -2.2.1 Event Notification - - +2.2.1. Description: - An event notification is sent to the initiator of an 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. + 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. Parameters: - Subscription Id: - - A unique identifier for this event subscription - Data: Contains notification-specific tagged content. - Positive Response: - - No response. - - Negative Response: + Response: - No response. + No response. Not applicable. -2.3 Terminating the Subscription +2.3. Terminating the Subscription Closing of the event notification subscription is done by terminating the Netconf session ( )or via some action outside the scope of this specification. 3. Supporting Concepts -3.1 Capabilities Exchange +3.1. Capabilities Exchange The ability to process and send event notifications is advertised during the capability exchange between the NETCONF client and server. - "urn:ietf:params:xml:ns:netconf:notification:1.0" + "urn:ietf:params:xml:ns:netconf:capability:notification:1.0" For Example urn:ietf:params:xml:ns:netconf:base:1.0 urn:ietf:params:xml:ns:netconf:capability:startup:1.0 - urn:ietf:params:xml:ns:netconf:notification:1.0 + urn:ietf:params:xml:ns:netconf:capability:notification:1.0 4 -3.2 Event Streams +3.2. Event Streams An event stream is defined herein as a set of event notifications matching some forwarding criteria. System components generate event notifications which are passed to a central component for classification and distribution. The central component inspects each event notification and matches the event notification against the set of stream definitions. When a match occurs, the event notification is considered to be a member of that event stream. An event notification may be part of multiple event @@ -372,198 +377,118 @@ | cn |---+ | (notification) +----+ +-----> ( logging ) ( service ) (------------) +-------+ +-------+ |netconf|<--->|netconf| -> |server | |client | +-------+ +-------+ -3.2.1 Event Stream Definition +3.2.1. Event Stream Definition - Event streams are pre-defined on the managed device. The + Event streams are predefined on the managed device. The configuration of event streams is outside the scope of this document. However, it is envisioned that event streams are either pre- established by the vendor (pre-configured) or user configurable (e.g. part of the device's configuration) or both. Device vendors may allow event stream configuration via NETCONF protocol (i.e. edit- config operation) -3.2.2 Event Stream Content Format +3.2.2. Event Stream Content Format The contents of all event streams made available to a NETCONF client (i.e. the notification sent by the NETCONF server) must be encoded in XML. -3.2.3 Default Event Stream +3.2.3. Default Event Stream A NETCONF server implementation supporting the notification capability must support the "NETCONF" notification event stream. This stream contains all NETCONF XML event notifications supported by the NETCONF server. The definition of the event notification and their contents for this event stream is outside the scope of this document. -3.2.4 Event Stream Sources +3.2.4. Event Stream Sources With the exception of the default event stream (NETCONF notifications) specification of additional event stream sources (e.g. SNMP, syslog, etc.) is outside the scope of this document. NETCONF server implementations may leverage any desired event stream source in the creation of supported event streams. -3.2.5 Event Stream Discovery +3.2.5. Event Stream Discovery A NETCONF client retrieves the list of supported event streams from a - NETCONF server using the or RPC request. + NETCONF server using the RPC request. -3.2.5.1 Name Retrieval using get, get-config RPC +3.2.5.1. Name Retrieval using operation The list of available event streams is retrieved by requesting the - subtree via a or operation. - Available event streams for the requesting session are returned in - the reply containing and elements, where - element is mandatory and its value is unique [Editor's Note: - should we then define it as a key?]. The returned list must only - include the names of those event streams for which the NETCONF - sessions has sufficient privileges. The NETCONF session privileges - are determined via access control mechanisms which are beyond the - scope of this document. An empty reply is returned if there are no - available event streams. - - Retrieving available event stream list using operation: + subtree via a operation. Available event streams + for the requesting session are returned in the reply containing + and elements, where element is mandatory + and its value is unique [Editor's Note: should we then define it as a + key?]. The returned list must only include the names of those event + streams for which the NETCONF sessions has sufficient privileges. + The NETCONF session privileges are determined via access control + mechanisms which are beyond the scope of this document. An empty + reply is returned if there are no available event streams. - - - - - - - - - - - - - + Retrieving available event stream list using operation: - - - - - - - NETCONF - Default netconf event stream - - - - snmp - SNMP notifications - - - syslog-critical - Critical and higher severity - - - - - - - - Retrieving available event stream list using operation: - - + - - - + NETCONF Default netconf event stream snmp SNMP notifications syslog-critical Critical and higher severity - -3.2.5.2 Device Supported Event Streams (System) +3.2.5.2. Device Supported Event Streams (System) 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 - subtree via a or - operation. - - - - - - - - - - - - + subtree via a operation. - - - - - - NETCONF - Default netconf event stream - - - - snmp - SNMP notifications - - - - syslog-critical - Critical and higher severity - - - - - - +3.2.5.3. Stream Retrieval Schema -3.2.5.3 Stream Retrieval Schema Schema for event streams @@ -572,33 +497,32 @@ NetconfNotificationSchema 2006-09-06T09:30:47-05:00 IETF A schema that can be used to learn about current - NetConf Event subscriptions and creating named - profiles + event streams. - + 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 @@ -612,51 +536,51 @@ -3.2.6 Event Stream Subscription +3.2.6. 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.6.1 Filtering Event Stream Contents +3.2.6.1. Filtering Event Stream Contents The set of event notifications delivered in an event stream may be further refined by applying a user-specified filter at subscription creation time ( ). This is a transient filter associated with the event notification subscription and does not modify the event stream configuration. -3.2.6.2 Subscription to Multiple Event Streams +3.2.6.2. Subscription to Multiple Event Streams Multiple event streams may be configured on a device and a NETCONF client may subscribe to one or more of the available event streams. - A NETCONF client subscribing to multiple event streams must do so by - either establishing a new NETCONF session or opening a new channel on - an existing NETCONF session. -3.3 Subscriptions and Datastores +3.3. Subscriptions not Configuration Data - Subscriptions are like NETCONF sessions in that they don't exist in - NETCONF datastores. The exception to this is the named profiles - feature. + 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 + comparable to NETCONF sessions. -3.4 Querying Subscription Properties + Named profiles, if used, are considered configuration data. + +3.4. Querying Subscription Properties The following Schema can be used to retrieve information about active event notification subscriptions NetconfNotificationSchema 2006-09-13T09:30:47-05:00 IETF A schema that can be used to learn about current - NetConf Event subscriptions and creating named + NETCONF Event subscriptions and creating named profiles - + @@ -717,81 +641,83 @@ - The session id associated with this subscription. + The session id associated with this + subscription. - + - The subscription id associated with this + A list of event streams associated with this subscription. The filters associated with this subscription. - + - The named profile associated with this subscription. - Note that the contents of the named profile may - have changed since it was last applied. + The named profile associated with this + subscription. Note that the contents of the + named profile may have changed since it was + last applied. - The last time this subscription was modified. If it - has not been modified since creation, this is the - time of subscription creation. + The last time this subscription was modified. If + it has not been modified since creation, this is + the time of subscription creation. + type="xs:unsignedInt" minOccurs="0"> A count of event notifications sent along this connection since the subscription was created. - + + + + + + The event streams associated with this named + profile. + + + + The filters associated with this named profile. 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. + 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. @@ -852,68 +791,53 @@ -3.5 One-way Notification Messages - - In order to support the concept that each individual event - notification is a well-defined XML-document that can be processed - 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 - independent messages that originate from the NETCONF server. In - order to support this model, this memo introduces the concept of - notifications, which are one-way messages. - - A one-way message is similar to the two-way RPC message, except that - no response is expected to the command. In the case of event - notification, this message will originate from the NETCONF server, - and not the NETCONF client. - -3.6 Filter Dependencies +3.5. Filter Dependencies Note that when multiple filters are specified (in-line Filter, Named Profiles), 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.6.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.6.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.7 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 | |-------------------------->| |<------------------------->| | | @@ -938,70 +862,60 @@ 4. XML Schema for Event Notifications - + + + This import accesses the xml: attribute groups for the xml:lang as declared on the error-message element. - - - - - - The unique identifier for this particular subscription within - the session. - - - - + - + - A monotonically increasing integer. Starts at 0. - Always increases by just one. Roll back to 0 after maximum - value is reached. + A list of event streams. - - + + + + - + + - + @@ -998,34 +912,34 @@ + - + - + + 5. Mapping to Transport Protocols Currently, the NETCONF family of specification allows for running NETCONF over a number of transport protocols, some of which support multiple configurations. Some of these options will be better suited for supporting event notifications then others. @@ -1023,112 +937,121 @@ 5. Mapping to Transport Protocols Currently, the NETCONF family of specification allows for running NETCONF over a number of transport protocols, some of which support multiple configurations. Some of these options will be better suited for supporting event notifications then others. -5.1 SSH +5.1. SSH Session establishment and two-way messages are based on the NETCONF - over SSH transport mapping [NETCONF-SSH] + over SSH transport mapping [NETCONF SSH] One-way event messages are supported as follows: Once the session has been established and capabilities have been exchanged, the server may send complete XML documents to the NETCONF client containing notification elements. No response is expected from the NETCONF client. - As the examples in [NETCONF-SSH] illustrate, a special character + As the examples in [NETCONF SSH] illustrate, a special character sequence, MUST be sent by both the client and the server after each XML document in the NETCONF exchange. This character sequence cannot legally appear in an XML document, so it can be unambiguously used to identify the end of the current document in the event notification of an XML syntax or parsing error, allowing resynchronization of the NETCONF exchange. The NETCONF over SSH session to receive an event notification might - look like the following. Note the event notification contents - (delimited by tags) are not defined in this document - and are provided herein simply for illustration purposes: + look like the following. In the example below the event notification + contents (delimited by tags) are not defined in this + document and are provided herein simply for illustration purposes. + The sample notification shows a configuration change on the running + configuration as a result of an operation. It has one + containment node ( ), with one element and + two changed attributes ( and ) (Note that this does not + refer to XML attributes). The same example is used in the BEEP and + SOAP transport mapping sections. - 123456 - + + notice 2 2000-01-12T12:13:14Z Fred Flinstone - + + Ethernet0/0 1500 + + + - ]]> - ]]> + ]]>]]> -5.2 BEEP +5.2. BEEP 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 Notification Messages in Beep +5.2.1. One-way Notification Messages in Beep One-way notification messages can be supported either by mapping to the existing one-to-many BEEP construct or by creating a new one-to- none construct. 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: "rpc", "notification", "rpc-reply" - Messages in positive replies: "rpc-reply", "rpc-one-way" + Messages in positive replies: "rpc-reply" -5.2.1.2 One-way notification 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 - update to 'The Blocks Extensible Exchange Protocol Core' RFC 3080. + update to 'The Blocks Extensible Exchange Protocol Core' [RFC3080]. MSG/NoANS: the client sends a "MSG" message, the server, sends no reply. In one-to-none exchanges, no reply to the "MSG" message is expected. -5.3 SOAP +5.3. SOAP Session management and message exchange are based on the NETCONF over - SOAP transport mapping NETCONF-SOAP + SOAP transport mapping [NETCONF SOAP] Note that the use of "persistent connections" "chunked transfer- coding" when using HTTP becomes even more important in the supporting of event notifications -5.3.1 A NETCONF over Soap over HTTP Example +5.3.1. A NETCONF over Soap over HTTP Example C: POST /netconf HTTP/1.1 C: Host: netconfdevice C: Content-Type: text/xml; charset=utf-8 C: Accept: application/soap+xml, text/* C: Cache-Control: no-cache C: Pragma: no-cache C: Content-Length: 465 C: C: @@ -1136,158 +1059,154 @@ C: xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> C: C: C: C: C: C: C: - The response: S: HTTP/1.1 200 OK S: Content-Type: application/soap+xml; charset=utf-8 S: Content-Length: 917 S: - S: S: S: S: S: S: - S: 123456 S: S: S: S: S: And then some time later S: HTTP/1.1 200 OK S: Content-Type: application/soap+xml; charset=utf-8 S: Content-Length: 917 S: S: S: S: S: - S: 123456 S: S: S: 2 S: 2000-01-12T12:13:14Z S: Fred Flinstone S: S: S: S: S: S: S: - S: + S: + S: Ethernet0/0 S: 1500 - S: + + S: S: S: S: S: S: S: S: S: 6. Filtering examples The following section provides examples to illustrate the various methods of filtering content on an event notification subscription. -6.1 Subtree Filtering +6.1. Subtree Filtering 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 (only for example purposes). 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 + schema definition has an element identifying the event + category (e.g. fault, state, config, etc.) and events have a element The following example illustrates selecting events which have severities of critical, major, or minor (presumably fault events). The filtering criteria evaluation is as follows: ((severity=critical) | (severity=major) | (severity=minor)) - - - - + + critical - + major - + minor - The following example illustrates selecting fault, state, config EventClasses or events which are related to card Ethernet0. The filtering criteria evaluation is as follows: (fault | state | config | card=Ethernet0) - fault state config Ethernet0 - + -6.2 XPATH filters +6.2. XPATH filters The following 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))) @@ -1320,103 +1239,187 @@ /event[severity="major"]) or (/event[eventClasses/fault] and /event[severity="minor"]) or /event[card="Ethernet0"])) 7. Notification Replay Capability -7.1 Overview +7.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. A replay of notifications is specified by including an optional parameter to the subscription command that indicates the start time of the replay. The end time of the replay is implicitly defined to be the time the replay request was initiated. An implementation that supports replay is not expected to have an unlimited supply of saved notifications available to accommodate any replay request. If a client requests a replay of notifications that predate the oldest notification available, then the NETCONF server - must return an warning message in the RPC reply and start replaying + must return a warning message in the RPC reply and start replaying the notifications it does have available, within the other - constraints, such as filtering, that the client has provided. + constraints, such as filtering, that the client has provided. The + warning message enables the NETCONF client to differentiate between + the case that there were no notifications generated within a given + time period from the case that no notifications are currently in the + log from that period. The actual number of stored notifications available for retrieval at - any given time is an agent implementation specific matter. Control - parameters for this aspect of the feature are outside the scope of - the current work. + any given time is an NETCONF server implementation specific matter. + Control parameters for this aspect of the feature are outside the + scope of the current work. A given subscription is either a replay subscription or a normal subscription, which sends event notifications as they happen. A replay subscription terminates once the it has completed replaying past events. -7.2 Dependencies +7.2. Dependencies This capability is dependent on the notification capability being - supported. It also requires that the device support some form of - notification logging, although it puts no restrictions on the size or - form of the log. + supported. It also requires that the device supporting the Netconf + server also support some form of notification logging, although it + puts no restrictions on the size or form of the log, nor where it + resides within the device. -7.3 Capability Identifier +7.3. Capability Identifier The Event Notification Replay capability is identified by following capability string: http://ietf.org/netconf/notificationReplay/1.0 -7.4 New Operations +7.4. New Operations None -7.5 Modifications to Existing Operations +7.5. Modifications to Existing Operations -7.5.1 create-subscription +7.5.1. create-subscription This capability adds an optional parameter to the command called 'startTime'. This identifies the earliest date and time of interest for event notifications being replayed. Events generated before this time are not matched. -7.5.2 Interactions with Other Capabilities + 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 parameter is + related to generation time. + + Negative Response: + + An element is included in the if the + startTime in replay request predates the oldest notification + available to be replayed. + + Error-tag: start-time-value + + Error-type: protocol + + Error-severity: warning + + Error-info: none + + Error-message: Start time predates oldest available + notification to be replayed + +7.5.2. Interactions with Other Capabilities [Edtitor's Note: If this capability does not interact with other capabilities, this section may be omitted.] +7.6. Replay Complete Notification + + The following notification is the last notification sent over a + replay subscription. It indicates that replay is complete. + + + + + + + + This notification is sent to signal the end of a replay + subscription. + + + + + + + + The event classification of this notification. + + + + + + + + + + 8. Security Considerations - To be determined once specific aspects of this solution are better - understood. In particular, the access control framework and the - choice of transport will have a major impact on the security of the - solution + The access control framework and the choice of transport will have a + major impact on the security of the solution. + + Note that the elements are never sent before the + transport layer and the netconf layer (capabilities exchange) have + been established, and the manager has been identified and + authenticated. + + It is recommended that care be taken to ensure the secure operation + of the following commands: + + o invocation + + o use of + + o read-only data models + + o read-write data models + + o notification content + + One issue related to the notifications draft is the transport of data + from non-netconf streams, such as syslog and SNMP. Note that this + data may be more vulnerable (or is not more 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. 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 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 + Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig, + Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William + Chow -10. References +10. Normative References [NETCONF] Enns, R., "NETCONF Configuration Protocol", ID draft-ietf-netconf-prot-12, February 2006. [NETCONF BEEP] Lear, E. and K. Crozier, "Using the NETCONF Protocol over Blocks Extensible Exchange Protocol (BEEP)", ID draft-ietf-netconf-beep-10, March 2006. [NETCONF Datamodel] @@ -1427,64 +1430,76 @@ [NETCONF SOAP] Goddard, T., "Using the Network Configuration Protocol (NETCONF) Over the Simple Object Access Protocol (SOAP)", ID draft-ietf-netconf-soap-08, March 2006. [NETCONF SSH] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration Protocol over Secure Shell (SSH)", ID draft-ietf-netconf-ssh-06.txt, March 2006. - [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform - Resource Identifiers (URI): Generic Syntax", RFC 2396, - August 1998. - - [XML] World Wide Web Consortium, "Extensible Markup Language - (XML) 1.0", W3C XML, February 1998, - . - - [refs.RFC2026] - Bradner, S., "The Internet Standards Process -- Revision + [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", RFC 2026, BCP 9, October 1996. - [refs.RFC2119] - Bradner, s., "Key words for RFCs to Indicate Requirements + [RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements Levels", RFC 2119, March 1997. - [refs.RFC2223] - Postel, J. and J. Reynolds, "Instructions to RFC Authors", + [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", RFC 2223, October 1997. - [refs.RFC3080] - Rose, M., "The Blocks Extensible Exchange Protocol Core", + [RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC 3080, March 2001. + [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. + Authors' Addresses Sharon Chisholm Nortel 3500 Carling Ave Nepean, Ontario K2H 8E9 Canada Email: schishol@nortel.com Hector Trevino Cisco Suite 400 9155 E. Nichols Ave Englewood, CO 80112 USA Email: htrevino@cisco.com -Intellectual Property Statement +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + 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 + 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 on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. @@ -1494,35 +1509,14 @@ such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. - The IETF has been notified of intellectual property rights claimed in - regard to some or all of the specification contained in this - document. For more information consult the online list of claimed - rights. - -Disclaimer of Validity - - 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 - WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Copyright Statement - - Copyright (C) The Internet Society (2006). 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. - Acknowledgment - Funding for the RFC Editor function is currently provided by the - Internet Society. + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA).