idnits 2.17.1 draft-ietf-netconf-rfc5277bis-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- ** 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.) == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 355 has weird spacing: '...lter-id fil...' == Line 422 has weird spacing: '...-result sub...' == Line 456 has weird spacing: '...-result sub...' == Line 472 has weird spacing: '...tion-id sub...' == Line 474 has weird spacing: '...-result sub...' == (7 more instances...) -- The document date (October 27, 2016) is 2738 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) == Missing Reference: 'RFC7923' is mentioned on line 129, but not defined ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-17 Summary: 2 errors (**), 0 flaws (~~), 10 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF A. Clemm 3 Internet-Draft Sympotech 4 Intended status: Standards Track A. Gonzalez Prieto 5 Expires: April 30, 2017 E. Voit 6 E. Nilsen-Nygaard 7 A. Tripathy 8 Cisco Systems 9 S. Chisholm 10 Ciena 11 H. Trevino 12 Cisco Systems 13 October 27, 2016 15 Subscribing to Event Notifications 16 draft-ietf-netconf-rfc5277bis-01 18 Abstract 20 This document defines capabilities and operations for subscribing to 21 content and providing asynchronous notification message delivery on 22 that content. Notification delivery can occur over a variety of 23 protocols used commonly in conjunction with YANG, such as NETCONF and 24 RESTCONF. The capabilities and operations defined in this document 25 when using in conjunction with draft-ietf-netconf-netconf-event- 26 notifications are intended to replace RFC 5277. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on April 30, 2017. 45 Copyright Notice 47 Copyright (c) 2016 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 65 1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 5 66 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 6 68 2.2. Event Stream Discovery . . . . . . . . . . . . . . . . . 7 69 2.3. Filters . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 2.4. Subscription State Model at the Publisher . . . . . . . . 7 71 3. Data Model Trees for Event Notifications . . . . . . . . . . 8 72 4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . . . 12 73 4.1. Establishing a Subscription . . . . . . . . . . . . . . . 12 74 4.2. Modifying a Subscription . . . . . . . . . . . . . . . . 13 75 4.3. Deleting a Subscription . . . . . . . . . . . . . . . . . 13 76 5. Configured Subscriptions . . . . . . . . . . . . . . . . . . 14 77 5.1. Establishing a Configured Subscription . . . . . . . . . 14 78 5.2. Modifying a Configured Subscription . . . . . . . . . . . 16 79 5.3. Deleting a Configured Subscription . . . . . . . . . . . 16 80 6. Event (Data Plane) Notifications . . . . . . . . . . . . . . 17 81 7. Control Plane Notifications . . . . . . . . . . . . . . . . . 18 82 7.1. replayComplete . . . . . . . . . . . . . . . . . . . . . 19 83 7.2. notificationComplete . . . . . . . . . . . . . . . . . . 19 84 7.3. subscription-started . . . . . . . . . . . . . . . . . . 19 85 7.4. subscription-modified . . . . . . . . . . . . . . . . . . 19 86 7.5. subscription-terminated . . . . . . . . . . . . . . . . . 19 87 7.6. subscription-suspended . . . . . . . . . . . . . . . . . 20 88 7.7. subscription-resumed . . . . . . . . . . . . . . . . . . 20 89 8. Data Model for Event Notifications . . . . . . . . . . . . . 20 90 9. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 40 91 10. Security Considerations . . . . . . . . . . . . . . . . . . . 41 92 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42 93 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 94 12.1. Normative References . . . . . . . . . . . . . . . . . . 42 95 12.2. Informative References . . . . . . . . . . . . . . . . . 42 96 Appendix A. Issues that are currently being worked and resolved 43 97 A.1. Unresolved and yet-to-be addressed issues . . . . . . . . 43 98 A.2. Agreement in principal . . . . . . . . . . . . . . . . . 43 99 A.3. Resolved Issues . . . . . . . . . . . . . . . . . . . . . 44 100 Appendix B. Changes between revisions . . . . . . . . . . . . . 44 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 103 1. Introduction 105 This document defines mechanisms that provide an asynchronous message 106 notification delivery service in a protocol-agnostic manner. This 107 document defines capabilities and operations for providing 108 asynchronous message notification delivery for notifications 109 including those necessary to establish, monitor, and support 110 subscriptions to notification delivery. 112 Notification delivery can occur over a variety of protocols used 113 commonly in conjunction with YANG, such as NETCONF [RFC6241] (defined 114 in [I-D.ietf-netconf-netconf-event-notif]) and Restconf 115 [I-D.ietf-netconf-restconf] (defined in 116 [I-D.ietf-netconf-restconf-notif]). The capabilities and operations 117 defined in this document are intended to replace RFC 5277, along with 118 their mapping onto NETCONF transport. 120 1.1. Motivation 122 The motivation for this work is to enable the sending of transport 123 agnostic asynchronous notification messages driven by a YANG 124 Subscription that are consistent with the data model (content) and 125 security model. Predating this work was used within a NETCONF 126 implementation. [RFC5277] which defined a limited defines a 127 notification mechanism for for NETCONF. However, there are various 128 [RFC5277] has limitations:, many of which have been exposed in 129 [RFC7923]. 131 The scope of the work aims at meeting the operational needs of 132 network subscriptions: 134 o Ability to dynamically or statically subscribe to event 135 notifications available on a publisher. 137 o Ability to negotiate acceptable dynamic subscription parameters. 139 o Ability to filter the subset of notifications to be pushed with 140 stream-specific semantics. 142 o Ability for the notification payload to be interpreted 143 independently of the transport protocol. (In other words, the 144 encoded notification fully describes itself.) 146 o Mechanism to communicate the notifications. 148 o Ability to replay locally logged notifications. 150 1.2. Terminology 152 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 153 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 154 document are to be interpreted as described in RFC 2119 [RFC2119]. 156 Configured subscription: A subscription installed via a configuration 157 interface which persists across reboots. 159 Dynamic subscription: A subscription agreed between subscriber and 160 publisher via create, establish, modify, and delete RPC control plane 161 signaling messages. 163 Event: An occurrence of something that may be of interest. (e.g., a 164 configuration change, a fault, a change in status, crossing a 165 threshold, or an external input to the system.) 167 Event notification: A set of information intended for a Receiver 168 indicating that one or more Event(s) have occurred. Details of the 169 Event(s) may be included within the Notification. 171 Filter: Evaluation criteria, which may be applied against a targeted 172 set of objects/events in a subscription. Information traverses the 173 filter only if specified filter criteria are met. 175 NACM: NETCONF Access Control Model. 177 OAM: Operations, Administration, Maintenance. 179 Publisher: An entity responsible for streaming Event Notifications 180 per the terms of a Subscriptions 182 Receiver: A target to which a publisher pushes event notifications. 183 For dynamic subscriptions, the receiver and subscriber will often be 184 the same entity. 186 RPC: Remote Procedure Call. 188 Stream (also referred to as "event stream"): A continuous ordered set 189 of events grouped under an explicit criteria. 191 Subscriber: An entity able to request and negotiate a contract for 192 the receipt of event notifications from a publisher. 194 Subscription: A contract with a publisher, stipulating which 195 information receiver(s) wishes to have pushed from the publisher 196 without the need for further solicitation. 198 1.3. Solution Overview 200 This document describes mechanisms for subscribing and receiving 201 event notifications from an event server publisher. This document 202 builds on top of the capabilities defined in [RFC5277], extending 203 them, and generalizing them to be protocol-agnostic. 205 Some enhancements over RFC 5277 include the ability to have multiple 206 subscriptions on a single transport session, to terminate a single 207 subscriptions without terminating the transport session, and to 208 modify existing subscriptions. 210 These enhancements do not affect existing RFC 5277 subscribers that 211 do not support these particular subscription requirements. 213 The solution supports subscribing to event notifications using two 214 mechanisms: 216 1. Dynamic subscriptions, where a subscriber initiates a 217 subscription negotiation with a publisher via RPC. A subscriber 218 initiates a negotiation by issuing a subscription request. If 219 the publisher wants to serve this request, it will accept it, and 220 then start pushing event notifications as negotiated. If the 221 publisher does not wish to serve it as requested, it may respond 222 with subscription parameters which it would have accepted. 224 2. Configured subscriptions, which is an optional mechanism that 225 enables managing subscriptions via a configuration interface so 226 that a publisher can send event notifications to configured 227 receiver(s). 229 Some key characteristics of configured and dynamic subscriptions 230 include: 232 o The lifetime of a dynamic subscription is limited by the lifetime 233 of the subscriber session used to establish it. Typically loss of 234 the transport session tears down any dependent dynamic 235 subscriptions. 237 o The lifetime of a configured subscription is driven by 238 configuration being present on the running configuration. This 239 implies configured subscriptions persist across reboots, and 240 persists even when transport is unavailable. This also means 241 configured subscriptions do not support negotiation. 243 o Subscriptions can be modified or terminated at any point of their 244 lifetime. configured subscriptions can be modified by any 245 configuration client with write rights on the configuration of the 246 subscription. 248 Note that there is no mixing-and-matching of dynamic and configured 249 subscriptions. Specifically, a configured subscription cannot be 250 modified or deleted using RPC. Similarly, a subscription created via 251 RPC cannot be modified through configuration operations. 253 The publisher may decide to terminate a dynamic subscription at any 254 time. Similarly, it may decide to temporarily suspend the sending of 255 event notifications for either configured or dynamic subscriptions. 256 Such termination or suspension may be driven by the publisher running 257 out of resources to serve the subscription, or by internal errors on 258 the publisher. 260 2. Solution 262 2.1. Event Streams 264 An event stream is a set of events available for subscription from a 265 publisher. It is out of the scope of this document to identify a) 266 how streams are defined, b) how events are defined/generated, and c) 267 how events are assigned to streams. 269 That said, some event streams will be standardized whereas others may 270 be vendor specific. One standardized event stream is the "NETCONF" 271 notification event stream. The NETCONF event stream contains all 272 NETCONF XML event notifications supported by the publisher, except 273 for those belonging only to streams that explicitly indicate that 274 they must be excluded from the NETCONF stream, such as notifications 275 that serve OAM and signaling purposes. 277 The following is a high-level description of the flow of a 278 notification. Note that it does not mandate and/or preclude an 279 implementation. As events are raised, they are assigned to streams. 280 An event may be assigned to multiple streams. The event is 281 distributed to subscribers and receivers based on the current 282 subscriptions and access control. Access control is needed because 283 if any receiver of that subscription does not have permission to 284 receive an event, then it never makes it into a notification, and 285 processing of the event is completed for that subscription. 287 2.2. Event Stream Discovery 289 A publisher maintains a list of available event streams as 290 operational data. This list contains both standardized and vendor- 291 specific event streams. A client can retrieve this list like any 292 other YANG-defined data, for example using the operation when 293 using NETCONF. 295 2.3. Filters 297 a publisher implementation SHOULD support the ability to perform 298 filtering of notification records per RFC 5277. (TODO: since 5277 is 299 to be obsoleted, we should describe the filter here.) 301 2.4. Subscription State Model at the Publisher 303 Below is the state machine of a subscription for the publisher. It 304 is important to note that a subscription doesn't exist at the 305 publisher until it is accepted and made active. The mere request by 306 a subscriber to establish a subscription is insufficient for that 307 asserted subscription to be externally visible via this state 308 machine. 310 .-------. 311 | start | 312 '-------' 313 | 314 establish 315 | 316 | .----------modify--------------. 317 v v ' 318 .-----------. .-----------. 319 .--------. | |------>suspend------->| | 320 modify '| active | | suspended | 321 '--------->| |<----resume----<------| | 322 '-----------' '-----------' 323 | | 324 delete delete 325 | | 326 v | 327 .-------. | 328 | end |<-----------------------------' 329 '-------' 331 Figure 1: Subscription states at publisher 333 Of interest in this state machine are the following: 335 o Successful or 336 requests put the subscription into an active state. 338 o Failed requests will leave the subscription 339 in its previous state, with no visible change to any streaming 340 updates. 342 o A request will delete the entire 343 subscription. 345 3. Data Model Trees for Event Notifications 347 The YANG data model for event notifications is depicted in this 348 section. 350 module: ietf-event-notifications 351 +--ro streams 352 | +--ro stream* stream 353 +--rw filters 354 | +--rw filter* [filter-id] 355 | +--rw filter-id filter-id 356 | +--rw (filter-type)? 357 | +--:(rfc5277) 358 | +--rw filter? 359 +--rw subscription-config {configured-subscriptions}? 360 | +--rw subscription* [subscription-id] 361 | +--rw subscription-id subscription-id 362 | +--rw stream? stream 363 | +--rw encoding? encoding 364 | +--rw (filter-type)? 365 | | +--:(rfc5277) 366 | | | +--rw filter? 367 | | +--:(by-reference) 368 | | +--rw filter-ref? filter-ref 369 | +--rw startTime? yang:date-and-time 370 | +--rw stopTime? yang:date-and-time 371 | +--rw receivers 372 | | +--rw receiver* [address] 373 | | +--rw address inet:host 374 | | +--rw port inet:port-number 375 | | +--rw protocol? transport-protocol 376 | +--rw (push-source)? 377 | +--:(interface-originated) 378 | | +--rw source-interface? if:interface-ref 379 | +--:(address-originated) 380 | +--rw source-vrf? uint32 381 | +--rw source-address inet:ip-address-no-zone 382 +--ro subscriptions 383 +--ro subscription* [subscription-id] 384 +--ro subscription-id subscription-id 385 +--ro configured-subscription? 386 | empty {configured-subscriptions}? 387 +--ro subscription-status? subscription-status 388 +--ro stream? stream 389 +--ro encoding? encoding 390 +--ro (filter-type)? 391 | +--:(rfc5277) 392 | | +--ro filter? 393 | +--:(by-reference) 394 | +--ro filter-ref? filter-ref 395 +--ro startTime? yang:date-and-time 396 +--ro stopTime? yang:date-and-time 397 +--ro receivers 398 | +--ro receiver* [address] 399 | +--ro address inet:host 400 | +--ro port inet:port-number 401 | +--ro protocol? transport-protocol 402 +--ro (push-source)? 403 +--:(interface-originated) 404 | +--ro source-interface? if:interface-ref 405 +--:(address-originated) 406 +--ro source-vrf? uint32 407 +--ro source-address inet:ip-address-no-zone 409 rpcs: 410 +---x establish-subscription 411 | +---w input 412 | | +---w stream? stream 413 | | +---w encoding? encoding 414 | | +---w (filter-type)? 415 | | | +--:(rfc5277) 416 | | | | +---w filter? 417 | | | +--:(by-reference) 418 | | | +---w filter-ref? filter-ref 419 | | +---w startTime? yang:date-and-time 420 | | +---w stopTime? yang:date-and-time 421 | +--ro output 422 | +--ro subscription-result subscription-result 423 | +--ro (result)? 424 | +--:(success) 425 | | +--ro subscription-id subscription-id 426 | +--:(no-success) 427 | +--ro stream? stream 428 | +--ro encoding? encoding 429 | +--ro (filter-type)? 430 | | +--:(rfc5277) 431 | | | +--ro filter? 432 | | +--:(by-reference) 433 | | +--ro filter-ref? filter-ref 434 | +--ro startTime? yang:date-and-time 435 | +--ro stopTime? yang:date-and-time 436 +---x create-subscription 437 | +---w input 438 | +---w stream? stream 439 | +---w encoding? encoding 440 | +---w (filter-type)? 441 | | +--:(rfc5277) 442 | | +---w filter? 443 | +---w startTime? yang:date-and-time 444 | +---w stopTime? yang:date-and-time 445 +---x modify-subscription 446 | +---w input 447 | | +---w subscription-id? subscription-id 448 | | +---w (filter-type)? 449 | | | +--:(rfc5277) 450 | | | | +---w filter? 451 | | | +--:(by-reference) 452 | | | +---w filter-ref? filter-ref 453 | | +---w startTime? yang:date-and-time 454 | | +---w stopTime? yang:date-and-time 455 | +--ro output 456 | +--ro subscription-result subscription-result 457 | +--ro (result)? 458 | +--:(success) 459 | | +--ro subscription-id subscription-id 460 | +--:(no-success) 461 | +--ro stream? stream 462 | +--ro encoding? encoding 463 | +--ro (filter-type)? 464 | | +--:(rfc5277) 465 | | | +--ro filter? 466 | | +--:(by-reference) 467 | | +--ro filter-ref? filter-ref 468 | +--ro startTime? yang:date-and-time 469 | +--ro stopTime? yang:date-and-time 470 +---x delete-subscription 471 +---w input 472 | +---w subscription-id subscription-id 473 +--ro output 474 +--ro subscription-result subscription-result 476 notifications: 477 +---n replay-complete 478 | +--ro subscription-id subscription-id 479 +---n notification-complete 480 | +--ro subscription-id subscription-id 481 +---n subscription-started 482 | +--ro subscription-id subscription-id 483 | +--ro stream? stream 484 | +--ro encoding? encoding 485 | +--ro (filter-type)? 486 | | +--:(rfc5277) 487 | | | +--ro filter? 488 | | +--:(by-reference) 489 | | +--ro filter-ref? filter-ref 490 | +--ro startTime? yang:date-and-time 491 | +--ro stopTime? yang:date-and-time 492 +---n subscription-suspended 493 | +--ro subscription-id subscription-id 494 | +--ro reason? subscription-susp-reason 495 +---n subscription-resumed 496 | +--ro subscription-id subscription-id 497 +---n subscription-modified 498 | +--ro subscription-id subscription-id 499 | +--ro stream? stream 500 | +--ro encoding? encoding 501 | +--ro (filter-type)? 502 | | +--:(rfc5277) 503 | | | +--ro filter? 504 | | +--:(by-reference) 505 | | +--ro filter-ref? filter-ref 506 | +--ro startTime? yang:date-and-time 507 | +--ro stopTime? yang:date-and-time 508 +---n subscription-terminated 509 +--ro subscription-id subscription-id 510 +--ro reason? subscription-term-reason 512 The data model is structured as follows: 514 o "Streams" contains a list of event streams that are supported by 515 the publisher and that can be subscribed to. 517 o "Filters" contains a configurable list of filters that can be 518 applied to a subscription. This allows users to reference an 519 existing filter definition as an alternative to defining a filter 520 inline for each subscription. 522 o "Subscription-config" contains the configuration of configured 523 subscriptions. The parameters of each configured subscription are 524 a superset of the parameters of a dynamic subscription and use the 525 same groupings. In addition, the configured subscriptions must 526 also specify intended receivers and may specify the push source 527 from which to send the stream of notification messages. 529 o "Subscriptions" contains a list of all subscriptions on a 530 publisher, both configured and dynamic. It can be used to 531 retrieve information about the subscriptions which an publisher is 532 serving. 534 The data model also contains a number of notifications that allow a 535 publisher to signal information about a subscription. Finally, the 536 data model contains a number of RPC definitions that are used to 537 manage dynamic subscriptions. 539 4. Dynamic Subscriptions 541 Dynamic subscriptions are managed via RPC. 543 4.1. Establishing a Subscription 545 This operation includes and extends the "create-subscription" 546 operation defined in RFC 5277. It allows a subscriber to request the 547 creation of a subscription both via RPC and configuration operations. 548 When invoking the RPC, establish-subscription permits negotiating the 549 subscription terms, changing them dynamically. 551 The input parameters of the operation are those of create 552 subscription plus: 554 o filter-ref: filters that have been previously (and separately) 555 configured can be referenced by a subscription. This mechanism 556 enables the reuse of filters. 558 o encoding: by default, updates are encoded using XML. Other 559 encodings may be supported, such as JSON. 561 If the publisher cannot satisfy the request, it sends a negative 562 element. 564 If the subscriber has no authorization to establish the subscription, 565 the indicates an authorization error. If the 566 request is rejected because the publisher is not able to serve it, 567 the publisher SHOULD include in the returned error what subscription 568 parameters would have been accepted for the request when it was 569 processed. However, they is no guarantee that subsequent requests 570 with those parameters for this subscriber or others will be accepted. 571 For instance, consider a subscription from 572 [I-D.ietf-netconf-yang-push], which augments the establish- 573 subscription with some additional parameters, including "period". 575 Subscription requests will fail if a filter with invalid syntax is 576 provided or if the name of a non-existent stream is provided. 578 4.2. Modifying a Subscription 580 This operation permits modifying the terms of a dynamic subscription 581 previously established. Subscriptions created by configuration 582 cannot be modified. Dynamic subscriptions can be modified one or 583 multiple times. If the publisher accepts the request, it immediately 584 starts sending events based on the new terms, completely ignoring the 585 previous ones. If the publisher rejects the request, the 586 subscription remains as prior to the request. That is, the request 587 has no impact whatsoever. The contents of negative responses to 588 modify-subscription requests are the subset of the establish 589 subscription request parameters which are allowed to be dynamically 590 modified. 592 Dynamic subscriptions established via RPC can only be modified (or 593 deleted) via RPC using the same transport session used to establish 594 that subscription. 596 Configured subscriptions cannot be modified (or deleted) using RPCs. 597 Instead, configured subscriptions are modified (or deleted) as part 598 of regular configuration operations. Publishers MUST reject any 599 attempts to modify (or delete) configured subscriptions via RPC. 601 4.3. Deleting a Subscription 603 This operation permits canceling a subscription previously 604 established. If the publisher accepts the request, it immediately 605 stops sending events for the subscription. If the publisher rejects 606 the request, all subscriptions remain as prior to the request. That 607 is, the request has no impact whatsoever. 609 Subscriptions created via RPC can only be deleted via RPC using the 610 same transport session used for subscription establishment. 611 Configured subscriptions cannot be deleted using RPCs. Instead, 612 configured subscriptions are deleted as part of regular configuration 613 operations. Publishers MUST reject any RPC attempt to delete 614 configured subscriptions. 616 The only parameter to delete-subscription is the identifier of the 617 subscription to delete. 619 If the publisher can satisfy the request, it sends an OK element. 621 If the publisher cannot satisfy the request, it sends an error-rpc 622 element. 624 5. Configured Subscriptions 626 A configured subscription is a subscription installed via a 627 configuration interface. 629 Configured subscriptions persist across reboots, and persist even 630 when transport is unavailable. This also means configured 631 subscriptions do not support negotiation. 633 Configured subscriptions can be modified by any configuration client 634 with write permissions for the configuration of the subscription. 635 Subscriptions can be modified or terminated at any point of their 636 lifetime. 638 Supporting configured subscriptions is optional and advertised using 639 the "configured-subscriptions" feature. 641 In addition to subscription parameters that apply to dynamic 642 subscriptions, the following additional parameters apply to 643 configured subscriptions: 645 o One or more receiver IP addresses (and corresponding ports) 646 intended as the destination for push updates for each 647 subscription. In addition, the transport protocol for each 648 destination may be defined. 650 o Optional parameters to identify an egress interface or IP address 651 / VRF where a subscription updates should be pushed from the 652 publisher. 654 5.1. Establishing a Configured Subscription 656 Configured subscriptions are established using configuration 657 operations against the top-level subtree subscription-config. There 658 are two key differences between RPC and configuration operations for 659 subscription establishment. Firstly, configuration operations do not 660 support negotiation while RPCs do. Secondly, while RPCs mandate that 661 the subscriber establishing the subscription is the only receiver of 662 the notifications, configuration operations permit specifying 663 receivers independent of any tracked subscriber. Immediately after a 664 subscription is successfully established, the publisher sends to its 665 receivers a control-plane notification stating the subscription has 666 been established (subscription-started). 668 Because there is no explicit association with an existing transport 669 session, configured configuration operations require additional 670 parameters to indicate the receivers of the notifications and 671 possibly the source of the notifications such as a specific egress 672 interface. 674 For example at subscription establishment, a client may send: 676 679 680 681 682 683 685 686 687 1922 688 689 690 foo 691 692 693
694 1.2.3.4 695
696 697 1234 698 699 700 701 702 703 705 Figure 2: Establish configured subscription 707 if the request is accepted, the publisher would reply: 709 711 712 714 Figure 3: Response to a successful configured subscription 715 establishment 717 if the request is not accepted because the publisher cannot serve it, 718 the publisher may reply: 720 721 722 application 723 resource-denied 724 error 725 726 Temporarily the publisher cannot serve this 727 subscription due to the current workload. 728 729 730 732 Figure 4: Response to a failed configured subscription establishment 734 5.2. Modifying a Configured Subscription 736 Configured subscriptions can be modified using configuration 737 operations against the top-level subtree subscription-config. 739 Immediately after a subscription is successfully modified, the 740 publisher sends to the existing receivers a control-plane 741 notification stating the subscription has been modified (i.e., 742 subscription-modified). 744 If the modification involved adding and/or removing receivers, those 745 modified receivers are sent control-plane notifications, indicating 746 they have been added (i.e, subscription-started to a specific 747 receiver) or removed (i.e., subscription-terminated to a specific 748 receiver.) 750 5.3. Deleting a Configured Subscription 752 Subscriptions can be deleted using configuration operations against 753 the top-level subtree subscription-config. For example, in RESTCONF: 755 DELETE /subscription-config/subscription=1922 HTTP/1.1 756 Host: example.com 758 HTTP/1.1 204 No Content 759 Date: Sun, 24 Jul 2016 11:23:40 GMT 760 Server: example-server 762 Figure 5: Deleting a configured subscription 764 Immediately after a subscription is successfully deleted, the 765 publisher sends to all receivers a control-plane notification stating 766 the subscription has been terminated (subscription-terminated). 768 6. Event (Data Plane) Notifications 770 Once a subscription has been set up, the publisher streams 771 (asynchronously) the event notifications per the terms of the 772 subscription. We refer to these as data plane notifications. For 773 dynamic subscriptions set up via RPC operations, event notifications 774 are sent over the session used to create or establish the 775 subscription. For configured subscriptions, event notifications are 776 sent over the specified connections. 778 An event notification is sent to the receiver(s) when an event of 779 interest (i.e., meeting the specified filtering criteria) has 780 occurred. An event notification is a complete and well-formed XML 781 document. Note that is not a Remote Procedure Call 782 (RPC) method but rather the top-level element identifying the one-way 783 message as a notification. Note that event notifications never 784 trigger responses. 786 The event notification always includes an element. It is 787 the time the event was generated by the event source. This parameter 788 is of type dateTime and compliant to [RFC3339]. Implementations must 789 support time zones. 791 The event notifications must also include the subscription-id if the 792 establish-subscription was used in its establishment, or if it was 793 configured via an operational interface. 795 The event notification also contains notification-specific tagged 796 content, if any. 798 The following is an example of an event notification from [RFC7950]: 800 notification link-failure { 801 description "A link failure has been detected"; 802 leaf if-name { 803 type leafref { 804 path "/interface/name"; 805 } 806 } 807 leaf if-admin-status { 808 type admin-status; 809 } 810 leaf if-oper-status { 811 type oper-status; 812 } 813 } 815 Figure 6: Definition of a data plane notification 817 819 2007-09-01T10:00:00Z 820 821 so-1/2/3.0 822 up 823 down 824 825 827 Figure 7: Data plane notification 829 The equivalent using json encoding would be 831 833 2007-09-01T10:00:00Z 834 835 { 836 "acme-system:link-failure": { 837 "if-name": "so-1/2/3.0", 838 "if-admin-status": "up", 839 "if-oper-status": "down " 840 } 841 } 842 843 845 Figure 8: Data plane notification using JSON encoding 847 7. Control Plane Notifications 849 In addition to data plane notifications, a publisher may send control 850 plane notifications to indicate to receivers that an event related to 851 the subscription management has occurred. 853 Control plane notifications are unlike other notifications in that 854 they are not general-purpose notifications. They cannot be filtered 855 out, and they are delivered only to the receiver of a subscription. 856 The definition of control plane notifications is distinct from other 857 notifications by making use of a YANG extension tagging them as 858 control plane notification. 860 Control plane notifications include indications that a replay of 861 notifications has been completed, that a subscription is done sending 862 notifications because an end time has been reached, and that a 863 subscription has started, been modified, been terminated, or been 864 suspended. They are described in the following subsections. 866 7.1. replayComplete 868 This notification is originally defined in [RFC5277]. It is sent to 869 indicate that all of the replay notifications have been sent. This 870 notification must not be sent for any other reason. 872 In the case of a subscription without a stop time or a stop time 873 which has not been reached, after the notification 874 has been sent, it can be expected that any notifications generated 875 since the start of the subscription creation will be sent, followed 876 by notifications in sequence as they arise naturally within the 877 system. 879 7.2. notificationComplete 881 This notification is originally defined in [RFC5277]. It is sent to 882 indicate that a subscription, which includes a stop time, has 883 finished passing events. 885 7.3. subscription-started 887 This notification indicates that a configured subscription has 888 started and data updates are beginning to be sent. This notification 889 includes the parameters of the subscription, except for the 890 receiver(s) addressing information and push-source information. Note 891 that for RPC-based subscriptions, no such notifications are sent. 893 7.4. subscription-modified 895 This notification indicates that a configured subscription has been 896 modified successfully. This notification includes the parameters of 897 the subscription, except for the receiver(s) addressing information 898 and push-source information. Note that for RPC-based subscriptions, 899 no such notifications are sent. 901 7.5. subscription-terminated 903 This notification indicates that a subscription has been terminated 904 by the publisher. The notification includes the reason for the 905 termination. The publisher may decide to terminate a subscription 906 when it is running out of resources for serving it, an internal error 907 occurs, etc. Publisher-driven terminations are notified to all 908 receivers. The management plane can also terminate configured 909 subscriptions using configuration operations. 911 Subscribers can terminate via RPC subscriptions established via RPC. 912 In such cases, no subscription-terminated notifications are sent. 914 7.6. subscription-suspended 916 This notification indicates that a publisher has suspended a 917 subscription. The notification includes the reason for the 918 suspension. A possible reason is the lack of resources to serve it. 919 No further data plane notifications will be sent until the 920 subscription resumes. Suspensions are notified to the subscriber (in 921 the case of dynamic subscriptions) and all receivers (in the case of 922 configured subscriptions). 924 7.7. subscription-resumed 926 This notification indicates that a previously suspended dubscription 927 has been resumed. Data plane notifications generated in the future 928 will be sent after the subscription terms. Resumptions are notified 929 to the subscriber (in the case of dynamic subscriptions) and all 930 receivers (in the case of configured subscriptions). 932 8. Data Model for Event Notifications 934 file "ietf-event-notifications@2016-10-27.yang" 935 module ietf-event-notifications { 936 namespace 937 "urn:ietf:params:xml:ns:yang:ietf-event-notifications"; 939 prefix notif-bis; 941 import ietf-yang-types { 942 prefix yang; 943 } 944 import ietf-inet-types { 945 prefix inet; 946 } 947 import ietf-interfaces { 948 prefix if; 949 } 951 organization "IETF"; 952 contact 953 "WG Web: <http://tools.ietf.org/wg/netconf/> 954 WG List: <mailto:netconf@ietf.org> 956 WG Chair: Mahesh Jethanandani 957 <mailto:mjethanandani@gmail.com> 959 WG Chair: Mehmet Ersue 960 <mailto:mehmet.ersue@nokia.com> 962 Editor: Alexander Clemm 963 <mailto:alex@sympotech.com> 965 Editor: Alberto Gonzalez Prieto 966 <mailto:albertgo@cisco.com> 968 Editor: Eric Voit 969 <mailto:evoit@cisco.com> 971 Editor: Einar Nilsen-Nygaard 972 <mailto:einarnn@cisco.com> 974 Editor: Ambika Prasad Tripathy 975 <mailto:ambtripa@cisco.com> 977 Editor: Sharon Chisholm 978 <mailto:schishol@ciena.com> 980 Editor: Hector Trevino 981 <mailto:htrevino@cisco.com"; 983 description 984 "This module contains conceptual YANG specifications 985 for NETCONF Event Notifications."; 987 revision 2016-10-27 { 988 description 989 "Tweaks to remove two notifications, 990 RPC for create subscription refined with stream default, 991 new grouping to eliminate some dymanically modifiable 992 parameters in modifiy subscription RPC"; 993 reference 994 "draft-ietf-netconf-rfc5277bis-01"; 995 } 997 /* 998 * FEATURES 999 */ 1001 feature json { 1002 description 1003 "This feature indicates that JSON encoding of notifications 1004 is supported."; 1005 } 1007 feature configured-subscriptions { 1008 description 1009 "This feature indicates that management plane configuration 1010 of subscription is supported."; 1011 } 1013 /* 1014 * EXTENSIONS 1015 */ 1017 extension control-plane-notif { 1018 description 1019 "This statement applies only to notifications. 1020 It indicates that the notification is a control-plane 1021 notification (aka OAM notification). Therefore it does 1022 not participate in a regular event stream and does not 1023 need to be specifically subscribed to."; 1024 } 1026 /* 1027 * IDENTITIES 1028 */ 1030 /* Identities for streams */ 1031 identity stream { 1032 description 1033 "Base identity to represent a generic stream of event 1034 notifications."; 1035 } 1037 identity NETCONF { 1038 base stream; 1039 description 1040 "Default NETCONF event stream, containing events based on 1041 notifications defined as YANG modules that are supported 1042 by the system."; 1043 } 1045 /* Identities for subscription results */ 1046 identity subscription-result { 1047 description 1048 "Base identity for RPC responses to requests surrounding 1049 management (e.g. creation, modification, deletion) of 1050 subscriptions."; 1051 } 1053 identity ok { 1054 base subscription-result; 1055 description 1056 "OK - RPC was successful and was performed as requested."; 1058 } 1060 identity error { 1061 base subscription-result; 1062 description 1063 "RPC was not successful. 1064 Base identity for error return codes."; 1065 } 1067 identity error-no-such-subscription { 1068 base error; 1069 description 1070 "A subscription with the requested subscription ID 1071 does not exist."; 1072 } 1074 identity error-no-such-option { 1075 base error; 1076 description 1077 "A requested parameter setting is not supported."; 1078 } 1080 identity error-insufficient-resources { 1081 base error; 1082 description 1083 "The publisher has insufficient resources to support the 1084 subscription as requested."; 1085 } 1087 identity error-configured-subscription { 1088 base error; 1089 description 1090 "Cannot apply RPC to a configured subscription, i.e. 1091 to a subscription that was not established via RPC."; 1092 } 1094 identity error-other { 1095 base error; 1096 description 1097 "An unspecified error has occurred (catch all)."; 1098 } 1100 /* Identities for subscription stream status */ 1101 identity subscription-stream-status { 1102 description 1103 "Base identity for the status of subscriptions and 1104 datastreams."; 1105 } 1106 identity active { 1107 base subscription-stream-status; 1108 description 1109 "Status is active and healthy."; 1110 } 1112 identity inactive { 1113 base subscription-stream-status; 1114 description 1115 "Status is inactive, for example outside the 1116 interval between start time and stop time."; 1117 } 1119 identity suspended { 1120 base subscription-stream-status; 1121 description 1122 "The status is suspended, meaning that the publisher 1123 is currently unable to provide the negotiated updates 1124 for the subscription."; 1125 } 1127 identity in-error { 1128 base subscription-stream-status; 1129 description 1130 "The status is in error or degraded, meaning that 1131 stream and/or subscription is currently unable to provide 1132 the negotiated notifications."; 1133 } 1135 /* Identities for subscription errors */ 1136 identity subscription-errors { 1137 description 1138 "Base identity for subscription error status. 1139 This identity is not to be confused with error return 1140 codes for RPCs"; 1141 } 1143 identity internal-error { 1144 base subscription-errors; 1145 description 1146 "Subscription failures caused by server internal error."; 1147 } 1149 identity no-resources { 1150 base subscription-errors; 1151 description 1152 "Lack of resources, e.g. CPU, memory, bandwidth"; 1153 } 1154 identity subscription-deleted { 1155 base subscription-errors; 1156 description 1157 "The subscription was terminated because the subscription 1158 was deleted."; 1159 } 1161 identity other { 1162 base subscription-errors; 1163 description 1164 "Fallback reason - any other reason"; 1165 } 1167 /* Identities for encodings */ 1168 identity encodings { 1169 description 1170 "Base identity to represent data encodings"; 1171 } 1173 identity encode-xml { 1174 base encodings; 1175 description 1176 "Encode data using XML"; 1177 } 1179 identity encode-json { 1180 base encodings; 1181 description 1182 "Encode data using JSON"; 1183 } 1185 /* Identities for transports */ 1186 identity transport { 1187 description 1188 "An identity that represents a transport protocol for 1189 event notifications"; 1190 } 1192 identity netconf { 1193 base transport; 1194 description 1195 "Netconf notifications as a transport."; 1196 } 1198 /* 1199 * TYPEDEFs 1200 */ 1202 typedef subscription-id { 1203 type uint32; 1204 description 1205 "A type for subscription identifiers."; 1206 } 1208 typedef filter-id { 1209 type uint32; 1210 description 1211 "A type to identify filters which can be associated with a 1212 subscription."; 1213 } 1215 typedef subscription-result { 1216 type identityref { 1217 base subscription-result; 1218 } 1219 description 1220 "The result of a subscription operation"; 1221 } 1223 typedef subscription-term-reason { 1224 type identityref { 1225 base subscription-errors; 1226 } 1227 description 1228 "Reason for a publisher to terminate a subscription."; 1229 } 1231 typedef subscription-susp-reason { 1232 type identityref { 1233 base subscription-errors; 1234 } 1235 description 1236 "Reason for a publisher to suspend a subscription."; 1237 } 1239 typedef encoding { 1240 type identityref { 1241 base encodings; 1242 } 1243 description 1244 "Specifies a data encoding, e.g. for a data subscription."; 1245 } 1247 typedef subscription-status { 1248 type identityref { 1249 base subscription-stream-status; 1251 } 1252 description 1253 "Specifies the status of a subscription or datastream."; 1254 } 1256 typedef transport-protocol { 1257 type identityref { 1258 base transport; 1259 } 1260 description 1261 "Specifies transport protocol used to send notifications to a 1262 receiver."; 1263 } 1265 typedef push-source { 1266 type enumeration { 1267 enum "interface-originated" { 1268 description 1269 "Notifications will be sent from a specific interface on 1270 a publisher"; 1271 } 1272 enum "address-originated" { 1273 description 1274 "Notifications will be sent from a specific address on a 1275 publisher"; 1276 } 1277 } 1278 description 1279 "Specifies from where notifications will be sourced when 1280 being sent by the publisher."; 1281 } 1283 typedef stream { 1284 type identityref { 1285 base stream; 1286 } 1287 description 1288 "Specifies a system-provided datastream."; 1289 } 1291 typedef filter-ref { 1292 type leafref { 1293 path "/notif-bis:filters/notif-bis:filter/notif-bis:filter-id"; 1294 } 1295 description 1296 "This type is used to reference a filter."; 1297 } 1298 /* 1299 * GROUPINGS 1300 */ 1302 grouping base-filter { 1303 description 1304 "This grouping defines the base for filters for 1305 notification events. 1306 It includes the filter defined in 5277 and 1307 it enables extending filtering to other 1308 types of filters"; 1309 choice filter-type { 1310 description 1311 "A filter needs to be a single filter of a given type. 1312 Mixing and matching of multiple filters does not occur 1313 at the level of this grouping."; 1314 case rfc5277 { 1315 anyxml filter { 1316 description 1317 "Filter per RFC 5277. Notification filter. 1318 If a filter element is specified to look for data of a 1319 particular value, and the data item is not present 1320 within a particular event notification for its value to 1321 be checked against, the notification will be filtered 1322 out. For example, if one were to check for 1323 'severity=critical' in a configuration event 1324 notification where this field was not supported, then 1325 the notification would be filtered out. For subtree 1326 filtering, a non-empty node set means that the filter 1327 matches. For XPath filtering, the mechanisms defined 1328 in [XPATH] should be used to convert the returned 1329 value to boolean."; 1330 } 1331 } 1332 } 1333 } 1335 grouping subscription-info-basic-non-modifiable { 1336 description 1337 "This grouping describes the information in a basic 1338 subscription request."; 1339 leaf stream { 1340 type stream; 1341 description 1342 "Indicates which stream of events is of interest. 1343 If not present, events in the default NETCONF stream 1344 will be sent."; 1345 } 1346 leaf encoding { 1347 type encoding; 1348 default "encode-xml"; 1349 description 1350 "The type of encoding for the subscribed data. 1351 Default is XML"; 1352 } 1353 } 1355 grouping subscription-info-basic-modifiable { 1356 description 1357 "This grouping describes some objects which may be changed 1358 in a subscription via an RPC."; 1359 uses base-filter; 1360 leaf startTime { 1361 type yang:date-and-time; 1362 description 1363 "Used to trigger the replay feature 1364 and indicate that the replay should start at the time 1365 specified. If is not present, this is not a 1366 replay subscription. It is not valid to specify start 1367 times that are later than the current time. If the 1368 specified is earlier than the log can support, 1369 the replay will begin with the earliest available 1370 notification. This parameter is of type dateTime and 1371 compliant to [RFC3339]. Implementations must 1372 support time zones."; 1373 } 1374 leaf stopTime { 1375 type yang:date-and-time; 1376 must "current() > ../startTime" { 1377 description 1378 "stopTime must be used with and be later than "; 1379 } 1380 description 1381 "Used with the optional replay feature to indicate the 1382 newest notifications of interest. If is 1383 not present, the notifications will continue until the 1384 subscription is terminated. Must be used with and be 1385 later than . Values of in the 1386 future are valid. This parameter is of type dateTime and 1387 compliant to [RFC3339]. Implementations must support time 1388 zones."; 1389 } 1390 } 1392 grouping subscription-info-all-modifiable { 1393 description 1394 "This grouping describes all rpc modifiable objects in a 1395 subscription."; 1396 uses subscription-info-basic-modifiable { 1397 augment "filter-type" { 1398 description 1399 "Post-5277 subscriptions allow references to existing 1400 filters"; 1401 case by-reference { 1402 description 1403 "Incorporate a filter that has been configured 1404 separately."; 1405 leaf filter-ref { 1406 type filter-ref; 1407 description 1408 "References filter which is associated with the 1409 subscription."; 1410 } 1411 } 1412 } 1413 } 1414 } 1416 grouping subscription-info { 1417 description 1418 "This grouping describes information concerning a 1419 subscription."; 1420 uses subscription-info-basic-non-modifiable; 1421 uses subscription-info-all-modifiable; 1422 } 1424 grouping push-source-info { 1425 description 1426 "Defines the sender source from which notifications 1427 for a configured subscription are sent."; 1428 choice push-source { 1429 description 1430 "Identifies the egress interface on the Publisher from 1431 which notifications will or are being sent."; 1432 case interface-originated { 1433 description 1434 "When the push source is out of an interface on the 1435 Publisher established via static configuration."; 1436 leaf source-interface { 1437 type if:interface-ref; 1438 description 1439 "References the interface for notifications."; 1440 } 1441 } 1442 case address-originated { 1443 description 1444 "When the push source is out of an IP address on the 1445 Publisher established via static configuration."; 1446 leaf source-vrf { 1447 type uint32 { 1448 range "16..1048574"; 1449 } 1450 description 1451 "Label of the vrf."; 1452 } 1453 leaf source-address { 1454 type inet:ip-address-no-zone; 1455 mandatory true; 1456 description 1457 "The source address for the notifications."; 1458 } 1459 } 1460 } 1461 } 1463 grouping receiver-info { 1464 description 1465 "Defines where and how to deliver notifications for a 1466 configured subscription. This includes 1467 specifying the receiver, as well as defining 1468 any network and transport aspects when sending of 1469 notifications occurs outside of Netconf."; 1470 container receivers { 1471 description 1472 "Set of receivers in a subscription."; 1473 list receiver { 1474 key "address"; 1475 min-elements 1; 1476 description 1477 "A single host or multipoint address intended as a target 1478 for the notifications for a subscription."; 1479 leaf address { 1480 type inet:host; 1481 mandatory true; 1482 description 1483 "Specifies the address for the traffic to reach a 1484 remote host. One of the following must be 1485 specified: an ipv4 address, an ipv6 address, 1486 or a host name."; 1487 } 1488 leaf port { 1489 type inet:port-number; 1490 mandatory true; 1491 description 1492 "This leaf specifies the port number to use for 1493 messages destined for a receiver."; 1494 } 1495 leaf protocol { 1496 type transport-protocol; 1497 default "netconf"; 1498 description 1499 "This leaf specifies the transport protocol used 1500 to deliver messages destined for the receiver."; 1501 } 1502 } 1503 } 1504 } 1506 grouping subscription-response { 1507 description 1508 "Defines the output to the rpc's establish-subscription 1509 and modify-subscription."; 1510 leaf subscription-result { 1511 type subscription-result; 1512 mandatory true; 1513 description 1514 "Indicates whether subscription is operational, 1515 or if a problem was encountered."; 1516 } 1517 choice result { 1518 description 1519 "Depending on the subscription result, different 1520 data is returned."; 1521 case success { 1522 description 1523 "This case is used when the subscription request 1524 was successful and a subscription was created/modified 1525 as a result"; 1526 leaf subscription-id { 1527 type subscription-id; 1528 mandatory true; 1529 description 1530 "Identifier used for this subscription."; 1531 } 1532 } 1533 case no-success { 1534 description 1535 "This case applies when a subscription request 1536 was not successful and no subscription was 1537 created (or modified) as a result. In this case, 1538 information MAY be returned that indicates 1539 suggested parameter settings that would have a 1540 high likelihood of succeeding in a subsequent 1541 establish-subscription or modify-subscription 1542 request."; 1543 uses subscription-info; 1544 } 1545 } 1546 } 1548 /* 1549 * RPCs 1550 */ 1552 rpc establish-subscription { 1553 description 1554 "This RPC allows a subscriber to create 1555 (and possibly negotiate) a subscription on its own behalf. 1556 If successful, the subscription 1557 remains in effect for the duration of the subscriber's 1558 association with the publisher, or until the subscription 1559 is terminated by virtue of a delete-subscription request. 1560 In case an error (as indicated by subscription-result) 1561 is returned, the subscription is 1562 not created. In that case, the RPC output 1563 MAY include suggested parameter settings 1564 that would have a high likelihood of succeeding in a 1565 subsequent establish-subscription request."; 1566 input { 1567 uses subscription-info; 1568 } 1569 output { 1570 uses subscription-response; 1571 } 1572 } 1574 rpc create-subscription { 1575 description 1576 "This operation initiates an event notification subscription 1577 that will send asynchronous event notifications to the 1578 initiator of the command until the association terminates. 1579 It is not possible to modify or delete a subscription 1580 that was created using this operation. It is included for 1581 reasons of backward compatibility with RFC 5277 1582 implementations."; 1583 input { 1584 uses subscription-info-basic-non-modifiable{ 1585 refine "stream" { 1586 default "NETCONF"; 1587 } 1588 } 1589 uses subscription-info-basic-modifiable; 1590 } 1591 } 1593 rpc modify-subscription { 1594 description 1595 "This RPC allows a subscriber to modify a subscription 1596 that was previously created using establish-subscription. 1597 If successful, the subscription 1598 remains in effect for the duration of the subscriber's 1599 association with the publisher, or until the subscription 1600 is terminated by virtue of a delete-subscription request. 1601 In case an error is returned (as indicated by 1602 subscription-result), the subscription is 1603 not modified and the original subscription parameters 1604 remain in effect. In that case, the rpc error response 1605 MAY include suggested parameter settings 1606 that would have a high likelihood of succeeding in a 1607 subsequent modify-subscription request."; 1608 input { 1609 leaf subscription-id { 1610 type subscription-id; 1611 description 1612 "Identifier to use for this subscription."; 1613 } 1614 uses subscription-info-all-modifiable; 1615 } 1616 output { 1617 uses subscription-response; 1618 } 1619 } 1621 rpc delete-subscription { 1622 description 1623 "This RPC allows a subscriber to delete a subscription that 1624 was previously created using establish-subscription."; 1625 input { 1626 leaf subscription-id { 1627 type subscription-id; 1628 mandatory true; 1629 description 1630 "Identifier of the subscription that is to be deleted. 1631 Only subscriptions that were created using 1632 establish-subscription can be deleted via this RPC."; 1633 } 1635 } 1636 output { 1637 leaf subscription-result { 1638 type subscription-result; 1639 mandatory true; 1640 description 1641 "Indicates whether subscription is operational, 1642 or if a problem was encountered."; 1643 } 1644 } 1645 } 1647 /* 1648 * NOTIFICATIONS 1649 */ 1651 notification replay-complete { 1652 notif-bis:control-plane-notif; 1653 description 1654 "This notification is sent to indicate that all of the 1655 replay notifications have been sent. It must not be 1656 sent for any other reason."; 1657 leaf subscription-id { 1658 type subscription-id; 1659 mandatory true; 1660 description 1661 "This references the affected subscription."; 1662 } 1663 } 1665 notification notification-complete { 1666 notif-bis:control-plane-notif; 1667 description 1668 "This notification is sent to indicate that a 1669 subscription, which includes a stop time, has 1670 finished passing events."; 1671 leaf subscription-id { 1672 type subscription-id; 1673 mandatory true; 1674 description 1675 "This references the affected subscription."; 1676 } 1677 } 1679 notification subscription-started { 1680 notif-bis:control-plane-notif; 1681 description 1682 "This notification indicates that a subscription has 1683 started and notifications are beginning to be sent. 1684 This notification shall only be sent to receivers 1685 of a subscription; it does not constitute a general-purpose 1686 notification."; 1687 leaf subscription-id { 1688 type subscription-id; 1689 mandatory true; 1690 description 1691 "This references the affected subscription."; 1692 } 1693 uses subscription-info; 1694 } 1696 notification subscription-suspended { 1697 notif-bis:control-plane-notif; 1698 description 1699 "This notification indicates that a suspension of the 1700 subscription by the publisher has occurred. No further 1701 notifications will be sent until subscription 1702 resumes. 1703 This notification shall only be sent to receivers 1704 of a subscription; it does not constitute a general-purpose 1705 notification."; 1706 leaf subscription-id { 1707 type subscription-id; 1708 mandatory true; 1709 description 1710 "This references the affected subscription."; 1711 } 1712 leaf reason { 1713 type subscription-susp-reason; 1714 description 1715 "Provides a reason for why the subscription was 1716 suspended."; 1717 } 1718 } 1720 notification subscription-resumed { 1721 notif-bis:control-plane-notif; 1722 description 1723 "This notification indicates that a subscription that had 1724 previously been suspended has resumed. Notifications 1725 will once again be sent."; 1726 leaf subscription-id { 1727 type subscription-id; 1728 mandatory true; 1729 description 1730 "This references the affected subscription."; 1731 } 1732 } 1734 notification subscription-modified { 1735 notif-bis:control-plane-notif; 1736 description 1737 "This notification indicates that a subscription has 1738 been modified. Notifications sent from this point 1739 on will conform to the modified terms of the 1740 subscription."; 1741 leaf subscription-id { 1742 type subscription-id; 1743 mandatory true; 1744 description 1745 "This references the affected subscription."; 1746 } 1747 uses subscription-info; 1748 } 1750 notification subscription-terminated { 1751 notif-bis:control-plane-notif; 1752 description 1753 "This notification indicates that a subscription has been 1754 terminated."; 1755 leaf subscription-id { 1756 type subscription-id; 1757 mandatory true; 1758 description 1759 "This references the affected subscription."; 1760 } 1761 leaf reason { 1762 type subscription-term-reason; 1763 description 1764 "Provides a reason for why the subscription was 1765 terminated."; 1766 } 1767 } 1769 /* 1770 * DATA NODES 1771 */ 1773 container streams { 1774 config false; 1775 description 1776 "This container contains a leaf list of built-in 1777 streams that are provided by the system."; 1778 leaf-list stream { 1779 type stream; 1780 description 1781 "Identifies the built-in streams that are supported by the 1782 system. Built-in streams are associated with their own 1783 identities, each of which carries a special semantics. 1784 In case configurable custom streams are supported, 1785 as indicated by the custom-stream identity, the 1786 configuration of those custom streams is provided 1787 separately."; 1788 } 1789 } 1790 container filters { 1791 description 1792 "This container contains a list of configurable filters 1793 that can be applied to subscriptions. This facilitates 1794 the reuse of complex filters once defined."; 1795 list filter { 1796 key "filter-id"; 1797 description 1798 "A list of configurable filters that can be applied to 1799 subscriptions."; 1800 leaf filter-id { 1801 type filter-id; 1802 description 1803 "An identifier to differentiate between filters."; 1804 } 1805 uses base-filter; 1806 } 1807 } 1808 container subscription-config { 1809 if-feature "configured-subscriptions"; 1810 description 1811 "Contains the list of subscriptions that are configured, 1812 as opposed to established via RPC or other means."; 1813 list subscription { 1814 key "subscription-id"; 1815 description 1816 "Content of a subscription."; 1817 leaf subscription-id { 1818 type subscription-id; 1819 description 1820 "Identifier to use for this subscription."; 1821 } 1822 uses subscription-info; 1823 uses receiver-info { 1824 if-feature "configured-subscriptions"; 1826 } 1827 uses push-source-info { 1828 if-feature "configured-subscriptions"; 1829 } 1830 } 1831 } 1832 container subscriptions { 1833 config false; 1834 description 1835 "Contains the list of currently active subscriptions, 1836 i.e. subscriptions that are currently in effect, 1837 used for subscription management and monitoring purposes. 1838 This includes subscriptions that have been setup via RPC 1839 primitives, e.g. create-subscription, establish- 1840 subscription, and modify-subscription, as well as 1841 subscriptions that have been established via 1842 configuration."; 1843 list subscription { 1844 key "subscription-id"; 1845 config false; 1846 description 1847 "Content of a subscription. 1848 Subscriptions can be created using a control channel 1849 or RPC, or be established through configuration."; 1850 leaf subscription-id { 1851 type subscription-id; 1852 description 1853 "Identifier of this subscription."; 1854 } 1856 leaf configured-subscription { 1857 if-feature "configured-subscriptions"; 1858 type empty; 1859 description 1860 "The presence of this leaf indicates that the 1861 subscription originated from configuration, not 1862 through a control channel or RPC."; 1863 } 1865 leaf subscription-status { 1866 type subscription-status; 1867 description 1868 "The status of the subscription."; 1869 } 1870 uses subscription-info; 1871 uses receiver-info { 1872 if-feature "configured-subscriptions"; 1873 } 1874 uses push-source-info { 1875 if-feature "configured-subscriptions"; 1876 } 1877 } 1878 } 1879 } 1880 1882 9. Backwards Compatibility 1884 Capabilities are advertised in messages sent by each peer during 1885 session establishment [RFC6241]. Publishers supporting the features 1886 in this document must advertise both capabilities 1887 "urn:ietf:params:netconf:capability:notification:1.0" and 1888 "urn:ietf:params:netconf:capability:notification:1.1". 1890 An example of a hello message by a publisher during session 1891 establishment would be: 1893 1894 1895 1896 urn:ietf:params:xml:ns:netconf:base:1.0 1897 1898 1899 urn:ietf:params:netconf:capability:startup:1.0 1900 1901 1902 urn:ietf:params:netconf:capability:notification:1.0 1903 1904 1905 urn:ietf:params:netconf:capability:notification:1.1 1906 1907 1908 4 1909 1911 Figure 9: Hello message 1913 Subscribers that only support [RFC5277] recognize capability 1914 "urn:ietf:params:netconf:capability:notification:1.0" and ignore 1915 capability "urn:ietf:params:netconf:capability:notification:1.1". 1916 This allows them interacting with the publisher as per [RFC5277]. 1917 Subscribers that support the features in this document recognize both 1918 capabilities. This allows them interacting with the publisher as per 1919 this document. 1921 Note that to support backwards compatibility, the yang models in this 1922 document include two types of naming conventions. That used in 1923 [RFC5277], e.g., replayComplete; and that commonly used in yang 1924 models, e.g., subscription-started. 1926 10. Security Considerations 1928 The elements are never sent before the transport 1929 layer, including capabilities exchange, has been established and the 1930 manager has been securely established. 1932 A secure transport is highly recommended and the publisher must 1933 ensure that the user has sufficient authorization to perform the 1934 function they are requesting against the specific subset of content 1935 involved. When a is received that refers to the content 1936 defined in this memo, clients should only be able to view the content 1937 for which they have sufficient privileges. and 1938 operations can be considered like deferred 1939 , and the content that different users can access may vary. 1940 This different access is reflected in the to which 1941 different users are able to subscribe. 1943 The contents of notifications, as well as the names of event streams, 1944 may contain sensitive information and care should be taken to ensure 1945 that they are viewed only by authorized users. The publisher MUST 1946 NOT include any content in a notification that the user is not 1947 authorized to view. 1949 If a malicious or buggy subscriber sends a number of requests, then these subscriptions accumulate and may 1951 use up system resources. In such a situation, subscriptions can be 1952 terminated by terminating the suspect underlying NETCONF sessions 1953 using the operation. If the subscriber uses 1954 , the publisher can also suspend or terminate 1955 subscriptions with per-subscription granularity. 1957 A subscription could be configured on another receiver's behalf, with 1958 the goal of flooding that receiver with updates. One or more 1959 publishers could be used to overwhelm a receiver, which doesn't even 1960 support subscriptions. Subscribers that do not want pushed data need 1961 only terminate or refuse any transport sessions from the publisher. 1962 In addition, the NETCONF Authorization Control Model [RFC6536] SHOULD 1963 be used to control and restrict authorization of subscription 1964 configuration. This control models permits specifying per-user 1965 permissions to receive specific event notification types. The 1966 permissions are specified as a set of access control rules. 1968 Note that streams can define additional authorization requirements. 1969 For instance, in [I-D.ietf-netconf-yang-push], each of the elements 1970 in its data plane notifications must also go through access control. 1972 11. Acknowledgments 1974 For their valuable comments, discussions, and feedback, we wish to 1975 acknowledge Andy Bierman, Yang Geng, Peipei Guo, Susan Hares, Tim 1976 Jenkins, Balazs Lengyel, Kent Watsen, Michael Scharf, and Guangying 1977 Zheng. 1979 12. References 1981 12.1. Normative References 1983 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1984 Requirement Levels", BCP 14, RFC 2119, 1985 DOI 10.17487/RFC2119, March 1997, 1986 . 1988 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1989 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1990 . 1992 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1993 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1994 . 1996 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1997 and A. Bierman, Ed., "Network Configuration Protocol 1998 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1999 . 2001 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2002 Protocol (NETCONF) Access Control Model", RFC 6536, 2003 DOI 10.17487/RFC6536, March 2012, 2004 . 2006 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", 2007 RFC 7950, August 2016. 2009 12.2. Informative References 2011 [I-D.ietf-netconf-netconf-event-notif] 2012 Gonzalez Prieto, Alberto., Clemm, Alexander., Voit, Eric., 2013 Nilsen-Nygaard, E., Tripathy, A., Chisholm, S., and H. 2014 Trevino, "NETCONF support for event notifications", August 2015 2016, . 2018 [I-D.ietf-netconf-restconf] 2019 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2020 Protocol", I-D draft-ietf-netconf-restconf-17, September 2021 2016. 2023 [I-D.ietf-netconf-restconf-notif] 2024 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen- 2025 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and 2026 HTTP transport for event notifications", August 2016, 2027 . 2030 [I-D.ietf-netconf-yang-push] 2031 Clemm, Alexander., Gonzalez Prieto, Alberto., Voit, Eric., 2032 Tripathy, A., and E. Nilsen-Nygaard, "Subscribing to YANG 2033 datastore push updates", June 2016, 2034 . 2037 Appendix A. Issues that are currently being worked and resolved 2039 (To be removed by RFC editor prior to publication) 2041 A.1. Unresolved and yet-to-be addressed issues 2043 EN1 - Definition of basic set of Stream types. What streams are 2044 provided and what do they contain (includes default 5277 stream). 2046 EN2 - Clarify interplay between filter definitions and different 2047 streams. Includes information in subtrees of event payloads. 2049 EN3 - Mechanisms for diagnostics, e.g. deal with dropped updates, 2050 monitoring when they occur, etc 2052 A.2. Agreement in principal 2054 EN4 - How to allow for seamless integration with non-standard 2055 encodings and transports (like GPB/GRPC). Specify requirements 2056 encoding and transport must meet, provide examples. 2058 EN7 - Detecting loss of a sequential update notification, and 2059 mechanisms to resend. Implications to transports must be thought 2060 through. 2062 EN6 - Stream discovery. Allow to discover additional stream 2063 properties. 2065 EN12 - Test-only option for a subscription is desired. But it still 2066 needs to be defined. 2068 EN14 - Ensure that Configured Subscriptions are fully defined in YANG 2069 model. 2071 A.3. Resolved Issues 2073 EN5 - This draft obsoletes 5277, as opposed to being in parallel with 2074 it 2076 EN8 - No mandatory transport 2078 EN15 - Term for Dynamic and Static Subscriptions (move to 2079 "Configured") 2081 EN9 - Multiple receivers per Configured Subscription is ok. 2083 EN13 - RFC6241 Subtree-filter definition in 5277bis cannot apply to 2084 elements of an event. Must explicitly define how 6241 doesn't apply 2085 filtering within a 5277bis event. 2087 EN10 - Replay support will be provided for selected stream types 2088 (modify vs. delete) 2090 EN11 - Required layering security requirements/considerations will be 2091 added into the YANG model for Configured Subscriptions. It will be 2092 up to the transport to meet these requirements. 2094 Appendix B. Changes between revisions 2096 (To be removed by RFC editor prior to publication) 2098 v00 - v01 2100 o YANG Model changes. New groupings for subscription info to allow 2101 restriction of what is changable via RPC. Removed notifications 2102 for adding and removing receivers of configured subscriptions. 2104 o Expanded/renamed defintions from event server to publisher, and 2105 client to subscriber as applicable. Updated the definitions to 2106 include and expand on RFC 5277. 2108 o Removal of redundant with other drafts 2110 o Many other clean-ups of wording and terminology 2112 Authors' Addresses 2114 Alexander Clemm 2115 Sympotech 2117 Email: alex@sympotech.com 2119 Alberto Gonzalez Prieto 2120 Cisco Systems 2122 Email: albertgo@cisco.com 2124 Eric Voit 2125 Cisco Systems 2127 Email: evoit@cisco.com 2129 Einar Nilsen-Nygaard 2130 Cisco Systems 2132 Email: einarnn@cisco.com 2134 Ambika Prasad Tripathy 2135 Cisco Systems 2137 Email: ambtripa@cisco.com 2139 Sharon Chisholm 2140 Ciena 2142 Email: schishol@ciena.com 2143 Hector Trevino 2144 Cisco Systems 2146 Email: htrevino@cisco.com