view Side-By-Side changes
Network Working Group S. Chisholm Internet-Draft Nortel Intended status: Standards Track H. Trevino Expires:August 24,November 16, 2007 CiscoFebruary 20,May 15, 2007 NETCONF Event Notificationsdraft-ietf-netconf-notification-06.txtdraft-ietf-netconf-notification-07.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 other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months 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 onAugust 24,November 16, 2007. Copyright Notice Copyright (C) The IETF Trust (2007). Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page 1] Internet-Draft NETCONF Event NotificationsFebruaryMay 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. Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page 2] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 4 1.2.Event Notifications in NETCONFMotivation . . . . . . . . . . . . . .5 1.3. Motivation. . . . . . . . . . 5 1.3. Event Notifications in NETCONF . . . . . . . . . . . . . . 5 1.4. Requirements . . . . . . . . . . . . . . . . . . . . . . .56 2. Notification-Related Operations . . . . . . . . . . . . . . . 7 2.1. Subscribing to receive Event Notifications . . . . . . . . 7 2.1.1. <create-subscription> . . . . . . . . . . . . . . . . 7 2.2. Sending Event Notifications . . . . . . . . . . . . . . .89 2.2.1. <notification> . . . . . . . . . . . . . . . . . . . .89 2.3. Terminating the Subscription . . . . . . . . . . . . . . .910 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . .1011 3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . .1011 3.1.1. Capability Identifier . . . . . . . . . . . . . . . .1011 3.1.2. Capability Example . . . . . . . . . . . . . . . . . .1011 3.2. Event Streams . . . . . . . . . . . . . . . . . . . . . .1011 3.2.1. Event Stream Definition . . . . . . . . . . . . . . .1112 3.2.2. Event Stream Content Format . . . . . . . . . . . . .1113 3.2.3. Default Event Stream . . . . . . . . . . . . . . . . .1113 3.2.4. Event Stream Sources . . . . . . . . . . . . . . . . .1213 3.2.5. Event Stream Discovery . . . . . . . . . . . . . . . .1213 3.3. NotificationManagement SchemaReplay . . . . . . . . . . . . . .13 3.4. Subscriptions not Configuration Data. . . . . 15 3.3.1. Overview . . . . . . . .16 3.5. Filter Dependencies. . . . . . . . . . . . . . . 15 3.3.2. Creating a Subscription with Replay . . . .17 3.5.1. Named Profiles. . . . . 16 3.3.3. Replay Complete Notification . . . . . . . . . . . . . 16 3.4. Notification Management Schema . . . . . . . . .17 3.5.2. Filtering. . . . . 16 3.5. Subscriptions Data . . . . . . . . . . . . . . . . .17. . . 20 3.6.Message FlowFilter Mechanics . . . . . . . . . . . . . . . . . . . . . 20 3.6.1. Named Profiles . .17 4. XML Schema for Event Notifications. . . . . . . . . . . . . .19 5. Filtering examples. . . . 21 3.6.2. Filtering . . . . . . . . . . . . . . . . . .22 5.1. Subtree Filtering. . . . 21 3.7. Message Flow . . . . . . . . . . . . . . . .22 5.2. XPATH filters. . . . . . . 21 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 23 5. Filtering Examples .25 6. Notification Replay. . . . . . . . . . . . . . . . . . . . . 276.1. Overview5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 27 5.2. XPATH filters . . . . .27 6.2. Creating a Subscription with Replay. . . . . . . . . . .27 6.3. Replay Complete Notification. . . . . . 30 6. Security Considerations . . . . . . . . . . . . . . . . . .28. 32 7.SecurityIANA Considerations . . . . . . . . . . . . . . . . . . .30. . 33 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . .3134 9. Normative References . . . . . . . . . . . . . . . . . . . . .3235 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . .3336 Intellectual Property and Copyright Statements . . . . . . . . . .3437 Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page 3] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 1. Introduction [NETCONF] can be conceptually partitioned into four layers: Layer Example +-------------+ +----------------------------------------+ | Content | | Configuration data | +-------------+ +----------------------------------------+ | | +-------------+ +-------------------------------------------+ | Operations | | <get-config>, <edit-config> <notification>| +-------------+ +-------------------------------------------+ | | | +-------------+ +-----------------------------+ | | RPC | | <rpc>, <rpc-reply> | | +-------------+ +-----------------------------+ | | | | +-------------+ +------------------------------------------+ | 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.Figure 11.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 [RFC2119]. 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.Chisholm & Trevino Expires August 24, 2007 [Page 4] Internet-Draft NETCONF Event Notifications February 2007Operation: 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.Chisholm & Trevino Expires November 16, 2007 [Page 4] Internet-Draft NETCONF Event Notificationsin NETCONFMay 2007 Event: 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 sentoutto interested parties to notify them that this event has occurred. Replay: The ability to send/re-send previously logged notifications upon request. These notifications are sent asynchronously. Thismemo defines a mechanism wherebyfeature is implemented by the NETCONFclient indicates interest in receiving event notifications from a NETCONFserver and invoked bycreatingthe NETCONF client. Stream: An event stream is asubscription to receiveset of eventnotifications.notifications matching some forwarding criteria and it is available to NETCONF clients for subscription. Named Profile: A predefined set of filtering criteria residing in the Network Element which may be applied to a notification session at subscription creation time. 1.2. 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.3. Event Notifications in NETCONF This memo defines a mechanism whereby the NETCONF client indicates interest in receiving event notifications from a NETCONF server by creating a subscription to receive event notifications. The NETCONF 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 subscriptionto terminateterminates 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.AnA NETCONF server is not required to process RPC requests on the session associated with the subscription until the notification 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. MotivationThemotivation for this workbehaviour of such a capability isto enableoutside thesendingscope ofasynchronous messages that are consistent with the data model (content) and security model used within athis document. Chisholm & Trevino Expires November 16, 2007 [Page 5] Internet-Draft NETCONFimplementation.Event Notifications May 2007 1.4. Requirements 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 configurationChisholm & Trevino Expires August 24, 2007 [Page 5] Internet-Draft NETCONF Event Notifications February 2007o 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 provide a subscription mechanism (A NETCONF server does not send notifications before being asked to do so and the NETCONF client initiates the flow of notifications) 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 support replay of locally logged notifications Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page 6] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 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. 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> Description: This operation initiates an event notification subscription which will send asynchronous event notifications to the initiator of the command until the subscriptiontoterminates. Parameters: Stream: An optional parameter that indicates which stream of events is 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. This is mutually exclusive with the named profile parameter. See section 3.6 for more information on filters. Named Profile: An optional parameter thatpointsrefers to a separately defined filter profile. 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. This is mutually exclusive with the filterparameterparameter. For more information on named profiles, see section 3.6.1. Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page 7] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 Start Time: A parameter used to trigger the replay feature and indicates that the replay should start at the time specified. Ifstart timestartTime is not present, this is not a replay subscription. It is valid to specify start times that are later than the current time. If the startTime specified is earlier then 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 'startTime'. It is valid to specify stop times that are later than the current time. This parameter is of type dateTime. Positive Response: If the NETCONF server can satisfy the request, the server sends an <ok> element. Negative Response: An <rpc-error> element is included within the <rpc-reply> 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 OnceIf a stopTime is specified in a request without having specified a startTime the following error is returned: Tag: missing-element Error-type: protocol Severity: error Error-info: <startTime 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: Chisholm & Trevino Expires November 16, 2007 [Page 8] Internet-Draft NETCONF Event Notifications May 2007 Tag: operation-failed Error-type: protocol Severity: error Error-info: none Description: Request could not be completed because the requested operation failed for some reason not covered by any other error condition 2.1.1.1. Usage Example <netconf:rpc message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> <create-subscription> </create-subscription> </netconf:rpc> 2.2. Sending Event Notifications Once the subscription has been set up, the NETCONF server sends the event notifications asynchronouslyalongover the connection. 2.2.1. <notification> Description: An event notification is sent to theinitiator ofclient who initiated a<create- subscription><create-subscription> command asynchronously when an event of interest(i.e.(i.e., meeting the specified filtering criteria) to them has occurred. An event notification is a complete and well-formed XML document. Note that <notification> 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. The content of the data tag is beyond the scope of this document. Response: Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page8]9] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007Data: 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 ( <kill-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, theNetconfNETCONF session will still be an active session. Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page9]10] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 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 "urn:ietf:params:netconf:capability:notification:1.0" 3.1.2. Capability Example <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <capabilities> <capability> urn:ietf:params:xml:ns:netconf:base:1.0 </capability> <capability> urn:ietf:params:netconf:capability:startup:1.0 </capability> <capability> urn:ietf:params:netconf:capability:notification:1.0 </capability> </capabilities> <session-id>4</session-id> </hello> 3.2. Event Streams An event stream is definedhereinas a set of event notifications matching some forwarding criteria. The diagram depicted in Figure 2 illustrates the notification flow and concepts identified in this document. The following is observed from the diagram below: System components (c1..cn) 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 eventstream.stream (stream 1..stream n). An event notification may be part of multiple event streams. When a NETCONF client subscribes to a given event stream, user- defined filters, if applicable, are applied to the event stream and matching event notifications are forwarded to the NETCONF server fordistribution to subscribed NETCONF clients.Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page10]11] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 distribution to subscribed NETCONF clients. For more information on filters, see section 3.6. A notification logging service may also be available, in which case, the central component logs notifications. The NETCONF server may later retrieve logged notifications via the optional replay feature. For more information on replay, see section 3.3. +----+ | c1 |---+ available streams +----+ | +---------+ +----+ | |central |-> stream 1 | c2 | +--->|event |-> stream 2 filter +-------+ +----+ | |processor|->netconfNETCONF stream--->|netconf|----->|netconf| ... | | |-> stream n |server |seeSystem | +---------+ +-------+belowComponents| |///\ ... | |//|| +----+ | | (------------) || | cn |---+ | (notification) || +----+ +-----> ( logging ) || ( service ) || (------------) || || || \/ +-------++-------+ |netconf|<--->|netconf| -> |server ||netconf| |client | +-------++-------+Figure 4 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) or user configurable(e.g.(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)(i.e., edit-config operation). Chisholm & Trevino Expires November 16, 2007 [Page 12] Internet-Draft NETCONF Event Notifications May 2007 3.2.2. Event Stream Content Format The contents of all event streams made available to a NETCONF client(i.e.(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. This stream contains all NETCONF XML event notifications supported by the NETCONF server. The definition of the eventnotificationnotifications and their contents for this event stream is outside the scope of this document.Chisholm & Trevino Expires August 24, 2007 [Page 11] Internet-Draft NETCONF Event Notifications February 20073.2.4. Event Stream Sources With the exception of the default event stream (NETCONF notifications) specification of additional event stream sources(e.g.(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 A NETCONF client retrieves the list of supported event streams from a NETCONF server using the <get> RPC request. 3.2.5.1. Name Retrieval using <get> operation The list of available event streams is retrieved by requesting the <eventStreams> subtree via a<get>operation.<get> operation. Available event streams for the requesting session are returned in the reply containing the <name> and <description> elements, where <name> 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 information is retrieved by requesting the <eventStreams> subtree via a <get> operation. Chisholm & Trevino Expires November 16, 2007 [Page 13] Internet-Draft NETCONF Event Notifications May 2007 Example: Retrieving available event stream list using <get> operation: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get> <filter type="subtree"> <eventStreamsxmlns="urn:ietf:params:xml:ns:netmod:base:1.0"/>xmlns="urn:ietf:params:xml:ns:netmod:notification"/> </filter> </get> </rpc>Chisholm & Trevino Expires August 24, 2007 [Page 12] Internet-Draft NETCONF Event Notifications February 2007The NETCONF server returns a list of event streams available for subscription: NETCONF, snmp, and syslog-critical in this example. <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <data> <eventStreamsxmlns="urn:ietf:params:xml:ns:netmod:base:1.0">xmlns="urn:ietf:params:xml:ns:netmod:notification"> <stream> <name>NETCONF</name> <description>Default netconf event stream </description> <replaySupport>true</replaySupport> </stream> <stream> <name>snmp</name> <description>SNMP notifications</description> <replaySupport>false</replaySupport> </stream> <stream> <name>syslog-critical</name> <description>Critical and higher severity </description> <replaySupport>true</replaySupport> </stream> </eventStreams> </data> </rpc-reply>3.2.5.2.Chisholm & Trevino Expires November 16, 2007 [Page 14] Internet-Draft NETCONF Event Notifications May 2007 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 <create- subscription> request with the desired event stream name. Omitting the event stream name from the <create-subscription> request results in subscription to the default NETCONF event stream. 3.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 ( <create-subscription> ). This is a transient filter associated with the event notification subscription and does not modify the event stream configuration. XPATH support for the Notification capability is advertised as part of the normal XPATH capability advertisement. If XPATH support is advertised via the XPATH capability then XPATH is supported for notification filtering and if this capability is not advertised, then XPATH is not supported for notification filtering. 3.3. NotificationManagement Schema Chisholm & Trevino Expires August 24, 2007 [Page 13] Internet-Draft NETCONF Event Notifications February 2007 <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0" xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:event:1.0" targetNamespace="urn:ietf:params:xml:ns:netmod:event:1.0" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:annotation> <xs:documentation xml:lang="en">Replay 3.3.1. Overview Replay is the ability to create an event subscription that will resend recently generated notifications. These notifications are sent the same way as normal notifications. Aschemareplay of notifications is specified by including an optional parameter to the subscription command thatcanindicates the start time of the replay. The end time is specified using the optional stopTime parameter. If not present, notifications will continue to beusedsent until the subscription is terminated. A notification stream that supports replay is not expected tolearn about current event streams andhave an unlimited supply of saved notifications available tomanage named profiles. </xs:documentation> </xs:annotation> <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd"/> <xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0" schemaLocation="urn:ietf:params:xml:ns:netconf:base:1.0"/> <xs:import namespace="urn:ietf:params:xml:ns:netconf:notification:1.0" schemaLocation= "urn:ietf:params:xml:ns:netconf:notification:1.0"/> <xs:element name="eventStreams" > <xs:annotation> <xs:documentation>accommodate any replay request. Thelistactual number ofevent streams supported by the system. When a querystored notifications available for retrieval at any given time isissued,a NETCONF server implementation specific matter. Control parameters for this aspect of thereturned setfeature are outside the scope ofstreamsthe current document. Replay isdetermined baseddependent onuser privileges </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element name="stream"> <xs:annotation> <xs:documentation> Stream name and description </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="name" type="xs:string"/> <xs:element name="description" type="xs:string"/> <xs:element name="replaySupport" type="xs:boolean"/> </xs:sequence> Chisholm & Trevino Expires August 24, 2007 [Page 14] Internet-Draft NETCONF Event Notifications February 2007 </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="namedProfile"> <xs:annotation> <xs:documentation> A named profile, which isasaved setnotification stream supporting some form ofparameters associated that may be associated with zeronotification logging, although it puts no restrictions on the size ormore active subscriptions. This object can be created, read, deleted and its individual components can be modified. </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="name"> <xs:annotation> <xs:documentation> The name associated withform of theprofile. This object is readable and modifiable. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="stream" minOccurs="0"> <xs:annotation> <xs:documentation xml:lang="en"> The event stream associated with this named profile. This object is readable and modifiable. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="filter" type="netconf:filterInlineType" minOccurs="0"> <xs:annotation> <xs:documentation xml:lang="en"> The filters associated with this named profile.log, nor where it resides within the device. Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page 15] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 3.3.2. Creating a Subscription with Replay Thisobject is readablefeature uses optional parameters to the <create-subscription> command called 'startTime' andmodifiable. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="lastModified" type="xs:dateTime"> <xs:annotation> <xs:documentation> The timestamp of'stopTime'. 'startTime' identifies thelast modification to this named Profile. Noteearliest date and time of interest for event notifications being replayed and also indicates thatmodificationa subscription will be providing replay ofthe profile does not cause an immediate update to all applicable subscription. Therefore,notifications. Events generated before this timeshould be compared withare not matched. 'stopTime' specifies thelast modifiedlatest date and timeassociated with the subscription.of interest for event notifications being replayed. Ifthis timeit isearlier,not present, then notifications will continue to be sent until the subscription isusing the exact set of parametersterminated. Note that startTime and stopTime are associated withthis named profile. If this time is later, thenthesubscription is usingtime anearlier version of this named profile andevent was generated by theexact parameters may not match. This objectsystem. A replay complete notification isread-only. </xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="namedProfiles"> <xs:complexType> <xs:sequence> <xs:element ref="manageEvent:namedProfile" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> 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 comparablesent toNETCONF sessions. Chisholm & Trevino Expires August 24, 2007 [Page 16] Internet-Draft NETCONF Event Notifications February 2007 Named profiles, if used, are considered configuration data. 3.5. Filter Dependencies Noteindicate thatwhen multiple filters are specified, they are applied collectively, so event notifications need to passallspecified filters in order to be sent toof thesubscriber.replay notifications have been sent. If this subscription has afilter is specified to look for data ofstop time, then this session becomes aparticular value, andnormal NETCONF session again. In thedata item is not present withincase of aparticular eventsubscription without a stop time, after the replay complete notificationfor its value to be checked against,has been sent, it can be expected that any notifications generated since the start of the subscription creation will befiltered out. For example, if one were to check for 'severity=critical' in a configuration event notification where this field was not supported, thensent followed by notifications as they arise naturally within the system. 3.3.3. Replay Complete Notification The replay complete notificationwould be filtered out. Note that the order that filters are applied does not matter since the resulting set of notificationsis theintersection of the set of notifications that pass each filtering criteria. 3.5.1. Named Profiles A named profile islast notification sent over afilterreplay subscription. It indicates that replay iscreated ahead of time and applied atcomplete. This notification will only be sent if a 'stopTime' was specified when thetime an eventreplay subscription was created. After this notification is received the subscription iscreated . Noteterminated and the session becomes a normal NETCONF session. The replayComplete can not be filtered out. It will always be sent on a relay subscription thatchangesspecified a stop time. 3.4. Notification Management Schema This Schema is used to learn about theprofile after the subscription has been created will have no effectevent streams supported on thesubscription. Since named profiles exist outside ofsystem and thesubscription, they persist afterquery and modify named profiles. It also contains thesubscription has been torn down. 3.5.2. Filtering Just-in-time filtering is explicitly stated whendefinition of theevent notification subscription is created. ThisreplayComplete, which isspecified via the 'filter' parameter. Filters only exist as parameterssent tothe subscription. 3.6. Message Flowindicate that an event replay has sent all applicable notifications." <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:ncEvent="urn:ietf:params:netconf:capability:notification:1.0" Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page17]16] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007The 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 | |-------------------------->| |<------------------------->| | | | <create-subscription> | |-------------------------->| |<--------------------------| | <rpc-reply> | | | | <notification> | |<--------------------------| | | | <notification> | |<--------------------------| | | | | | | | <notification> | |<--------------------------| | | | | Chisholm & Trevino Expires August 24, 2007 [Page 18] Internet-Draft NETCONF Event Notifications February 2007 4. XML Schema for Event Notifications The following [XML Schema] defines Netconf Event Notifications. <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" targetNamespace="urn:ietf:params:xml:ns:netconf:notification:1.0"xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification" targetNamespace="urn:ietf:params:xml:ns:netmod:notification" elementFormDefault="qualified"attributeFormDefault="unqualified" xml:lang="en"> <!-- import standard XML definitions --> <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd">attributeFormDefault="unqualified"> <xs:annotation><xs:documentation> This import accesses the xml: attribute groups for the xml:lang as declared on<xs:documentation xml:lang="en"> A schema that can be used to learn about current event streams and to manage named profiles. It also contains theerror-message element.replayComplete notification. </xs:documentation> </xs:annotation></xs:import> <!-- import base netconf definitions --><xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd"/> <xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"schemaLocation="urn:ietf:params:xml:ns:netconf:base:1.0" /> <!-- ************** Symmetrical Operations ********************--> <!-- <create-subscription> operation -->schemaLocation="urn:ietf:params:xml:ns:netconf:base:1.0"/> <xs:import namespace= "urn:ietf:params:netconf:capability:notification:1.0" schemaLocation= "urn:ietf:params:netconf:capability:notification:1.0"/> <xs:element name="netconf" type="manageEvent:Netconf"/> <xs:complexTypename="createSubscriptionType"> <xs:complexContent> <xs:extension base="netconf:rpcOperationType">name="Netconf"> <xs:sequence> <xs:elementname="stream" type="xs:string" minOccurs="0">name="eventStreams" > <xs:annotation> <xs:documentation>An optional parameter that indicates which streamThe list ofeventsevent streams supported by the system. When a query isof interest. If not present, then events inissued, thedefault NETCONF stream will be sent.returned set of streams is determined based on user privileges. </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <xs:element name="stream"> <xs:annotation> <xs:documentation> Stream name and description. </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="name" type="xs:string"/> <xs:element name="description" type="xs:string"/> Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page19]17] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007</xs:annotation> </xs:element> <xs:choice><xs:elementname="filter" type="netconf:filterInlineType" minOccurs="0">name="replaySupport" type="xs:boolean"/> <xs:element name="replayLogStartTime" type="xs:dateTime"> <xs:annotation> <xs:documentation>An optional parameter that indicates which subset of all possible events are of interest.Theformat of this parameter is the same as thatstart time of thefilter parameter inlog used to support theNETCONF protocol operations.replay function. If replay is notpresent, all events not precluded by other parameterssupported, this willbe sent. This is mutually exclusive withreturn thenamed profile parameter.current time. </xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:elementname="named-profile" type="xs:string"name="namedProfiles" minOccurs="0"><xs:annotation> <xs:documentation> An optional parameter that points to a separately defined filter profile. 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. This is mutually exclusive with the filter parameter </xs:documentation> </xs:annotation> </xs:element> </xs:choice><xs:complexType> <xs:sequence> <xs:elementname="startTime" type="xs:dateTime"name="namedProfile" type="manageEvent:NamedProfile" minOccurs="0">maxOccurs="unbounded" /> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="replayComplete" type="manageEvent:ReplayCompleteNotificationType" minOccurs="0"> <xs:annotation> <xs:documentation>A parameter usedThis notification is sent totrigger the replay feature and indicates that the replay should start atsignal thetime specified. If start time is not present, this is notend of a replay portion of a subscription. </xs:documentation> </xs:annotation> </xs:element><xs:element name="stopTime" type="xs:dateTime" minOccurs="0"</xs:sequence> </xs:complexType> <xs:complexType name="ReplayCompleteNotificationType" ><xs:annotation> <xs:documentation> An optional parameter used with the optional replay feature to indicate the newest notifications of<xs:complexContent> <xs:extension base="ncEvent:NotificationType"> <xs:sequence> Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page20]18] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007interest. If stop time is not present, the notifications will continue until the subscription is terminated. Must be used with 'startTime'. </xs:documentation> </xs:annotation> </xs:element><xs:element name="eventClass"/> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType><xs:element name="create-subscription" type="createSubscriptionType" substitutionGroup="netconf:rpcOperation"><xs:complexType name="NamedProfile"> <xs:annotation> <xs:documentation>The command to createA named profile, which is anotification subscription. It takes as argument the namesaved set ofthe notification stream and filterparameters that may be associated with zero orprofile information. All of those options limit the content of the subscription. In addition, there are two time-related parameters startTimemore active subscriptions. This object can be created, read, deleted andstopTime whichits individual components can beused to selectmodified. </xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="name"> <xs:annotation> <xs:documentation> The name associated with thetime interval of interest.profile. This object is readable and modifiable. </xs:documentation> </xs:annotation> </xs:element><!-- ************** One-way Operations ******************--> <!-- <Notification> operation --> <xs:complexType name="NotificationType"> <xs:sequence><xs:elementname="data" type="netconf:dataInlineType" /> </xs:sequence> </xs:complexType>name="stream" minOccurs="0"> <xs:annotation> <xs:documentation xml:lang="en"> The event stream associated with this named profile. This object is readable and modifiable. </xs:documentation> </xs:annotation> </xs:element> <xs:elementname="notification" type="NotificationType"/> </xs:schema>name="filter" type="netconf:filterInlineType" minOccurs="0"> <xs:annotation> <xs:documentation xml:lang="en"> The filters associated with this named profile. Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page21]19] Internet-Draft NETCONF Event NotificationsFebruaryMay 20075. Filtering examplesThis object is readable and modifiable. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="lastModified" type="xs:dateTime"> <xs:annotation> <xs:documentation> Thefollowing section provides examples to illustratetimestamp of thevarious methodslast modification to this named Profile. Note that modification offiltering content on an event notification subscription. 5.1. Subtree Filtering XML subtree filtering isthe profile does notwell suited for creating elaborate filter definitions given that it only supports equality comparisons and logical OR operations (e.g. incause anevent subtree give meimmediate update to allevent notifications which have severity=critical or severity=major or severity=minor). Nevertheless, it mayapplicable subscription. Therefore, this time should beused for defining simple event notification forwarding filters as shown below. In order to illustratecompared with theuse of filter expressions itlast modified time associated with the subscription. If this time isnecessary to assume some ofearlier, then theevent notification content. The examples herein assume thatsubscription is using theevent notification schema definition hasexact set of parameters associated with this named profile. If this time is later, then the subscription is using an<events> element atearlier version of this named profile and thetop levelexact parameters may not match. Note there is no guarantee thatcontains one or more child elements <eventEntry> consisting oftheevent class (e.g. fault, state, config, etc.) reporting entityprofile named in the subscription will be found at all." This object is read-only. </xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:complexType> </xs:schema> 3.5. Subscriptions 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 andeither severity or operational state. Chisholm & Trevino Expires August 24, 2007 [Page 22] Internet-Draft NETCONF Event Notifications February 2007 Sampletheir lifetime is defined by their session. Named profiles, if used, are considered configuration data. 3.6. Filter Mechanics Note that when multiple filter elements are specified, they are applied collectively, so eventlist <events> <eventEntry> <eventClass>fault</eventClass> <reportingEntity> <card>Ethernet0</card> </reportingEntity> <severity>major</severity> </eventEntry> <eventEntry> <eventClass>fault</eventClass> <reportingEntity> <card>Ethernet2</card> </reportingEntity> <severity>critical</severity> </eventEntry> <eventEntry> <eventClass>fault</eventClass> <reportingEntity> <card>ATM1</card> </reportingEntity> <severity>minor</severity> </eventEntry> <eventEntry> <eventClass>state</eventClass> <reportingEntity> <card>Ethernet0</card> </reportingEntity> <operState>enabled</operState> </eventEntry> </events> The following example illustrates selecting events which have severities of critical, major, or minor (presumably fault events). The filtering criteria evaluationnotifications need to pass all specified filters in order to be sent to the subscriber. If a filter element isas follows: ((severity=critical) | (severity=major) | (severity=minor))specified to look for data of a particular value, and the Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page23]20] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <netconf:filter type="subtree"> <event xmlns="http://example.com/event/1.0"> <severity>critical</severity> </event> <event xmlns="http://example.com/event/1.0"> <severity>major</severity> </event> <event xmlns="http://example.com/event/1.0"> <severity>minor</severity> </event> </netconf:filter> </create-subscription> </rpc> The following example illustrates selecting state or config EventClasses or fault eventsdata 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 filter elements arerelatedapplied does not matter since the resulting set of notifications is the intersection of the set of notifications that pass each filtering criteria. 3.6.1. Named Profiles A named profile is a filter that is created ahead of time and applied at the time an event notification subscription is created. Note that changes tocard Ethernet0. Thethe 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 Inline filteringcriteria evaluationis explicitly stated when the event notification subscription is created. This is specified via the 'filter' parameter. Filters only exist asfollows: ( state | config | fault & card=Ethernet0)parameters to the subscription. 3.7. Message Flow Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page24]21] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007<rpc message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> <create-subscription> <netconf:filter type="subtree"> xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <event xmlns="http://example.com/event/1.0"> <events> <eventEntry> <eventClass>fault</eventClass> </eventEntry> <eventEntry> <eventClass>state</eventClass> </eventEntry> <eventEntry> <eventClass>config</eventClass> </eventEntry> <eventEntry> <eventClass>fault</eventClass> <reportingElement> <card>Ethernet0</card> </reportingElement> </eventEntry> </events> </event> </netconf:filter> </create-subscription> </rpc> 5.2. XPATH filtersThe 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))) <rpc message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> <create-subscription> <netconf:filter type="xpath" select="event/eventClasses/fault'figure depicts message flow between a NETCONF client (C) and(event[severity='critical'] or event[severity='major'] or event[severity='minor')))"/> </create-subscription> Chisholm & Trevino Expires August 24, 2007 [Page 25] Internet-DraftNETCONFEvent Notifications February 2007 </rpc> The following example illustrates selecting stateserver (S) in order create a subscription andconfig EventClasses or fault events that have severitiesbegin the flow ofcritical, major, or minornotifications. It is possible that many rpc/rpc-reply sequences occur before the subscription is created orcome from card Ethernet0. The filtering criteria evaluationafter a stopTime in a replay subscription, but this isas follows: (( statenot depicted in the figure. C S |config) & ((fault & severity=critical)|(fault & severity=major)|(fault & severity = minor)capability exchange | |-------------------------->| |<------------------------->| | | |(fault & card=Ethernet0))) <rpc message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"><create-subscription><netconf:filter type="xpath" 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']))"/> </create-subscription> </rpc>| |-------------------------->| |<--------------------------| | <rpc-reply> | | | | <notification> | |<--------------------------| | | | <notification> | |<--------------------------| | | | | | | | <notification> | |<--------------------------| | | | | Figure 8 Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page26]22] Internet-Draft NETCONF Event NotificationsFebruaryMay 20076. Notification Replay 6.1. Overview Replay is4. XML Schema for Event Notifications The following [XML Schema] defines NETCONF Event Notifications. <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:ietf:params:netconf:capability:notification:1.0" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0" targetNamespace= "urn:ietf:params:netconf:capability:notification:1.0" elementFormDefault="qualified" attributeFormDefault="unqualified" xml:lang="en"> <!-- import standard XML definitions --> <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd"> <xs:annotation> <xs:documentation> This import accesses theability to create an event subscription that will resend recently sent notifications. These notifications are sentxml: attribute groups for thesame wayxml:lang asnormal notifications. A replaydeclared on the error-message element. </xs:documentation> </xs:annotation> </xs:import> <!-- import base netconf definitions --> <xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0" schemaLocation="urn:ietf:params:xml:ns:netconf:base:1.0" /> <!-- ************** Symmetrical Operations ********************--> <!-- <create-subscription> operation --> <xs:complexType name="createSubscriptionType"> <xs:complexContent> <xs:extension base="netconf:rpcOperationType"> <xs:sequence> <xs:element name="stream" type="streamNameType" minOccurs="0"> <xs:annotation> <xs:documentation> An optional parameter that indicates which stream ofnotificationsevents isspecified by including anof interest. If Chisholm & Trevino Expires November 16, 2007 [Page 23] Internet-Draft NETCONF Event Notifications May 2007 not present, then events in the default NETCONF stream will be sent. </xs:documentation> </xs:annotation> </xs:element> <xs:choice> <xs:element name="filter" type="netconf:filterInlineType" minOccurs="0"> <xs:annotation> <xs:documentation> An optional parameterto the subscription commandthat indicates which subset of all possible events are of interest. The format of this parameter is thestart timesame as that of thereplay. The end timefilter parameter in the NETCONF protocol operations. If not present, all events not precluded by other parameters will be sent. This isspecified usingmutually exclusive with theoptional stopTimenamed profile parameter. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="named-profile" type="namedProfileType" minOccurs="0"> <xs:annotation> <xs:documentation> An optional parameter that points to a separately defined filter profile. If not present,notificationsno additional filtering willcontinue tobesent untilapplied. Note that changes to the profile after the subscription has been created will have no effect. This isterminated.mutually exclusive with the filter parameter. </xs:documentation> </xs:annotation> </xs:element> </xs:choice> <xs:element name="startTime" type="xs:dateTime" minOccurs="0" > <xs:annotation> <xs:documentation> Anotification stream that supports replay is not expected to have an unlimited supply of saved notifications availableparameter used toaccommodate any replay request. If a client requests atrigger the replayof notificationsfeature and indicates thatpredatetheoldest notification available, thenreplay should start at theNETCONF server 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. The warning message enables the NETCONF client to differentiate between the case that there were no notifications generated within a giventimeperiod 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 givenspecified. If start time isan NETCONF server implementation specific matter. Control parameters fornot present, thisaspect of the feature are outside the scope of the current work. This featureisdependent on a notification stream supporting 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. 6.2. Creatingnot aSubscriptionChisholm & Trevino Expires November 16, 2007 [Page 24] Internet-Draft NETCONF Event Notifications May 2007 replay subscription. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="stopTime" type="xs:dateTime" minOccurs="0" > <xs:annotation> <xs:documentation> An optional parameter used withReplay This feature usesthe optionalparametersreplay feature to indicate the<create-subscription> command called 'startTime' and 'stopTime'. 'startTime' identifies the earliest date and time of interest for eventnewest notificationsbeing replayed and also indicates that a subscription will be providing replay of notifications. Events generated before this time are not matched. 'stopTime' specifies the latest date and timeofinterest for event notifications being replayed.interest. Ifitstop time is not present,thenthe notifications will continueto be sentuntil the subscription is terminated.Note that whileMust be used with 'startTime'. </xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:extension> </xs:complexContent> </xs:complexType> <xs:simpleType name="namedProfileType"> <xs:annotation> <xs:documentation> The name of anotification has three potential times associated Chisholmsaved profile containing filtering elements. </xs:documentation> </xs:annotation> <xs:restriction base="xs:string"/> </xs:simpleType> <xs:simpleType name="streamNameType"> <xs:annotation> <xs:documentation> The name of an event stream. </xs:documentation> </xs:annotation> <xs:restriction base="xs:string"/> </xs:simpleType> <xs:element name="create-subscription" type="createSubscriptionType" substitutionGroup="netconf:rpcOperation"> <xs:annotation> <xs:documentation> Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page27]25] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007it -The command to create a notification subscription. It takes as argument thetime it was generated,name of thetime it was loggednotification stream and filter or profile information. All of those options limit thetime it was sent out by the NETCONF server -content of the subscription. In addition, there are two time-related parameters startTime and stopTimeparameters are relatedwhich can be used togeneration time. Inselect theevent of an error with severitytime interval ofwarning,interest. </xs:documentation> </xs:annotation> </xs:element> <!-- ************** One-way Operations ******************--> <!-- <Notification> operation --> <xs:complexType name="NotificationType"> <xs:sequence> <xs:element name="data" type="netconf:dataInlineType" /> </xs:sequence> </xs:complexType> <xs:element name="notification" type="NotificationType"/> </xs:schema> Chisholm & Trevino Expires November 16, 2007 [Page 26] Internet-Draft NETCONF Event Notifications May 2007 5. Filtering Examples The following section provides examples to illustrate thesubscription will still be created. Negative Response: An <rpc-error> elementvarious methods of filtering content on an event notification subscription. 5.1. Subtree Filtering XML subtree filtering isincluded in the <rpc-reply> if the startTimenot well suited for creating elaborate filter definitions given that it only supports equality comparisons and logical OR operations (e.g., inreplay request predates the oldestan 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 notificationavailableforwarding filters as shown below. In order tobe replayed or ifillustrate thestopTimeuse of filter expressions it isearlier then the startTime. Error-tag: start-time-too-early Error-type: protocol Error-severity: warning Error-info: <log-startime> : Timestampnecessary to assume some ofearliestthe eventavailable for replay Error-message: Start time predates oldest availablenotificationto be replayed Error-tag: start-stop-time-mismatch Error-type: protocol Error-severity: error Error-info: none Error-message: stopTime predates startTime. 6.3. Replay Complete Notificationcontent. Thefollowing notification isexamples herein assume that thelastevent notificationsent over a replay subscription. It indicatesschema definition has an <events> element at the top level thatreplay is complete. This notification will only be sent if a 'stopTime' was specified whencontains one or more child elements <eventEntry> consisting of thereplay subscription was created. After this notificationevent class (e.g., fault, state, config, etc.) reporting entity and either severity or operational state. Chisholm & Trevino Expires November 16, 2007 [Page 27] Internet-Draft NETCONF Event Notifications May 2007 Sample event list <events> <eventEntry> <eventClass>fault</eventClass> <reportingEntity> <card>Ethernet0</card> </reportingEntity> <severity>major</severity> </eventEntry> <eventEntry> <eventClass>fault</eventClass> <reportingEntity> <card>Ethernet2</card> </reportingEntity> <severity>critical</severity> </eventEntry> <eventEntry> <eventClass>fault</eventClass> <reportingEntity> <card>ATM1</card> </reportingEntity> <severity>minor</severity> </eventEntry> <eventEntry> <eventClass>state</eventClass> <reportingEntity> <card>Ethernet0</card> </reportingEntity> <operState>enabled</operState> </eventEntry> </events> The following example illustrates selecting events which have severities of critical, major, or minor (presumably fault events). The filtering criteria evaluation isreceived the subscriptionas follows: ((severity=critical) | (severity=major) | (severity=minor)) Chisholm & Trevino Expires November 16, 2007 [Page 28] Internet-Draft NETCONF Event Notifications May 2007 <netconf:rpc message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> <create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <filter netconf:type="subtree"> <event xmlns="http://example.com/event/1.0"> <events> <eventEntry> <eventClass>fault</eventClass> <severity>critical</severity> </eventEntry> <eventEntry> <eventClass>fault</eventClass> <severity>major</severity> </eventEntry> <eventEntry> <eventClass>fault</eventClass> <severity>minor</severity> </eventEntry> </events> </event> </filter> </create-subscription> </netconf:rpc> The following example illustrates selecting state or config EventClasses or fault events that are related to card Ethernet0. The filtering criteria evaluation isterminatedas follows: ( state | config | fault & card=Ethernet0) Chisholm & Trevino Expires November 16, 2007 [Page 29] Internet-Draft NETCONF Event Notifications May 2007 <netconf:rpc message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> <create-subscription> <filter netconf:type="subtree"> xmlns="urn:ietf:params:netconf:capability:notification:1.0"> <event xmlns="http://example.com/event/1.0"> <events> <eventEntry> <eventClass>fault</eventClass> </eventEntry> <eventEntry> <eventClass>state</eventClass> </eventEntry> <eventEntry> <eventClass>config</eventClass> </eventEntry> <eventEntry> <eventClass>fault</eventClass> <reportingElement> <card>Ethernet0</card> </reportingElement> </eventEntry> </events> </event> </filter> </create-subscription> </netconf:rpc> 5.2. XPATH filters 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))) <netconf:rpc message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> <create-subscription> <filter netconf:type="xpath" select="//eventEntry[(eventClass='fault' andthe 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.(severity='minor' or severity='major' or severity='critical'))]"/> </create-subscription> </netconf:rpc> Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page28]30] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:ietf:params:xml:ns:netconf:replayNotification:1.0" targetNamespace= "urn:ietf:params:xml:ns:netconf:replayNotification:1.0"> <xs:element name="replayCompleteNotification" > <xs:annotation> <xs:documentation> This notification is sent to signal the end of a replay subscription. </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="eventClass" default="informational"> <xs:annotation> <xs:documentation>Theevent classificationfollowing example illustrates selecting state and config EventClasses or fault events that have severities ofthis notification. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="timeGenerated" type="xs:dateTime"/> <xs:element name="numberEventsReplayed" type="xs:integer"/> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>critical, major, or minor or come from card Ethernet0. The filtering criteria evaluation is as follows: (( state | config) & ((fault & severity=critical) | (fault & severity=major) | (fault & severity = minor) | (fault & card=Ethernet0))) <netconf:rpc message-id="101" xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> <create-subscription> <filter netconf:type="xpath" select="//eventEntry[(eventClass='fault' and severity='minor') or (eventClass='fault' and severity='major') or (eventClass='fault' and severity='critical') or (eventClass='fault' and card='Ethernet0') or eventClass='state' or eventClass='config']"/> </create-subscription> </netconf:rpc> Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page29]31] Internet-Draft NETCONF Event NotificationsFebruaryMay 20077.6. Security Considerations The security considerations from the base [NETCONF] document apply also to the Notification capability. The access control framework and the choice of transport will have a major impact on the security of the solution. Note that the <notification> 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 <create-subscription> invocation ouse of <kill-session> oread-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. 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. Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page30]32] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 7. IANA Considerations This document registers two URIs for the NETCONF XML namespace in the IETF XML registry [7]. 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 Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace. Chisholm & Trevino Expires November 16, 2007 [Page 33] Internet-Draft NETCONF Event Notifications May 2007 8. 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, RobEnnes,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. Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page31]34] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 9. Normative References [NETCONF] Enns, R., "NETCONF Configuration Protocol",ID draft-ietf-netconf-prot-12, FebruaryRFC 4741, December 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 Levels", RFC 2119, March 1997. [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", RFC 2223, October 1997. [XML] World Wide Web Consortium, "Extensible Markup Language (XML) 1.0", W3C XML, February 1998, <http://www.w3.org/TR/1998/REC-xml-19980210>. [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. Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page32]35] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 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 Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page33]36] Internet-Draft NETCONF Event NotificationsFebruaryMay 2007 Full Copyright Statement 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, 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 on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of 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. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Chisholm & Trevino ExpiresAugust 24,November 16, 2007 [Page34]37] ----