idnits 2.17.1 draft-ietf-netconf-notification-07.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 1331. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1342. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1349. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1355. 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 1021 has weird spacing: '... and filte...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- 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 (May 15, 2007) is 6191 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) -- Looks like a reference, but probably isn't: '7' on line 1244 == Unused Reference: 'RFC2026' is defined on line 1276, but no explicit reference was found in the text == Unused Reference: 'RFC2223' is defined on line 1282, but no explicit reference was found in the text ** Obsolete normative reference: RFC 4741 (ref. 'NETCONF') (Obsoleted by RFC 6241) ** Obsolete normative reference: RFC 2223 (Obsoleted by RFC 7322) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 10 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: November 16, 2007 Cisco 5 May 15, 2007 7 NETCONF Event Notifications 8 draft-ietf-netconf-notification-07.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 November 16, 2007. 35 Copyright Notice 37 Copyright (C) The IETF Trust (2007). 39 Abstract 41 This document defines mechanisms which provide an asynchronous 42 message notification delivery service for the NETCONF protocol. This 43 is an optional capability built on top of the base NETCONF 44 definition. This document defines the capabilities and operations 45 necessary to 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 . . . . . . . . . . . . . . 5 53 1.4. Requirements . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . 12 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 . . . . . . . . . . . . . . . . . . . 15 71 3.3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 15 72 3.3.2. Creating a Subscription with Replay . . . . . . . . . 16 73 3.3.3. Replay Complete Notification . . . . . . . . . . . . . 16 74 3.4. Notification Management Schema . . . . . . . . . . . . . . 16 75 3.5. Subscriptions Data . . . . . . . . . . . . . . . . . . . . 20 76 3.6. Filter Mechanics . . . . . . . . . . . . . . . . . . . . . 20 77 3.6.1. Named Profiles . . . . . . . . . . . . . . . . . . . . 21 78 3.6.2. Filtering . . . . . . . . . . . . . . . . . . . . . . 21 79 3.7. Message Flow . . . . . . . . . . . . . . . . . . . . . . . 21 80 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 23 81 5. Filtering Examples . . . . . . . . . . . . . . . . . . . . . . 27 82 5.1. Subtree Filtering . . . . . . . . . . . . . . . . . . . . 27 83 5.2. XPATH filters . . . . . . . . . . . . . . . . . . . . . . 30 84 6. Security Considerations . . . . . . . . . . . . . . . . . . . 32 85 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 86 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 34 87 9. Normative References . . . . . . . . . . . . . . . . . . . . . 35 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 36 89 Intellectual Property and Copyright Statements . . . . . . . . . . 37 91 1. Introduction 93 [NETCONF] can be conceptually partitioned into four layers: 95 Layer Example 96 +-------------+ +----------------------------------------+ 97 | Content | | Configuration data | 98 +-------------+ +----------------------------------------+ 99 | | 100 +-------------+ +-------------------------------------------+ 101 | Operations | | , | 102 +-------------+ +-------------------------------------------+ 103 | | | 104 +-------------+ +-----------------------------+ | 105 | RPC | | , | | 106 +-------------+ +-----------------------------+ | 107 | | | 108 +-------------+ +------------------------------------------+ 109 | Transport | | BEEP, SSH, SSL, console | 110 | Protocol | | | 111 +-------------+ +------------------------------------------+ 113 Figure 1 115 This document defines mechanisms which provide an asynchronous 116 message notification delivery service for the [NETCONF] protocol. 117 This is an optional capability built on top of the base NETCONF 118 definition. This memo defines the capabilities and operations 119 necessary to support this service. 121 1.1. Definition of Terms 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 125 document are to be interpreted as described in [RFC2119]. 127 Element: An [XML] Element. 129 Subscription: A concept related to the delivery of notifications (if 130 any to send) involving destination and selection of notifications. 131 It is bound to the lifetime of a session. 133 Operation: This term is used to refer to NETCONF protocol 134 operations. Specifically within this document, operation refers 135 to NETCONF protocol operations defined in support of NETCONF 136 notifications. 138 Event: An event is something that happens which may be of interest - 139 a configuration change, a fault, a change in status, crossing a 140 threshold, or an external input to the system, for example. Often 141 this results in an asynchronous message, sometimes referred to as 142 a notification or event notification, being sent to interested 143 parties to notify them that this event has occurred. 145 Replay: The ability to send/re-send previously logged notifications 146 upon request. These notifications are sent asynchronously. This 147 feature is implemented by the NETCONF server and invoked by the 148 NETCONF client. 150 Stream: An event stream is a set of event notifications matching 151 some forwarding criteria and it is available to NETCONF clients 152 for subscription. 154 Named Profile: A predefined set of filtering criteria residing in 155 the Network Element which may be applied to a notification session 156 at subscription creation time. 158 1.2. Motivation 160 The motivation for this work is to enable the sending of asynchronous 161 messages that are consistent with the data model (content) and 162 security model used within a NETCONF implementation. 164 1.3. Event Notifications in NETCONF 166 This memo defines a mechanism whereby the NETCONF client indicates 167 interest in receiving event notifications from a NETCONF server by 168 creating a subscription to receive event notifications. The NETCONF 169 server replies to indicate whether the subscription request was 170 successful and, if it was successful, begins sending the event 171 notifications to the NETCONF client as the events occur within the 172 system. These event notifications will continue to be sent until 173 either the NETCONF session is terminated or the subscription 174 terminates for some other reason. The event notification 175 subscription allows a number of options to enable the NETCONF client 176 to specify which events are of interest. These are specified when 177 the subscription is created. 179 A NETCONF server is not required to process RPC requests on the 180 session associated with the subscription until the notification 181 subscription is done and may silently discard these requests. A 182 capability may be advertised to announce that a server is able to 183 process RPCs while a notification stream is active on a session. The 184 behaviour of such a capability is outside the scope of this document. 186 1.4. Requirements 188 The following requirements have been addressed by the solution: 190 o Initial release should ensure it supports notification in support 191 of configuration operations 193 o Data content must not preclude the use of the same data model as 194 used in configuration 196 o solution should support a reasonable message size limit (syslog 197 and SNMP are rather constrained in terms of message sizes) 199 o solution should provide reliable delivery of notifications 201 o solution should provide a subscription mechanism (A NETCONF server 202 does not send notifications before being asked to do so and the 203 NETCONF client initiates the flow of notifications) 205 o solution should provide a filtering mechanism within the NETCONF 206 server 208 o solution should send sufficient information in a notification so 209 that it can be analyzed independent of the transport mechanism 210 (data content fully describes a notification; protocol information 211 is not needed to understand a notification) 213 o solution should support replay of locally logged notifications 215 2. Notification-Related Operations 217 2.1. Subscribing to receive Event Notifications 219 The event notification subscription is initiated by the NETCONF 220 client and responded to by the NETCONF server. When the event 221 notification subscription is created, the events of interest are 222 specified. 224 Content for an event notification subscription can be selected by 225 applying user-specified filters. 227 2.1.1. 229 Description: 231 This operation initiates an event notification subscription which 232 will send asynchronous event notifications to the initiator of the 233 command until the subscription terminates. 235 Parameters: 237 Stream: 239 An optional parameter that indicates which stream of events is 240 of interest. If not present, then events in the default 241 NETCONF stream will be sent. 243 Filter: 245 An optional parameter that indicates which subset of all 246 possible events are of interest. The format of this parameter 247 is the same as that of the filter parameter in the NETCONF 248 protocol operations. If not present, all events not precluded 249 by other parameters will be sent. This is mutually exclusive 250 with the named profile parameter. See section 3.6 for more 251 information on filters. 253 Named Profile: 255 An optional parameter that refers to a separately defined 256 filter profile. If not present, no additional filtering will 257 be applied. Note that changes to the profile after the 258 subscription has been created will have no effect. This is 259 mutually exclusive with the filter parameter. For more 260 information on named profiles, see section 3.6.1. 262 Start Time: 264 A parameter used to trigger the replay feature and indicates 265 that the replay should start at the time specified. If 266 startTime is not present, this is not a replay subscription. 267 It is valid to specify start times that are later than the 268 current time. If the startTime specified is earlier then the 269 log can support, the replay will begin with the earliest 270 available notification. This parameter is of type dateTime. 272 Stop Time: 274 An optional parameter used with the optional replay feature to 275 indicate the newest notifications of interest. If stop time is 276 not present, the notifications will continue until the 277 subscription is terminated. Must be used with 'startTime'. It 278 is valid to specify stop times that are later than the current 279 time. This parameter is of type dateTime. 281 Positive Response: 283 If the NETCONF server can satisfy the request, the server sends an 284 element. 286 Negative Response: 288 An element is included within the if the 289 request cannot be completed for any reason. Subscription requests 290 will fail if a filter with invalid syntax is provided or if the 291 name of a non-existent profile or stream is provided. 293 If a stopTime is specified in a request without having specified a 294 startTime the following error is returned: 296 Tag: missing-element 298 Error-type: protocol 300 Severity: error 302 Error-info: 324 325 326 328 2.2. Sending Event Notifications 330 Once the subscription has been set up, the NETCONF server sends the 331 event notifications asynchronously over the connection. 333 2.2.1. 335 Description: 337 An event notification is sent to the client who initiated a 338 command asynchronously when an event of 339 interest (i.e., meeting the specified filtering criteria) to them 340 has occurred. An event notification is a complete and well-formed 341 XML document. Note that is not an RPC method but 342 rather the top level element identifying the one way message as a 343 notification. 345 Parameters: 347 Data: 349 Contains notification-specific tagged content. The content of 350 the data tag is beyond the scope of this document. 352 Response: 354 No response. Not applicable. 356 2.3. Terminating the Subscription 358 Closing of the event notification subscription can be done by 359 terminating the NETCONF session ( ) or the underlying 360 transport session. If a stop time is provided when the subscription 361 is created, then the subscription will terminate after the stop time 362 is reached. In this case, the NETCONF session will still be an 363 active session. 365 3. Supporting Concepts 367 3.1. Capabilities Exchange 369 The ability to process and send event notifications is advertised 370 during the capability exchange between the NETCONF client and server. 372 3.1.1. Capability Identifier 374 "urn:ietf:params:netconf:capability:notification:1.0" 376 3.1.2. Capability Example 378 379 380 381 urn:ietf:params:xml:ns:netconf:base:1.0 382 383 384 urn:ietf:params:netconf:capability:startup:1.0 385 386 387 urn:ietf:params:netconf:capability:notification:1.0 388 389 390 4 391 393 3.2. Event Streams 395 An event stream is defined as a set of event notifications matching 396 some forwarding criteria. 398 The diagram depicted in Figure 2 illustrates the notification flow 399 and concepts identified in this document. The following is observed 400 from the diagram below: System components (c1..cn) generate event 401 notifications which are passed to a central component for 402 classification and distribution. The central component inspects each 403 event notification and matches the event notification against the set 404 of stream definitions. When a match occurs, the event notification 405 is considered to be a member of that event stream (stream 1..stream 406 n). An event notification may be part of multiple event streams. 408 When a NETCONF client subscribes to a given event stream, user- 409 defined filters, if applicable, are applied to the event stream and 410 matching event notifications are forwarded to the NETCONF server for 411 distribution to subscribed NETCONF clients. For more information on 412 filters, see section 3.6. 414 A notification logging service may also be available, in which case, 415 the central component logs notifications. The NETCONF server may 416 later retrieve logged notifications via the optional replay feature. 417 For more information on replay, see section 3.3. 419 +----+ 420 | c1 |---+ available streams 421 +----+ | +---------+ 422 +----+ | |central |-> stream 1 423 | c2 | +--->|event |-> stream 2 filter +-------+ 424 +----+ | |processor|-> NETCONF stream ----->|netconf| 425 ... | | |-> stream n |server | 426 System | +---------+ +-------+ 427 Components| | /\ 428 ... | | || 429 +----+ | | (------------) || 430 | cn |---+ | (notification) || 431 +----+ +-----> ( logging ) || 432 ( service ) || 433 (------------) || 434 || 435 || 436 \/ 437 +-------+ 438 |netconf| 439 |client | 440 +-------+ 442 Figure 4 444 3.2.1. Event Stream Definition 446 Event streams are predefined on the managed device. The 447 configuration of event streams is outside the scope of this document. 448 However, it is envisioned that event streams are either pre- 449 established by the vendor (pre-configured) or user configurable 450 (e.g., part of the device's configuration) or both. Device vendors 451 may allow event stream configuration via NETCONF protocol (i.e., 452 edit-config operation). 454 3.2.2. Event Stream Content Format 456 The contents of all event streams made available to a NETCONF client 457 (i.e., the notification sent by the NETCONF server) must be encoded 458 in XML. 460 3.2.3. Default Event Stream 462 A NETCONF server implementation supporting the notification 463 capability must support the "NETCONF" notification event stream. 464 This stream contains all NETCONF XML event notifications supported by 465 the NETCONF server. The definition of the event notifications and 466 their contents for this event stream is outside the scope of this 467 document. 469 3.2.4. Event Stream Sources 471 With the exception of the default event stream (NETCONF 472 notifications) specification of additional event stream sources 473 (e.g., SNMP, syslog, etc.) is outside the scope of this document. 474 NETCONF server implementations may leverage any desired event stream 475 source in the creation of supported event streams. 477 3.2.5. Event Stream Discovery 479 A NETCONF client retrieves the list of supported event streams from a 480 NETCONF server using the RPC request. 482 3.2.5.1. Name Retrieval using operation 484 The list of available event streams is retrieved by requesting the 485 subtree via a operation. Available event 486 streams for the requesting session are returned in the reply 487 containing the and elements, where 488 element is mandatory and its value is unique. The returned list must 489 only include the names of those event streams for which the NETCONF 490 session has sufficient privileges. The NETCONF session privileges 491 are determined via access control mechanisms which are beyond the 492 scope of this document. An empty reply is returned if there are no 493 available event streams. The information is retrieved by requesting 494 the subtree via a operation. 496 Example: Retrieving available event stream list using 497 operation: 499 502 503 504 505 506 507 509 The NETCONF server returns a list of event streams available for 510 subscription: NETCONF, snmp, and syslog-critical in this example. 512 514 515 516 517 NETCONF 518 Default netconf event stream 519 520 true 521 522 523 snmp 524 SNMP notifications 525 false 526 527 528 syslog-critical 529 Critical and higher severity 530 531 true 532 533 534 535 537 3.2.5.2. Event Stream Subscription 539 A NETCONF client may request from the NETCONF server the list of 540 available event streams to this session and then issue a request with the desired event stream name. Omitting 542 the event stream name from the request results 543 in subscription to the default NETCONF event stream. 545 3.2.5.2.1. Filtering Event Stream Contents 547 The set of event notifications delivered in an event stream may be 548 further refined by applying a user-specified filter at subscription 549 creation time ( ). This is a transient filter 550 associated with the event notification subscription and does not 551 modify the event stream configuration. 553 XPATH support for the Notification capability is advertised as part 554 of the normal XPATH capability advertisement. If XPATH support is 555 advertised via the XPATH capability then XPATH is supported for 556 notification filtering and if this capability is not advertised, then 557 XPATH is not supported for notification filtering. 559 3.3. Notification Replay 561 3.3.1. Overview 563 Replay is the ability to create an event subscription that will 564 resend recently generated notifications. These notifications are 565 sent the same way as normal notifications. 567 A replay of notifications is specified by including an optional 568 parameter to the subscription command that indicates the start time 569 of the replay. The end time is specified using the optional stopTime 570 parameter. If not present, notifications will continue to be sent 571 until the subscription is terminated. 573 A notification stream that supports replay is not expected to have an 574 unlimited supply of saved notifications available to accommodate any 575 replay request. 577 The actual number of stored notifications available for retrieval at 578 any given time is a NETCONF server implementation specific matter. 579 Control parameters for this aspect of the feature are outside the 580 scope of the current document. 582 Replay is dependent on a notification stream supporting some form of 583 notification logging, although it puts no restrictions on the size or 584 form of the log, nor where it resides within the device. 586 3.3.2. Creating a Subscription with Replay 588 This feature uses optional parameters to the 589 command called 'startTime' and 'stopTime'. 'startTime' identifies the 590 earliest date and time of interest for event notifications being 591 replayed and also indicates that a subscription will be providing 592 replay of notifications. Events generated before this time are not 593 matched. 'stopTime' specifies the latest date and time of interest 594 for event notifications being replayed. If it is not present, then 595 notifications will continue to be sent until the subscription is 596 terminated. 598 Note that startTime and stopTime are associated with the time an 599 event was generated by the system. 601 A replay complete notification is sent to indicate that all of the 602 replay notifications have been sent. If this subscription has a stop 603 time, then this session becomes a normal NETCONF session again. In 604 the case of a subscription without a stop time, after the replay 605 complete notification has been sent, it can be expected that any 606 notifications generated since the start of the subscription creation 607 will be sent followed by notifications as they arise naturally within 608 the system. 610 3.3.3. Replay Complete Notification 612 The replay complete notification is the last notification sent over a 613 replay subscription. It indicates that replay is complete. This 614 notification will only be sent if a 'stopTime' was specified when the 615 replay subscription was created. After this notification is received 616 the subscription is terminated and the session becomes a normal 617 NETCONF session. 619 The replayComplete can not be filtered out. It will always be sent 620 on a relay subscription that specified a stop time. 622 3.4. Notification Management Schema 624 This Schema is used to learn about the event streams supported on the 625 system and the query and modify named profiles. It also contains the 626 definition of the replayComplete, which is sent to indicate that an 627 event replay has sent all applicable notifications." 629 630 637 638 639 A schema that can be used to learn about current 640 event streams and to manage named profiles. It also 641 contains the replayComplete notification. 642 643 645 647 649 654 656 657 658 659 660 661 The list of event streams supported by the 662 system. When a query is issued, the returned 663 set of streams is determined based on user 664 privileges. 665 666 667 668 669 670 671 672 Stream name and description. 673 674 675 676 677 678 681 683 685 686 687 The start time of the log used to 688 support the replay function. If 689 replay is not supported, this will 690 return the current time. 691 692 693 694 695 696 697 698 699 701 702 703 704 707 708 709 711 714 715 716 This notification is sent to signal the end of a replay 717 portion of a subscription. 718 719 720 721 722 724 725 726 727 728 729 730 731 732 734 735 736 737 A named profile, which is a saved set of parameters 738 that may be associated with zero or more 739 active subscriptions. 741 This object can be created, read, deleted and its 742 individual components can be modified. 743 744 745 747 748 749 750 The name associated with the profile. 751 This object is readable and modifiable. 752 753 754 756 757 758 759 The event stream associated with this named 760 profile. 762 This object is readable and modifiable. 763 764 765 767 769 770 771 The filters associated with this named 772 profile. 774 This object is readable and modifiable. 775 776 777 779 780 781 782 The timestamp of the last modification to this 783 named Profile. Note that modification of the 784 profile does not cause an immediate update 785 to all applicable subscription. Therefore, 786 this time should be compared with the last 787 modified time associated with the 788 subscription. If this time is earlier, then 789 the subscription is using the exact set of 790 parameters associated with this named profile. 791 If this time is later, then the subscription 792 is using an earlier version of this named 793 profile and the exact parameters may not 794 match. Note there is no guarantee that the 795 profile named in the subscription will be 796 found at all." 798 This object is read-only. 799 800 801 802 803 804 806 3.5. Subscriptions Data 808 While it may be possible to retrieve information about subscriptions 809 via a get operation, subscriptions are not stored configuration. 810 They are non-persistent state information and their lifetime is 811 defined by their session. 813 Named profiles, if used, are considered configuration data. 815 3.6. Filter Mechanics 817 Note that when multiple filter elements are specified, they are 818 applied collectively, so event notifications need to pass all 819 specified filters in order to be sent to the subscriber. If a filter 820 element is specified to look for data of a particular value, and the 821 data item is not present within a particular event notification for 822 its value to be checked against, it will be filtered out. For 823 example, if one were to check for 'severity=critical' in a 824 configuration event notification where this field was not supported, 825 then the notification would be filtered out. 827 Note that the order that filter elements are applied does not matter 828 since the resulting set of notifications is the intersection of the 829 set of notifications that pass each filtering criteria. 831 3.6.1. Named Profiles 833 A named profile is a filter that is created ahead of time and applied 834 at the time an event notification subscription is created. Note that 835 changes to the profile after the subscription has been created will 836 have no effect on the subscription. Since named profiles exist 837 outside of the subscription, they persist after the subscription has 838 been torn down. 840 3.6.2. Filtering 842 Inline filtering is explicitly stated when the event notification 843 subscription is created. This is specified via the 'filter' 844 parameter. Filters only exist as parameters to the subscription. 846 3.7. Message Flow 847 The following figure depicts message flow between a NETCONF client 848 (C) and NETCONF server (S) in order create a subscription and begin 849 the flow of notifications. It is possible that many rpc/rpc-reply 850 sequences occur before the subscription is created or after a 851 stopTime in a replay subscription, but this is not depicted in the 852 figure. 854 C S 855 | | 856 | capability exchange | 857 |-------------------------->| 858 |<------------------------->| 859 | | 860 | | 861 |-------------------------->| 862 |<--------------------------| 863 | | 864 | | 865 | | 866 |<--------------------------| 867 | | 868 | | 869 |<--------------------------| 870 | | 871 | | 872 | | 873 | | 874 |<--------------------------| 875 | | 876 | | 878 Figure 8 880 4. XML Schema for Event Notifications 882 The following [XML Schema] defines NETCONF Event Notifications. 884 885 894 896 898 899 900 This import accesses the xml: attribute groups for the 901 xml:lang as declared on the error-message element. 902 903 904 906 907 910 912 914 915 916 917 918 920 921 922 An optional parameter that indicates 923 which stream of events is of interest. If 924 not present, then events in the default 925 NETCONF stream will be sent. 926 927 928 929 930 933 934 935 An optional parameter that indicates 936 which subset of all possible events 937 are of interest. The format of this 938 parameter is the same as that of the 939 filter parameter in the NETCONF 940 protocol operations. If not present, 941 all events not precluded by other 942 parameters will be sent. This is 943 mutually exclusive with the named 944 profile parameter. 945 946 947 948 950 951 952 An optional parameter that points to 953 a separately defined filter profile. 954 If not present, no additional 955 filtering will be applied. Note that 956 changes to the profile after the 957 subscription has been created will 958 have no effect. This is mutually 959 exclusive with the filter parameter. 960 961 962 963 964 966 967 968 A parameter used to trigger the replay 969 feature and indicates that the replay 970 should start at the time specified. If 971 start time is not present, this is not a 972 replay subscription. 973 974 975 976 978 979 980 An optional parameter used with the 981 optional replay feature to indicate the 982 newest notifications of interest. If 983 stop time is not present, the 984 notifications will continue until the 985 subscription is terminated. Must be used 986 with 'startTime'. 987 988 989 990 991 992 993 995 996 997 998 The name of a saved profile containing filtering 999 elements. 1000 1001 1002 1003 1005 1006 1007 1008 The name of an event stream. 1009 1010 1011 1012 1014 1017 1018 1019 The command to create a notification subscription. It 1020 takes as argument the name of the notification stream 1021 and filter or profile information. All of those options 1022 limit the content of the subscription. In addition, 1023 there are two time-related parameters startTime and 1024 stopTime which can be used to select the time interval 1025 of interest. 1026 1027 1028 1030 1032 1033 1034 1035 1036 1037 1039 1041 1043 5. Filtering Examples 1045 The following section provides examples to illustrate the various 1046 methods of filtering content on an event notification subscription. 1048 5.1. Subtree Filtering 1050 XML subtree filtering is not well suited for creating elaborate 1051 filter definitions given that it only supports equality comparisons 1052 and logical OR operations (e.g., in an event subtree give me all 1053 event notifications which have severity=critical or severity=major or 1054 severity=minor). Nevertheless, it may be used for defining simple 1055 event notification forwarding filters as shown below. 1057 In order to illustrate the use of filter expressions it is necessary 1058 to assume some of the event notification content. The examples 1059 herein assume that the event notification schema definition has an 1060 element at the top level that contains one or more child 1061 elements consisting of the event class (e.g., fault, 1062 state, config, etc.) reporting entity and either severity or 1063 operational state. 1065 Sample event list 1067 1068 1069 fault 1070 1071 Ethernet0 1072 1073 major 1074 1075 1076 fault 1077 1078 Ethernet2 1079 1080 critical 1081 1082 1083 fault 1084 1085 ATM1 1086 1087 minor 1088 1089 1090 state 1091 1092 Ethernet0 1093 1094 enabled 1095 1096 1098 The following example illustrates selecting events which have 1099 severities of critical, major, or minor (presumably fault events). 1100 The filtering criteria evaluation is as follows: 1102 ((severity=critical) | (severity=major) | (severity=minor)) 1104 1106 1108 1109 1110 1111 1112 fault 1113 critical 1114 1115 1116 fault 1117 major 1118 1119 1120 fault 1121 minor 1122 1123 1124 1125 1126 1127 1129 The following example illustrates selecting state or config 1130 EventClasses or fault events that are related to card Ethernet0. The 1131 filtering criteria evaluation is as follows: 1133 ( state | config | fault & card=Ethernet0) 1135 1137 1138 1139 xmlns="urn:ietf:params:netconf:capability:notification:1.0"> 1140 1141 1142 1143 fault 1144 1145 1146 state 1147 1148 1149 config 1150 1151 1152 fault 1153 1154 Ethernet0 1155 1156 1157 1158 1159 1160 1161 1163 5.2. XPATH filters 1165 The following [XPATH] example illustrates selecting fault EventClass 1166 notifications that have severities of critical, major, or minor. The 1167 filtering criteria evaluation is as follows: 1169 ((fault) & ((severity=critical) | (severity=major) | (severity = 1170 minor))) 1172 1174 1175 1179 1180 1182 The following example illustrates selecting state and config 1183 EventClasses or fault events that have severities of critical, major, 1184 or minor or come from card Ethernet0. The filtering criteria 1185 evaluation is as follows: 1187 (( state | config) & ((fault & severity=critical) | (fault & 1188 severity=major) | (fault & severity = minor) | (fault & 1189 card=Ethernet0))) 1191 1193 1194 1201 1202 1204 6. Security Considerations 1206 The security considerations from the base [NETCONF] document apply 1207 also to the Notification capability. 1209 The access control framework and the choice of transport will have a 1210 major impact on the security of the solution. 1212 Note that the elements are never sent before the 1213 transport layer and the netconf layer (capabilities exchange) have 1214 been established, and the manager has been identified and 1215 authenticated. 1217 It is recommended that care be taken to ensure the secure operation 1218 of the following commands: 1220 o invocation 1222 o read-only data models 1224 o read-write data models 1226 o notification content 1228 One issue related to the notifications draft is the transport of data 1229 from non-netconf streams, such as syslog and SNMP. Note that this 1230 data may be more vulnerable (or is not more vulnerable) when being 1231 transported over netconf than when being transported using the 1232 protocol normally used for transporting it, depending on the security 1233 credentials of the two subsystems. 1235 If a user does not have permission to view content via other NETCONF 1236 operations it does not have permission to access that content via 1237 Notifications. If a user is not permitted to view one element in the 1238 content of the notification, the notification is not sent to that 1239 user. 1241 7. IANA Considerations 1243 This document registers two URIs for the NETCONF XML namespace in the 1244 IETF XML registry [7]. 1246 Following the format in RFC 3688, IANA has made the following 1247 registration. 1249 URI: urn:ietf:params:netconf:capability:notification:1.0 1251 URI: urn:ietf:params:xml:ns:netmod:notification 1253 Registrant Contact: The IESG. 1255 XML: N/A, the requested URI is an XML namespace. 1257 8. Acknowledgements 1259 Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing 1260 their input into the early work on this document. In addition, the 1261 editors would like to acknowledge input at the Vancouver editing 1262 session from the following people: Orly Nicklass, James Balestriere, 1263 Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, 1264 Dave Partain, Ray Atarashi and Dave Perkins and the following 1265 additional people from the Montreal editing session: Balazs Lengyel, 1266 Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen, 1267 Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig, 1268 Martin Bjorklund, Olivier Festor, Radu State, Brian Trammell, William 1269 Chow. 1271 9. Normative References 1273 [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 1274 December 2006. 1276 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 1277 3", RFC 2026, BCP 9, October 1996. 1279 [RFC2119] Bradner, s., "Key words for RFCs to Indicate Requirements 1280 Levels", RFC 2119, March 1997. 1282 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 1283 RFC 2223, October 1997. 1285 [XML] World Wide Web Consortium, "Extensible Markup Language 1286 (XML) 1.0", W3C XML, February 1998, 1287 . 1289 [XML Schema] 1290 Fallside, D. and P. Walmsley, "XML Schema Part 0: Primer 1291 Second Edition", W3C XML Schema, October 2004. 1293 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 1294 Version 1.0", 1295 W3C http://www.w3.org/TR/1999/REC-xpath-19991116, 1296 November 1999. 1298 Authors' Addresses 1300 Sharon Chisholm 1301 Nortel 1302 3500 Carling Ave 1303 Nepean, Ontario K2H 8E9 1304 Canada 1306 Email: schishol@nortel.com 1308 Hector Trevino 1309 Cisco 1310 Suite 400 1311 9155 E. Nichols Ave 1312 Englewood, CO 80112 1313 USA 1315 Email: htrevino@cisco.com 1317 Full Copyright Statement 1319 Copyright (C) The IETF Trust (2007). 1321 This document is subject to the rights, licenses and restrictions 1322 contained in BCP 78, and except as set forth therein, the authors 1323 retain all their rights. 1325 This document and the information contained herein are provided on an 1326 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1327 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1328 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1329 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1330 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1331 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1333 Intellectual Property 1335 The IETF takes no position regarding the validity or scope of any 1336 Intellectual Property Rights or other rights that might be claimed to 1337 pertain to the implementation or use of the technology described in 1338 this document or the extent to which any license under such rights 1339 might or might not be available; nor does it represent that it has 1340 made any independent effort to identify any such rights. Information 1341 on the procedures with respect to rights in RFC documents can be 1342 found in BCP 78 and BCP 79. 1344 Copies of IPR disclosures made to the IETF Secretariat and any 1345 assurances of licenses to be made available, or the result of an 1346 attempt made to obtain a general license or permission for the use of 1347 such proprietary rights by implementers or users of this 1348 specification can be obtained from the IETF on-line IPR repository at 1349 http://www.ietf.org/ipr. 1351 The IETF invites any interested party to bring to its attention any 1352 copyrights, patents or patent applications, or other proprietary 1353 rights that may cover technology that may be required to implement 1354 this standard. Please address the information to the IETF at 1355 ietf-ipr@ietf.org. 1357 Acknowledgment 1359 Funding for the RFC Editor function is provided by the IETF 1360 Administrative Support Activity (IASA).