idnits 2.17.1 draft-ietf-netconf-notification-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1521. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1493. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1500. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1506. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 757 has weird spacing: '...hat the conte...' == Line 873 has weird spacing: '...one-way messa...' == Line 875 has weird spacing: '...one-way messa...' == Line 886 has weird spacing: '...r event notif...' == Line 983 has weird spacing: '...nically incre...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 14, 2006) is 6405 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'NETCONF-PROTO' is mentioned on line 138, but not defined -- Looks like a reference, but probably isn't: '3' on line 135 == Missing Reference: 'NETCONF-SSH' is mentioned on line 1047, but not defined == Unused Reference: 'NETCONF' is defined on line 1418, but no explicit reference was found in the text == Unused Reference: 'NETCONF BEEP' is defined on line 1421, but no explicit reference was found in the text == Unused Reference: 'NETCONF SOAP' is defined on line 1431, but no explicit reference was found in the text == Unused Reference: 'NETCONF SSH' is defined on line 1436, but no explicit reference was found in the text == Unused Reference: 'URI' is defined on line 1441, but no explicit reference was found in the text ** Downref: Normative reference to an Historic draft: draft-ietf-netconf-beep (ref. 'NETCONF BEEP') ** Downref: Normative reference to an Historic draft: draft-ietf-netconf-soap (ref. 'NETCONF SOAP') ** Obsolete normative reference: RFC 2396 (ref. 'URI') (Obsoleted by RFC 3986) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' Summary: 8 errors (**), 0 flaws (~~), 14 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Chisholm 3 Internet-Draft Nortel 4 Expires: March 18, 2007 H. Trevino 5 Cisco 6 September 14, 2006 8 NETCONF Event Notifications 9 draft-ietf-netconf-notification-03.txt 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on March 18, 2007. 36 Copyright Notice 38 Copyright (C) The Internet Society (2006). 40 Abstract 42 This memo defines a framework for sending asynchronous messages, or 43 event notifications in NETCONF. It defines both the operations 44 necessary to support this concept, and also discusses implications 45 for the mapping to transport protocols. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 50 1.1 Definition of Terms . . . . . . . . . . . . . . . . . . . 4 51 1.2 Event Notifications in NETCONF . . . . . . . . . . . . . . 5 52 1.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . 5 53 1.4 Requirements . . . . . . . . . . . . . . . . . . . . . . . 5 54 2. Notification-Related Operations . . . . . . . . . . . . . . . 7 55 2.1 Subscribing to receive Event Notifications . . . . . . . . 7 56 2.1.1 create-subscription . . . . . . . . . . . . . . . . . 7 57 2.2 Sending Event Notifications . . . . . . . . . . . . . . . 8 58 2.2.1 Event Notification . . . . . . . . . . . . . . . . . . 8 59 2.3 Terminating the Subscription . . . . . . . . . . . . . . . 9 60 3. Supporting Concepts . . . . . . . . . . . . . . . . . . . . . 10 61 3.1 Capabilities Exchange . . . . . . . . . . . . . . . . . . 10 62 3.2 Event Streams . . . . . . . . . . . . . . . . . . . . . . 10 63 3.2.1 Event Stream Definition . . . . . . . . . . . . . . . 11 64 3.2.2 Event Stream Content Format . . . . . . . . . . . . . 11 65 3.2.3 Default Event Stream . . . . . . . . . . . . . . . . . 11 66 3.2.4 Event Stream Sources . . . . . . . . . . . . . . . . . 12 67 3.2.5 Event Stream Discovery . . . . . . . . . . . . . . . . 12 68 3.2.6 Event Stream Subscription . . . . . . . . . . . . . . 17 69 3.3 Subscriptions and Datastores . . . . . . . . . . . . . . . 17 70 3.4 Querying Subscription Properties . . . . . . . . . . . . . 18 71 3.5 One-way Notification Messages . . . . . . . . . . . . . . 22 72 3.6 Filter Dependencies . . . . . . . . . . . . . . . . . . . 22 73 3.6.1 Named Profiles . . . . . . . . . . . . . . . . . . . . 23 74 3.6.2 Filtering . . . . . . . . . . . . . . . . . . . . . . 23 75 3.7 Message Flow . . . . . . . . . . . . . . . . . . . . . . . 23 76 4. XML Schema for Event Notifications . . . . . . . . . . . . . . 25 77 5. Mapping to Transport Protocols . . . . . . . . . . . . . . . . 27 78 5.1 SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 79 5.2 BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 80 5.2.1 One-way Notification Messages in Beep . . . . . . . . 28 81 5.3 SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 82 5.3.1 A NETCONF over Soap over HTTP Example . . . . . . . . 29 83 6. Filtering examples . . . . . . . . . . . . . . . . . . . . . . 32 84 6.1 Subtree Filtering . . . . . . . . . . . . . . . . . . . . 32 85 6.2 XPATH filters . . . . . . . . . . . . . . . . . . . . . . 33 86 7. Notification Replay Capability . . . . . . . . . . . . . . . . 35 87 7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 35 88 7.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . 35 89 7.3 Capability Identifier . . . . . . . . . . . . . . . . . . 35 90 7.4 New Operations . . . . . . . . . . . . . . . . . . . . . . 35 91 7.5 Modifications to Existing Operations . . . . . . . . . . . 36 92 7.5.1 create-subscription . . . . . . . . . . . . . . . . . 36 93 7.5.2 Interactions with Other Capabilities . . . . . . . . . 36 94 8. Security Considerations . . . . . . . . . . . . . . . . . . . 37 95 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 38 96 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 39 98 Intellectual Property and Copyright Statements . . . . . . . . 40 100 1. Introduction 102 NETCONF [NETCONF-PROTO] can be conceptually partitioned into four 103 layers: 105 Layer Example 106 +-------------+ +----------------------------------------+ 107 | Content | | Configuration data | 108 +-------------+ +----------------------------------------+ 109 | | 110 +-------------+ +-------------------------------------------+ 111 | Operations | | , | 112 +-------------+ +-------------------------------------------+ 113 | | | 114 +-------------+ +-----------------------------+ | 115 | RPC | | , | | 116 +-------------+ +-----------------------------+ | 117 | | | 118 +-------------+ +------------------------------------------+ 119 | Transport | | BEEP, SSH, SSL, console | 120 | Protocol | | | 121 +-------------+ +------------------------------------------+ 123 This document defines a framework for sending asynchronous messages, 124 or event notifications in NETCONF. It defines both the operations 125 necessary to support this concept, and also discusses implications 126 for the mapping to transport protocols. 128 Figure 1 130 1.1 Definition of Terms 132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 134 document are to be interpreted as described in RFC 2119 [3]. 136 Element: An XML Element[XML]. 138 Managed Entity: A node, which supports NETCONF[NETCONF-PROTO] and has 139 access to management instrumentation. This is also known as the 140 NETCONF server. 142 Managed Object: A collection of one of more Elements that define an 143 abstract thing of interest. 145 Subscription: A concept related to the delivery of notifications (if 146 any to send) involving destination and selection of notifications. 147 It is bound to the lifetime of a session. 149 1.2 Event Notifications in NETCONF 151 An event is something that happens which may be of interest - a 152 configuration change, a fault, a change in status, crossing a 153 threshold, or an external input to the system, for example. Often 154 this results in an asynchronous message, sometimes referred to as a 155 notification or event notification, being sent out to interested 156 parties to notify them that this event has occurred. 158 This memo defines a mechanism whereby the NETCONF client indicates 159 interest in receiving event notifications from a NETCONF server by 160 creating a subscription to receive event notifications. The NETCONF 161 server replies to indicate whether the subscription request was 162 successful and, if it was successful, begins sending the event 163 notifications to the NETCONF client as the events occur within the 164 system. These event notifications will continue to be sent until 165 either the NETCONF session is terminated or some event, outside the 166 scope of this specification, causes the subscription to terminate. 167 The event notification subscription allows a number of options to 168 enable the NETCONF client to specify which events are of interest. 169 These are specified when the subscription is created. 171 An agent is not required to process RPC requests until the 172 notification stream is done. A capability may be defined to announce 173 that a server is able to process RPCs while a notification stream is 174 active on a session. 176 1.3 Motivation 178 The motivation for this work is to enable the sending of asynchronous 179 messages that are consistent with the data model (content) and 180 security model used within a Netconf implementation. 182 1.4 Requirements 184 The requirements for this solution are as follows: 186 o Initial release should ensure it supports notification in support 187 of configuration operations 189 o Data content must not preclude the use of the same data model as 190 used in configuration 192 o solution should support a reasonable message size limit (syslog 193 and SNMP are rather constrained in terms of message sizes) 195 o solution should provide reliable delivery of notifications 197 o solution should support agent initiated connections 199 o solution should provide a subscription mechanism (An agent does 200 not send notifications before asked to do so and the manager 201 initiates the flow of notifications) 203 o solution should provide a filtering mechanism 205 o solution should send sufficient information in a notification so 206 that it can be analyzed independent of the transport mechanism 207 (data content fully describes a notification; protocol information 208 is not needed to understand a notification) 210 o solution should not bind subscriptions to a connection 212 o channels for configuration change notifications should share fate 213 with a session that includes a configuration channel 215 o solution should support replay of locally logged notifications 217 2. Notification-Related Operations 219 2.1 Subscribing to receive Event Notifications 221 The event notification subscription is initiated by the NETCONF 222 client and responded to by the NETCONF server. When the event 223 notification subscription is created, the events of interest are 224 specified. 226 Content for an event notification subscription can be selected by 227 applying user-specified filters. 229 2.1.1 create-subscription 231 233 Description: 235 This operation initiates an event notification subscription which 236 will send asynchronous event notifications to the initiator of the 237 command until the NETCONF session terminates or some event, 238 outside the scope of this specification, causes the subscription 239 to terminate. 241 Parameters: 243 Stream: 245 An optional parameter that indicates which stream(s) of events 246 are of interest. If not present, then events in the default 247 NETCONF stream will be sent. 249 Filter: 251 An optional parameter that indicates which subset of all 252 possible events are of interest. The format of this parameter 253 is the same as that of the filter parameter in the NETCONF 254 protocol operations. If not present, all events not precluded 255 by other parameters will be sent. 257 Named Profile 259 An optional parameter that points to a separately defined 260 filter profile. The contents of the profile are specified in 261 the provided XML Schema. If not present, no additional 262 filtering will be applied. Note that changes to the profile 263 after the subscription has been created will have no effect. 265 Positive Response: 267 If the NETCONF server can satisfy the request, the server sends an 268 element containing a element containing the 269 subscription ID. 271 Negative Response: 273 An element is included within the if the 274 request cannot be completed for any reason. Subscription requests 275 will fail if a filter with invalid syntax is provided or if the 276 name of a non-existent profile or stream is provided. 278 2.2 Sending Event Notifications 280 Once the subscription has been set up, the NETCONF server sends the 281 event notifications asynchronously along the connection. 283 2.2.1 Event Notification 285 287 Description: 289 An event notification is sent to the initiator of an command asynchronously when an event of interest 291 (i.e. meeting the specified filtering criteria) to them has 292 occurred. An event notification is a complete XML document. 294 Parameters: 296 Subscription Id: 298 A unique identifier for this event subscription 300 Data: 302 Contains notification-specific tagged content. 304 Positive Response: 306 No response. 308 Negative Response: 310 No response. 312 2.3 Terminating the Subscription 314 Closing of the event notification subscription is done by terminating 315 the Netconf session ( )or via some action outside the 316 scope of this specification. 318 3. Supporting Concepts 320 3.1 Capabilities Exchange 322 The ability to process and send event notifications is advertised 323 during the capability exchange between the NETCONF client and server. 325 "urn:ietf:params:xml:ns:netconf:notification:1.0" 327 For Example 329 330 331 332 urn:ietf:params:xml:ns:netconf:base:1.0 333 334 335 urn:ietf:params:xml:ns:netconf:capability:startup:1.0 336 337 338 urn:ietf:params:xml:ns:netconf:notification:1.0 339 340 341 4 342 344 3.2 Event Streams 346 An event stream is defined herein as a set of event notifications 347 matching some forwarding criteria. 349 System components generate event notifications which are passed to a 350 central component for classification and distribution. The central 351 component inspects each event notification and matches the event 352 notification against the set of stream definitions. When a match 353 occurs, the event notification is considered to be a member of that 354 event stream. An event notification may be part of multiple event 355 streams. 357 When a NETCONF client subscribes to a given event stream, user- 358 defined filters, if applicable, are applied to the event stream and 359 matching event notifications are forwarded to the NETCONF server for 360 distribution to subscribed NETCONF clients. 362 +----+ 363 | c1 |---+ available streams 364 +----+ | +---------+ 365 +----+ | |central |-> stream 1 366 | c2 | +--->|event |-> stream 2 filter +-------+ 367 +----+ | |processor|-> netconf stream --->|netconf| 368 ... | | |-> stream n |server | see 369 System | +---------+ +-------+ below 370 Components| | // 371 ... | | // 372 +----+ | | (------------) 373 | cn |---+ | (notification) 374 +----+ +-----> ( logging ) 375 ( service ) 376 (------------) 378 +-------+ +-------+ 379 |netconf|<--->|netconf| 380 -> |server | |client | 381 +-------+ +-------+ 383 3.2.1 Event Stream Definition 385 Event streams are pre-defined on the managed device. The 386 configuration of event streams is outside the scope of this document. 387 However, it is envisioned that event streams are either pre- 388 established by the vendor (pre-configured) or user configurable (e.g. 389 part of the device's configuration) or both. Device vendors may 390 allow event stream configuration via NETCONF protocol (i.e. edit- 391 config operation) 393 3.2.2 Event Stream Content Format 395 The contents of all event streams made available to a NETCONF client 396 (i.e. the notification sent by the NETCONF server) must be encoded in 397 XML. 399 3.2.3 Default Event Stream 401 A NETCONF server implementation supporting the notification 402 capability must support the "NETCONF" notification event stream. 403 This stream contains all NETCONF XML event notifications supported by 404 the NETCONF server. The definition of the event notification and 405 their contents for this event stream is outside the scope of this 406 document. 408 3.2.4 Event Stream Sources 410 With the exception of the default event stream (NETCONF 411 notifications) specification of additional event stream sources (e.g. 412 SNMP, syslog, etc.) is outside the scope of this document. NETCONF 413 server implementations may leverage any desired event stream source 414 in the creation of supported event streams. 416 3.2.5 Event Stream Discovery 418 A NETCONF client retrieves the list of supported event streams from a 419 NETCONF server using the or RPC request. 421 3.2.5.1 Name Retrieval using get, get-config RPC 423 The list of available event streams is retrieved by requesting the 424 subtree via a or operation. 425 Available event streams for the requesting session are returned in 426 the reply containing and elements, where 427 element is mandatory and its value is unique [Editor's Note: 428 should we then define it as a key?]. The returned list must only 429 include the names of those event streams for which the NETCONF 430 sessions has sufficient privileges. The NETCONF session privileges 431 are determined via access control mechanisms which are beyond the 432 scope of this document. An empty reply is returned if there are no 433 available event streams. 435 Retrieving available event stream list using operation: 437 438 439 440 441 442 443 444 445 446 447 448 449 451 453 454 455 456 457 458 NETCONF 459 Default netconf event stream 460 461 462 463 snmp 464 SNMP notifications 465 466 467 syslog-critical 468 Critical and higher severity 469 470 471 472 473 474 475 477 Retrieving available event stream list using operation: 479 480 481 482 483 484 485 486 487 488 490 492 493 494 495 496 497 NETCONF 498 Default netconf event stream 499 500 501 502 snmp 503 SNMP notifications 504 505 506 syslog-critical 507 Critical and higher severity 508 509 510 511 512 513 514 516 3.2.5.2 Device Supported Event Streams (System) 518 The list of all event streams configured on a device may be retrieved 519 over a NETCONF session with sufficient privileges (e.g. 520 administrator). The information is retrieved by requesting the 521 subtree via a or 522 operation. 524 525 526 527 528 529 530 531 532 533 534 536 538 539 540 541 542 NETCONF 543 Default netconf event stream 544 545 546 547 snmp 548 SNMP notifications 549 550 551 552 syslog-critical 553 Critical and higher severity 554 555 556 557 558 559 561 3.2.5.3 Stream Retrieval Schema 562 563 567 568 569 Schema for event streams 570 571 572 574 575 NetconfNotificationSchema 576 577 578 2006-09-06T09:30:47-05:00 579 580 IETF 581 582 583 A schema that can be used to learn about current 584 NetConf Event subscriptions and creating named 585 profiles 586 587 588 589 591 593 596 597 598 599 The list of event streams supported by the system. 600 When a query is issued, the returned set of streams is 601 determined based on user privileges 602 603 604 605 606 607 608 609 Stream name and description 610 611 612 613 614 615 616 617 618 619 620 621 622 624 3.2.6 Event Stream Subscription 626 A NETCONF client may request from the NETCONF server the list of 627 available event streams to this session and then issue a request with the desired event stream name. Omitting 629 the event stream name from the request results 630 in subscription to the default NETCONF event stream. 632 3.2.6.1 Filtering Event Stream Contents 634 The set of event notifications delivered in an event stream may be 635 further refined by applying a user-specified filter at subscription 636 creation time ( ). This is a transient filter 637 associated with the event notification subscription and does not 638 modify the event stream configuration. 640 3.2.6.2 Subscription to Multiple Event Streams 642 Multiple event streams may be configured on a device and a NETCONF 643 client may subscribe to one or more of the available event streams. 644 A NETCONF client subscribing to multiple event streams must do so by 645 either establishing a new NETCONF session or opening a new channel on 646 an existing NETCONF session. 648 3.3 Subscriptions and Datastores 650 Subscriptions are like NETCONF sessions in that they don't exist in 651 NETCONF datastores. The exception to this is the named profiles 652 feature. 654 3.4 Querying Subscription Properties 656 The following Schema can be used to retrieve information about active 657 event notification subscriptions 659 668 669 670 Schema for reporting on Event Subscriptions 671 672 673 675 NetconfNotificationSchema 676 2006-09-13T09:30:47-05:00 677 678 IETF 679 680 A schema that can be used to learn about current 681 NetConf Event subscriptions and creating named 682 profiles 683 684 685 686 688 690 694 697 698 700 701 703 704 705 707 709 710 711 712 713 715 716 717 718 719 720 721 722 723 725 727 728 729 The session id associated with this subscription. 730 731 732 734 736 737 738 The subscription id associated with this 739 subscription. 740 741 742 744 746 747 748 The filters associated with this subscription. 749 750 751 753 754 755 756 The named profile associated with this subscription. 757 Note that the contents of the named profile may 758 have changed since it was last applied. 759 760 761 763 765 766 767 The last time this subscription was modified. If it 768 has not been modified since creation, this is the 769 time of subscription creation. 770 771 772 774 776 777 778 A count of event notifications sent along 779 this connection since the subscription was 780 created. 781 782 783 785 786 787 788 789 790 791 792 794 795 797 798 799 800 803 804 805 807 808 809 810 811 812 813 814 815 816 817 818 820 821 822 The filters associated with this named 823 profile. 824 825 826 828 829 830 831 The timestamp of the last modification to this 832 named Profile. Note that modification of the 833 profile does not cause an immediate update 834 to all applicable subscription. Therefore, this 835 time should be compared with the last 836 modified time associated with the subscription. 837 If this time is earlier, then the subscription 838 is using the exact set of parameters associated 839 with this named profile. If this time is 840 later, then the subscription is using an earlier 841 version of this named profile and the exact 842 parameters may not match. 843 844 845 846 847 848 849 850 851 852 854 855 856 857 859 860 861 863 865 3.5 One-way Notification Messages 867 In order to support the concept that each individual event 868 notification is a well-defined XML-document that can be processed 869 without waiting for all events to come in, it makes sense to define 870 events, not as an endless reply to a subscription command, but as 871 independent messages that originate from the NETCONF server. In 872 order to support this model, this memo introduces the concept of 873 notifications, which are one-way messages. 875 A one-way message is similar to the two-way RPC message, except that 876 no response is expected to the command. In the case of event 877 notification, this message will originate from the NETCONF server, 878 and not the NETCONF client. 880 3.6 Filter Dependencies 882 Note that when multiple filters are specified (in-line Filter, Named 883 Profiles), they are applied collectively, so event notifications need 884 to pass all specified filters in order to be sent to the subscriber. 885 If a filter is specified to look for data of a particular value, and 886 the data item is not present within a particular event notification 887 for its value to be checked against, it will be filtered out. For 888 example, if one were to check for 'severity=critical' in a 889 configuration event notification where this field was not supported, 890 then the notification would be filtered out. 892 Note that the order that filters are applied does not matter since 893 the resulting set of notifications is the intersection of the set of 894 notifications that pass each filtering criteria. 896 3.6.1 Named Profiles 898 A named profile is a filter that is created ahead of time and applied 899 at the time an event notification subscription is created . Note 900 that changes to the profile after the subscription has been created 901 will have no effect on the subscription. Since named profiles exist 902 outside of the subscription, they persist after the subscription has 903 been torn down. 905 3.6.2 Filtering 907 Just-in-time filtering is explicitly stated when the event 908 notification subscription is created. This is specified via the 909 Filter parameter. Filters only exist as parameters to the 910 subscription. 912 3.7 Message Flow 913 The following figure depicts message flow between a Netconf client 914 (C) and Netconf server (S) in order create a subscription and begin 915 the flow of notifications. 917 C S 918 | | 919 | capability exchange | 920 |-------------------------->| 921 |<------------------------->| 922 | | 923 | | 924 |-------------------------->| 925 |<--------------------------| 926 | | 927 | | 928 | | 929 |<--------------------------| 930 | | 931 | | 932 |<--------------------------| 933 | | 934 | | 935 | | 936 | | 937 |<--------------------------| 938 | | 939 | | 941 4. XML Schema for Event Notifications 943 944 951 954 956 957 958 This import accesses the xml: attribute groups for the 959 xml:lang as declared on the error-message element. 960 961 962 964 965 968 970 971 972 973 The unique identifier for this particular subscription within 974 the session. 975 976 977 978 980 981 982 983 A monotonically increasing integer. Starts at 0. 984 Always increases by just one. Roll back to 0 after maximum 985 value is reached. 986 987 988 989 991 993 996 997 998 999 1000 1001 1003 1005 1007 1008 1009 1010 1011 1015 1017 1020 1021 1022 1023 1024 1025 1027 1029 5. Mapping to Transport Protocols 1031 Currently, the NETCONF family of specification allows for running 1032 NETCONF over a number of transport protocols, some of which support 1033 multiple configurations. Some of these options will be better suited 1034 for supporting event notifications then others. 1036 5.1 SSH 1038 Session establishment and two-way messages are based on the NETCONF 1039 over SSH transport mapping [NETCONF-SSH] 1041 One-way event messages are supported as follows: Once the session has 1042 been established and capabilities have been exchanged, the server may 1043 send complete XML documents to the NETCONF client containing 1044 notification elements. No response is expected from the NETCONF 1045 client. 1047 As the examples in [NETCONF-SSH] illustrate, a special character 1048 sequence, MUST be sent by both the client and the server after each 1049 XML document in the NETCONF exchange. This character sequence cannot 1050 legally appear in an XML document, so it can be unambiguously used to 1051 identify the end of the current document in the event notification of 1052 an XML syntax or parsing error, allowing resynchronization of the 1053 NETCONF exchange. 1055 The NETCONF over SSH session to receive an event notification might 1056 look like the following. Note the event notification contents 1057 (delimited by tags) are not defined in this document 1058 and are provided herein simply for illustration purposes: 1060 1061 1063 123456 1064 1065 1066 2 1067 2000-01-12T12:13:14Z 1068 Fred Flinstone 1069 1070 1071 1072 1073 1074 1075 1076 1077 Ethernet0/0 1078 1500 1079 1080 1081 1082 1083 1084 1085 1086 ]]> 1087 ]]> 1089 5.2 BEEP 1091 Session establishment and two-way messages are based on the NETCONF 1092 over BEEP transport mapping NETCONF-BEEP 1094 5.2.1 One-way Notification Messages in Beep 1096 One-way notification messages can be supported either by mapping to 1097 the existing one-to-many BEEP construct or by creating a new one-to- 1098 none construct. 1100 This area is for future study. 1102 5.2.1.1 One-way messages via the One-to-many Construct 1104 Messages in one-to-many exchanges: "rpc", "notification", "rpc-reply" 1106 Messages in positive replies: "rpc-reply", "rpc-one-way" 1108 5.2.1.2 One-way notification messages via the One-to-none Construct 1110 Note that this construct would need to be added to an extension or 1111 update to 'The Blocks Extensible Exchange Protocol Core' RFC 3080. 1113 MSG/NoANS: the client sends a "MSG" message, the server, sends no 1114 reply. 1116 In one-to-none exchanges, no reply to the "MSG" message is expected. 1118 5.3 SOAP 1120 Session management and message exchange are based on the NETCONF over 1121 SOAP transport mapping NETCONF-SOAP 1123 Note that the use of "persistent connections" "chunked transfer- 1124 coding" when using HTTP becomes even more important in the supporting 1125 of event notifications 1127 5.3.1 A NETCONF over Soap over HTTP Example 1129 C: POST /netconf HTTP/1.1 1130 C: Host: netconfdevice 1131 C: Content-Type: text/xml; charset=utf-8 1132 C: Accept: application/soap+xml, text/* 1133 C: Cache-Control: no-cache 1134 C: Pragma: no-cache 1135 C: Content-Length: 465 1136 C: 1137 C: 1138 C: 1140 C: 1141 C: 1144 C: 1145 C: 1146 C: 1147 C: 1148 C: 1150 The response: 1152 S: HTTP/1.1 200 OK 1153 S: Content-Type: application/soap+xml; charset=utf-8 1154 S: Content-Length: 917 1155 S: 1157 S: 1158 S: 1160 S: 1161 S: 1163 S: 1164 S: 1166 S: 123456 1167 S: 1168 S: 1169 S: 1170 S: 1171 S: 1173 And then some time later 1175 S: HTTP/1.1 200 OK 1176 S: Content-Type: application/soap+xml; charset=utf-8 1177 S: Content-Length: 917 1178 S: 1179 S: 1180 S: 1182 S: 1183 S: 1185 S: 123456 1186 S: 1187 S: 1188 S: 2 1189 S: 2000-01-12T12:13:14Z 1190 S: Fred Flinstone 1191 S: 1192 S: 1193 S: 1194 S: 1195 S: 1196 S: 1197 S: 1198 S: 1199 S: Ethernet0/0 1200 S: 1500 1201 S: 1202 S: 1203 S: 1204 S: 1205 S: 1206 S: 1207 S: 1208 S: 1209 S: 1211 6. Filtering examples 1213 The following section provides examples to illustrate the various 1214 methods of filtering content on an event notification subscription. 1216 6.1 Subtree Filtering 1218 XML subtree filtering is not well suited for creating elaborate 1219 filter definitions given that it only supports equality comparisons 1220 and logical OR operations (e.g. in an event subtree give me all event 1221 notifications which have severity=critical or severity=major or 1222 severity=minor). Nevertheless, it may be used for defining simple 1223 event notification forwarding filters as shown below. 1225 In order to illustrate the use of filter expressions it is necessary 1226 to assume some of the event notification content (only for example 1227 purposes). The examples herein assume that the event notification 1228 schema definition has an element identifying the 1229 event category (e.g. fault, state, config, etc.) and events have a 1230 element 1232 The following example illustrates selecting events which have 1233 severities of critical, major, or minor (presumably fault events). 1234 The filtering criteria evaluation is as follows: 1236 ((severity=critical) | (severity=major) | (severity=minor)) 1238 1240 1241 1242 1244 1245 critical 1246 1247 1248 major 1249 1250 1251 minor 1252 1253 1254 1255 1256 1258 The following example illustrates selecting fault, state, config 1259 EventClasses or events which are related to card Ethernet0. The 1260 filtering criteria evaluation is as follows: 1262 (fault | state | config | card=Ethernet0) 1264 1266 1267 1268 1270 1271 fault 1272 1273 1274 state 1275 1276 1277 config 1278 1279 1280 Ethernet0 1281 1282 1283 1284 1285 1287 6.2 XPATH filters 1289 The following example illustrates selecting fault EventClass 1290 notifications that have severities of critical, major, or minor. The 1291 filtering criteria evaluation is as follows: 1293 ((fault) & ((severity=critical) | (severity=major) | (severity = 1294 minor))) 1295 1297 1298 1299 (/event[eventClasses/fault] and 1300 (/event[severity="critical"] or 1301 /event[severity="major"] or /event[severity="minor"])) 1302 1303 1304 1306 The following example illustrates selecting fault, state and config 1307 EventClasses which have severities of critical, major, or minor and 1308 come from card Ethernet0. The filtering criteria evaluation is as 1309 follows: 1311 ((fault | state | config) & ((fault & severity=critical) | (fault & 1312 severity=major) | (fault & severity = minor) | (card=Ethernet0))) 1314 1316 1317 1318 ((/event[eventClasses/fault] or 1319 /event[eventClasses/state] or 1320 /event[eventClasses/config]) and 1321 ( (/event[eventClasses/fault] and 1322 /event[severity="critical"]) or 1323 (/event[eventClasses/fault] and 1324 /event[severity="major"]) or 1325 (/event[eventClasses/fault] and 1326 /event[severity="minor"]) or 1327 /event[card="Ethernet0"])) 1328 1329 1330 1332 7. Notification Replay Capability 1334 7.1 Overview 1336 Replay is the ability to create an event subscription that will 1337 resend recently sent notifications. These notifications are sent the 1338 same way as normal notifications. 1340 A replay of notifications is specified by including an optional 1341 parameter to the subscription command that indicates the start time 1342 of the replay. The end time of the replay is implicitly defined to 1343 be the time the replay request was initiated. 1345 An implementation that supports replay is not expected to have an 1346 unlimited supply of saved notifications available to accommodate any 1347 replay request. If a client requests a replay of notifications that 1348 predate the oldest notification available, then the NETCONF server 1349 must return an warning message in the RPC reply and start replaying 1350 the notifications it does have available, within the other 1351 constraints, such as filtering, that the client has provided. 1353 The actual number of stored notifications available for retrieval at 1354 any given time is an agent implementation specific matter. Control 1355 parameters for this aspect of the feature are outside the scope of 1356 the current work. 1358 A given subscription is either a replay subscription or a normal 1359 subscription, which sends event notifications as they happen. A 1360 replay subscription terminates once the it has completed replaying 1361 past events. 1363 7.2 Dependencies 1365 This capability is dependent on the notification capability being 1366 supported. It also requires that the device support some form of 1367 notification logging, although it puts no restrictions on the size or 1368 form of the log. 1370 7.3 Capability Identifier 1372 The Event Notification Replay capability is identified by following 1373 capability string: 1375 http://ietf.org/netconf/notificationReplay/1.0 1377 7.4 New Operations 1379 None 1381 7.5 Modifications to Existing Operations 1383 7.5.1 create-subscription 1385 This capability adds an optional parameter to the command called 'startTime'. This identifies the 1387 earliest date and time of interest for event notifications being 1388 replayed. Events generated before this time are not matched. 1390 7.5.2 Interactions with Other Capabilities 1392 [Edtitor's Note: If this capability does not interact with other 1393 capabilities, this section may be omitted.] 1395 8. Security Considerations 1397 To be determined once specific aspects of this solution are better 1398 understood. In particular, the access control framework and the 1399 choice of transport will have a major impact on the security of the 1400 solution 1402 9. Acknowledgements 1404 Thanks to Gilbert Gagnon, Greg Wilbur and Kim Curran for providing 1405 their input into the early work on this document. In addition, the 1406 editors would like to acknowledge input at the Vancouver editing 1407 session from the following people: Orly Nicklass, James Balestriere, 1408 Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington, 1409 Dave Partain, Ray Atarashi and Dave Perkins and the following 1410 additional people from the Montreal editing session: Balazs Lengyel, 1411 Phil Shafer, Rob Ennes, Andy Bierman, Dan Romascanu, Bert Wijnen, 1412 Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent 1413 Cridlig, Martin Bjorklund, Olivier Festor, Radu State, Brian 1414 Trammell, William Chow 1416 10. References 1418 [NETCONF] Enns, R., "NETCONF Configuration Protocol", 1419 ID draft-ietf-netconf-prot-12, February 2006. 1421 [NETCONF BEEP] 1422 Lear, E. and K. Crozier, "Using the NETCONF Protocol over 1423 Blocks Extensible Exchange Protocol (BEEP)", 1424 ID draft-ietf-netconf-beep-10, March 2006. 1426 [NETCONF Datamodel] 1427 Chisholm, S. and S. Adwankar, "Framework for NETCONF 1428 Content", ID draft-chisholm-netconf-model-05.txt, 1429 April 2006. 1431 [NETCONF SOAP] 1432 Goddard, T., "Using the Network Configuration Protocol 1433 (NETCONF) Over the Simple Object Access Protocol (SOAP)", 1434 ID draft-ietf-netconf-soap-08, March 2006. 1436 [NETCONF SSH] 1437 Wasserman, M. and T. Goddard, "Using the NETCONF 1438 Configuration Protocol over Secure Shell (SSH)", 1439 ID draft-ietf-netconf-ssh-06.txt, March 2006. 1441 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1442 Resource Identifiers (URI): Generic Syntax", RFC 2396, 1443 August 1998. 1445 [XML] World Wide Web Consortium, "Extensible Markup Language 1446 (XML) 1.0", W3C XML, February 1998, 1447 . 1449 [refs.RFC2026] 1450 Bradner, S., "The Internet Standards Process -- Revision 1451 3", RFC 2026, BCP 9, October 1996. 1453 [refs.RFC2119] 1454 Bradner, s., "Key words for RFCs to Indicate Requirements 1455 Levels", RFC 2119, March 1997. 1457 [refs.RFC2223] 1458 Postel, J. and J. Reynolds, "Instructions to RFC Authors", 1459 RFC 2223, October 1997. 1461 [refs.RFC3080] 1462 Rose, M., "The Blocks Extensible Exchange Protocol Core", 1463 RFC 3080, March 2001. 1465 Authors' Addresses 1467 Sharon Chisholm 1468 Nortel 1469 3500 Carling Ave 1470 Nepean, Ontario K2H 8E9 1471 Canada 1473 Email: schishol@nortel.com 1475 Hector Trevino 1476 Cisco 1477 Suite 400 1478 9155 E. Nichols Ave 1479 Englewood, CO 80112 1480 USA 1482 Email: htrevino@cisco.com 1484 Intellectual Property Statement 1486 The IETF takes no position regarding the validity or scope of any 1487 Intellectual Property Rights or other rights that might be claimed to 1488 pertain to the implementation or use of the technology described in 1489 this document or the extent to which any license under such rights 1490 might or might not be available; nor does it represent that it has 1491 made any independent effort to identify any such rights. Information 1492 on the procedures with respect to rights in RFC documents can be 1493 found in BCP 78 and BCP 79. 1495 Copies of IPR disclosures made to the IETF Secretariat and any 1496 assurances of licenses to be made available, or the result of an 1497 attempt made to obtain a general license or permission for the use of 1498 such proprietary rights by implementers or users of this 1499 specification can be obtained from the IETF on-line IPR repository at 1500 http://www.ietf.org/ipr. 1502 The IETF invites any interested party to bring to its attention any 1503 copyrights, patents or patent applications, or other proprietary 1504 rights that may cover technology that may be required to implement 1505 this standard. Please address the information to the IETF at 1506 ietf-ipr@ietf.org. 1508 The IETF has been notified of intellectual property rights claimed in 1509 regard to some or all of the specification contained in this 1510 document. For more information consult the online list of claimed 1511 rights. 1513 Disclaimer of Validity 1515 This document and the information contained herein are provided on an 1516 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1517 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1518 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1519 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1520 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1521 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1523 Copyright Statement 1525 Copyright (C) The Internet Society (2006). This document is subject 1526 to the rights, licenses and restrictions contained in BCP 78, and 1527 except as set forth therein, the authors retain all their rights. 1529 Acknowledgment 1531 Funding for the RFC Editor function is currently provided by the 1532 Internet Society.