idnits 2.17.1 draft-ietf-netconf-notification-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 1357. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1368. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1375. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1381. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Bad filename characters: the document name given in the document, 'draft-ietf-netconf-notification-08.txt.pre-release', contains other characters than digits, lowercase letters and dash. ** Missing revision: the document name given in the document, 'draft-ietf-netconf-notification-08.txt.pre-release', does not give the document revision number ~~ Missing draftname component: the document name given in the document, 'draft-ietf-netconf-notification-08.txt.pre-release', does not seem to contain all the document name components required ('draft' prefix, document source, document name, and revision) -- see https://www.ietf.org/id-info/guidelines#naming for more information. == Mismatching filename: the document gives the document name as 'draft-ietf-netconf-notification-08.txt.pre-release', but the file name used is 'draft-ietf-netconf-notification-08' Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 906 has weird spacing: '... and filte...' == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- The document date (July 8, 2007) is 6109 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2026' is defined on line 1177, but no explicit reference was found in the text == Unused Reference: 'RFC2223' is defined on line 1183, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4741 (ref. 'NETCONF') (Obsoleted by RFC 6241) ** Obsolete normative reference: RFC 2223 (Obsoleted by RFC 7322) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' Summary: 5 errors (**), 1 flaw (~~), 6 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Chisholm 3 Internet-Draft Nortel 4 Intended status: Standards Track H. Trevino 5 Expires: January 9, 2008 Cisco 6 July 8, 2007 8 NETCONF Event Notifications 9 draft-ietf-netconf-notification-08.txt.pre-release 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on January 9, 2008. 36 Copyright Notice 38 Copyright (C) The IETF Trust (2007). 40 Abstract 42 This document defines mechanisms which provide an asynchronous 43 message notification delivery service for the NETCONF protocol. This 44 is an optional capability built on top of the base NETCONF 45 definition. This document defines the capabilities and operations 46 necessary to support this service. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 51 1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 4 52 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 53 1.3. Event Notifications in NETCONF . . . . . . . . . . . . . . 5 54 1.4. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6 55 2. Notification-Related Operations . . . . . . . . . . . . . . . 7 56 2.1. Subscribing to Receive Event Notifications . . . . . . . . 7 57 2.1.1. . . . . . . . . . . . . . . . . 7 58 2.2. Sending Event Notifications . . . . . . . . . . . . . . . 9 59 2.2.1. . . . . . . . . . . . . . . . . . . . . 9 60 2.3. Terminating the Subscription . . . . . . . . . . . . . . . 10 61 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 11 62 3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 11 63 3.1.1. Capability Identifier . . . . . . . . . . . . . . . . 11 64 3.1.2. Capability Example . . . . . . . . . . . . . . . . . . 11 65 3.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 11 66 3.2.1. Event Stream Definition . . . . . . . . . . . . . . . 12 67 3.2.2. Event Stream Content Format . . . . . . . . . . . . . 13 68 3.2.3. Default Event Stream . . . . . . . . . . . . . . . . . 13 69 3.2.4. Event Stream Sources . . . . . . . . . . . . . . . . . 13 70 3.2.5. Event Stream Discovery . . . . . . . . . . . . . . . . 13 71 3.3. Notification Replay . . . . . . . . . . . . . . . . . . . 15 72 3.3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 15 73 3.3.2. Creating a Subscription with Replay . . . . . . . . . 16 74 3.3.3. Replay Complete Notification . . . . . . . . . . . . . 16 75 3.4. Notification Management Schema . . . . . . . . . . . . . . 16 76 3.5. Subscriptions Data . . . . . . . . . . . . . . . . . . . . 19 77 3.6. Filter Mechanics . . . . . . . . . . . . . . . . . . . . . 19 78 3.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 19 79 3.7. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 19 80 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 21 81 5. Filtering Examples . . . . . . . . . . . . . . . . . . . . . . 25 82 5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 25 83 5.2. XPATH filters . . . . . . . . . . . . . . . . . . . . . . 28 84 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 85 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 86 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 32 87 9. Normative References . . . . . . . . . . . . . . . . . . . . . 33 88 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 34 89 A.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 34 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 37 91 Intellectual Property and Copyright Statements . . . . . . . . . . 38 93 1. Introduction 95 [NETCONF] can be conceptually partitioned into four layers: 97 Layer Example 98 +-------------+ +----------------------------------------+ 99 | Content | | Configuration data | 100 +-------------+ +----------------------------------------+ 101 | | 102 +-------------+ +-------------------------------------------+ 103 | Operations | | , | 104 +-------------+ +-------------------------------------------+ 105 | | | 106 +-------------+ +-----------------------------+ | 107 | RPC | | , | | 108 +-------------+ +-----------------------------+ | 109 | | | 110 +-------------+ +------------------------------------------+ 111 | Transport | | BEEP, SSH, SSL, console | 112 | Protocol | | | 113 +-------------+ +------------------------------------------+ 115 Figure 1 117 This document defines mechanisms which provide an asynchronous 118 message notification delivery service for the [NETCONF] protocol. 119 This is an optional capability built on top of the base NETCONF 120 definition. This memo defines the capabilities and operations 121 necessary to support this service. 123 1.1. Definition of Terms 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 127 document are to be interpreted as described in [RFC2119]. 129 Element: An [XML] Element. 131 Subscription: An agreement and method to receive event notifications 132 over a NETCONF session. A concept related to the delivery of 133 notifications (if any to send) involving destination and selection 134 of notifications. It is bound to the lifetime of a session. 136 Operation: This term is used to refer to NETCONF protocol operations 137 [NETCONF]. Specifically within this document, operation refers to 138 NETCONF protocol operations defined in support of NETCONF 139 notifications. 141 Event: An event is something that happens which may be of interest - 142 a configuration change, a fault, a change in status, crossing a 143 threshold, or an external input to the system, for example. Often 144 this results in an asynchronous message, sometimes referred to as 145 a notification or event notification, being sent to interested 146 parties to notify them that this event has occurred. 148 Replay: The ability to send/re-send previously logged notifications 149 upon request. These notifications are sent asynchronously. This 150 feature is implemented by the NETCONF server and invoked by the 151 NETCONF client. 153 Stream: An event stream is a set of event notifications matching 154 some forwarding criteria and it is available to NETCONF clients 155 for subscription. 157 Filter: A parameter that indicates which subset of all possible 158 events are of interest. 160 1.2. Motivation 162 The motivation for this work is to enable the sending of asynchronous 163 messages that are consistent with the data model (content) and 164 security model used within a NETCONF implementation. 166 1.3. Event Notifications in NETCONF 168 This memo defines a mechanism whereby the NETCONF client indicates 169 interest in receiving event notifications from a NETCONF server by 170 creating a subscription to receive event notifications. The NETCONF 171 server replies to indicate whether the subscription request was 172 successful and, if it was successful, begins sending the event 173 notifications to the NETCONF client as the events occur within the 174 system. These event notifications will continue to be sent until 175 either the NETCONF session is terminated or the subscription 176 terminates for some other reason. The event notification 177 subscription allows a number of options to enable the NETCONF client 178 to specify which events are of interest. These are specified when 179 the subscription is created. 181 A NETCONF server is will not read RPC requests, by default, on the 182 session associated with the subscription until the notification 183 subscription is done. A capability may be advertised to announce 184 that a server is able to process RPCs while a notification stream is 185 active on a session. The behaviour of such a capability is outside 186 the scope of this document. 188 1.4. Requirements 190 The following requirements have been addressed by the solution: 192 o Initial release should ensure it supports notification in support 193 of configuration operations 195 o Data content must not preclude the use of the same data model as 196 used in configuration 198 o Solution should support a reasonable message size limit (ie, not 199 too short) 201 o Solution should provide reliable delivery of notifications 203 o Solution should provide a subscription mechanism (A NETCONF server 204 does not send notifications before being asked to do so and the 205 NETCONF client initiates the flow of notifications) 207 o Solution should provide a filtering mechanism within the NETCONF 208 server 210 o Solution should send sufficient information in a notification so 211 that it can be analyzed independent of the transport mechanism 212 (data content fully describes a notification; protocol information 213 is not needed to understand a notification) 215 o Solution should support replay of locally logged notifications 217 2. Notification-Related Operations 219 2.1. Subscribing to Receive Event Notifications 221 The event notification subscription is initiated by the NETCONF 222 client and responded to by the NETCONF server. When the event 223 notification subscription is created, the events of interest are 224 specified. 226 Content for an event notification subscription can be selected by 227 applying user-specified filters. 229 2.1.1. 231 Description: 233 This operation initiates an event notification subscription which 234 will send asynchronous event notifications to the initiator of the 235 command until the subscription terminates. 237 Parameters: 239 Stream: 241 An optional parameter that indicates which stream of events is 242 of interest. If not present, then events in the default 243 NETCONF stream will be sent. 245 Filter: 247 An optional parameter that indicates which subset of all 248 possible events are of interest. The format of this parameter 249 is the same as that of the filter parameter in the NETCONF 250 protocol operations. If not present, all events not precluded 251 by other parameters will be sent. See section 3.6 for more 252 information on filters. 254 Start Time: 256 A parameter used to trigger the replay feature and indicate 257 that the replay should start at the time specified. If 258 startTime is not present, this is not a replay subscription. 259 It is valid to specify start times that are later than the 260 current time. If the startTime specified is earlier than the 261 log can support, the replay will begin with the earliest 262 available notification. This parameter is of type dateTime. 264 Stop Time: 266 An optional parameter used with the optional replay feature to 267 indicate the newest notifications of interest. If stop time is 268 not present, the notifications will continue until the 269 subscription is terminated. Must be used with and be later 270 than 'startTime'. It is valid to specify stop times that are 271 later than the current time. This parameter is of type 272 dateTime. 274 Positive Response: 276 If the NETCONF server can satisfy the request, the server sends an 277 element. 279 Negative Response: 281 An element is included within the if the 282 request cannot be completed for any reason. Subscription requests 283 will fail if a filter with invalid syntax is provided or if the 284 name of a non-existent profile or stream is provided. 286 If a stopTime is specified in a request without having specified a 287 startTime the following error is returned: 289 Tag: missing-element 291 Error-type: protocol 293 Severity: error 295 Error-info: : startTime 297 Description: An expected element is missing. 299 If the optional replay feature is requested but it is not 300 supported by the NETCONF server, the following error is returned: 302 Tag: operation-failed 304 Error-type: protocol 306 Severity: error 308 Error-info: none 309 Description: Request could not be completed because the 310 requested operation failed for some reason not covered by any 311 other error condition 313 2.1.1.1. Usage Example 315 317 319 320 322 Figure 2 324 2.2. Sending Event Notifications 326 Once the subscription has been set up, the NETCONF server sends the 327 event notifications asynchronously over the connection. 329 2.2.1. 331 Description: 333 An event notification is sent to the client who initiated a 334 command asynchronously when an event of 335 interest (i.e., meeting the specified filtering criteria) to them 336 has occurred. An event notification is a complete and well-formed 337 XML document. Note that is not an RPC method but 338 rather the top level element identifying the one way message as a 339 notification. 341 Parameters: 343 Contains notification-specific tagged content. The content of 344 the data tag is beyond the scope of this document. 346 Response: 348 No response. Not applicable. 350 2.3. Terminating the Subscription 352 Closing of the event notification subscription can be done by 353 terminating the NETCONF session ( ) or the underlying 354 transport session. If a stop time is provided when the subscription 355 is created, then the subscription will terminate after the stop time 356 is reached. In this case, the NETCONF session will still be an 357 active session. 359 3. Supporting Concepts 361 3.1. Capabilities Exchange 363 The ability to process and send event notifications is advertised 364 during the capability exchange between the NETCONF client and server. 366 3.1.1. Capability Identifier 368 "urn:ietf:params:netconf:capability:notification:1.0" 370 3.1.2. Capability Example 372 373 374 375 urn:ietf:params:xml:ns:netconf:base:1.0 376 377 378 urn:ietf:params:netconf:capability:startup:1.0 379 380 381 urn:ietf:params:netconf:capability:notification:1.0 382 383 384 4 385 387 Figure 3 389 3.2. Event Streams 391 An event stream is defined as a set of event notifications matching 392 some forwarding criteria. 394 The diagram depicted in Figure 2 illustrates the notification flow 395 and concepts identified in this document. The following is observed 396 from the diagram below: System components (c1..cn) generate event 397 notifications which are passed to a central component for 398 classification and distribution. The central component inspects each 399 event notification and matches the event notification against the set 400 of stream definitions. When a match occurs, the event notification 401 is considered to be a member of that event stream (stream 1..stream 402 n). An event notification may be part of multiple event streams. 404 When a NETCONF client subscribes to a given event stream, user- 405 defined filters, if applicable, are applied to the event stream and 406 matching event notifications are forwarded to the NETCONF server for 407 distribution to subscribed NETCONF clients. For more information on 408 filters, see section 3.6. 410 A notification logging service may also be available, in which case, 411 the central component logs notifications. The NETCONF server may 412 later retrieve logged notifications via the optional replay feature. 413 For more information on replay, see section 3.3. 415 +----+ 416 | c1 |----+ available streams 417 +----+ | +---------+ 418 +----+ | |central |-> stream 1 419 | c2 | +--->|event |-> stream 2 filter +-------+ 420 +----+ | |processor|-> NETCONF stream ----->|netconf| 421 ... | | |-> stream n |server | 422 System | +---------+ +-------+ 423 Components| | /\ 424 ... | | || 425 +----+ | | (------------) || 426 | cn |----+ | (notification) || 427 +----+ +-----> ( logging ) || 428 ( service ) || 429 (------------) || 430 || 431 || 432 \/ 433 +-------+ 434 |netconf| 435 |client | 436 +-------+ 438 Figure 4 440 3.2.1. Event Stream Definition 442 Event streams are predefined on the managed device. The 443 configuration of event streams is outside the scope of this document. 444 However, it is envisioned that event streams are either pre- 445 established by the vendor (pre-configured) or user configurable 446 (e.g., part of the device's configuration) or both. Device vendors 447 may allow event stream configuration via NETCONF protocol (i.e., 448 edit-config operation). 450 3.2.2. Event Stream Content Format 452 The contents of all event streams made available to a NETCONF client 453 (i.e., the notification sent by the NETCONF server) must be encoded 454 in XML. 456 3.2.3. Default Event Stream 458 A NETCONF server implementation supporting the notification 459 capability must support the "NETCONF" notification event stream. 460 This stream contains all NETCONF XML event notifications supported by 461 the NETCONF server. The definition of the event notifications and 462 their contents for this event stream is outside the scope of this 463 document. 465 3.2.4. Event Stream Sources 467 With the exception of the default event stream (NETCONF 468 notifications) specification of additional event stream sources 469 (e.g., SNMP, syslog, etc.) is outside the scope of this document. 470 NETCONF server implementations may leverage any desired event stream 471 source in the creation of supported event streams. 473 3.2.5. Event Stream Discovery 475 A NETCONF client retrieves the list of supported event streams from a 476 NETCONF server using the RPC request. 478 3.2.5.1. Name Retrieval using operation 480 The list of available event streams is retrieved by requesting the 481 subtree via a operation. Available event 482 streams for the requesting session are returned in the reply 483 containing the and elements, where the 484 element is mandatory and its value is unique within the scope of a 485 NETCONF server. The returned list must only include the names of 486 those event streams for which the NETCONF session has sufficient 487 privileges. The NETCONF session privileges are determined via access 488 control mechanisms which are beyond the scope of this document. An 489 empty reply is returned if there are no available event streams. The 490 information is retrieved by requesting the subtree via 491 a operation. 493 Example: Retrieving available event stream list using 494 operation: 496 499 500 501 502 503 504 506 Figure 5 508 The NETCONF server returns a list of event streams available for 509 subscription: NETCONF, SNMP, and syslog-critical in this example. 511 513 514 515 516 NETCONF 517 Default netconf event stream 518 519 true 520 2007-07-08T00:00:00Z 521 522 523 SNMP 524 SNMP notifications 525 false 526 527 528 syslog-critical 529 Critical and higher severity 530 531 true 532 2007-07-01T00:00:00Z 533 534 535 536 537 Figure 6 539 3.2.5.2. Event Stream Subscription 541 A NETCONF client may request from the NETCONF server the list of 542 event streams available to this session and then issue a request with the desired event stream name. Omitting 544 the event stream name from the request results 545 in subscription to the default NETCONF event stream. 547 3.2.5.2.1. Filtering Event Stream Contents 549 The set of event notifications delivered in an event stream may be 550 further refined by applying a user-specified filter at subscription 551 creation time ( ). This is a transient filter 552 associated with the event notification subscription and does not 553 modify the event stream configuration. 555 XPATH support for the Notification capability is advertised as part 556 of the normal XPATH capability advertisement. If XPATH support is 557 advertised via the XPATH capability then XPATH is supported for 558 notification filtering and if this capability is not advertised, then 559 XPATH is not supported for notification filtering. 561 3.3. Notification Replay 563 3.3.1. Overview 565 Replay is the ability to create an event subscription that will 566 resend recently generated notifications, or in some cases send them 567 for the first time to a particular NETCONF client. These 568 notifications are sent the same way as normal notifications. 570 A replay of notifications is specified by including an optional 571 parameter to the subscription command that indicates the start time 572 of the replay. The end time is specified using the optional stopTime 573 parameter. If not present, notifications will continue to be sent 574 until the subscription is terminated. 576 A notification stream that supports replay is not expected to have an 577 unlimited supply of saved notifications available to accommodate any 578 replay request. 580 The actual number of stored notifications available for retrieval at 581 any given time is a NETCONF server implementation specific matter. 582 Control parameters for this aspect of the feature are outside the 583 scope of the current document. 585 Replay is dependent on a notification stream supporting some form of 586 notification logging, although it puts no restrictions on the size or 587 form of the log, nor where it resides within the device. Whether or 588 not a stream supports replay can be discovered by doing a 589 operation on the eventStreams element of the Notification Management 590 Schema. This schema also provides the replayLogStartTime element to 591 indicate the earliest available logged notification. 593 3.3.2. Creating a Subscription with Replay 595 This feature uses optional parameters to the 596 command called 'startTime' and 'stopTime'. 'startTime' identifies the 597 earliest date and time of interest for event notifications being 598 replayed and also indicates that a subscription will be providing 599 replay of notifications. Events generated before this time are not 600 matched. 'stopTime' specifies the latest date and time of interest 601 for event notifications being replayed. If it is not present, then 602 notifications will continue to be sent until the subscription is 603 terminated. 605 Note that startTime and stopTime are associated with the time an 606 event was generated by the system. 608 A replayComplete notification is sent to indicate that all of the 609 replay notifications have been sent. If this subscription has a stop 610 time, then this session becomes a normal NETCONF session again. In 611 the case of a subscription without a stop time, after the 612 replayComplete notification has been sent, it can be expected that 613 any notifications generated since the start of the subscription 614 creation will be sent followed by notifications as they arise 615 naturally within the system. 617 3.3.3. Replay Complete Notification 619 The replayComplete notification is the last notification sent over a 620 replay subscription. It indicates that replay is complete. After 621 this notification is received the subscription is terminated and the 622 session becomes normal command-response NETCONF session. 624 The replayComplete can not be filtered out. It will always be sent 625 on a relay subscription that specified a stop time. 627 3.4. Notification Management Schema 629 This Schema is used to learn about the event streams supported on the 630 system. It also contains the definition of the replayComplete, which 631 is sent to indicate that an event replay has sent all applicable 632 notifications." 634 635 642 643 644 A schema that can be used to learn about current 645 event streams. It also 646 contains the replayComplete notification. 647 648 650 652 655 660 662 663 664 665 666 667 The list of event streams supported by the 668 system. When a query is issued, the returned 669 set of streams is determined based on user 670 privileges. 671 672 673 674 675 676 677 678 Stream name and description. 679 680 681 682 683 684 686 688 690 691 692 The start time of the log used to 693 support the replay function. This 694 object MUST be present if replay is 695 supported. 696 697 698 699 700 701 702 703 704 705 706 708 709 710 711 712 714 717 718 719 This notification is sent to signal the end of a replay 720 portion of a subscription. 721 722 724 725 727 Figure 7 729 3.5. Subscriptions Data 731 While it may be possible to retrieve information about subscriptions 732 via a get operation, subscriptions are not stored configuration. 733 They are non-persistent state information and their lifetime is 734 defined by their session. 736 3.6. Filter Mechanics 738 When multiple filter elements are specified, they are applied 739 collectively, so event notifications need to pass all specified 740 filters in order to be sent to the subscriber. If a filter element 741 is specified to look for data of a particular value, and the data 742 item is not present within a particular event notification for its 743 value to be checked against, the notification will be filtered out. 744 For example, if one were to check for 'severity=critical' in a 745 configuration event notification where this field was not supported, 746 then the notification would be filtered out. 748 The order that filter elements are applied does not matter since the 749 resulting set of notifications is the intersection of the set of 750 notifications that pass each filtering criteria. 752 3.6.1. Filtering 754 Filtering is explicitly stated when the event notification 755 subscription is created. This is specified via the 'filter' 756 parameter. Filters only exist as parameters to the subscription. 758 3.7. Message Flow 759 The following figure depicts message flow between a NETCONF client 760 (C) and NETCONF server (S) in order create a subscription and begin 761 the flow of notifications. It is possible that many rpc/rpc-reply 762 sequences occur before the subscription is created or after a 763 stopTime in a replay subscription, but this is not depicted in the 764 figure. 766 C S 767 | | 768 | capability exchange | 769 |-------------------------->| 770 |<------------------------->| 771 | | 772 | | 773 |-------------------------->| 774 |<--------------------------| 775 | | 776 | | 777 | | 778 |<--------------------------| 779 | | 780 | | 781 |<--------------------------| 782 | | 783 | | 784 | | 785 | | 786 |<--------------------------| 787 | | 788 | | 790 Figure 8 792 4. XML Schema for Event Notifications 794 The following [XML Schema] defines NETCONF Event Notifications. 796 797 806 808 810 811 812 This import accesses the xml: attribute groups for the 813 xml:lang as declared on the error-message element. 814 815 816 818 819 823 825 827 828 829 830 831 833 834 835 An optional parameter that indicates 836 which stream of events is of interest. If 837 not present, then events in the default 838 NETCONF stream will be sent. 839 840 841 842 845 846 847 An optional parameter that indicates 848 which subset of all possible events 849 are of interest. The format of this 850 parameter is the same as that of the 851 filter parameter in the NETCONF 852 protocol operations. If not present, 853 all events not precluded by other 854 parameters will be sent. 855 856 857 858 860 861 862 A parameter used to trigger the replay 863 feature and indicates that the replay 864 should start at the time specified. If 865 start time is not present, this is not a 866 replay subscription. 867 868 869 870 872 873 874 An optional parameter used with the 875 optional replay feature to indicate the 876 newest notifications of interest. If 877 stop time is not present, the 878 notifications will continue until the 879 subscription is terminated. Must be used 880 with 'startTime'. 881 882 883 885 886 887 888 890 891 892 893 The name of an event stream. 894 895 896 897 899 902 903 904 The command to create a notification subscription. It 905 takes as argument the name of the notification stream 906 and filter or profile information. All of those options 907 limit the content of the subscription. In addition, 908 there are two time-related parameters startTime and 909 stopTime which can be used to select the time interval 910 of interest. 911 912 913 915 917 918 920 923 924 925 926 927 929 931 933 Figure 9 935 5. Filtering Examples 937 The following section provides examples to illustrate the various 938 methods of filtering content on an event notification subscription. 940 5.1. Subtree Filtering 942 XML subtree filtering is not well suited for creating elaborate 943 filter definitions given that it only supports equality comparisons 944 and logical OR operations (e.g., in an event subtree give me all 945 event notifications which have severity=critical or severity=major or 946 severity=minor). Nevertheless, it may be used for defining simple 947 event notification forwarding filters as shown below. 949 In order to illustrate the use of filter expressions it is necessary 950 to assume some of the event notification content. The examples 951 herein assume that the event notification schema definition has an 952 element at the top level that contains one or more child 953 elements consisting of the event class (e.g., fault, 954 state, config, etc.) reporting entity and either severity or 955 operational state. 957 Sample event list 959 960 fault 961 962 Ethernet0 963 964 major 965 967 968 fault 969 970 Ethernet2 971 972 critical 973 975 976 fault 977 978 ATM1 979 980 minor 981 983 984 state 985 986 Ethernet0 987 988 enabled 989 991 Figure 10 993 The following example illustrates selecting events which have 994 severities of critical, major, or minor (presumably fault events). 995 The filtering criteria evaluation is as follows: 997 ((severity=critical) | (severity=major) | (severity=minor)) 998 1000 1002 1003 1004 fault 1005 critical 1006 1007 1008 fault 1009 major 1010 1011 1012 fault 1013 minor 1014 1015 1016 1017 1019 Figure 11 1021 The following example illustrates selecting state or config 1022 EventClasses or fault events that are related to card Ethernet0. The 1023 filtering criteria evaluation is as follows: 1025 ( state | config | fault & card=Ethernet0) 1026 1028 1030 1031 1032 fault 1033 1034 1035 state 1036 1037 1038 config 1039 1040 1041 fault 1042 1043 Ethernet0 1044 1045 1046 1047 1048 1050 5.2. XPATH filters 1052 The following [XPATH] example illustrates selecting fault EventClass 1053 notifications that have severities of critical, major, or minor. The 1054 filtering criteria evaluation is as follows: 1056 ((fault) & ((severity=critical) | (severity=major) | (severity = 1057 minor))) 1059 1061 1063 1068 1069 1070 Figure 13 1072 The following example illustrates selecting state and config 1073 EventClasses or fault events that have severities of critical, major, 1074 or minor or come from card Ethernet0. The filtering criteria 1075 evaluation is as follows: 1077 (( state | config) & ((fault & severity=critical) | (fault & 1078 severity=major) | (fault & severity = minor) | (fault & 1079 card=Ethernet0))) 1081 1083 1085 1095 1096 1098 Figure 14 1100 6. Security Considerations 1102 The security considerations from the base [NETCONF] document apply 1103 also to the Notification capability. 1105 The access control framework and the choice of transport will have a 1106 major impact on the security of the solution. 1108 The elements are never sent before the transport layer 1109 and the netconf layer (capabilities exchange) have been established, 1110 and the manager has been identified and authenticated. 1112 It is recommended that care be taken to ensure the secure operation 1113 of the following commands: 1115 o invocation 1117 o read-only data models 1119 o read-write data models 1121 o notification content 1123 One issue related to the notifications draft is the transport of data 1124 from non-netconf streams, such as syslog and SNMP. This data may be 1125 more vulnerable (or is not more vulnerable) when being transported 1126 over netconf than when being transported using the protocol normally 1127 used for transporting it, depending on the security credentials of 1128 the two subsystems. The NETCONF server is responsible for providing 1129 access control to stream content. 1131 If a user does not have permission to view content via other NETCONF 1132 operations it does not have permission to access that content via 1133 Notifications. If a user is not permitted to view one element in the 1134 content of the notification, the notification is not sent to that 1135 user. 1137 If a subscription is created with a stopTime, the NETCONF session 1138 will return to being a normal command-response NETCONF session when 1139 the replay is completed. It is the responsibility of the NETCONF 1140 client to close off this session when it is no longer of use. 1142 7. IANA Considerations 1144 This document registers two URIs for the NETCONF XML namespace in the 1145 IETF XML registry [RFC3688]. 1147 Following the format in RFC 3688, IANA has made the following 1148 registration. 1150 URI: urn:ietf:params:netconf:capability:notification:1.0 1152 URI: urn:ietf:params:xml:ns:netmod:notification 1154 Registrant Contact: The IESG. 1156 XML: N/A, the requested URI is an XML namespace. 1158 8. Acknowledgements 1160 Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing 1161 their input into the early work on this document. In addition, the 1162 editors would like to acknowledge input at the Vancouver editing 1163 session from the following people: Orly Nicklass, James Balestriere, 1164 Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, 1165 Dave Partain, Ray Atarashi and Dave Perkins and the following 1166 additional people from the Montreal editing session: Balazs Lengyel, 1167 Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen, 1168 Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig, 1169 Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William 1170 Chow. 1172 9. Normative References 1174 [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 1175 December 2006. 1177 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 1178 3", RFC 2026, BCP 9, October 1996. 1180 [RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements 1181 Levels", RFC 2119, March 1997. 1183 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 1184 RFC 2223, October 1997. 1186 [RFC3688] Bradner, s., "The IETF XML Registry", RFC 3688, January 1187 2004. 1189 [XML] World Wide Web Consortium, "Extensible Markup Language 1190 (XML) 1.0", W3C XML, February 1998, 1191 . 1193 [XML Schema] 1194 Fallside, D. and P. Walmsley, "XML Schema Part 0: Primer 1195 Second Edition", W3C XML Schema, October 2004. 1197 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 1198 Version 1.0", 1199 W3C http://www.w3.org/TR/1999/REC-xpath-19991116, 1200 November 1999. 1202 Appendix A. Change Log 1204 A.1. Version -08 1206 1. Removed named profiles 1208 2. Removed eventClass that was accidentally included in the 1209 definition of the replayComplete notification 1211 3. Deleted data wrapper from notification 1213 4. Changed replayLogStartTime to have a minOccurs of 0. It will 1214 only be there when replay is supported. Verify examples in 1215 section 3.2.5.1 are correct with respect to this element. 1217 5. Error codes in section 2.1.1, fixed formatting issue 1219 6. Moved replayComplete to not be under 1221 7. Section 2.1, fixed capitalization 1223 8. In figure 4, the line was pushed out by 'system components', 1224 fixed this. 1226 9. On page 8, replaced "If the startTime specified is earlier then 1227 the" with 'If the startTime specified is earlier than the" 1229 10. Updated some name spaces and schemaLocations as per Andy's June 1230 3rd email. 1232 11. Added discussion of replayLogStartTime to draft in section 3.3.1 1233 as follows "Whether or not a stream supports replay can be 1234 discovered by doing a operation on the eventStreams 1235 elements of the Notification Management Schema. This schema 1236 also provides the replayLogStartTime element to indicate the 1237 earliest available logged notification." 1239 12. Removed most of the uses of the phrase 'Note that'. I kept two 1240 uses that prevent sentences from starting with either a lower 1241 case letter or an angle bracket. 1243 13. In section 3.6 replaced "it will be filtered out" with "the 1244 notification will be filtered out" 1246 14. In section 3.4, replaced "and the query" with "and to query" 1248 15. Replaced 3 instances of "replay complete notification" with 1249 "replayComplete notification" 1251 16. In section 3.3.2, replaced "normal NETCONF session" with "normal 1252 command-response NETCONF session" 1254 17. In section 3.3.1, replaced "create an event subscription that 1255 will resend recently generated notification" with "create an 1256 event subscription that will resend recently generated 1257 notification, or is some cases send them for the first time to a 1258 particular NETCONF client." 1260 18. In section 3.2.5.2, s/available event streams to/event streams 1261 available to/ 1263 19. In one spot, changed snmp to SNMP (the other gets deleted) 1265 20. In section 3.2.5.1 s/where element is/where the 1266 element is/ 1268 21. In section 3.2.5.1, clarified that "value is unique" - within 1269 the scope of a NETCONF server. 1271 22. In section 2.1.1, clarified that stopTime cannot preceded start 1272 time. 1274 23. In section 2.1.1, in Start Time s/indicates/indicate/ 1276 24. In section 2.1.1, in Filter: s/This is mutually exclusive/The 1277 filter parameter is mutually exclusive/ ("this" could refer to 1278 the behavior described in the previous sentence.) 1280 25. In section 1.4, third bullet, replaced "syslog and SNMP are 1281 rather constrained in terms of message sizes)" with (ie, not too 1282 short) 1284 26. In section 1.4, made all bullets start with capital leters. 1286 27. Added definition of Filter to section 1.1 1288 28. In section 1.1, improved the definition of subscription with "An 1289 agreement and method to receive event notifications over a 1290 NETCONF session." 1292 29. In section 1.1, in the definition of operation, added a 1293 reference to [NETCONF]. 1295 30. Created a change log section 1297 31. Fixed reference to IETF XML Registry in IANA Considerations 1298 section. 1300 32. In section 3.3.3, deleted "This notification will only be sent 1301 if a 'stopTime' was specified when the replay subscription was 1302 created." 1304 33. Added text to the security considerations section that says "If 1305 a subscription is created with a stopTime, the NETCONF session 1306 will return to being a normal command-response NETCONF session 1307 when the replay is completed. It is the responsibility of the 1308 NETCONF client to close off this session when it is no longer of 1309 use". 1311 34. Update examples in section 5 to get rid of extra wrapper tag. 1313 35. In section 2.1, replace "A NETCONF server is not required to 1314 process RPC requests on the session associated with the 1315 subscription until the notification subscription is done and may 1316 silently discard these requests." with "A NETCONF server is will 1317 not read RPC requests, by default, on the session associated 1318 with the subscription until the notification subscription is 1319 done. 1321 36. Updated the notification definition and the replyComplete 1322 notification definition to use a substitution group. 1324 Authors' Addresses 1326 Sharon Chisholm 1327 Nortel 1328 3500 Carling Ave 1329 Nepean, Ontario K2H 8E9 1330 Canada 1332 Email: schishol@nortel.com 1334 Hector Trevino 1335 Cisco 1336 Suite 400 1337 9155 E. Nichols Ave 1338 Englewood, CO 80112 1339 USA 1341 Email: htrevino@cisco.com 1343 Full Copyright Statement 1345 Copyright (C) The IETF Trust (2007). 1347 This document is subject to the rights, licenses and restrictions 1348 contained in BCP 78, and except as set forth therein, the authors 1349 retain all their rights. 1351 This document and the information contained herein are provided on an 1352 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1353 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1354 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1355 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1356 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1357 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1359 Intellectual Property 1361 The IETF takes no position regarding the validity or scope of any 1362 Intellectual Property Rights or other rights that might be claimed to 1363 pertain to the implementation or use of the technology described in 1364 this document or the extent to which any license under such rights 1365 might or might not be available; nor does it represent that it has 1366 made any independent effort to identify any such rights. Information 1367 on the procedures with respect to rights in RFC documents can be 1368 found in BCP 78 and BCP 79. 1370 Copies of IPR disclosures made to the IETF Secretariat and any 1371 assurances of licenses to be made available, or the result of an 1372 attempt made to obtain a general license or permission for the use of 1373 such proprietary rights by implementers or users of this 1374 specification can be obtained from the IETF on-line IPR repository at 1375 http://www.ietf.org/ipr. 1377 The IETF invites any interested party to bring to its attention any 1378 copyrights, patents or patent applications, or other proprietary 1379 rights that may cover technology that may be required to implement 1380 this standard. Please address the information to the IETF at 1381 ietf-ipr@ietf.org. 1383 Acknowledgment 1385 Funding for the RFC Editor function is provided by the IETF 1386 Administrative Support Activity (IASA).