idnits 2.17.1 draft-ietf-netconf-notification-09.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 1638. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1649. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1656. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1662. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. 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 536 has weird spacing: '...netconf xmlns...' == Line 677 has weird spacing: '...omplete notif...' == Line 690 has weird spacing: '...e above schem...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 10, 2007) is 6071 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) ** Obsolete normative reference: RFC 4741 (ref. 'NETCONF') (Obsoleted by RFC 6241) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 9 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: March 13, 2008 Cisco 6 September 10, 2007 8 NETCONF Event Notifications 9 draft-ietf-netconf-notification-09.txt 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 March 13, 2008. 36 Copyright Notice 38 Copyright (C) The IETF Trust (2007). 40 Abstract 42 This document defines mechanisms that provide an asynchronous message 43 notification delivery service for the NETCONF protocol. This is an 44 optional capability built on top of the base NETCONF definition. 45 This document defines the capabilities and operations necessary to 46 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 . . . . . . . . . . . . . . 6 54 2. Notification-Related Operations . . . . . . . . . . . . . . . 7 55 2.1. Subscribing to Receive Event Notifications . . . . . . . . 7 56 2.1.1. . . . . . . . . . . . . . . . . 7 57 2.2. Sending Event Notifications . . . . . . . . . . . . . . . 9 58 2.2.1. . . . . . . . . . . . . . . . . . . . . 9 59 2.3. Terminating the Subscription . . . . . . . . . . . . . . . 10 60 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 11 61 3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 11 62 3.1.1. Capability Identifier . . . . . . . . . . . . . . . . 11 63 3.1.2. Capability Example . . . . . . . . . . . . . . . . . . 11 64 3.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 11 65 3.2.1. Event Stream Definition . . . . . . . . . . . . . . . 13 66 3.2.2. Event Stream Content Format . . . . . . . . . . . . . 13 67 3.2.3. Default Event Stream . . . . . . . . . . . . . . . . . 13 68 3.2.4. Event Stream Sources . . . . . . . . . . . . . . . . . 13 69 3.2.5. Event Stream Discovery . . . . . . . . . . . . . . . . 13 70 3.3. Notification Replay . . . . . . . . . . . . . . . . . . . 16 71 3.3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 16 72 3.3.2. Creating a Subscription with Replay . . . . . . . . . 17 73 3.4. Notification Management Schema . . . . . . . . . . . . . . 17 74 3.5. Subscriptions Data . . . . . . . . . . . . . . . . . . . . 21 75 3.6. Filter Mechanics . . . . . . . . . . . . . . . . . . . . . 21 76 3.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 21 77 3.7. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 21 78 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 24 79 5. Filtering Examples . . . . . . . . . . . . . . . . . . . . . . 28 80 5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 32 81 5.2. XPATH filters . . . . . . . . . . . . . . . . . . . . . . 33 82 6. Security Considerations . . . . . . . . . . . . . . . . . . . 35 83 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 84 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 37 85 9. Normative References . . . . . . . . . . . . . . . . . . . . . 38 86 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 39 87 A.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 39 88 A.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . . 41 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 44 90 Intellectual Property and Copyright Statements . . . . . . . . . . 45 92 1. Introduction 94 [NETCONF] can be conceptually partitioned into four layers: 96 Layer Example 97 +-------------+ +----------------------------------------+ 98 | Content | | Configuration data | 99 +-------------+ +----------------------------------------+ 100 | | 101 +-------------+ +-------------------------------------------+ 102 | Operations | | , | 103 +-------------+ +-------------------------------------------+ 104 | | | 105 +-------------+ +-----------------------------+ | 106 | RPC | | , | | 107 +-------------+ +-----------------------------+ | 108 | | | 109 +-------------+ +------------------------------------------+ 110 | Transport | | BEEP, SSH, SSL, console | 111 | Protocol | | | 112 +-------------+ +------------------------------------------+ 114 Figure 1 116 This document defines mechanisms which provide an asynchronous 117 message notification delivery service for the [NETCONF] protocol. 118 This is an optional capability built on top of the base NETCONF 119 definition. This memo defines the capabilities and operations 120 necessary to support this service. 122 1.1. Definition of Terms 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in [RFC2119]. 128 Element: An [XML] Element. 130 Subscription: An agreement and method to receive event notifications 131 over a NETCONF session. A concept related to the delivery of 132 notifications (if there are any to send) involving destination and 133 selection of notifications. It is bound to the lifetime of a 134 session. 136 Operation: This term is used to refer to NETCONF protocol operations 137 [NETCONF]. Within this document, operation refers to NETCONF 138 protocol operations defined in support of NETCONF notifications. 140 Event: An event is something that happens which may be of interest - 141 a configuration change, a fault, a change in status, crossing a 142 threshold, or an external input to the system, for example. Often 143 this results in an asynchronous message, sometimes referred to as 144 a notification or event notification, being sent to interested 145 parties to notify them that this event has occurred. 147 Replay: The ability to send/re-send previously logged notifications 148 upon request. These notifications are sent asynchronously. This 149 feature is implemented by the NETCONF server and invoked by the 150 NETCONF client. 152 Stream: An event stream is a set of event notifications matching 153 some forwarding criteria and available to NETCONF clients for 154 subscription. 156 Filter: A parameter that indicates which subset of all possible 157 events are of interest. A filter is defined as one or more filter 158 element [NETCONF], which each identifies a portion of the overall 159 filter. 161 1.2. Motivation 163 The motivation for this work is to enable the sending of asynchronous 164 messages that are consistent with the data model (content) and 165 security model used within a NETCONF implementation. 167 The scope of the work aims meeting the following operational needs: 169 o Initial release should ensure it supports notifications in support 170 of configuration operations. 172 o It should be possible to use the same data model for notifications 173 as for configuration operations. 175 o Solution should support a reasonable message size limit (i.e., not 176 too short) 178 o The notifications should be carried over a connection-oriented 179 delivery mechanism. 181 o A subscription mechanism for notifications should be provided. 182 This takes into account that a NETCONF server does not send 183 notifications before being asked to do so and that it is the 184 NETCONF client who initiates the flow of notifications. 186 o A filtering mechanism for sending notifications should be put in 187 place within the NETCONF server. 189 o The information contained in a notification should be sufficient 190 so that it can be analyzed independent of the transport mechanism. 191 In other words the data content fully describes a notification; 192 protocol information is not needed to understand a notification. 194 o The server should have the capability to replay locally logged 195 notifications. 197 1.3. Event Notifications in NETCONF 199 This memo defines a mechanism whereby the NETCONF client indicates 200 interest in receiving event notifications from a NETCONF server by 201 creating a subscription to receive event notifications. The NETCONF 202 server replies to indicate whether the subscription request was 203 successful and, if it was successful, begins sending the event 204 notifications to the NETCONF client as the events occur within the 205 system. These event notifications will continue to be sent until 206 either the NETCONF session is terminated or the subscription 207 terminates for some other reason. The event notification 208 subscription allows a number of options to enable the NETCONF client 209 to specify which events are of interest. These are specified when 210 the subscription is created. 212 The NETCONF server MUST accept and process the close-session 213 operation, even while the notification subscription is active. The 214 NETCONF server MAY accept and process other commands, otherwise they 215 will be rejected and the server MUST send a 'resource-denied' error. 216 An example of when other commands would be processed is if a separate 217 capability was advertised indicating support of this functionality. 219 2. Notification-Related Operations 221 2.1. Subscribing to Receive Event Notifications 223 The event notification subscription is initiated by the NETCONF 224 client and responded to by the NETCONF server. A subscription is 225 bound to a single stream for the lifetime of the subscription. When 226 the event notification subscription is created, the events of 227 interest are specified. 229 Content for an event notification subscription can be selected by 230 applying user-specified filters. 232 2.1.1. 234 Description: 236 This operation initiates an event notification subscription which 237 will send asynchronous event notifications to the initiator of the 238 command until the subscription terminates. 240 Parameters: 242 Stream: 244 An optional parameter, , that indicates which stream of 245 events is of interest. If not present, events in the default 246 NETCONF stream will be sent. 248 Filter: 250 An optional parameter, , that indicates which subset of 251 all possible events is of interest. The format of this 252 parameter is the same as that of the filter parameter in the 253 NETCONF protocol operations. If not present, all events not 254 precluded by other parameters will be sent. See section 3.6 255 for more information on filters. 257 Start Time: 259 A parameter, , used to trigger the replay feature 260 and indicate that the replay should start at the time 261 specified. If is not present, this is not a replay 262 subscription. It is not valid to specify start times that are 263 later than the current time. If the specified is 264 earlier than the log can support, the replay will begin with 265 the earliest available notification. This parameter is of type 266 dateTime. 268 Stop Time: 270 An optional parameter, , used with the optional 271 replay feature to indicate the newest notifications of 272 interest. If stop time is not present, the notifications will 273 continue until the subscription is terminated. Must be used 274 with and be later than . A stop times that is later 275 than the current time, will be interpreted as being the time of 276 the subscription creation (current time). This parameter is of 277 type dateTime. 279 Positive Response: 281 If the NETCONF server can satisfy the request, the server sends an 282 element. 284 Negative Response: 286 An element is included within the if the 287 request cannot be completed for any reason. Subscription requests 288 will fail if a filter with invalid syntax is provided or if the 289 name of a non-existent stream is provided. 291 If a is specified in a request without having specified 292 a , the following error is returned: 294 Tag: missing-element 296 Error-type: protocol 298 Severity: error 300 Error-info: : startTime 302 Description: An expected element is missing. 304 If the optional replay feature is requested but it is not 305 supported by the NETCONF server, the following error is returned: 307 Tag: operation-failed 309 Error-type: protocol 311 Severity: error 312 Error-info: none 314 Description: Request could not be completed because the 315 requested operation failed for some reason not covered by any 316 other error condition 318 2.1.1.1. Usage Example 320 The following demonstrates creating a simple subscription. More 321 complex examples can be found in section 5. 323 325 327 328 330 2.2. Sending Event Notifications 332 Once the subscription has been set up, the NETCONF server sends the 333 event notifications asynchronously over the connection. 335 2.2.1. 337 Description: 339 An event notification is sent to the client who initiated a 340 command asynchronously when an event of 341 interest (i.e., meeting the specified filtering criteria) has 342 occurred. An event notification is a complete and well-formed XML 343 document. Note that is not an RPC method but 344 rather the top level element identifying the one-way message as a 345 notification. 347 Parameters: 349 eventTime 351 The time the event was generated by the event source 353 Also contains notification-specific tagged content, if any. With 354 the exception of , the content of the notification is 355 beyond the scope of this document. 357 Response: 359 No response. Not applicable. 361 2.3. Terminating the Subscription 363 Closing of the event notification subscription can be done by 364 terminating the NETCONF session ( ) or the underlying 365 transport session. If a stop time is provided when the subscription 366 is created, the subscription will terminate after the stop time is 367 reached. In this case, the NETCONF session will still be an active 368 session. 370 3. Supporting Concepts 372 3.1. Capabilities Exchange 374 The ability to process and send event notifications is advertised 375 during the capability exchange between the NETCONF client and server. 377 3.1.1. Capability Identifier 379 "urn:ietf:params:netconf:capability:notification:1.0" 381 3.1.2. Capability Example 383 384 385 386 urn:ietf:params:xml:ns:netconf:base:1.0 387 388 389 urn:ietf:params:netconf:capability:startup:1.0 390 391 392 urn:ietf:params:netconf:capability:notification:1.0 393 394 395 4 396 398 3.2. Event Streams 400 An event stream is defined as a set of event notifications matching 401 some forwarding criteria. 403 Figure 2 illustrates the notification flow and concepts identified in 404 this document. The following is observed from the diagram below: 405 System components (c1..cn) generate event notifications which are 406 passed to a central component for classification and distribution. 407 The central component inspects each event notification and matches 408 the event notification against the set of stream definitions. When a 409 match occurs, the event notification is considered to be a member of 410 that event stream (stream 1..stream n). An event notification may be 411 part of multiple event streams. 413 At some point after the NETCONF server receives the internal event 414 from a stream, it is converted to an appropriate XML encoding by the 415 server, and a element is ready to send to all NETCONF 416 sessions subscribed to that stream. 418 After generation of the element, access control is 419 applied by the server. If a session does not have permission to 420 receive the , then it is discarded for that session, 421 and processing of the internal event is completed for that session. 423 When a NETCONF client subscribes to a given event stream, user- 424 defined filter elements, if applicable, are applied to the event 425 stream and matching event notifications are forwarded to the NETCONF 426 server for distribution to subscribed NETCONF clients. A filter is 427 transferred from the client to the server during the operation and applied against each 429 element generated by the stream. For more information on filtering, 430 see section 3.6. 432 A notification logging service may also be available, in which case, 433 the central component logs notifications. The NETCONF server may 434 later retrieve logged notifications via the optional replay feature. 435 For more information on replay, see section 3.3. 437 +----+ 438 | c1 |----+ available streams 439 +----+ | +---------+ 440 +----+ | |central |-> stream 1 441 | c2 | +--->|event |-> stream 2 filter +-------+ 442 +----+ | |processor|-> NETCONF stream ----->|NETCONF| 443 ... | | |-> stream n |server | 444 System | +---------+ +-------+ 445 Components| | /\ 446 ... | | || 447 +----+ | | (------------) || 448 | cn |----+ | (notification) || 449 +----+ +-----> ( logging ) || 450 ( service ) || 451 (------------) || 452 || 453 || 454 \/ 455 +-------+ 456 |NETCONF| 457 |client | 458 +-------+ 460 Figure 2 462 3.2.1. Event Stream Definition 464 Event streams are predefined on the managed device. The 465 configuration of event streams is outside the scope of this document. 466 However, it is envisioned that event streams are either pre- 467 established by the vendor (pre-configured), user configurable (e.g., 468 part of the device's configuration) or both. Device vendors may 469 allow event stream configuration via the NETCONF protocol (i.e., 470 edit-config operation). 472 3.2.2. Event Stream Content Format 474 The contents of all event streams made available to a NETCONF client 475 (i.e., the notification sent by the NETCONF server) must be encoded 476 in XML. 478 3.2.3. Default Event Stream 480 A NETCONF server implementation supporting the notification 481 capability must support the "NETCONF" notification event stream. 482 This stream contains all NETCONF XML event notifications supported by 483 the NETCONF server. The exact string "NETCONF" is used during 484 advertisement of stream support during the operation on 485 and during the operation. Definition 486 of the event notifications and their contents, beyond the inclusion 487 of , for this event stream is outside the scope of this 488 document. 490 3.2.4. Event Stream Sources 492 With the exception of the default event stream (NETCONF), 493 specification of additional event stream sources (e.g., SNMP, syslog) 494 is outside the scope of this document. NETCONF server 495 implementations may leverage any desired event stream source in the 496 creation of supported event streams. 498 3.2.5. Event Stream Discovery 500 A NETCONF client retrieves the list of supported event streams from a 501 NETCONF server using the operation. 503 3.2.5.1. Name Retrieval using operation 505 The list of available event streams is retrieved by requesting the 506 subtree via a operation. Available event streams for 507 the requesting session are returned in the reply containing the 508 and elements, where the element is 509 mandatory, and its value is unique within the scope of a NETCONF 510 server. An empty reply is returned if there are no available event 511 streams. 513 Additional information available about a stream include whether 514 notification replay is available and if so, the timestamp of the 515 earliest possible notification to replay. 517 The following example shows retrieving the list of available event 518 stream list using the operation. 520 522 523 524 525 526 527 528 529 530 The NETCONF server returns a list of event streams available for 531 subscription: NETCONF, SNMP, and syslog-critical in this example. 533 535 536 537 538 539 NETCONF 540 default NETCONF event stream 541 542 true 543 544 2007-07-08T00:00:00Z 545 546 547 548 SNMP 549 SNMP notifications 550 false 551 552 553 syslog-critical 554 Critical and higher severity 555 556 true 557 558 2007-07-01T00:00:00Z 559 560 561 562 563 564 566 3.2.5.2. Event Stream Subscription 568 A NETCONF client may request from the NETCONF server the list of 569 event streams available to this session and then issue a request with the desired event stream name. Omitting 571 the event stream name from the request results 572 in subscription to the default NETCONF event stream. 574 3.2.5.2.1. Filtering Event Stream Contents 576 The set of event notifications delivered in an event stream may be 577 further refined by applying a user-specified filter supplied at 578 subscription creation time ( ). This is a 579 transient filter associated with the event notification subscription 580 and does not modify the event stream configuration. The filter 581 element is applied against the contents of the wrapper 582 and not the wrapper itself. See section 5 for examples. Either 583 subtree or XPATH filtering can be used. 585 XPATH support for the Notification capability is advertised as part 586 of the normal XPATH capability advertisement. If XPATH support is 587 advertised via the XPATH capability then XPATH is supported for 588 notification filtering and if this capability is not advertised, 589 XPATH is not supported for notification filtering. 591 3.3. Notification Replay 593 3.3.1. Overview 595 Replay is the ability to create an event subscription that will 596 resend recently generated notifications, or in some cases send them 597 for the first time to a particular NETCONF client. These 598 notifications are sent the same way as normal notifications. 600 A replay of notifications is specified by including the optional 601 parameter to the subscription command, which indicates 602 the start time of the replay. The end time is specified using the 603 optional parameter. If not present, notifications will 604 continue to be sent until the subscription is terminated. 606 A notification stream that supports replay is not expected to have an 607 unlimited supply of saved notifications available to accommodate any 608 replay request. 610 The actual number of stored notifications available for retrieval at 611 any given time is a NETCONF server implementation specific matter. 612 Control parameters for this aspect of the feature are outside the 613 scope of this document. 615 Replay is dependent on a notification stream supporting some form of 616 notification logging, although it puts no restrictions on the size or 617 form of the log, or where it resides within the device. Whether or 618 not a stream supports replay can be discovered by doing a 619 operation on the element of the Notification Management 620 Schema and looking at the value of the object. This 621 schema also provides the element to indicate 622 the earliest available logged notification. 624 3.3.2. Creating a Subscription with Replay 626 This feature uses optional parameters to the 627 command called and . identifies the 628 earliest date and time of interest for event notifications being 629 replayed and also indicates that a subscription will be providing 630 replay of notifications. Events generated before this time are not 631 matched. specifies the latest date and time of interest 632 for event notifications being replayed. If it is not present, then 633 notifications will continue to be sent until the subscription is 634 terminated. 636 Note that and are associated with the time an 637 event was generated by the event source. 639 A notification is sent to indicate that all of the 640 replay notifications have been sent. If this subscription has a stop 641 time, then this session becomes a normal NETCONF session again. When 642 a has been specified, notification 643 is the last notification sent on the subscription before it 644 terminates and the NETCONF session returns to being a normal NETCONF 645 session. The NETCONF server will then accept operations. In 646 the case of a subscription without a stop time, after the 647 notification has been sent, it can be expected that 648 any notifications generated since the start of the subscription 649 creation will be sent, followed by notifications as they arise 650 naturally within the system. 652 The and notifications cannot 653 be filtered out. They will always be sent on a replay subscription 654 that specified a startTime and stopTime respectively. 656 3.4. Notification Management Schema 658 This Schema is used to learn about the event streams supported on the 659 system. It also contains the definition of the and 660 notifications, which are sent to indicate that 661 an event replay has sent all applicable notifications and that the 662 subscription has terminated, respectively. 664 665 673 674 675 A schema that can be used to learn about current 676 event streams. It also contains the replayComplete 677 and notificationComplete notification. 678 679 681 683 686 690 693 695 696 697 698 699 700 The list of event streams supported by the 701 system. When a query is issued, the returned 702 set of streams is determined based on user 703 privileges. 704 705 706 707 708 709 710 711 Stream name, description and other information. 712 713 714 715 716 718 719 720 The name of the event stream. If this is 721 the default NETCONF stream, this must have 722 the value "NETCONF". 723 724 725 726 728 729 730 A description of the event stream, including 731 such information as the type of events that 732 are sent over this stream. 733 734 735 736 738 739 740 An indication of whether or not event replay 741 is available on this stream. 742 743 744 745 747 748 749 The timestamp of the creation of the log 750 used to support the replay function on 751 this stream. 752 Note that this might be earlier then 753 the earliest available 754 notification in the log. This object 755 is updated if the log resets 756 for some reason. This 757 object MUST be present if replay is 758 supported. 759 760 761 762 765 766 767 The timestamp of the last notification 768 aged out of the log. This 769 object MUST be present if replay is 770 supported and any notifications 771 have been aged out of the log. 772 773 774 775 776 777 778 779 780 781 782 784 785 786 787 788 790 793 794 795 This notification is sent to signal the end of a replay 796 portion of a subscription. 797 798 799 801 802 803 804 805 807 810 811 812 This notification is sent to signal the end of a 813 notification subscription. It is sent in the case 814 that stopTime was specified during the creation of 815 the subscription. 816 817 818 820 822 3.5. Subscriptions Data 824 Subscriptions are non-persistent state information and their lifetime 825 is defined by their session or by the paramter. 827 3.6. Filter Mechanics 829 When multiple filter elements are specified, they are applied 830 collectively, so event notifications need to pass all specified 831 filter elements in order to be sent to the subscriber. If a filter 832 element is specified to look for data of a particular value, and the 833 data item is not present within a particular event notification for 834 its value to be checked against, the notification will be filtered 835 out. For example, if one were to check for 'severity=critical' in a 836 configuration event notification where this field was not supported, 837 then the notification would be filtered out. 839 For subtree filtering, a non-empty node set means that the filter 840 matches. For XPath filtering, the mechanisms defined in [XPATH] 841 should be used to convert the returned value to boolean. 843 3.6.1. Filtering 845 Filtering is explicitly stated when the event notification 846 subscription is created. This is specified via the 'filter' 847 parameter. A Filter only exist as a parameter to the subscription. 849 3.7. Message Flow 850 The following figure depicts message flow between a NETCONF client 851 (C) and NETCONF server (S) in order to create a subscription and 852 begin the flow of notifications. This subscription specified a 853 , so the server starts by replaying logged notifications. 854 It is possible that many rpc/rpc-reply sequences occur before the 855 subscription is created, but this is not depicted in the figure. 857 C S 858 | | 859 | capability exchange | 860 |-------------------------->| 861 |<------------------------->| 862 | | 863 | | 864 |-------------------------->| 865 |<--------------------------| 866 | | 867 | | 868 | | 869 |<--------------------------| 870 | | 871 | | 872 |<--------------------------| 873 | | (replayComplete) 874 |<--------------------------| 875 | | 876 | | 877 | | 878 | | 879 |<--------------------------| 880 | | 881 | | 882 | | 883 |<--------------------------| 884 | | 885 | | 887 Figure 3 889 The following figure depicts message flow between a NETCONF client 890 (C) and NETCONF server (S) in order to create a subscription and 891 begin the flow of notifications. This subscription specified a 892 and so it starts by replaying logged 893 notifications and then returns to be a normal command-response 894 NETCONF session after the and 895 notifications are sent and it is available to process requests. 896 It is possible that many rpc/rpc-reply sequences occur before the 897 subscription is created, but this is not depicted in the figure. 899 C S 900 | | 901 | capability exchange | 902 |-------------------------->| 903 |<------------------------->| 904 | | 905 | | 906 |-------------------------->| 907 |<--------------------------| 908 | | 909 | | 910 | | 911 |<--------------------------| 912 | | 913 | | 914 |<--------------------------| 915 | | (replayComplete) 916 |<--------------------------| 917 | |(notificationComplete) 918 |<--------------------------| 919 | | 920 | | 921 | | 922 | | 923 |-------------------------->| 924 |<--------------------------| 925 | | 926 | | 928 Figure 4 930 4. XML Schema for Event Notifications 932 The following [XML Schema] defines NETCONF Event Notifications. 934 935 944 946 948 949 950 This import accesses the xml: attribute groups for the 951 xml:lang as declared on the error-message element. 952 953 954 956 957 961 963 965 966 967 968 969 971 972 973 An optional parameter that indicates 974 which stream of events is of interest. If 975 not present, then events in the default 976 NETCONF stream will be sent. 977 978 979 980 983 984 985 An optional parameter that indicates 986 which subset of all possible events 987 is of interest. The format of this 988 parameter is the same as that of the 989 filter parameter in the NETCONF 990 protocol operations. If not present, 991 all events not precluded by other 992 parameters will be sent. 993 994 995 996 998 999 1000 A parameter used to trigger the replay 1001 feature and indicates that the replay 1002 should start at the time specified. If 1003 start time is not present, this is not a 1004 replay subscription. 1005 1006 1007 1008 1010 1011 1012 An optional parameter used with the 1013 optional replay feature to indicate the 1014 newest notifications of interest. If 1015 stop time is not present, the 1016 notifications will continue until the 1017 subscription is terminated. Must be used 1018 with startTime. 1019 1020 1021 1023 1024 1025 1026 1028 1029 1030 1031 The name of an event stream. 1032 1033 1034 1035 1037 1040 1041 1042 The command to create a notification subscription. It 1043 takes as argument the name of the notification stream 1044 and filter. Both of those options 1045 limit the content of the subscription. In addition, 1046 there are two time-related parameters, startTime and 1047 stopTime, which can be used to select the time interval 1048 of interest to the notification replay feature. 1049 1050 1051 1053 1055 1056 1058 1061 1062 1063 1064 1065 1066 The time the event was generated by the event source 1067 1068 1070 1071 1072 1073 1075 1077 1079 5. Filtering Examples 1081 The following section provides examples to illustrate the various 1082 methods of filtering content on an event notification subscription. 1084 In order to illustrate the use of filter expressions, it is necessary 1085 to assume some of the event notification content. The examples below 1086 assume that the event notification schema definition has an 1087 element at the top level consisting of the event class (e.g., fault, 1088 state, config), reporting entity and either severity or operational 1089 state. 1091 Examples in this section are generated from the following fictional 1092 Schema. 1094 1095 1101 1106 1107 1108 1109 1110 1111 1112 1113 1114 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1128 1132 1134 The above fictional notification definition could result in the 1135 following is a sample notification list, whihc is used in the 1136 examples in this section. 1138 1140 2007-07-08T00:01:00Z 1141 1142 fault 1143 1144 Ethernet0 1145 1146 major 1147 1148 1150 1152 2007-07-08T00:02:00Z 1153 1154 fault 1155 1156 Ethernet2 1157 1158 critical 1159 1160 1162 1164 2007-07-08T00:04:00Z 1165 1166 fault 1167 1168 ATM1 1169 1170 minor 1171 1172 1174 1176 2007-07-08T00:10:00Z 1177 1178 state 1179 1180 Ethernet0 1181 1182 enabled 1183 1184 1186 5.1. Subtree Filtering 1188 XML subtree filtering is not well-suited for creating elaborate 1189 filter definitions given that it only supports equality comparisons 1190 and application of the logical OR operators (e.g., in an event 1191 subtree give me all event notifications which have severity=critical 1192 or severity=major or severity=minor). Nevertheless, it may be used 1193 for defining simple event notification forwarding filters as shown 1194 below. 1196 The following example illustrates how to select fault events which 1197 have severities of critical, major, or minor. The filtering criteria 1198 evaluation is as follows: 1200 ((severity=critical) | (severity=major) | (severity=minor)) 1202 1204 1206 1207 1208 fault 1209 critical 1210 1211 1212 fault 1213 major 1214 1215 1216 fault 1217 minor 1218 1219 1220 1221 1223 The following example illustrates how to select state or config 1224 EventClasses or fault events that are related to card Ethernet0. The 1225 filtering criteria evaluation is as follows: 1227 ( state | config | ( fault & ( card=Ethernet0))) 1229 1231 1233 1234 1235 fault 1236 1237 1238 state 1239 1240 1241 config 1242 1243 1244 fault 1245 1246 Ethernet0 1247 1248 1249 1250 1251 1253 5.2. XPATH filters 1255 The following [XPATH] example illustrates how to select fault 1256 EventClass notifications that have severities of critical, major, or 1257 minor. The filtering criteria evaluation is as follows: 1259 ((fault) & ((severity=critical) | (severity=major) | (severity = 1260 minor))) 1262 1264 1266 1271 1272 1274 The following example illustrates how to select state and config 1275 EventClasses or fault events of any severity that come from card 1276 Ethernet0. The filtering criteria evaluation is as follows: 1278 (( state | config) & (fault & card=Ethernet0)) 1280 1282 1284 1289 1290 1292 6. Security Considerations 1294 The security considerations from the base [NETCONF] document also 1295 apply to the Notification capability. 1297 The access control framework and the choice of transport will have a 1298 major impact on the security of the solution. 1300 The elements are never sent before the transport layer 1301 and the NETCONF layer, including capabilities exchange, have been 1302 established, and the manager has been identified and authenticated. 1304 It is recommended that care be taken to secure execution: 1306 o invocation 1308 o on read-only data models 1310 o content 1312 One potential security issue is the transport of data from non- 1313 NETCONF streams, such as syslog and SNMP. This data may be more 1314 vulnerable (or less vulnerable) when being transported over NETCONF 1315 than when being transported using the protocol normally used for 1316 transporting it, depending on the security credentials of the two 1317 subsystems. The NETCONF server is responsible for applying access 1318 control to stream content. 1320 The contents of notifications as well as the name of event streams 1321 may contain sensitive information and care should be taken to ensure 1322 that it is viewed only by authorized users. If a user does not have 1323 permission to view content via other NETCONF operations, it does not 1324 have permission to access that content via Notifications. If a user 1325 is not permitted to view one element in the content of the 1326 notification, the notification is not sent to that user. 1328 If a subscription is created with a , the NETCONF session 1329 will return to being a normal command-response NETCONF session when 1330 the replay is completed. It is the responsibility of the NETCONF 1331 client to close this session when it is no longer of use. 1333 7. IANA Considerations 1335 This document registers three URIs for the NETCONF XML namespace in 1336 the IETF XML registry [RFC3688]. 1338 Following the format in RFC 3688, IANA has made the following 1339 registration. 1341 URI: urn:ietf:params:netconf:capability:notification:1.0 1343 URI: urn:ietf:params:xml:ns:netmod:notification 1345 URI: urn:ietf:params:xml:ns:netconf:notification 1347 Registrant Contact: The IESG. 1349 XML: N/A, the requested URI is an XML namespace. 1351 8. Acknowledgements 1353 Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing 1354 their input into the early work on this document. In addition, the 1355 editors would like to acknowledge input at the Vancouver editing 1356 session from the following people: Orly Nicklass, James Balestriere, 1357 Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, 1358 Dave Partain, Ray Atarashi and David Perkins and the following 1359 additional people from the Montreal editing session: Balazs Lengyel, 1360 Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen, 1361 Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig, 1362 Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William 1363 Chow. We would also like to thank Li Yan for his numerous reviews. 1365 9. Normative References 1367 [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 1368 December 2006. 1370 [RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements 1371 Levels", RFC 2119, March 1997. 1373 [RFC3688] Bradner, s., "The IETF XML Registry", RFC 3688, January 1374 2004. 1376 [XML] World Wide Web Consortium, "Extensible Markup Language 1377 (XML) 1.0", W3C XML, February 1998, 1378 . 1380 [XML Schema] 1381 Fallside, D. and P. Walmsley, "XML Schema Part 0: Primer 1382 Second Edition", W3C XML Schema, October 2004. 1384 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 1385 Version 1.0", 1386 W3C http://www.w3.org/TR/1999/REC-xpath-19991116, 1387 November 1999. 1389 Appendix A. Change Log 1391 A.1. Version -08 1393 1. Removed named profiles 1395 2. Removed eventClass that was accidentally included in the 1396 definition of the replayComplete notification 1398 3. Deleted data wrapper from notification 1400 4. Changed replayLogStartTime to have a minOccurs of 0. It will 1401 only be there when replay is supported. Verify examples in 1402 section 3.2.5.1 are correct with respect to this element. 1404 5. Error codes in section 2.1.1, fixed formatting issue 1406 6. Moved replayComplete to not be under 1408 7. Section 2.1, fixed capitalization 1410 8. In figure 4, the line was pushed out by 'system components', 1411 fixed this. 1413 9. On page 8, replaced "If the startTime specified is earlier then 1414 the" with 'If the startTime specified is earlier than the" 1416 10. Updated some name spaces and schemaLocations as per Andy's June 1417 3rd email. 1419 11. Added discussion of replayLogStartTime to draft in section 3.3.1 1420 as follows "Whether or not a stream supports replay can be 1421 discovered by doing a operation on the elements 1422 of the Notification Management Schema. This schema also 1423 provides the replayLogStartTime element to indicate the earliest 1424 available logged notification." 1426 12. Removed most of the uses of the phrase 'Note that'. I kept two 1427 uses that prevent sentences from starting with either a lower 1428 case letter or an angle bracket. 1430 13. In section 3.6 replaced "it will be filtered out" with "the 1431 notification will be filtered out" 1433 14. In section 3.4, replaced "and the query" with "and to query" 1435 15. Replaced 3 instances of "replay complete notification" with 1436 "replayComplete notification" 1438 16. In section 3.3.2, replaced "normal NETCONF session" with "normal 1439 command-response NETCONF session" 1441 17. In section 3.3.1, replaced "create an event subscription that 1442 will resend recently generated notification" with "create an 1443 event subscription that will resend recently generated 1444 notification, or is some cases send them for the first time to a 1445 particular NETCONF client." 1447 18. In section 3.2.5.2, s/available event streams to/event streams 1448 available to/ 1450 19. In one spot, changed snmp to SNMP (the other gets deleted) 1452 20. In section 3.2.5.1 s/where element is/where the 1453 element is/ 1455 21. In section 3.2.5.1, clarified that "value is unique" - within 1456 the scope of a NETCONF server. 1458 22. In section 2.1.1, clarified that stopTime cannot preceded start 1459 time. 1461 23. In section 2.1.1, in Start Time s/indicates/indicate/ 1463 24. In section 2.1.1, in Filter: s/This is mutually exclusive/The 1464 filter parameter is mutually exclusive/ ("this" could refer to 1465 the behavior described in the previous sentence.) 1467 25. In section 1.4, third bullet, replaced "syslog and SNMP are 1468 rather constrained in terms of message sizes)" with (ie, not too 1469 short) 1471 26. In section 1.4, made all bullets start with capital leters. 1473 27. Added definition of Filter to section 1.1 1475 28. In section 1.1, improved the definition of subscription with "An 1476 agreement and method to receive event notifications over a 1477 NETCONF session." 1479 29. In section 1.1, in the definition of operation, added a 1480 reference to [NETCONF]. 1482 30. Created a change log section 1484 31. Fixed reference to IETF XML Registry in IANA Considerations 1485 section. 1487 32. In section 3.3.3, deleted "This notification will only be sent 1488 if a 'stopTime' was specified when the replay subscription was 1489 created." 1491 33. Added text to the security considerations section that says "If 1492 a subscription is created with a stopTime, the NETCONF session 1493 will return to being a normal command-response NETCONF session 1494 when the replay is completed. It is the responsibility of the 1495 NETCONF client to close off this session when it is no longer of 1496 use". 1498 34. Update examples in section 5 to get rid of extra wrapper tag. 1500 35. In section 2.1, replace "A NETCONF server is not required to 1501 process RPC requests on the session associated with the 1502 subscription until the notification subscription is done and may 1503 silently discard these requests." with "A NETCONF server is will 1504 not read RPC requests, by default, on the session associated 1505 with the subscription until the notification subscription is 1506 done. 1508 36. Updated the notification definition and the replyComplete 1509 notification definition to use a substitution group. 1511 A.2. Version -09 1513 1. In section 5.1 "logical OR operation" -> "application of the 1514 logical OR operator" 1516 2. In section 6 "ensure the secure operation of the following 1517 commands" -> "secure execution" 1519 3. Removed a couple remaining references to named profiles. 1521 4. Updated name datatype in eventStreams element. 1523 5. Modified the cardinality of eventStreams to reflect that there 1524 will always be at least one event stream. 1526 6. Fixed description of examples to remove reference to eventEntry, 1527 which is no longer part of the actual example. 1529 7. In examples, for consistency changed some references to 1530 reportingElement to be reportingEntity 1532 8. Fixed section 3.2, third pararaph to talk about filter elements 1533 instead of filters. 1535 9. Merge section 3.3.2 and section 3.3.3. Delete the first 1536 paragraph in (old) section 3.3.3 since it both duplicates and 1537 contradicts text in section 3.3.2 1539 10. In section 3.2.5.2.1, added clarification to first paragraph 1540 that "Either subtree or XPATH filtering can be used. " 1542 11. Removed discussion of not allowing the return of stream names 1543 for which the user does not have permissions from the body of 1544 the document to the security considerations section. 1546 12. Fixed typos and did wordsmithing in various parts of the 1547 document. 1549 13. In section 2.1, explicitly stated that a subscription is bound 1550 to a single stream for the lifetime of the subscription. 1552 14. removed single quotes around some instances of stopTime and 1553 startTime for consistency. When appropriate, put between angle 1554 brackets. 1556 15. In section 2.1.1, changed "Error-info: : startTime" 1557 to use bad-element. 1559 16. In section 2.2.1, under the parameter tag, replaced "Contains 1560 notification-specific tagged content." with "Contains 1561 notification-specific tagged content, if any. " 1563 17. Clarified some text in section 3.2, paragraph 3 around sending 1564 of filters from client and the fitlers later being applied to 1565 the notifications. 1567 18. Fixed target namespace in section 4. 1569 19. Added missing lang and version information to schema in section 1570 3.4 1572 20. Clarified that the examples in section 5 all used the same 1573 example event list. 1575 21. Cleaned up security considerations section. 1577 22. In section 3.4, clarified the definition of replayLogStart time 1578 to be the timestamp of the earliest available notification in 1579 the log used to support the replay function in the description 1580 tag for the object definition. 1582 23. In section 3.3.2, clarified that the time an event was generated 1583 by the system means time an event was generated by the event 1584 source. 1586 24. In section 3.5, deleted discussion about possibly defining 1587 subscriptions in XML Schema. 1589 25. In section 3.6, deleted discussion about filter element 1590 execution order not mattering. 1592 26. Fixed examples in section 5 to add tag and to make 1593 other corrections 1595 27. Added XML Schema definition for examples in section 5 and showed 1596 the event list with wrappers. 1598 28. Added notification 1600 29. Removed support of startTime and stopTime in the future. 1602 30. Replaced replayLogStartTime with replayLogCreationTime and 1603 replayLogAgedTime. 1605 Authors' Addresses 1607 Sharon Chisholm 1608 Nortel 1609 3500 Carling Ave 1610 Nepean, Ontario K2H 8E9 1611 Canada 1613 Email: schishol@nortel.com 1615 Hector Trevino 1616 Cisco 1617 Suite 400 1618 9155 E. Nichols Ave 1619 Englewood, CO 80112 1620 USA 1622 Email: htrevino@cisco.com 1624 Full Copyright Statement 1626 Copyright (C) The IETF Trust (2007). 1628 This document is subject to the rights, licenses and restrictions 1629 contained in BCP 78, and except as set forth therein, the authors 1630 retain all their rights. 1632 This document and the information contained herein are provided on an 1633 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1634 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1635 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1636 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1637 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1638 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1640 Intellectual Property 1642 The IETF takes no position regarding the validity or scope of any 1643 Intellectual Property Rights or other rights that might be claimed to 1644 pertain to the implementation or use of the technology described in 1645 this document or the extent to which any license under such rights 1646 might or might not be available; nor does it represent that it has 1647 made any independent effort to identify any such rights. Information 1648 on the procedures with respect to rights in RFC documents can be 1649 found in BCP 78 and BCP 79. 1651 Copies of IPR disclosures made to the IETF Secretariat and any 1652 assurances of licenses to be made available, or the result of an 1653 attempt made to obtain a general license or permission for the use of 1654 such proprietary rights by implementers or users of this 1655 specification can be obtained from the IETF on-line IPR repository at 1656 http://www.ietf.org/ipr. 1658 The IETF invites any interested party to bring to its attention any 1659 copyrights, patents or patent applications, or other proprietary 1660 rights that may cover technology that may be required to implement 1661 this standard. Please address the information to the IETF at 1662 ietf-ipr@ietf.org. 1664 Acknowledgment 1666 Funding for the RFC Editor function is provided by the IETF 1667 Administrative Support Activity (IASA).