idnits 2.17.1 draft-ietf-netconf-notification-10.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 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 1727. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1738. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1745. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1751. 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 569 has weird spacing: '...netconf xmlns...' == Line 710 has weird spacing: '...omplete notif...' == Line 723 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 (October 17, 2007) is 6007 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. -------------------------------------------------------------------------------- 1 Network Working Group S. Chisholm 2 Internet-Draft Nortel 3 Intended status: Standards Track H. Trevino 4 Expires: April 19, 2008 Cisco 5 October 17, 2007 7 NETCONF Event Notifications 8 draft-ietf-netconf-notification-10.txt 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on April 19, 2008. 35 Copyright Notice 37 Copyright (C) The IETF Trust (2007). 39 Abstract 41 This document defines mechanisms that provide an asynchronous message 42 notification delivery service for the NETCONF protocol. This is an 43 optional capability built on top of the base NETCONF definition. 44 This document defines the capabilities and operations necessary to 45 support this service. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 50 1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 4 51 1.2. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 52 1.3. Event Notifications in NETCONF . . . . . . . . . . . . . . 6 53 2. Notification-Related Operations . . . . . . . . . . . . . . . 7 54 2.1. Subscribing to Receive Event Notifications . . . . . . . . 7 55 2.1.1. . . . . . . . . . . . . . . . . 7 56 2.2. Sending Event Notifications . . . . . . . . . . . . . . . 10 57 2.2.1. . . . . . . . . . . . . . . . . . . . . 10 58 2.3. Terminating the Subscription . . . . . . . . . . . . . . . 10 59 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 11 60 3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 11 61 3.1.1. Capability Identifier . . . . . . . . . . . . . . . . 11 62 3.1.2. Capability Example . . . . . . . . . . . . . . . . . . 11 63 3.2. Event Streams . . . . . . . . . . . . . . . . . . . . . . 11 64 3.2.1. Event Stream Definition . . . . . . . . . . . . . . . 13 65 3.2.2. Event Stream Content Format . . . . . . . . . . . . . 13 66 3.2.3. Default Event Stream . . . . . . . . . . . . . . . . . 13 67 3.2.4. Event Stream Sources . . . . . . . . . . . . . . . . . 13 68 3.2.5. Event Stream Discovery . . . . . . . . . . . . . . . . 13 69 3.3. Notification Replay . . . . . . . . . . . . . . . . . . . 16 70 3.3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 16 71 3.3.2. Creating a Subscription with Replay . . . . . . . . . 17 72 3.4. Notification Management Schema . . . . . . . . . . . . . . 17 73 3.5. Subscriptions Data . . . . . . . . . . . . . . . . . . . . 21 74 3.6. Filter Mechanics . . . . . . . . . . . . . . . . . . . . . 21 75 3.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 21 76 3.7. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 21 77 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 24 78 5. Filtering Examples . . . . . . . . . . . . . . . . . . . . . . 28 79 5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 32 80 5.2. XPATH filters . . . . . . . . . . . . . . . . . . . . . . 33 81 6. Interleave Capability . . . . . . . . . . . . . . . . . . . . 35 82 6.1. Description . . . . . . . . . . . . . . . . . . . . . . . 35 83 6.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 35 84 6.3. Capability Identifier . . . . . . . . . . . . . . . . . . 35 85 6.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 35 86 6.5. Modifications to Existing Operations . . . . . . . . . . . 35 87 7. Security Considerations . . . . . . . . . . . . . . . . . . . 36 88 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 89 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 38 90 10. Normative References . . . . . . . . . . . . . . . . . . . . . 39 91 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 40 92 A.1. Version -08 . . . . . . . . . . . . . . . . . . . . . . . 40 93 A.2. Version -09 . . . . . . . . . . . . . . . . . . . . . . . 42 94 A.3. Version -10 . . . . . . . . . . . . . . . . . . . . . . . 44 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 45 96 Intellectual Property and Copyright Statements . . . . . . . . . . 46 98 1. Introduction 100 [NETCONF] can be conceptually partitioned into four layers: 102 Layer Example 103 +-------------+ +-------------------------------------------+ 104 | Content | | Configuration data | 105 +-------------+ +-------------------------------------------+ 106 | | 107 +-------------+ +-------------------------------------------+ 108 | Operations | | , | 109 +-------------+ +-------------------------------------------+ 110 | | | 111 +-------------+ +-----------------------------+ | 112 | RPC | | , | | 113 +-------------+ +-----------------------------+ | 114 | | | 115 +-------------+ +-------------------------------------------+ 116 | Transport | | BEEP, SSH, SSL, console | 117 | Protocol | | | 118 +-------------+ +-------------------------------------------+ 120 Figure 1 122 This document defines mechanisms which provide an asynchronous 123 message notification delivery service for the [NETCONF] protocol. 124 This is an optional capability built on top of the base NETCONF 125 definition. This memo defines the capabilities and operations 126 necessary to support this service. 128 1.1. Definition of Terms 130 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 131 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 132 document are to be interpreted as described in [RFC2119]. 134 Element: An [XML] Element. 136 Subscription: An agreement and method to receive event notifications 137 over a NETCONF session. A concept related to the delivery of 138 notifications (if there are any to send) involving destination and 139 selection of notifications. It is bound to the lifetime of a 140 session. 142 Operation: This term is used to refer to NETCONF protocol operations 143 [NETCONF]. Within this document, operation refers to NETCONF 144 protocol operations defined in support of NETCONF notifications. 146 Event: An event is something that happens which may be of interest - 147 a configuration change, a fault, a change in status, crossing a 148 threshold, or an external input to the system, for example. Often 149 this results in an asynchronous message, sometimes referred to as 150 a notification or event notification, being sent to interested 151 parties to notify them that this event has occurred. 153 Replay: The ability to send/re-send previously logged notifications 154 upon request. These notifications are sent asynchronously. This 155 feature is implemented by the NETCONF server and invoked by the 156 NETCONF client. 158 Stream: An event stream is a set of event notifications matching 159 some forwarding criteria and available to NETCONF clients for 160 subscription. 162 Filter: A parameter that indicates which subset of all possible 163 events are of interest. A filter is defined as one or more filter 164 element [NETCONF], which each identifies a portion of the overall 165 filter. 167 1.2. Motivation 169 The motivation for this work is to enable the sending of asynchronous 170 messages that are consistent with the data model (content) and 171 security model used within a NETCONF implementation. 173 The scope of the work aims meeting the following operational needs: 175 o Initial release should ensure it supports notifications in support 176 of configuration operations. 178 o It should be possible to use the same data model for notifications 179 as for configuration operations. 181 o Solution should support a reasonable message size limit (i.e., not 182 too short) 184 o The notifications should be carried over a connection-oriented 185 delivery mechanism. 187 o A subscription mechanism for notifications should be provided. 188 This takes into account that a NETCONF server does not send 189 notifications before being asked to do so and that it is the 190 NETCONF client who initiates the flow of notifications. 192 o A filtering mechanism for sending notifications should be put in 193 place within the NETCONF server. 195 o The information contained in a notification should be sufficient 196 so that it can be analyzed independent of the transport mechanism. 197 In other words the data content fully describes a notification; 198 protocol information is not needed to understand a notification. 200 o The server should have the capability to replay locally logged 201 notifications. 203 1.3. Event Notifications in NETCONF 205 This memo defines a mechanism whereby the NETCONF client indicates 206 interest in receiving event notifications from a NETCONF server by 207 creating a subscription to receive event notifications. The NETCONF 208 server replies to indicate whether the subscription request was 209 successful and, if it was successful, begins sending the event 210 notifications to the NETCONF client as the events occur within the 211 system. These event notifications will continue to be sent until 212 either the NETCONF session is terminated or the subscription 213 terminates for some other reason. The event notification 214 subscription allows a number of options to enable the NETCONF client 215 to specify which events are of interest. These are specified when 216 the subscription is created. 218 The NETCONF server MUST accept and process the 219 operation, even while the notification subscription is active. The 220 NETCONF server MAY accept and process other commands, otherwise they 221 will be rejected and the server MUST send a 'resource-denied' error. 222 A NETCONF server advertises support of the ability to process other 223 commands via the interleave capability. 225 2. Notification-Related Operations 227 2.1. Subscribing to Receive Event Notifications 229 The event notification subscription is initiated by the NETCONF 230 client and responded to by the NETCONF server. A subscription is 231 bound to a single stream for the lifetime of the subscription. When 232 the event notification subscription is created, the events of 233 interest are specified. 235 Content for an event notification subscription can be selected by 236 applying user-specified filters. 238 2.1.1. 240 Description: 242 This operation initiates an event notification subscription which 243 will send asynchronous event notifications to the initiator of the 244 command until the subscription terminates. 246 Parameters: 248 Stream: 250 An optional parameter, , that indicates which stream of 251 events is of interest. If not present, events in the default 252 NETCONF stream will be sent. 254 Filter: 256 An optional parameter, , that indicates which subset of 257 all possible events is of interest. The format of this 258 parameter is the same as that of the filter parameter in the 259 NETCONF protocol operations. If not present, all events not 260 precluded by other parameters will be sent. See section 3.6 261 for more information on filters. 263 Start Time: 265 A parameter, , used to trigger the replay feature 266 and indicate that the replay should start at the time 267 specified. If is not present, this is not a replay 268 subscription. It is not valid to specify start times that are 269 later than the current time. If the specified is 270 earlier than the log can support, the replay will begin with 271 the earliest available notification. This parameter is of type 272 dateTime. 274 Stop Time: 276 An optional parameter, , used with the optional 277 replay feature to indicate the newest notifications of 278 interest. If stop time is not present, the notifications will 279 continue until the subscription is terminated. Must be used 280 with and be later than . Values of in 281 the future are valid. This parameter is of type dateTime. 283 Positive Response: 285 If the NETCONF server can satisfy the request, the server sends an 286 element. 288 Negative Response: 290 An element is included within the if the 291 request cannot be completed for any reason. Subscription requests 292 will fail if a filter with invalid syntax is provided or if the 293 name of a non-existent stream is provided. 295 If a is specified in a request without having specified 296 a , the following error is returned: 298 Tag: missing-element 300 Error-type: protocol 302 Severity: error 304 Error-info: : startTime 306 Description: An expected element is missing. 308 If the optional replay feature is requested but it is not 309 supported by the NETCONF server, the following error is returned: 311 Tag: operation-failed 313 Error-type: protocol 315 Severity: error 317 Error-info: none 318 Description: Request could not be completed because the 319 requested operation failed for some reason not covered by any 320 other error condition 322 If a is requested which is earlier then the specified 323 , the following error is returned: 325 Tag: bad-element 327 Error-type: protocol 329 Severity: error 331 Error-info: : stopTime 333 Description: An element value is not correct; e.g., wrong type, 334 out of range, pattern mismatch. 336 If a is requested which is later then the current 337 time, the following error is returned: 339 Tag: bad-element 341 Error-type: protocol 343 Severity: error 345 Error-info: : startTime 347 Description: An element value is not correct; e.g., wrong type, 348 out of range, pattern mismatch. 350 2.1.1.1. Usage Example 352 The following demonstrates creating a simple subscription. More 353 complex examples can be found in section 5. 355 357 359 360 362 2.2. Sending Event Notifications 364 Once the subscription has been set up, the NETCONF server sends the 365 event notifications asynchronously over the connection. 367 2.2.1. 369 Description: 371 An event notification is sent to the client who initiated a 372 command asynchronously when an event of 373 interest (i.e., meeting the specified filtering criteria) has 374 occurred. An event notification is a complete and well-formed XML 375 document. Note that is not an RPC method but 376 rather the top level element identifying the one-way message as a 377 notification. 379 Parameters: 381 eventTime 383 The time the event was generated by the event source 385 Also contains notification-specific tagged content, if any. With 386 the exception of , the content of the notification is 387 beyond the scope of this document. 389 Response: 391 No response. Not applicable. 393 2.3. Terminating the Subscription 395 Closing of the event notification subscription can be done by using 396 the operation from the subscriptions session or 397 terminating the NETCONF session ( ) or the underlying 398 transport session from another session. If a stop time is provided 399 when the subscription is created, the subscription will terminate 400 after the stop time is reached. In this case, the NETCONF session 401 will still be an active session. 403 3. Supporting Concepts 405 3.1. Capabilities Exchange 407 The ability to process and send event notifications is advertised 408 during the capability exchange between the NETCONF client and server. 410 3.1.1. Capability Identifier 412 "urn:ietf:params:netconf:capability:notification:1.0" 414 3.1.2. Capability Example 416 417 418 419 urn:ietf:params:xml:ns:netconf:base:1.0 420 421 422 urn:ietf:params:netconf:capability:startup:1.0 423 424 425 urn:ietf:params:netconf:capability:notification:1.0 426 427 428 4 429 431 3.2. Event Streams 433 An event stream is defined as a set of event notifications matching 434 some forwarding criteria. 436 Figure 2 illustrates the notification flow and concepts identified in 437 this document. The following is observed from the diagram below: 438 System components (c1..cn) generate event notifications which are 439 passed to a central component for classification and distribution. 440 The central component inspects each event notification and matches 441 the event notification against the set of stream definitions. When a 442 match occurs, the event notification is considered to be a member of 443 that event stream (stream 1..stream n). An event notification may be 444 part of multiple event streams. 446 At some point after the NETCONF server receives the internal event 447 from a stream, it is converted to an appropriate XML encoding by the 448 server, and a element is ready to send to all NETCONF 449 sessions subscribed to that stream. 451 After generation of the element, access control is 452 applied by the server. If a session does not have permission to 453 receive the , then it is discarded for that session, 454 and processing of the internal event is completed for that session. 456 When a NETCONF client subscribes to a given event stream, user- 457 defined filter elements, if applicable, are applied to the event 458 stream and matching event notifications are forwarded to the NETCONF 459 server for distribution to subscribed NETCONF clients. A filter is 460 transferred from the client to the server during the operation and applied against each 462 element generated by the stream. For more information on filtering, 463 see section 3.6. 465 A notification logging service may also be available, in which case, 466 the central component logs notifications. The NETCONF server may 467 later retrieve logged notifications via the optional replay feature. 468 For more information on replay, see section 3.3. 470 +----+ 471 | c1 |----+ available streams 472 +----+ | +---------+ 473 +----+ | |central |-> stream 1 474 | c2 | +--->|event |-> stream 2 filter +-------+ 475 +----+ | |processor|-> NETCONF stream ----->|NETCONF| 476 ... | | |-> stream n |server | 477 System | +---------+ +-------+ 478 Components| | /\ 479 ... | | || 480 +----+ | | (------------) || 481 | cn |----+ | (notification) || 482 +----+ +-----> ( logging ) || 483 ( service ) || 484 (------------) || 485 || 486 || 487 \/ 488 +-------+ 489 |NETCONF| 490 |client | 491 +-------+ 493 Figure 2 495 3.2.1. Event Stream Definition 497 Event streams are predefined on the managed device. The 498 configuration of event streams is outside the scope of this document. 499 However, it is envisioned that event streams are either pre- 500 established by the vendor (pre-configured), user configurable (e.g., 501 part of the device's configuration) or both. Device vendors may 502 allow event stream configuration via the NETCONF protocol (i.e., 503 operation). 505 3.2.2. Event Stream Content Format 507 The contents of all event streams made available to a NETCONF client 508 (i.e., the notification sent by the NETCONF server) MUST be encoded 509 in XML. 511 3.2.3. Default Event Stream 513 A NETCONF server implementation supporting the notification 514 capability MUST support the "NETCONF" notification event stream. 515 This stream contains all NETCONF XML event notifications supported by 516 the NETCONF server. The exact string "NETCONF" is used during 517 advertisement of stream support during the operation on 518 and during the operation. Definition 519 of the event notifications and their contents, beyond the inclusion 520 of , for this event stream is outside the scope of this 521 document. 523 3.2.4. Event Stream Sources 525 With the exception of the default event stream (NETCONF), 526 specification of additional event stream sources (e.g., SNMP, syslog) 527 is outside the scope of this document. NETCONF server 528 implementations may leverage any desired event stream source in the 529 creation of supported event streams. 531 3.2.5. Event Stream Discovery 533 A NETCONF client retrieves the list of supported event streams from a 534 NETCONF server using the operation. 536 3.2.5.1. Name Retrieval using operation 538 The list of available event streams is retrieved by requesting the 539 subtree via a operation. Available event streams for 540 the requesting session are returned in the reply containing the 541 and elements, where the element is 542 mandatory, and its value is unique within the scope of a NETCONF 543 server. An empty reply is returned if there are no available event 544 streams, due to user-specified filters on the operation . 546 Additional information available about a stream include whether 547 notification replay is available and if so, the timestamp of the 548 earliest possible notification to replay. 550 The following example shows retrieving the list of available event 551 stream list using the operation. 553 555 556 557 558 559 560 561 562 563 The NETCONF server returns a list of event streams available for 564 subscription: NETCONF, SNMP, and syslog-critical in this example. 566 568 569 570 571 572 NETCONF 573 default NETCONF event stream 574 575 true 576 577 2007-07-08T00:00:00Z 578 579 580 581 SNMP 582 SNMP notifications 583 false 584 585 586 syslog-critical 587 Critical and higher severity 588 589 true 590 591 2007-07-01T00:00:00Z 592 593 594 595 596 597 599 3.2.5.2. Event Stream Subscription 601 A NETCONF client may request from the NETCONF server the list of 602 event streams available to this session and then issue a request with the desired event stream name. Omitting 604 the event stream name from the request results 605 in subscription to the default NETCONF event stream. 607 3.2.5.2.1. Filtering Event Stream Contents 609 The set of event notifications delivered in an event stream may be 610 further refined by applying a user-specified filter supplied at 611 subscription creation time ( ). This is a 612 transient filter associated with the event notification subscription 613 and does not modify the event stream configuration. The filter 614 element is applied against the contents of the wrapper 615 and not the wrapper itself. See section 5 for examples. Either 616 subtree or XPATH filtering can be used. 618 XPATH support for the Notification capability is advertised as part 619 of the normal XPATH capability advertisement. If XPATH support is 620 advertised via the XPATH capability then XPATH is supported for 621 notification filtering and if this capability is not advertised, 622 XPATH is not supported for notification filtering. 624 3.3. Notification Replay 626 3.3.1. Overview 628 Replay is the ability to create an event subscription that will 629 resend recently generated notifications, or in some cases send them 630 for the first time to a particular NETCONF client. These 631 notifications are sent the same way as normal notifications. 633 A replay of notifications is specified by including the optional 634 parameter to the subscription command, which indicates 635 the start time of the replay. The end time is specified using the 636 optional parameter. If not present, notifications will 637 continue to be sent until the subscription is terminated. 639 A notification stream that supports replay is not expected to have an 640 unlimited supply of saved notifications available to accommodate any 641 replay request. 643 The actual number of stored notifications available for retrieval at 644 any given time is a NETCONF server implementation specific matter. 645 Control parameters for this aspect of the feature are outside the 646 scope of this document. 648 Replay is dependent on a notification stream supporting some form of 649 notification logging, although it puts no restrictions on the size or 650 form of the log, or where it resides within the device. Whether or 651 not a stream supports replay can be discovered by doing a 652 operation on the element of the Notification Management 653 Schema and looking at the value of the object. This 654 schema also provides the element to indicate 655 the earliest available logged notification. 657 3.3.2. Creating a Subscription with Replay 659 This feature uses optional parameters to the 660 command called and . identifies the 661 earliest date and time of interest for event notifications being 662 replayed and also indicates that a subscription will be providing 663 replay of notifications. Events generated before this time are not 664 matched. specifies the latest date and time of interest 665 for event notifications being replayed. If it is not present, then 666 notifications will continue to be sent until the subscription is 667 terminated. 669 Note that and are associated with the time an 670 event was generated by the event source. 672 A notification is sent to indicate that all of the 673 replay notifications have been sent. If this subscription has a stop 674 time, then this session becomes a normal NETCONF session again. When 675 a has been specified, notification 676 is the last notification sent on the subscription before it 677 terminates and the NETCONF session returns to being a normal NETCONF 678 session. The NETCONF server will then accept operations. In 679 the case of a subscription without a stop time, after the 680 notification has been sent, it can be expected that 681 any notifications generated since the start of the subscription 682 creation will be sent, followed by notifications as they arise 683 naturally within the system. 685 The and notifications cannot 686 be filtered out. They will always be sent on a replay subscription 687 that specified a startTime and stopTime respectively. 689 3.4. Notification Management Schema 691 This Schema is used to learn about the event streams supported on the 692 system. It also contains the definition of the and 693 notifications, which are sent to indicate that 694 an event replay has sent all applicable notifications and that the 695 subscription has terminated, respectively. 697 698 706 707 708 A schema that can be used to learn about current 709 event streams. It also contains the replayComplete 710 and notificationComplete notification. 711 712 714 716 719 723 726 728 729 730 731 732 733 The list of event streams supported by the 734 system. When a query is issued, the returned 735 set of streams is determined based on user 736 privileges. 737 738 739 740 741 742 743 744 Stream name, description and other information. 745 746 747 748 749 751 752 753 The name of the event stream. If this is 754 the default NETCONF stream, this must have 755 the value "NETCONF". 756 757 758 759 761 762 763 A description of the event stream, including 764 such information as the type of events that 765 are sent over this stream. 766 767 768 769 771 772 773 An indication of whether or not event replay 774 is available on this stream. 775 776 777 778 780 781 782 The timestamp of the creation of the log 783 used to support the replay function on 784 this stream. 785 Note that this might be earlier then 786 the earliest available 787 notification in the log. This object 788 is updated if the log resets 789 for some reason. This 790 object MUST be present if replay is 791 supported. 792 793 794 795 798 799 800 The timestamp of the last notification 801 aged out of the log. This 802 object MUST be present if replay is 803 supported and any notifications 804 have been aged out of the log. 805 806 807 808 809 810 811 812 813 814 815 817 818 819 820 821 823 826 827 828 This notification is sent to signal the end of a replay 829 portion of a subscription. 830 831 832 834 835 836 837 838 840 843 844 845 This notification is sent to signal the end of a 846 notification subscription. It is sent in the case 847 that stopTime was specified during the creation of 848 the subscription. 849 850 851 853 855 3.5. Subscriptions Data 857 Subscriptions are non-persistent state information and their lifetime 858 is defined by their session or by the parameter. 860 3.6. Filter Mechanics 862 When multiple filter elements are specified, they are applied 863 collectively, so event notifications need to pass all specified 864 filter elements in order to be sent to the subscriber. If a filter 865 element is specified to look for data of a particular value, and the 866 data item is not present within a particular event notification for 867 its value to be checked against, the notification will be filtered 868 out. For example, if one were to check for 'severity=critical' in a 869 configuration event notification where this field was not supported, 870 then the notification would be filtered out. 872 For subtree filtering, a non-empty node set means that the filter 873 matches. For XPath filtering, the mechanisms defined in [XPATH] 874 should be used to convert the returned value to boolean. 876 3.6.1. Filtering 878 Filtering is explicitly stated when the event notification 879 subscription is created. This is specified via the 'filter' 880 parameter. A Filter only exist as a parameter to the subscription. 882 3.7. Message Flow 883 The following figure depicts message flow between a NETCONF client 884 (C) and NETCONF server (S) in order to create a subscription and 885 begin the flow of notifications. This subscription specified a 886 , so the server starts by replaying logged notifications. 887 It is possible that many rpc/rpc-reply sequences occur before the 888 subscription is created, but this is not depicted in the figure. 890 C S 891 | | 892 | capability exchange | 893 |-------------------------->| 894 |<------------------------->| 895 | | 896 | | (startTime) 897 |-------------------------->| 898 |<--------------------------| 899 | | 900 | | 901 | | 902 |<--------------------------| 903 | | 904 | | 905 |<--------------------------| 906 | | (replayComplete) 907 |<--------------------------| 908 | | 909 | | 910 | | 911 | | 912 |<--------------------------| 913 | | 914 | | 915 | | 916 |<--------------------------| 917 | | 918 | | 920 Figure 3 922 The following figure depicts message flow between a NETCONF client 923 (C) and NETCONF server (S) in order to create a subscription and 924 begin the flow of notifications. This subscription specified a 925 and so it starts by replaying logged 926 notifications and then returns to be a normal command-response 927 NETCONF session after the and 928 notifications are sent and it is available to process requests. 929 It is possible that many rpc/rpc-reply sequences occur before the 930 subscription is created, but this is not depicted in the figure. 932 C S 933 | | 934 | capability exchange | 935 |-------------------------->| 936 |<------------------------->| 937 | | 938 | | (startTime, 939 |-------------------------->| stopTime) 940 |<--------------------------| 941 | | 942 | | 943 | | 944 |<--------------------------| 945 | | 946 | | 947 |<--------------------------| 948 | | (replayComplete) 949 |<--------------------------| 950 | |(notificationComplete) 951 |<--------------------------| 952 | | 953 | | 954 | | 955 | | 956 |-------------------------->| 957 |<--------------------------| 958 | | 959 | | 961 Figure 4 963 4. XML Schema for Event Notifications 965 The following [XML Schema] defines NETCONF Event Notifications. 967 968 977 979 981 982 983 This import accesses the xml: attribute groups for the 984 xml:lang as declared on the error-message element. 985 986 987 989 990 994 996 998 999 1000 1001 1002 1004 1005 1006 An optional parameter that indicates 1007 which stream of events is of interest. If 1008 not present, then events in the default 1009 NETCONF stream will be sent. 1010 1011 1012 1013 1016 1017 1018 An optional parameter that indicates 1019 which subset of all possible events 1020 is of interest. The format of this 1021 parameter is the same as that of the 1022 filter parameter in the NETCONF 1023 protocol operations. If not present, 1024 all events not precluded by other 1025 parameters will be sent. 1026 1027 1028 1029 1031 1032 1033 A parameter used to trigger the replay 1034 feature and indicates that the replay 1035 should start at the time specified. If 1036 start time is not present, this is not a 1037 replay subscription. 1038 1039 1040 1041 1043 1044 1045 An optional parameter used with the 1046 optional replay feature to indicate the 1047 newest notifications of interest. If 1048 stop time is not present, the 1049 notifications will continue until the 1050 subscription is terminated. Must be used 1051 with startTime. 1052 1053 1054 1056 1057 1058 1059 1061 1062 1063 1064 The name of an event stream. 1065 1066 1067 1068 1070 1073 1074 1075 The command to create a notification subscription. It 1076 takes as argument the name of the notification stream 1077 and filter. Both of those options 1078 limit the content of the subscription. In addition, 1079 there are two time-related parameters, startTime and 1080 stopTime, which can be used to select the time interval 1081 of interest to the notification replay feature. 1082 1083 1084 1086 1088 1089 1091 1094 1095 1096 1097 1098 1099 The time the event was generated by the event source 1100 1101 1103 1104 1105 1106 1108 1110 1112 5. Filtering Examples 1114 The following section provides examples to illustrate the various 1115 methods of filtering content on an event notification subscription. 1117 In order to illustrate the use of filter expressions, it is necessary 1118 to assume some of the event notification content. The examples below 1119 assume that the event notification schema definition has an 1120 element at the top level consisting of the event class (e.g., fault, 1121 state, config), reporting entity and either severity or operational 1122 state. 1124 Examples in this section are generated from the following fictional 1125 Schema. 1127 1128 1134 1139 1140 1141 1142 1143 1144 1145 1146 1147 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1161 1165 1167 The above fictional notification definition could result in the 1168 following is a sample notification list, which is used in the 1169 examples in this section. 1171 1173 2007-07-08T00:01:00Z 1174 1175 fault 1176 1177 Ethernet0 1178 1179 major 1180 1181 1183 1185 2007-07-08T00:02:00Z 1186 1187 fault 1188 1189 Ethernet2 1190 1191 critical 1192 1193 1195 1197 2007-07-08T00:04:00Z 1198 1199 fault 1200 1201 ATM1 1202 1203 minor 1204 1205 1207 1209 2007-07-08T00:10:00Z 1210 1211 state 1212 1213 Ethernet0 1214 1215 enabled 1216 1217 1219 5.1. Subtree Filtering 1221 XML subtree filtering is not well-suited for creating elaborate 1222 filter definitions given that it only supports equality comparisons 1223 and application of the logical OR operators (e.g., in an event 1224 subtree give me all event notifications which have severity=critical 1225 or severity=major or severity=minor). Nevertheless, it may be used 1226 for defining simple event notification forwarding filters as shown 1227 below. 1229 The following example illustrates how to select fault events which 1230 have severities of critical, major, or minor. The filtering criteria 1231 evaluation is as follows: 1233 ((fault & severity=critical) | (fault & severity=major) | (fault & 1234 severity=minor)) 1236 1238 1240 1241 1242 fault 1243 critical 1244 1245 1246 fault 1247 major 1248 1249 1250 fault 1251 minor 1252 1253 1254 1255 1257 The following example illustrates how to select state or config 1258 EventClasses or fault events that are related to card Ethernet0. The 1259 filtering criteria evaluation is as follows: 1261 ( state | config | ( fault & ( card=Ethernet0))) 1263 1265 1267 1268 1269 state 1270 1271 1272 config 1273 1274 1275 fault 1276 1277 Ethernet0 1278 1279 1280 1281 1282 1284 5.2. XPATH filters 1286 The following [XPATH] example illustrates how to select fault 1287 EventClass notifications that have severities of critical, major, or 1288 minor. The filtering criteria evaluation is as follows: 1290 ((fault) & ((severity=critical) | (severity=major) | (severity = 1291 minor))) 1293 1295 1297 1302 1303 1305 The following example illustrates how to select state and config 1306 EventClasses or fault events of any severity that come from card 1307 Ethernet0. The filtering criteria evaluation is as follows: 1309 ( state | config | (fault & card=Ethernet0)) 1311 1313 1315 1320 1321 1323 6. Interleave Capability 1325 6.1. Description 1327 The Interleave capability indicates that the NETCONF peer supports 1328 the ability to interleave other NETCONF operations within a 1329 Notification subscription. This means the NETCONF server is able to 1330 receive, process and respond to NETCONF requests on a session with an 1331 active notification subscription. 1333 6.2. Dependencies 1335 This capability is dependant on the notification capability being 1336 supported. 1338 6.3. Capability Identifier 1340 The :interleave capability is identified by the following capability 1341 string: 1343 urn:ietf:params:netconf:capability:interleave:1.0 1345 6.4. New Operations 1347 None. 1349 6.5. Modifications to Existing Operations 1351 When a is sent while another subscription is 1352 active on that session, the following error will be returned: 1354 Tag: operation-failed 1356 Error-type: protocol 1358 Severity: error 1360 Error-info: : startTime 1362 Description: Request could not be completed because the requested 1363 operation failed for some reason not covered by any other error 1364 condition. 1366 7. Security Considerations 1368 The security considerations from the base [NETCONF] document also 1369 apply to the Notification capability. 1371 The access control framework and the choice of transport will have a 1372 major impact on the security of the solution. 1374 The elements are never sent before the transport layer 1375 and the NETCONF layer, including capabilities exchange, have been 1376 established, and the manager has been identified and authenticated. 1378 It is recommended that care be taken to secure execution: 1380 o invocation 1382 o on read-only data models 1384 o content 1386 One potential security issue is the transport of data from non- 1387 NETCONF streams, such as syslog and SNMP. This data may be more 1388 vulnerable (or less vulnerable) when being transported over NETCONF 1389 than when being transported using the protocol normally used for 1390 transporting it, depending on the security credentials of the two 1391 subsystems. The NETCONF server is responsible for applying access 1392 control to stream content. 1394 The contents of notifications as well as the name of event streams 1395 may contain sensitive information and care should be taken to ensure 1396 that it is viewed only by authorized users. If a user does not have 1397 permission to view content via other NETCONF operations, it must not 1398 have access that content via Notifications. If a user is not 1399 permitted to view one element in the content of the notification, the 1400 notification is not sent to that user. 1402 If a subscription is created with a , the NETCONF session 1403 will return to being a normal command-response NETCONF session when 1404 the replay is completed. It is the responsibility of the NETCONF 1405 client to close this session when it is no longer of use. 1407 8. IANA Considerations 1409 This document registers three URIs for the NETCONF XML namespace in 1410 the IETF XML registry [RFC3688]. 1412 Following the format in RFC 3688, IANA has made the following 1413 registration. 1415 URI: urn:ietf:params:netconf:capability:notification:1.0 1417 URI: urn:ietf:params:xml:ns:netmod:notification 1419 URI: urn:ietf:params:xml:ns:netconf:notification:1.0 1421 URI: urn:ietf:params:netconf:capability:interleave:1.0 1423 Registrant Contact: The IESG. 1425 XML: N/A, the requested URI is an XML namespace. 1427 9. Acknowledgements 1429 Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing 1430 their input into the early work on this document. In addition, the 1431 editors would like to acknowledge input at the Vancouver editing 1432 session from the following people: Orly Nicklass, James Balestriere, 1433 Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, 1434 Dave Partain, Ray Atarashi and David Perkins and the following 1435 additional people from the Montreal editing session: Balazs Lengyel, 1436 Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen, 1437 Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig, 1438 Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William 1439 Chow. We would also like to thank Li Yan for his numerous reviews. 1441 10. Normative References 1443 [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 1444 December 2006. 1446 [RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements 1447 Levels", RFC 2119, March 1997. 1449 [RFC3688] Bradner, s., "The IETF XML Registry", RFC 3688, January 1450 2004. 1452 [XML] World Wide Web Consortium, "Extensible Markup Language 1453 (XML) 1.0", W3C XML, February 1998, 1454 . 1456 [XML Schema] 1457 Fallside, D. and P. Walmsley, "XML Schema Part 0: Primer 1458 Second Edition", W3C XML Schema, October 2004. 1460 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 1461 Version 1.0", 1462 W3C http://www.w3.org/TR/1999/REC-xpath-19991116, 1463 November 1999. 1465 Appendix A. Change Log 1467 A.1. Version -08 1469 1. Removed named profiles 1471 2. Removed eventClass that was accidentally included in the 1472 definition of the replayComplete notification 1474 3. Deleted data wrapper from notification 1476 4. Changed replayLogStartTime to have a minOccurs of 0. It will 1477 only be there when replay is supported. Verify examples in 1478 section 3.2.5.1 are correct with respect to this element. 1480 5. Error codes in section 2.1.1, fixed formatting issue 1482 6. Moved replayComplete to not be under 1484 7. Section 2.1, fixed capitalization 1486 8. In figure 4, the line was pushed out by 'system components', 1487 fixed this. 1489 9. On page 8, replaced "If the startTime specified is earlier then 1490 the" with 'If the startTime specified is earlier than the" 1492 10. Updated some name spaces and schemaLocations as per Andy's June 1493 3rd email. 1495 11. Added discussion of replayLogStartTime to draft in section 3.3.1 1496 as follows "Whether or not a stream supports replay can be 1497 discovered by doing a operation on the elements 1498 of the Notification Management Schema. This schema also 1499 provides the replayLogStartTime element to indicate the earliest 1500 available logged notification." 1502 12. Removed most of the uses of the phrase 'Note that'. I kept two 1503 uses that prevent sentences from starting with either a lower 1504 case letter or an angle bracket. 1506 13. In section 3.6 replaced "it will be filtered out" with "the 1507 notification will be filtered out" 1509 14. In section 3.4, replaced "and the query" with "and to query" 1511 15. Replaced 3 instances of "replay complete notification" with 1512 "replayComplete notification" 1514 16. In section 3.3.2, replaced "normal NETCONF session" with "normal 1515 command-response NETCONF session" 1517 17. In section 3.3.1, replaced "create an event subscription that 1518 will resend recently generated notification" with "create an 1519 event subscription that will resend recently generated 1520 notification, or is some cases send them for the first time to a 1521 particular NETCONF client." 1523 18. In section 3.2.5.2, s/available event streams to/event streams 1524 available to/ 1526 19. In one spot, changed snmp to SNMP (the other gets deleted) 1528 20. In section 3.2.5.1 s/where element is/where the 1529 element is/ 1531 21. In section 3.2.5.1, clarified that "value is unique" - within 1532 the scope of a NETCONF server. 1534 22. In section 2.1.1, clarified that stopTime cannot preceded start 1535 time. 1537 23. In section 2.1.1, in Start Time s/indicates/indicate/ 1539 24. In section 2.1.1, in Filter: s/This is mutually exclusive/The 1540 filter parameter is mutually exclusive/ ("this" could refer to 1541 the behaviour described in the previous sentence.) 1543 25. In section 1.4, third bullet, replaced "syslog and SNMP are 1544 rather constrained in terms of message sizes)" with (ie, not too 1545 short) 1547 26. In section 1.4, made all bullets start with capital letters. 1549 27. Added definition of Filter to section 1.1 1551 28. In section 1.1, improved the definition of subscription with "An 1552 agreement and method to receive event notifications over a 1553 NETCONF session." 1555 29. In section 1.1, in the definition of operation, added a 1556 reference to [NETCONF]. 1558 30. Created a change log section 1560 31. Fixed reference to IETF XML Registry in IANA Considerations 1561 section. 1563 32. In section 3.3.3, deleted "This notification will only be sent 1564 if a 'stopTime' was specified when the replay subscription was 1565 created." 1567 33. Added text to the security considerations section that says "If 1568 a subscription is created with a stopTime, the NETCONF session 1569 will return to being a normal command-response NETCONF session 1570 when the replay is completed. It is the responsibility of the 1571 NETCONF client to close off this session when it is no longer of 1572 use". 1574 34. Update examples in section 5 to get rid of extra wrapper tag. 1576 35. In section 2.1, replace "A NETCONF server is not required to 1577 process RPC requests on the session associated with the 1578 subscription until the notification subscription is done and may 1579 silently discard these requests." with "A NETCONF server is will 1580 not read RPC requests, by default, on the session associated 1581 with the subscription until the notification subscription is 1582 done. 1584 36. Updated the notification definition and the replyComplete 1585 notification definition to use a substitution group. 1587 A.2. Version -09 1589 1. In section 5.1 "logical OR operation" -> "application of the 1590 logical OR operator" 1592 2. In section 6 "ensure the secure operation of the following 1593 commands" -> "secure execution" 1595 3. Removed a couple remaining references to named profiles. 1597 4. Updated name datatype in eventStreams element. 1599 5. Modified the cardinality of eventStreams to reflect that there 1600 will always be at least one event stream. 1602 6. Fixed description of examples to remove reference to eventEntry, 1603 which is no longer part of the actual example. 1605 7. In examples, for consistency changed some references to 1606 reportingElement to be reportingEntity 1608 8. Fixed section 3.2, third paragraph to talk about filter elements 1609 instead of filters. 1611 9. Merge section 3.3.2 and section 3.3.3. Delete the first 1612 paragraph in (old) section 3.3.3 since it both duplicates and 1613 contradicts text in section 3.3.2 1615 10. In section 3.2.5.2.1, added clarification to first paragraph 1616 that "Either subtree or XPATH filtering can be used. " 1618 11. Removed discussion of not allowing the return of stream names 1619 for which the user does not have permissions from the body of 1620 the document to the security considerations section. 1622 12. Fixed typos and did wordsmithing in various parts of the 1623 document. 1625 13. In section 2.1, explicitly stated that a subscription is bound 1626 to a single stream for the lifetime of the subscription. 1628 14. removed single quotes around some instances of stopTime and 1629 startTime for consistency. When appropriate, put between angle 1630 brackets. 1632 15. In section 2.1.1, changed "Error-info: : startTime" 1633 to use bad-element. 1635 16. In section 2.2.1, under the parameter tag, replaced "Contains 1636 notification-specific tagged content." with "Contains 1637 notification-specific tagged content, if any. " 1639 17. Clarified some text in section 3.2, paragraph 3 around sending 1640 of filters from client and the filters later being applied to 1641 the notifications. 1643 18. Fixed target namespace in section 4. 1645 19. Added missing lang and version information to schema in section 1646 3.4 1648 20. Clarified that the examples in section 5 all used the same 1649 example event list. 1651 21. Cleaned up security considerations section. 1653 22. In section 3.4, clarified the definition of replayLogStart time 1654 to be the timestamp of the earliest available notification in 1655 the log used to support the replay function in the description 1656 tag for the object definition. 1658 23. In section 3.3.2, clarified that the time an event was generated 1659 by the system means time an event was generated by the event 1660 source. 1662 24. In section 3.5, deleted discussion about possibly defining 1663 subscriptions in XML Schema. 1665 25. In section 3.6, deleted discussion about filter element 1666 execution order not mattering. 1668 26. Fixed examples in section 5 to add tag and to make 1669 other corrections 1671 27. Added XML Schema definition for examples in section 5 and showed 1672 the event list with wrappers. 1674 28. Added notification 1676 29. Removed support of startTime and stopTime in the future. 1678 30. Replaced replayLogStartTime with replayLogCreationTime and 1679 replayLogAgedTime. 1681 A.3. Version -10 1683 1. Changed the description of stopTime to allow stopTimes in the 1684 future. 1686 2. Added interleave capability 1688 3. Clarified create-subscription error messages. 1690 4. Corrected targetNamespace in Netconf Notification XSD 1692 5. Fixed typos and made minor edits. 1694 Authors' Addresses 1696 Sharon Chisholm 1697 Nortel 1698 3500 Carling Ave 1699 Nepean, Ontario K2H 8E9 1700 Canada 1702 Email: schishol@nortel.com 1704 Hector Trevino 1705 Cisco 1706 Suite 400 1707 9155 E. Nichols Ave 1708 Englewood, CO 80112 1709 USA 1711 Email: htrevino@cisco.com 1713 Full Copyright Statement 1715 Copyright (C) The IETF Trust (2007). 1717 This document is subject to the rights, licenses and restrictions 1718 contained in BCP 78, and except as set forth therein, the authors 1719 retain all their rights. 1721 This document and the information contained herein are provided on an 1722 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1723 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1724 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1725 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1726 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1727 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1729 Intellectual Property 1731 The IETF takes no position regarding the validity or scope of any 1732 Intellectual Property Rights or other rights that might be claimed to 1733 pertain to the implementation or use of the technology described in 1734 this document or the extent to which any license under such rights 1735 might or might not be available; nor does it represent that it has 1736 made any independent effort to identify any such rights. Information 1737 on the procedures with respect to rights in RFC documents can be 1738 found in BCP 78 and BCP 79. 1740 Copies of IPR disclosures made to the IETF Secretariat and any 1741 assurances of licenses to be made available, or the result of an 1742 attempt made to obtain a general license or permission for the use of 1743 such proprietary rights by implementers or users of this 1744 specification can be obtained from the IETF on-line IPR repository at 1745 http://www.ietf.org/ipr. 1747 The IETF invites any interested party to bring to its attention any 1748 copyrights, patents or patent applications, or other proprietary 1749 rights that may cover technology that may be required to implement 1750 this standard. Please address the information to the IETF at 1751 ietf-ipr@ietf.org. 1753 Acknowledgment 1755 Funding for the RFC Editor function is provided by the IETF 1756 Administrative Support Activity (IASA).