idnits 2.17.1 draft-ietf-netconf-subscribed-notifications-07.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.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 438 has weird spacing: '...ter-ref str...' == Line 452 has weird spacing: '...rotocol tra...' == Line 502 has weird spacing: '...ter-ref str...' == Line 527 has weird spacing: '...ter-ref str...' == Line 536 has weird spacing: '...-result sub...' == (10 more instances...) -- The document date (October 30, 2017) is 2341 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) == Outdated reference: A later version (-09) exists of draft-ietf-netconf-rfc6536bis-01 -- Possible downref: Normative reference to a draft: ref. 'RFC6536bis' -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF E. Voit 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track A. Clemm 5 Expires: May 3, 2018 Huawei 6 A. Gonzalez Prieto 7 VMWare 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 October 30, 2017 13 Custom Subscription to Event Streams 14 draft-ietf-netconf-subscribed-notifications-07 16 Abstract 18 This document defines capabilities and operations for the customized 19 establishment of subscriptions upon a publisher's event streams. 20 Also defined are delivery mechanisms for instances of the resulting 21 notification messages. Effectively this allows a subscriber to 22 request and receive a continuous, custom feed of publisher generated 23 information. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on May 3, 2018. 42 Copyright Notice 44 Copyright (c) 2017 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 5 63 1.4. Relationship to RFC-5277 . . . . . . . . . . . . . . . . 6 64 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 6 66 2.2. Event Stream Filters . . . . . . . . . . . . . . . . . . 7 67 2.3. Subscription State Model at the Publisher . . . . . . . . 7 68 3. Data Model Trees . . . . . . . . . . . . . . . . . . . . . . 9 69 4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . . . 14 70 4.1. Establishing a Subscription . . . . . . . . . . . . . . . 14 71 4.2. Modifying a Subscription . . . . . . . . . . . . . . . . 16 72 4.3. Deleting a Subscription . . . . . . . . . . . . . . . . . 16 73 4.4. Killing a Subscription . . . . . . . . . . . . . . . . . 16 74 5. Configured Subscriptions . . . . . . . . . . . . . . . . . . 17 75 5.1. Creating a Configured Subscription . . . . . . . . . . . 17 76 5.2. Modifying a Configured Subscription . . . . . . . . . . . 18 77 5.3. Deleting a Configured Subscription . . . . . . . . . . . 18 78 6. Deleting a Configured Subscription . . . . . . . . . . . . . 19 79 7. Asynchronous Subscribed Event Delivery . . . . . . . . . . . 19 80 8. Subscription State Notifications . . . . . . . . . . . . . . 20 81 8.1. subscription-started . . . . . . . . . . . . . . . . . . 20 82 8.2. subscription-modified . . . . . . . . . . . . . . . . . . 21 83 8.3. subscription-terminated . . . . . . . . . . . . . . . . . 21 84 8.4. subscription-suspended . . . . . . . . . . . . . . . . . 21 85 8.5. subscription-resumed . . . . . . . . . . . . . . . . . . 21 86 8.6. subscription-completed . . . . . . . . . . . . . . . . . 22 87 8.7. replay-completed . . . . . . . . . . . . . . . . . . . . 22 88 9. Administrative Functions . . . . . . . . . . . . . . . . . . 22 89 9.1. Subscription Monitoring . . . . . . . . . . . . . . . . . 22 90 9.2. Advertisement . . . . . . . . . . . . . . . . . . . . . . 23 91 9.3. Event Stream Discovery . . . . . . . . . . . . . . . . . 23 92 10. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 23 93 11. Considerations . . . . . . . . . . . . . . . . . . . . . . . 46 94 11.1. Implementation Considerations . . . . . . . . . . . . . 46 95 11.2. Security Considerations . . . . . . . . . . . . . . . . 46 96 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47 97 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 98 13.1. Normative References . . . . . . . . . . . . . . . . . . 48 99 13.2. Informative References . . . . . . . . . . . . . . . . . 48 100 Appendix A. Changes between revisions . . . . . . . . . . . . . 49 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 52 103 1. Introduction 105 This document defines capabilities and operations for the customized 106 establishment of subscriptions upon system generated event streams. 107 Effectively this enables a "Subscribe then Publish" capability where 108 the customized information needs of each target receiver are 109 understood by the publisher before subscribed event records are 110 marshalled and pushed. The receiver then gets a continuous, custom 111 feed of publisher generated information. 113 While the functionality defined in this document is transport- 114 agnostic, protocols like NETCONF [RFC6241] or RESTCONF [RFC8040] can 115 be used to configure or dynamically signal subscriptions, and there 116 are bindings defined for subscribed event record delivery for NETCONF 117 within [I-D.draft-ietf-netconf-netconf-event-notifications], and for 118 HTTP2 or HTTP1.1 within [I-D.draft-ietf-netconf-restconf-notif]. 120 1.1. Motivation 122 There are various [RFC5277] limitations, many of which have been 123 exposed in [RFC7923] which needed to be solved. Key capabilities 124 supported by this document include: 126 o multiple subscriptions on a single transport session 128 o support for dynamic and statically configured subscriptions 130 o modification of an existing subscription 132 o operational counters and instrumentation 134 o negotiation of subscription parameters (through the use of hints 135 returned as part of declined subscription requests) 137 o state change notifications (e.g., publisher driven suspension, 138 parameter modification) 140 o independence from transport protocol 142 1.2. Terminology 144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 146 document are to be interpreted as described in RFC 2119 [RFC2119]. 148 Configured subscription: A subscription installed via a configuration 149 interface which persists across reboots. 151 Dynamic subscription: A subscription agreed between subscriber and 152 publisher created via RPC subscription state signaling messages. 154 Event: An occurrence of something that may be of interest. (e.g., a 155 configuration change, a fault, a change in status, crossing a 156 threshold, or an external input to the system.) 158 Event record: A set of information detailing an event. 160 NACM: NETCONF Access Control Model. 162 Notification message: A set of transport encapsulated information 163 intended for a receiver indicating that one or more event(s) have 164 occurred. A notification message may include event records. 166 Publisher: An entity responsible for streaming notification messages 167 per the terms of a Subscription. 169 Receiver: A target to which a publisher pushes subscribed event 170 records. For dynamic subscriptions, the receiver and subscriber are 171 the same entity. 173 Stream (also referred to as "event stream"): A continuous ordered set 174 of events aggregated under some context. 176 Stream filter: Evaluation criteria which may be applied against a 177 event records within a stream. Event records pass the filter when 178 specified criteria are met. 180 Subscribed event records: Event records which have met the terms of 181 the subscription. This include terms (such as security checks) 182 enforced by the publisher. 184 Subscriber: An entity able to request and negotiate a contract for 185 the generation and push of event records from a publisher. 187 Subscription: A contract with a publisher, stipulating which 188 information one or more receivers wish to have pushed from the 189 publisher without the need for further solicitation. 191 1.3. Solution Overview 193 This document describes a transport agnostic mechanism for 194 subscribing to and receiving content from a stream instantiated 195 within a publisher. This mechanism is through the use of a 196 subscription. 198 Two types of subscriptions are supported: 200 1. Dynamic subscriptions, where a subscriber initiates a 201 subscription negotiation with a publisher via RPC. If the 202 publisher wants to serve this request, it accepts it, and then 203 starts pushing notification messages. If the publisher does not 204 wish to serve it as requested, then an error response is 205 returned. This response MAY include hints at subscription 206 parameters which would have been accepted. 208 2. Configured subscriptions, which allow the management of 209 subscriptions via a configuration interface so that a publisher 210 can send notification messages to configured receiver(s). 211 Support for this capability is optional. 213 Additional characteristics differentiating configured from dynamic 214 subscriptions include: 216 o The lifetime of a dynamic subscription is bounded by the transport 217 session used to establish it. For connection-oriented stateful 218 transport like NETCONF, the loss of the transport session will 219 result in the immediate termination of associated dynamic 220 subscriptions. For connectionless or stateless transports like 221 HTTP, it is the lack of receipt acknowledgement of a sequential 222 set of notification messages and/or keep-alives which will 223 terminate dynamic subscriptions. The lifetime of a configured 224 subscription is driven by relevant configuration being present on 225 the running configuration. This implies configured subscriptions 226 persist across reboots, and persist even when transport is 227 unavailable. 229 o Configured subscriptions can be modified by any configuration 230 client with write permission on the configuration of the 231 subscription. Dynamic subscriptions can only be modified via an 232 RPC request made upon the original subscribing transport session. 234 Note that there is no mixing-and-matching of dynamic and configured 235 subscriptions. Specifically, a configured subscription cannot be 236 modified or deleted using RPC. Similarly, a subscription established 237 via RPC cannot be modified through configuration operations (if 238 needed, an operator may use a kill RPC however). 240 The publisher MAY decide to terminate a dynamic subscription at any 241 time. Similarly, it MAY decide to temporarily suspend the sending of 242 notification messages for either configured or dynamic subscriptions. 243 Such termination or suspension MAY be driven by the publisher running 244 out of resources to serve the subscription, or by internal errors on 245 the publisher. 247 1.4. Relationship to RFC-5277 249 This document is intended to provide a superset of the subscription 250 capabilities initially defined within [RFC5277]. Especially when 251 extending an existing [RFC5277] implementation, it is important to 252 understand what has been reused and what has been replaced. Key 253 realtionships between these two documents include: 255 o the data model in this document replaces the data model in 256 [RFC5277]. 258 o the RPC operations in this draft replaces the symetrical 259 operations of [RFC5277], section 4. 261 o the one way operation of [RFC5277] is still used. However this 262 operation will no longer be required with the availability of 263 [I.D.draft-ietf-netconf-notification-messages]. 265 o the definition and contents of the NETCONF stream are identical 266 between this document and [RFC5277]. 268 o a publisher MAY implement both the data model and RPCs defined in 269 [RFC5277] and this new document concurrently, in order to support 270 old clients. However the use of both alternatives on a single 271 transport session is prohibited. 273 2. Solution 275 2.1. Event Streams 277 An event stream is a named entity on a publisher which exposes a 278 continuously updating set of events. Each event stream is available 279 for subscription. It is out of the scope of this document to 280 identify a) how streams are defined, b) how events are defined/ 281 generated, and c) how events are assigned to streams. 283 There is only one reserved event stream within this document: 284 NETCONF. The NETCONF event stream contains all NETCONF XML event 285 record information supported by the publisher, except for where it 286 has been explicitly indicated that this the event record MUST be 287 excluded from the NETCONF stream. Beyond NETCONF, implementations 288 are free to add additional event streams. 290 As events are raised by a system, they may be assigned to one or more 291 streams. The event record is distributed to receivers where: (1) a 292 subscription includes the identified stream, and (2) subscription 293 filtering does not exclude the event record from that receiver. 295 If access control permissions are in use to secure publisher content, 296 then for notification messages to be sent to a receiver, that 297 receiver MUST be allowed access to all the event records on the 298 stream. If subscriber permissions change during the lifecycle of a 299 subscription, then the subscription MUST be continued or terminated 300 accordingly. 302 2.2. Event Stream Filters 304 This document defines an extensible filtering mechanism. Two 305 optional stream filtering syntaxes supported are [XPATH] and subtree 306 [RFC6241]. The subsets of these filtering syntaxes supported are 307 left to each implementation. A subset of information is never 308 stripped from within the event record. 310 If no stream filter is provided, all event records on a stream are to 311 be sent. 313 2.3. Subscription State Model at the Publisher 315 Below is the state machine of a subscription for the publisher for a 316 dynamic subscription. It is important to note that such a 317 subscription doesn't exist at the publisher until it is accepted and 318 made active. The mere request by a subscriber to establish a 319 subscription is insufficient for that asserted subscription to be 320 externally visible via this state machine. 322 .-------. 323 | start | 324 '-------' 325 | 326 establish 327 | 328 | .----------modify------------. 329 v v ' 330 .-----------. .-----------. 331 .--------. | |-----suspend------->| | 332 modify '| active | | suspended | 333 '--------->| |<----resume---------| | 334 '-----------' '-----------' 335 | | 336 delete/kill delete/kill 337 | | 338 v | 339 .-------. | 340 | end |<---------------------------' 341 '-------' 343 Figure 1: Dynamic subscription states 345 Of interest in this state machine are the following: 347 o Successful establish or modify RPCs put the subscription into an 348 active state. 350 o Failed modify RPCs will leave the subscription in its previous 351 state, with no visible change to any streaming updates. 353 o A delete or kill RPC will end the subscription. 355 o Suspend and resume state changes are driven by internal process 356 and prioritization. There are no external controls over suspend 357 and resume. 359 As shown below, a very similar state machine exists for configured 360 subscriptions. Creation, modification, and deletion is via 361 configuration operations rather than via RPC. When a subscription is 362 first created, the operational status of each receiver is initially 363 set to connecting. Individual are receivers are moved to an active 364 status when a subscription-started state change notification is 365 successfully delivered. Configured subscriptions remain active if 366 transport connectivity is not lost and event records are not being 367 dropped due to buffer overflow. A configured subscription MUST be 368 moved connecting if transport connectivity is lost. 370 A configured subscription MUST be moved to a suspended status if 371 notification messages are being dropped despite the presence of 372 transport connectivity. A configured subscription MUST be returned 373 to an active status from the suspended status as soon as transport 374 connectivity is re-established, and a receiver acknowledges receipt 375 of a "subscription-resumed". Otherwise, it MUST be moved to 376 connecting. 378 .-------. 379 | start | 380 '-------' 381 | 382 create 383 | 384 v 385 .---------------------------------------------------. 386 .--------. | Subscription | 387 modify '| .---------------------. | 388 '--------->| .--| connecting receiver |--. | 389 | | '---------------------' | | 390 | V ^ ^ V | 391 | .---------------. -suspend-> .------------------. | 392 | |active receiver| |suspended receiver| | 393 | '---------------' <--resume- '------------------' | 394 '---------------------------------------------------' 395 | 396 delete 397 | 398 v 399 .-------. 400 | end | 401 '-------' 403 Figure 2: Configured subscription and receiver states 405 The interaction model described within this section is mirrored in 406 the RPCs and Notifications later in the document. It should be noted 407 that these RPCs and Notifications have been designed to be extensible 408 and allow subscriptions into targets other than event streams. 409 [I-D.ietf-netconf-yang-push] provides an example of such an 410 extension. 412 3. Data Model Trees 414 module: ietf-subscribed-notifications 415 +--ro streams 416 | +--ro stream* [name] 417 | +--ro name stream 418 | +--ro description string 419 | +--ro replay-support? empty {replay}? 420 | +--ro replay-log-creation-time? yang:date-and-time {replay}? 421 | +--ro replay-log-aged-time? yang:date-and-time {replay}? 422 +--rw filters 423 | +--rw stream-filter* [identifier] 424 | +--rw identifier filter-id 425 | +--rw (filter-spec)? 426 | +--:(subtree-filter) 427 | | +--rw subtree-filter? {subtree}? 428 | +--:(xpath-filter) 429 | +--rw xpath-filter? yang:xpath1.0 {xpath}? 430 +--rw subscription-config {configured}? 431 | +--rw subscription* [identifier] 432 | +--rw identifier subscription-id 433 | +--rw encoding encoding 434 | +--rw (target) 435 | | +--:(stream) 436 | | +--rw (stream-filter)? 437 | | | +--:(by-reference) 438 | | | | +--rw stream-filter-ref stream-filter-ref 439 | | | +--:(within-subscription) 440 | | | +--rw (filter-spec)? 441 | | | +--:(subtree-filter) 442 | | | | +--rw subtree-filter? {subtree}? 443 | | | +--:(xpath-filter) 444 | | | +--rw xpath-filter? yang:xpath1.0 {xpath}? 445 | | +--rw stream stream 446 | | +--rw replay-start-time? yang:date-and-time {replay}? 447 | +--rw stop-time? yang:date-and-time 448 | +--rw receivers 449 | | +--rw receiver* [address port] 450 | | +--rw address inet:host 451 | | +--rw port inet:port-number 452 | | +--rw protocol transport 453 | | +--rw status? enumeration 454 | +--rw (notification-message-origin)? 455 | +--:(interface-originated) 456 | | +--rw source-interface? if:interface-ref 457 | +--:(address-originated) 458 | +--rw source-vrf? string 459 | +--rw source-address? inet:ip-address-no-zone 460 +--ro subscriptions 461 +--ro subscription* [identifier] 462 +--ro identifier subscription-id 463 +--ro configured-subscription? empty {configured}? 464 +--ro encoding encoding 465 +--ro (target) 466 | +--:(stream) 467 | +--ro (stream-filter)? 468 | | +--:(by-reference) 469 | | | +--ro stream-filter-ref stream-filter-ref 470 | | +--:(within-subscription) 471 | | +--ro (filter-spec)? 472 | | +--:(subtree-filter) 473 | | | +--ro subtree-filter? {subtree}? 474 | | +--:(xpath-filter) 475 | | +--ro xpath-filter? yang:xpath1.0 {xpath}? 476 | +--ro stream stream 477 | +--ro replay-start-time? yang:date-and-time {replay}? 478 +--ro stop-time? yang:date-and-time 479 +--ro (notification-message-origin)? 480 | +--:(interface-originated) 481 | | +--ro source-interface? if:interface-ref 482 | +--:(address-originated) 483 | +--ro source-vrf? string 484 | +--ro source-address? inet:ip-address-no-zone 485 +--ro receivers 486 +--ro receiver* [address port] 487 +--ro address inet:host 488 +--ro port inet:port-number 489 +--ro protocol transport 490 +--ro pushed-notifications? yang:counter64 491 +--ro excluded-notifications? yang:counter64 492 +--ro status enumeration 494 rpcs: 495 +---x establish-subscription 496 | +---w input 497 | | +---w encoding? encoding 498 | | +---w (target) 499 | | | +--:(stream) 500 | | | +---w (stream-filter)? 501 | | | | +--:(by-reference) 502 | | | | | +---w stream-filter-ref stream-filter-ref 503 | | | | +--:(within-subscription) 504 | | | | +---w (filter-spec)? 505 | | | | +--:(subtree-filter) 506 | | | | | +---w subtree-filter? {subtree}? 507 | | | | +--:(xpath-filter) 508 | | | | +---w xpath-filter? yang:xpath1.0 {xpath}? 509 | | | +---w stream stream 510 | | | +---w replay-start-time? yang:date-and-time {replay}? 511 | | +---w stop-time? yang:date-and-time 512 | +--ro output 513 | +--ro subscription-result subscription-result 514 | +--ro (result)? 515 | +--:(no-success) 516 | | +--ro filter-failure? string 517 | | +--ro replay-start-time-hint? yang:date-and-time 518 | +--:(success) 519 | +--ro identifier subscription-id 520 +---x modify-subscription 521 | +---w input 522 | | +---w identifier? subscription-id 523 | | +---w (target) 524 | | | +--:(stream) 525 | | | +---w (stream-filter)? 526 | | | +--:(by-reference) 527 | | | | +---w stream-filter-ref stream-filter-ref 528 | | | +--:(within-subscription) 529 | | | +---w (filter-spec)? 530 | | | +--:(subtree-filter) 531 | | | | +---w subtree-filter? {subtree}? 532 | | | +--:(xpath-filter) 533 | | | +---w xpath-filter? yang:xpath1.0 {xpath}? 534 | | +---w stop-time? yang:date-and-time 535 | +--ro output 536 | +--ro subscription-result subscription-result 537 | +--ro (result)? 538 | +--:(no-success) 539 | +--ro filter-failure? string 540 +---x delete-subscription 541 | +---w input 542 | | +---w identifier subscription-id 543 | +--ro output 544 | +--ro subscription-result subscription-result 545 +---x kill-subscription 546 +---w input 547 | +---w identifier subscription-id 548 +--ro output 549 +--ro subscription-result subscription-result 551 notifications: 552 +---n replay-completed {replay}? 553 | +--ro identifier subscription-id 554 +---n subscription-completed 555 | +--ro identifier subscription-id 556 +---n subscription-started {configured}? 557 | +--ro identifier subscription-id 558 | +--ro encoding encoding 559 | +--ro (target) 560 | | +--:(stream) 561 | | +--ro (stream-filter)? 562 | | | +--:(by-reference) 563 | | | | +--ro stream-filter-ref stream-filter-ref 564 | | | +--:(within-subscription) 565 | | | +--ro (filter-spec)? 566 | | | +--:(subtree-filter) 567 | | | | +--ro subtree-filter? {subtree}? 568 | | | +--:(xpath-filter) 569 | | | +--ro xpath-filter? yang:xpath1.0 {xpath}? 570 | | +--ro stream stream 571 | | +--ro replay-start-time? yang:date-and-time {replay}? 572 | +--ro stop-time? yang:date-and-time 573 +---n subscription-resumed 574 | +--ro identifier subscription-id 575 +---n subscription-modified {configured}? 576 | +--ro identifier subscription-id 577 | +--ro encoding encoding 578 | +--ro (target) 579 | | +--:(stream) 580 | | +--ro (stream-filter)? 581 | | | +--:(by-reference) 582 | | | | +--ro stream-filter-ref stream-filter-ref 583 | | | +--:(within-subscription) 584 | | | +--ro (filter-spec)? 585 | | | +--:(subtree-filter) 586 | | | | +--ro subtree-filter? {subtree}? 587 | | | +--:(xpath-filter) 588 | | | +--ro xpath-filter? yang:xpath1.0 {xpath}? 589 | | +--ro stream stream 590 | | +--ro replay-start-time? yang:date-and-time {replay}? 591 | +--ro stop-time? yang:date-and-time 592 +---n subscription-terminated 593 | +--ro identifier subscription-id 594 | +--ro error-id subscription-errors 595 | +--ro filter-failure? string 596 +---n subscription-suspended 597 +--ro identifier subscription-id 598 +--ro error-id subscription-errors 599 +--ro filter-failure? string 601 The top-level decompositions of data model are as follows: 603 o "Streams" contains a list of event streams that are supported by 604 the publisher and against which subscription is allowed. 606 o "Filters" contains a configurable list of filters that can be 607 applied to a subscription. This allows users to reference an 608 existing filter definition as an alternative to defining a filter 609 inline for each subscription. 611 o "Subscription-config" contains the configuration of configured 612 subscriptions. The parameters of each configured subscription are 613 a superset of the parameters of a dynamic subscription and use the 614 same groupings. In addition, the configured subscriptions MUST 615 also specify intended receivers and MAY specify the push source 616 from which to send the stream of notification messages. 618 o "Subscriptions" contains a list of all subscriptions on a 619 publisher, both configured and dynamic. It can be used to 620 retrieve information about the subscriptions which a publisher is 621 serving. 623 The data model also contains a number of YANG Notifications that 624 allow a publisher to signal information about a subscription. 625 Finally, the data model contains a number of RPC definitions that are 626 used to manage dynamic subscriptions. 628 4. Dynamic Subscriptions 630 Dynamic subscriptions are managed via RPC, and are made against 631 targets located within the publisher. These RPCs have been designed 632 extensibly so that they may be augmented for targets beyond event 633 streams. 635 4.1. Establishing a Subscription 637 The "establish-subscription" operation allows a subscriber to request 638 the creation of a subscription via RPC. Multiple establish 639 subscription RPC requests can be made within the same transport 640 session. 642 The input parameters of the operation are: 644 o A stream name which identifies the continuous feed of events 645 against which the subscription is applied. 647 o A filter which may reduce the set of event records pushed. 649 o The desired encoding for the notification message. 651 o An optional stop time for the subscription. 653 o An optional start time which indicates that this subscription is 654 requesting a replay of previously generated information from the 655 event stream. 657 If the publisher cannot satisfy the "establish-subscription" request, 658 it sends a negative "subscription-result" element. If the subscriber 659 has no authorization to establish the subscription, the 660 "subscription-result" indicates an authorization error. Optionally, 661 the "subscription-result" MAY include one or more hints on 662 alternative input parameters and value which would have resulted in 663 an accepted subscription. 665 Subscription requests MUST fail if a filter with invalid syntax is 666 provided or if a non-existent stream is referenced. 668 4.1.1. Replay Subscription 670 Replay provides the ability to establish an subscription which is 671 also capable of passing along recently generated event records. In 672 other words, as the subscription initializes itself, it sends any 673 previously generated content from within target event stream which 674 meet the filter and timeframe criteria. These historical event 675 records would then be followed by event records generated after the 676 subscription has been established. All event records will be 677 delivered in the order generated. Replay is only viable for dynamic 678 subscriptions. Replay is an optional feature. Replay is dependent 679 on an event stream supporting some form of logging, although it puts 680 no restrictions on the size or form of the log, or where it resides 681 within the device. 683 The inclusion of a replay-start-time within an "establish- 684 subscription" RPC indicates a replay request. If the "replay-start- 685 time" contains a value that is earlier than content stored within the 686 publisher's replay buffer, then the subscription MUST be rejected, 687 and the leaf "replay-start-time-hint" MUST be set in the reply. 689 An end time MAY be specified using the optional stop-time parameter, 690 which only in the case of replay MAY also be earlier than the current 691 time. If no stop-time is present, notification messages will 692 continue to be sent until the subscription is terminated. The 693 publisher MUST NOT accept a replay-start-time for a future time. 695 If the replay-start-time is later than any information stored in the 696 replay buffer, then the publisher MUST send a "replay-completed" 697 notification immediately after the "subscription-started" 698 notification. 700 Not all streams will support replay. Those that do MUST include they 701 do via the "replay-support" object. In addition, a event stream that 702 does support replay is not expected to have an unlimited supply of 703 saved notifications available to accommodate any given replay 704 request. Subscribers MAY do a get on "replay-log-creation-time" and 705 "replay-log-aged-time" to assess the availability of replay. The 706 actual size of the replay log at any given time is a publisher 707 specific matter. Control parameters for this aspect of the feature 708 are outside the scope of this document. 710 4.2. Modifying a Subscription 712 The "modify-subscription" operation permits changing the terms of an 713 existing dynamic subscription previously established on that 714 transport session. Subscriptions created by configuration operations 715 cannot be modified via this RPC. Dynamic subscriptions can be 716 modified one or multiple times. If the publisher accepts the 717 requested modifications, it replies that this change has been made, 718 then immediately starts sending event records based on the new terms. 719 If the publisher rejects the request, the subscription remains as 720 prior to the request. That is, the request has no impact whatsoever. 721 The contents of a such a rejected modification MAY include one or 722 more hints on alternative input parameters and value which would have 723 resulted in a successfully modified subscription. 725 Dynamic subscriptions established via RPC can only be modified via 726 RPC using the same transport session used to establish that 727 subscription. 729 4.3. Deleting a Subscription 731 The "delete-subscription" operation permits canceling an existing 732 subscription previously established on that transport session. If 733 the publisher accepts the request, and the publisher has indicated 734 this successful reply has been sent, the publisher MUST NOT send any 735 more notification messages for this subscription. If the publisher 736 rejects the request, all subscriptions remain as prior to the 737 request. That is, the request has no impact whatsoever. 739 Subscriptions established via RPC can only be deleted via RPC using 740 the same transport session used for subscription establishment. 741 Configured subscriptions cannot be deleted using RPCs. 743 4.4. Killing a Subscription 745 The "kill-subscription" operation permits an operator to end a 746 dynamic subscription which is not associated the transport session 747 used for the RPC. This operation MUST be secured so that only 748 connections with sufficiently privileged access rights are able to 749 invoke this RPC. A publisher MUST terminate any dynamic subscription 750 identified by RPC request. An operator may find subscription 751 identifiers which may be used with "kill-subscription" by searching 752 for the ip address of a receiver within the yang tree. 754 Configured subscriptions cannot be killed using this RPC. Instead, 755 configured subscriptions are deleted as part of regular configuration 756 operations. Publishers MUST reject any RPC attempt to kill a 757 configured subscription. 759 5. Configured Subscriptions 761 A configured subscription is a subscription installed via a 762 configuration interface. Such a subscription MAY push notification 763 messages to more than one receiver. The publisher does not provide 764 information about receivers are provided no information about other 765 receivers. Supporting configured subscriptions is optional and 766 advertised using the "configured" feature. 768 Configured subscriptions persist across reboots, and persist even 769 when transport is unavailable. 771 Configured subscriptions can be modified by any configuration client 772 with write permissions for the configuration of the subscription. 773 Subscriptions can be modified or terminated via the configuration 774 interface at any point of their lifetime. 776 In addition to subscription parameters that apply to dynamic 777 subscriptions, the following additional parameters apply to 778 configured subscriptions: 780 o One or more receiver IP addresses (and corresponding ports) 781 intended as the destination for notification messages for each 782 subscription. In addition, the transport for each destination MAY 783 be defined. 785 o Optional parameters to identify an egress interface, a host IP 786 address, a VRF, or an IP address plus VRF out of which 787 notification messages should be pushed from the publisher. Where 788 any of this info is not explicitly included, or where just the VRF 789 is provided, notification messages MUST egress the publisher's 790 default interface towards that receiver. 792 5.1. Creating a Configured Subscription 794 Configured subscriptions are established using configuration 795 operations against the top-level subtree subscription-config. There 796 are two key differences between RPCs and configuration operations for 797 subscription creation. Firstly, configuration operations install a 798 subscription without question, while RPCs are designed to the support 799 negotiation and rejection of requests. Secondly, while RPCs mandate 800 that the subscriber establishing the subscription is the only 801 receiver of the notification messages, configuration operations 802 permit specifying receivers independent of any tracked subscriber. 803 Because there is no explicit association with an existing transport 804 session, configuration operations require additional parameters 805 beyond those of dynamic subscriptions to indicate receivers, and 806 possibly whether the notification messages need to come from a 807 specific egress interface on the publisher. 809 After a subscription is successfully created, the publisher 810 immediately sends a subscription-started state change notification to 811 each receiver. It is quite possible that upon configuration, reboot, 812 or even steady-state operations, a transport session may not be 813 currently available to the receiver. In this case, when there is 814 something to transport for an active subscription, transport specific 815 call-home operations will be used to establish the connection. When 816 transport connectivity is available, as successful receipt of the 817 subscription start change notification by a particular receiver 818 indicated, notification messages may then be pushed. 820 To see an example at subscription creation using configuration 821 operations over NETCONF, see Appendix A of 822 [I-D.draft-ietf-netconf-netconf-event-notifications]. 824 Note that is possible to configure replay on a configured 825 subscription. This is to allows a configured subscription to exist 826 on a system so that event records generated during boot can be 827 buffered and pushed as soon as the transport session is established. 829 5.2. Modifying a Configured Subscription 831 Configured subscriptions can be modified using configuration 832 operations against the top-level subtree subscription-config. 834 Immediately after a subscription is successfully modified, the 835 publisher sends to the existing receivers a state change notification 836 stating the subscription has been modified (i.e., subscription- 837 modified). 839 If the modification involved adding and/or removing receivers, those 840 modified receivers are sent state change notifications, indicating 841 they have been added (i.e, subscription-started to a specific 842 receiver) or removed (i.e., subscription-terminated to a specific 843 receiver.) 845 5.3. Deleting a Configured Subscription 847 Subscriptions can be deleted using configuration operations against 848 the top-level subtree subscription-config. For example, in RESTCONF: 850 DELETE /subscription-config/subscription=1922 HTTP/1.1 851 Host: example.com 853 HTTP/1.1 204 No Content 854 Date: Sun, 24 Jul 2016 11:23:40 GMT 855 Server: example-server 857 Figure 3: Deleting a configured subscription 859 Immediately after a subscription is successfully deleted, the 860 publisher sends to all receivers of that subscription a state change 861 notification stating the subscription has been terminated (i.e., 862 subscription-terminated). 864 6. Deleting a Configured Subscription 866 Configured subscriptions can be deleted using configuration 867 operations against the top-level subtree subscription-config. 869 Immediately after a subscription is successfully deleted, the 870 publisher sends to the existing receivers a state change notification 871 stating the subscription has been terminated (i.e., subscription- 872 terminated). 874 7. Asynchronous Subscribed Event Delivery 876 Once a subscription has been set up, the publisher streams subscribed 877 event records via notification messages per the terms of the 878 subscription. For dynamic subscriptions set up via RPC operations, 879 notification messages are sent over the session used to establish the 880 subscription. For configured subscriptions, notification messages 881 are sent over the specified connections. 883 A notification message is sent to a receiver when something of 884 interest occurs which is able to traverse all specified filtering and 885 access control criteria. 887 This notification message MUST be encoded as one-way notification 888 element of [RFC5277], Section 4. The following example within 889 [RFC7950] section 7.16.3 is an example of a compliant message: 891 893 2007-09-01T10:00:00Z 894 895 so-1/2/3.0 896 up 897 down 898 899 901 Figure 4: subscribed notification message 903 This [RFC5277] section 4 one-way operation has the drawback of not 904 including useful header information such as a subscription 905 identifier. When using this mechanism, it is left up to 906 implementations or augmentations to this document to determine which 907 event records belong to which subscription. 909 These drawbacks, along with other useful common headers and the 910 ability to bundle multiple event records together is being explored 911 within [I.D.draft-ietf-netconf-notification-messages]. When the 912 notification-messages is supported, this document will be updated to 913 indicate support. 915 8. Subscription State Notifications 917 In addition to subscribed event records, a publisher will send 918 subscription state notifications to indicate to receivers that an 919 event related to the subscription management has occurred. 921 Subscription state notifications are unlike other notifications which 922 might be found in the event stream. They cannot be filtered out, and 923 they are delivered only to directly impacted receiver(s) of a 924 subscription. The definition of subscription state notifications is 925 distinct from other notification messages by making use of a YANG 926 extension tagging them as subscription state notification. 928 Subscription state notifications include indications that a replay of 929 event records has been completed, that a subscription is done because 930 an end time has been reached, and that a subscription has started, 931 been modified, been terminated, or been suspended. They are 932 described in the following subsections. 934 8.1. subscription-started 936 This indicates that a configured subscription has started and data 937 updates are beginning to be sent. This state change notification 938 includes the parameters of the subscription, except for the 939 receiver(s) addressing information and origin information indicating 940 where notification messages will egress the publisher. Note that for 941 RPC-based subscriptions, no "subscription-started" notifications are 942 sent. 944 8.2. subscription-modified 946 This indicates that a configured subscription has been modified 947 successfully. This state change notification includes the parameters 948 of the subscription, except for the receiver(s) addressing 949 information and origin information indicating where notification 950 messages will egress the publisher. Note that for RPC-based 951 subscriptions, no "subscription-modified" state change notifications 952 are sent. 954 8.3. subscription-terminated 956 This indicates that a subscription has been terminated by the 957 publisher. The state change notification includes the reason for the 958 termination. The publisher MAY decide to terminate a subscription 959 when it is running out of resources for serving it, an internal error 960 occurs, etc. Publisher-driven terminations are notified to all 961 receivers. Northbound systems MAY also terminate configured 962 subscriptions using configuration operations. 964 Subscribers can terminate via RPC subscriptions established via a 965 delete-subscription RPC. In such cases, no subscription-terminated 966 state change notifications are sent. However if a kill-subscription 967 RPC is sent, or some other event other than reaching the 968 subscription's stop time results in the end of a subscription, then 969 there MUST be this state change notification that the subscription 970 has been ended. 972 8.4. subscription-suspended 974 This indicates that a publisher has suspended a subscription. The 975 state change notification includes the reason for the suspension. A 976 possible reason is the lack of resources to serve it. No further 977 subscribed event records will be sent until the subscription resumes. 978 Suspensions are notified to the subscriber (in the case of dynamic 979 subscriptions) and all receivers (in the case of configured 980 subscriptions). 982 8.5. subscription-resumed 984 This indicates that a previously suspended subscription has been 985 resumed. Subscribed event records generated after the generation of 986 this state change notification will be sent. These state change 987 notifications go to the subscriber (in the case of dynamic 988 subscriptions) and all receivers (in the case of configured 989 subscriptions). 991 8.6. subscription-completed 993 This indicates that a subscription, which includes a stop time, has 994 successfully finished passing event records upon the reaching of that 995 stop time. 997 8.7. replay-completed 999 This indicates that all of the event records prior to the current 1000 time have been sent. This includes new event records generated since 1001 the start of the subscription. This notification MUST NOT be sent 1002 for any other reason. 1004 If subscription contains no stop time, or has a stop time which has 1005 not been reached, then after the replay-completed notification has 1006 been sent event records will be sent in sequence as they arise 1007 naturally within the system. 1009 9. Administrative Functions 1011 9.1. Subscription Monitoring 1013 Container "subscriptions" in the YANG module below contains the state 1014 of all known subscriptions. This includes subscriptions that were 1015 established (and have not yet been deleted) using RPCs, as well as 1016 subscriptions that have been configured as part of configuration. 1017 Using the "get" operation with NETCONF, or subscribing to this 1018 information via [I-D.ietf-netconf-yang-push] allows the status of 1019 subscriptions to be monitored. 1021 Each subscription is represented as a list element. The associated 1022 information includes an identifier for the subscription, receiver 1023 counter information, the status of the subscription, as well as the 1024 various subscription parameters that are in effect. The subscription 1025 status indicates the subscription's state with each receiver (e.g., 1026 is currently active or suspended). Leaf "configured-subscription" 1027 indicates whether the subscription came into being via configuration 1028 or via RPC. 1030 Subscriptions that were established by RPC are removed from the list 1031 once they expire (reaching stop-time) or when they are terminated. 1032 Subscriptions that were established by configuration need to be 1033 deleted from the configuration by a configuration editing operation 1034 even if the stop time has been passed. 1036 9.2. Advertisement 1038 Publishers supporting this document MUST indicate support the yang 1039 model "ietf-subscribed-notifications" within the YANG library of the 1040 publisher. In addition support for optional features: encode-xml, 1041 encode-json, configured, and replay MUST also be indicated if 1042 supported. 1044 If a publisher supports this specification but not subscriptions via 1045 [RFC5277], the publisher MUST NOT advertise 1046 "urn:ietf:params:netconf:capability:notification:1.0". Even without 1047 this advertisement however, the publisher MUST support the one-way 1048 notification element of [RFC5277] Section 4. 1050 9.3. Event Stream Discovery 1052 A publisher maintains a list of available event streams as 1053 operational data. This list contains both standardized and vendor- 1054 specific event streams. A client can retrieve this list like any 1055 other YANG-defined data. 1057 10. Data Model 1059 file "ietf-subscribed-notifications.yang" 1060 module ietf-subscribed-notifications { 1061 yang-version 1.1; 1062 namespace 1063 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"; 1065 prefix sn; 1067 import ietf-yang-types { 1068 prefix yang; 1069 } 1070 import ietf-inet-types { 1071 prefix inet; 1072 } 1073 import ietf-interfaces { 1074 prefix if; 1075 } 1077 organization "IETF"; 1078 contact 1079 "WG Web: 1080 WG List: 1082 Editor: Alexander Clemm 1083 1085 Editor: Eric Voit 1086 1088 Editor: Alberto Gonzalez Prieto 1089 1091 Editor: Einar Nilsen-Nygaard 1092 1094 Editor: Ambika Prasad Tripathy 1095 "; 1097 description 1098 "Contains a YANG specification for subscribing to event records 1099 and receiving matching content within notification messages."; 1101 revision 2017-10-27 { 1102 description 1103 "Initial version"; 1104 reference 1105 "draft-ietf-netconf-subscribed-notifications-06"; 1106 } 1108 /* 1109 * FEATURES 1110 */ 1112 feature encode-json { 1113 description 1114 "This feature indicates that JSON encoding of notification 1115 messages is supported."; 1116 } 1118 feature encode-xml { 1119 description 1120 "This feature indicates that XML encoding of notification 1121 messages is supported."; 1122 } 1124 feature configured { 1125 description 1126 "This feature indicates that configuration of subscription is 1127 supported."; 1128 } 1130 feature replay { 1131 description 1132 "This feature indicates that historical event record replay is 1133 supported. With replay, it is possible for past event records to 1134 be streamed in chronological order."; 1135 } 1137 feature xpath { 1138 description 1139 "This feature indicates support for xpath filtering."; 1140 reference "http://www.w3.org/TR/1999/REC-xpath-19991116"; 1141 } 1143 feature subtree { 1144 description 1145 "This feature indicates support for YANG subtree filtering."; 1146 reference "RFC 6241, Section 6."; 1147 } 1149 /* 1150 * EXTENSIONS 1151 */ 1153 extension subscription-state-notif { 1154 description 1155 "This statement applies only to notifications. It indicates that 1156 the notification is a subscription state notification. Therefore 1157 it does not participate in a regular event stream and does not 1158 need to be specifically subscribed to in order to be received. 1159 This statement can only occur as a substatement to the YANG 1160 'notification' statement."; 1161 } 1163 /* 1164 * IDENTITIES 1165 */ 1167 /* Identities for subscription results */ 1168 identity subscription-result { 1169 description 1170 "Base identity for RPC responses and State Change Notifications 1171 providing information on the creation, modification, deletion of 1172 subscriptions."; 1173 } 1175 identity ok { 1176 base subscription-result; 1177 description 1178 "OK - RPC was successful and was performed as requested."; 1179 } 1180 identity error { 1181 base subscription-result; 1182 description 1183 "Problem with subscription. Base identity for error return 1184 codes for RPCs and State Change Notifications."; 1185 } 1187 /* Identities for subscription errors */ 1189 identity suspension-timeout { 1190 base error; 1191 description 1192 "Termination of previously suspended subscription. The publisher 1193 has eliminated the subscription as it exceeded a time limit for 1194 suspension."; 1195 } 1197 identity stream-unavailable { 1198 base error; 1199 description 1200 "Stream does not exist or is not available to the receiver."; 1201 } 1203 identity encoding-unavailable { 1204 base error; 1205 description 1206 "Encoding not supported"; 1207 } 1209 identity replay-unsupported { 1210 base error; 1211 description 1212 "Replay cannot be performed for this subscription. The publisher 1213 does not provide the requested historic information via replay."; 1214 } 1216 identity history-unavailable { 1217 base error; 1218 description 1219 "Replay request too far into the past. The publisher does store 1220 historic information for all parts of requested subscription, but 1221 not back to the requested timestamp."; 1222 } 1224 identity filter-unavailable { 1225 base error; 1226 description 1227 "Referenced filter does not exist"; 1229 } 1231 identity filter-type-unsupported { 1232 base error; 1233 description 1234 "Publisher does not support filters constructed using this 1235 filtering technology syntax."; 1236 } 1238 identity filter-unsupported { 1239 base error; 1240 description 1241 "Failure can be from a syntax error, or a syntax too complex to be 1242 processed by the platform. The supplemental info should include 1243 the invalid part of the filter."; 1244 } 1246 identity namespace-unavailable { 1247 base error; 1248 description 1249 "Referenced namespace doesn't exist or is unavailable 1250 to the receiver."; 1251 } 1253 identity no-such-subscription { 1254 base error; 1255 description 1256 "Referenced subscription doesn't exist. This may be as a result of 1257 a non-existent subscription ID, an ID which belongs to another 1258 subscriber, or an ID for acceptable subscription which has been 1259 statically configured."; 1260 } 1262 identity insufficient-resources { 1263 base error; 1264 description 1265 "The publisher has insufficient resources to support the 1266 subscription as requested by an RPC."; 1267 } 1269 identity unsupportable-volume { 1270 base error; 1271 description 1272 "The publisher cannot support the volume of information intended 1273 to be sent for an existing subscription."; 1274 } 1276 identity error-no-such-option { 1277 base error; 1278 description 1279 "A requested parameter setting is not supported."; 1280 } 1282 /* Identities for encodings */ 1283 identity encodings { 1284 description 1285 "Base identity to represent data encodings"; 1286 } 1288 identity encode-xml { 1289 base encodings; 1290 if-feature "encode-xml"; 1291 description 1292 "Encode data using XML"; 1293 } 1295 identity encode-json { 1296 base encodings; 1297 if-feature "encode-json"; 1298 description 1299 "Encode data using JSON"; 1300 } 1302 /* Identities for transports */ 1303 identity transport { 1304 description 1305 "An identity that represents a the underlying mechanism for 1306 passing notification messages."; 1307 } 1309 identity netconf { 1310 base transport; 1311 description 1312 "Netconf is used a transport for notification messages and state 1313 change notifications."; 1314 reference "draft-ietf-netconf-netconf-event-notifications"; 1315 } 1317 identity http2 { 1318 base transport; 1319 description 1320 "HTTP2 is used a transport for notification messages and state 1321 change notifications."; 1322 reference "draft-ietf-netconf-restconf-notif-03, Sections 3.1.1" + 1323 "3.1.3"; 1324 } 1325 identity http1.1 { 1326 base transport; 1327 description 1328 "HTTP1.1 is used a transport for notification messages and state 1329 change notifications."; 1330 reference "draft-ietf-netconf-restconf-notif-03, Section 3.1.2"; 1331 } 1332 /* 1333 * TYPEDEFs 1334 */ 1336 typedef subscription-id { 1337 type uint32; 1338 description 1339 "A type for subscription identifiers."; 1340 } 1342 typedef filter-id { 1343 type string; 1344 description 1345 "A type to identify filters which can be associated with a 1346 subscription."; 1347 } 1349 typedef subscription-result { 1350 type identityref { 1351 base subscription-result; 1352 } 1353 description 1354 "The result of a subscription operation"; 1355 } 1357 typedef subscription-errors { 1358 type identityref { 1359 base error; 1360 } 1361 description 1362 "The reason for the failure of an RPC request or the sending 1363 of a subscription suspension or termination state change 1364 notification"; 1365 } 1367 typedef encoding { 1368 type identityref { 1369 base encodings; 1370 } 1371 description 1372 "Specifies a data encoding, e.g. for a data subscription."; 1374 } 1376 typedef transport { 1377 type identityref { 1378 base transport; 1379 } 1380 description 1381 "Specifies protocol used to send notification messages to a 1382 receiver."; 1383 } 1385 typedef stream { 1386 type string; 1387 description 1388 "Specifies a system-provided datastream."; 1389 } 1391 typedef stream-filter-ref { 1392 type leafref { 1393 path "/sn:filters/sn:stream-filter/sn:identifier"; 1394 } 1395 description 1396 "This type is used to reference a stream filter."; 1397 } 1399 /* 1400 * GROUPINGS 1401 */ 1403 grouping stream-filter-elements { 1404 description 1405 "This grouping defines the base for filters applied to event 1406 streams."; 1407 choice filter-spec { 1408 description 1409 "The content filter specification for this request."; 1410 anydata subtree-filter { 1411 if-feature "subtree"; 1412 description 1413 "Event stream evaluation criteria encoded in a syntax of a 1414 supported type of an RFC 6241, Section 6 filter. The subtree 1415 filter is applied to the representation of individual, 1416 delineated event records as contained within the event 1417 stream. For example, if the notification message contains an 1418 instance of a notification defined in YANG, then the top- 1419 level element is the name of the YANG notification. If the 1420 stream filter matches an event record from the stream, the 1421 event record should be included in a notification message 1422 to the receiver(s)."; 1423 } 1424 leaf xpath-filter { 1425 if-feature "xpath"; 1426 type yang:xpath1.0; 1427 description 1428 "Event stream evaluation criteria encoded in a syntax of xpath 1429 1.0 and applied against an event stream. The result of 1430 applying XPath expression is converted to a boolean value 1431 using the standard XPath 1.0 rules. If the boolean value is 1432 'true', the stream filter matches an event record within the 1433 stream, and the notification message should be sent to the 1434 receiver(s)."; 1435 } 1436 } 1437 } 1439 grouping subscription-policy-modifiable { 1440 description 1441 "This grouping describes all objects which may be changed 1442 in a subscription via an RPC."; 1443 choice target { 1444 mandatory true; 1445 description 1446 "Identifies the source of information against which a 1447 subscription is being applied, as well as specifics on the 1448 subset of information desired from that source. This choice 1449 exists so that additional filter types can be added via 1450 augmentation."; 1451 case stream { 1452 choice stream-filter { 1453 description 1454 "An event stream filter can be applied to a subscription. 1455 That filter will come either referenced from a global list, 1456 or be provided within the subscription itself."; 1457 case by-reference { 1458 description 1459 "Apply a filter that has been configured separately."; 1460 leaf stream-filter-ref { 1461 type stream-filter-ref; 1462 mandatory true; 1463 description 1464 "References an existing stream-filter which is to 1465 be applied to stream for the subscription."; 1466 } 1467 } 1468 case within-subscription { 1469 description 1470 "Local definition allows a filter to have the same 1471 lifecycle as the subscription."; 1472 uses stream-filter-elements; 1473 } 1474 } 1475 } 1476 } 1477 leaf stop-time { 1478 type yang:date-and-time; 1479 description 1480 "Identifies a time after which notification messages for a 1481 subscription should not be sent. If stop-time is not present, 1482 the notification messages will continue until the subscription 1483 is terminated. If replay-start-time exists, stop-time must be 1484 for a subsequent time. If replay-start-time doesn't exist, 1485 stop-time must be for a future time."; 1486 } 1487 } 1489 grouping subscription-policy { 1490 description 1491 "This grouping describes information concerning a subscription."; 1492 leaf encoding { 1493 type encoding; 1494 mandatory true; 1495 description 1496 "The type of encoding for the subscribed data."; 1497 } 1498 uses subscription-policy-modifiable { 1499 augment target/stream { 1500 description 1501 "Adds additional objects which must be set just by RPC."; 1502 leaf stream { 1503 type stream; 1504 mandatory true; 1505 description 1506 "Indicates a stream of event records against which to apply 1507 a stream filter."; 1508 } 1509 leaf replay-start-time { 1510 if-feature "replay"; 1511 type yang:date-and-time; 1512 description 1513 "Used to trigger the replay feature and indicate that the 1514 replay should start at the time specified. If 1515 replay-start-time is not present, this is not a replay 1516 subscription and event record push should start immediately. 1517 It is never valid to specify start times that are later than 1518 or equal to the current time."; 1519 } 1520 } 1521 } 1522 } 1524 grouping notification-origin-info { 1525 description 1526 "Defines the sender source from which notification messages for a 1527 configured subscription are sent."; 1528 choice notification-message-origin { 1529 description 1530 "Identifies the egress interface on the Publisher from which 1531 notification messages are to be sent."; 1532 case interface-originated { 1533 description 1534 "When the push source is out of an interface on the 1535 Publisher established via static configuration."; 1536 leaf source-interface { 1537 type if:interface-ref; 1538 description 1539 "References the interface for notification messages."; 1540 } 1541 } 1542 case address-originated { 1543 description 1544 "When the push source is out of an IP address on the 1545 Publisher established via static configuration."; 1546 leaf source-vrf { 1547 type string; 1548 description 1549 "Network instance name for the VRF. This could also have 1550 been a leafref to draft-ietf-rtgwg-ni-model, but that model 1551 is not complete, and might not be implemented on a box."; 1552 } 1553 leaf source-address { 1554 type inet:ip-address-no-zone; 1555 description 1556 "The source address for the notification messages. If a 1557 source VRF exists, but this object doesn't, a publisher's 1558 default address for that VRF must be used."; 1559 } 1560 } 1561 } 1562 } 1564 grouping receiver-info { 1565 description 1566 "Defines where and how to get notification messages for a 1567 configured subscriptions to one or more targeted recipient. This 1568 includes specifying the destination addressing as well as a 1569 transport protocol acceptable to the receiver."; 1570 container receivers { 1571 description 1572 "Set of receivers in a subscription."; 1573 list receiver { 1574 key "address port"; 1575 min-elements 1; 1576 description 1577 "A single host or multipoint address intended as a target 1578 for the notification messages of a subscription."; 1579 leaf address { 1580 type inet:host; 1581 description 1582 "Specifies the address for the traffic to reach a remote 1583 host. One of the following must be specified: an ipv4 1584 address, an ipv6 address, or a host name."; 1585 } 1586 leaf port { 1587 type inet:port-number; 1588 description 1589 "This leaf specifies the port number to use for messages 1590 destined for a receiver."; 1591 } 1592 leaf protocol { 1593 type transport; 1594 mandatory true; 1595 description 1596 "This leaf specifies the transport protocol used 1597 to deliver messages destined for the receiver. Each 1598 protocol may use the address and port information 1599 differently as applicable."; 1600 } 1601 } 1602 } 1603 } 1605 grouping error-identifier { 1606 description 1607 "A code passed back within an RPC response to describe why the RFC 1608 has failed, or within a state change notification to describe why 1609 the change has occurred."; 1610 leaf error-id { 1611 type subscription-errors; 1612 mandatory true; 1613 description 1614 "Identifies the subscription error condition."; 1615 } 1616 } 1618 grouping hints { 1619 description 1620 "Objects passed back within an RPC response to describe why the 1621 RFC has failed, or within a state change notification to 1622 describe why the change has occurred."; 1623 leaf filter-failure { 1624 type string; 1625 description 1626 "Information describing where and/or why a provided filter was 1627 unsupportable for a subscription."; 1628 } 1629 } 1631 grouping subscription-response-with-hints { 1632 description 1633 "Defines the output for the establish-subscription and 1634 modify-subscription RPCs."; 1635 leaf subscription-result { 1636 type subscription-result; 1637 mandatory true; 1638 description 1639 "Indicates whether subscription is operational, or if a problem 1640 was encountered."; 1641 } 1642 choice result { 1643 description 1644 "Depending on the subscription result, different data is 1645 returned."; 1646 case no-success { 1647 description 1648 "This case applies when a subscription request was not 1649 successful and no subscription was created (or modified) as a 1650 result. In this case, information MAY be returned that 1651 indicates suggested parameter settings that would have a 1652 high likelihood of succeeding in a subsequent establish- 1653 subscription or modify-subscription request."; 1654 uses hints; 1655 } 1656 } 1657 } 1659 /* 1660 * RPCs 1661 */ 1663 rpc establish-subscription { 1664 description 1665 "This RPC allows a subscriber to create (and possibly negotiate) 1666 a subscription on its own behalf. If successful, the 1667 subscription remains in effect for the duration of the 1668 subscriber's association with the publisher, or until the 1669 subscription is terminated. In case an error (as indicated by 1670 subscription-result) is returned, the subscription is not 1671 created. In that case, the RPC reply MAY include suggested 1672 parameter settings that would have a higher likelihood of 1673 succeeding in a subsequent establish-subscription request."; 1674 input { 1675 uses subscription-policy { 1676 refine "encoding" { 1677 mandatory false; 1678 description 1679 "The type of encoding for the subscribed data. If not 1680 included as part of the RPC, the encoding MUST be set by the 1681 publisher to be the encoding used by this RPC."; 1682 } 1683 } 1684 } 1685 output { 1686 uses subscription-response-with-hints { 1687 augment "result" { 1688 description 1689 "Allows information to be passed back as part of a 1690 successful subscription establishment."; 1691 case success { 1692 description 1693 "This case is used when the subscription request was 1694 successful."; 1695 leaf identifier { 1696 type subscription-id; 1697 mandatory true; 1698 description 1699 "Identifier used for this subscription."; 1700 } 1701 } 1702 } 1703 augment "result/no-success" { 1704 description 1705 "Contains establish RPC specific objects which can be 1706 returned as hints for future attempts."; 1707 leaf replay-start-time-hint { 1708 type yang:date-and-time; 1709 description 1710 "If a replay has been requested, but the requested replay 1711 time cannot be honored, this may provide a hint at an 1712 alternate time which may be supportable."; 1713 } 1714 } 1715 } 1716 } 1717 } 1719 rpc modify-subscription { 1720 description 1721 "This RPC allows a subscriber to modify a subscription that was 1722 previously created using establish-subscription. If successful, 1723 the changed subscription remains in effect for the duration of 1724 the subscriber's association with the publisher, or until the 1725 subscription is again modified or terminated. In case an error 1726 is returned (as indicated by subscription-result), the 1727 subscription is not modified and the original subscription 1728 parameters remain in effect. In that case, the rpc error 1729 response MAY include suggested parameter hints that would have 1730 a high likelihood of succeeding in a subsequent 1731 modify-subscription request."; 1732 input { 1733 leaf identifier { 1734 type subscription-id; 1735 description 1736 "Identifier to use for this subscription."; 1737 } 1738 uses subscription-policy-modifiable; 1739 } 1740 output { 1741 uses subscription-response-with-hints; 1742 } 1743 } 1745 rpc delete-subscription { 1746 description 1747 "This RPC allows a subscriber to delete a subscription that 1748 was previously created from by that same subscriber using the 1749 establish-subscription RPC."; 1750 input { 1751 leaf identifier { 1752 type subscription-id; 1753 mandatory true; 1754 description 1755 "Identifier of the subscription that is to be deleted. 1756 Only subscriptions that were created using 1757 establish-subscription can be deleted via this RPC."; 1758 } 1760 } 1761 output { 1762 leaf subscription-result { 1763 type subscription-result; 1764 mandatory true; 1765 description 1766 "Indicates whether subscription has been deleted, or if a 1767 problem was encountered."; 1768 } 1769 } 1770 } 1772 rpc kill-subscription { 1773 description 1774 "This RPC allows an operator to delete a dynamic subscription 1775 without restrictions on the originating subscriber or underlying 1776 transport session."; 1777 input { 1778 leaf identifier { 1779 type subscription-id; 1780 mandatory true; 1781 description 1782 "Identifier of the subscription that is to be deleted. Only 1783 subscriptions that were created using establish-subscription 1784 can be deleted via this RPC."; 1785 } 1786 } 1787 output { 1788 leaf subscription-result { 1789 type subscription-result; 1790 mandatory true; 1791 description 1792 "Indicates whether subscription has been killed, or if a 1793 problem was encountered."; 1794 } 1795 } 1796 } 1798 /* 1799 * NOTIFICATIONS 1800 */ 1802 notification replay-completed { 1803 sn:subscription-state-notif; 1804 if-feature "replay"; 1805 description 1806 "This notification is sent to indicate that all of the replay 1807 notifications have been sent. It must not be sent for any other 1809 reason."; 1810 leaf identifier { 1811 type subscription-id; 1812 mandatory true; 1813 description 1814 "This references the affected subscription."; 1815 } 1816 } 1818 notification subscription-completed { 1819 sn:subscription-state-notif; 1820 description 1821 "This notification is sent to indicate that a subscription has 1822 finished passing event records."; 1823 leaf identifier { 1824 type subscription-id; 1825 mandatory true; 1826 description 1827 "This references the gracefully completed subscription."; 1828 } 1829 } 1831 notification subscription-started { 1832 sn:subscription-state-notif; 1833 if-feature "configured"; 1834 description 1835 "This notification indicates that a subscription has started and 1836 notifications are beginning to be sent. This notification shall 1837 only be sent to receivers of a subscription; it does not 1838 constitute a general-purpose notification."; 1839 leaf identifier { 1840 type subscription-id; 1841 mandatory true; 1842 description 1843 "This references the affected subscription."; 1844 } 1845 uses subscription-policy { 1846 refine "target/stream/replay-start-time" { 1847 description 1848 "Indicates the time that a replay using for the streaming of 1849 buffered event records. This will be populated with the most 1850 recent of the following: replay-log-creation-time, 1851 replay-log-aged-time, replay-start-time, or the most recent 1852 publisher boot time."; 1853 } 1854 } 1855 } 1856 notification subscription-resumed { 1857 sn:subscription-state-notif; 1858 description 1859 "This notification indicates that a subscription that had 1860 previously been suspended has resumed. Notifications will once 1861 again be sent."; 1862 leaf identifier { 1863 type subscription-id; 1864 mandatory true; 1865 description 1866 "This references the affected subscription."; 1867 } 1868 } 1870 notification subscription-modified { 1871 sn:subscription-state-notif; 1872 if-feature "configured"; 1873 description 1874 "This notification indicates that a subscription has been 1875 modified. Notification messages sent from this point on will 1876 conform to the modified terms of the subscription. For 1877 completeness, this state change notification includes both 1878 modified and non-modified aspects of a subscription."; 1879 leaf identifier { 1880 type subscription-id; 1881 mandatory true; 1882 description 1883 "This references the affected subscription."; 1884 } 1885 uses subscription-policy; 1886 } 1888 notification subscription-terminated { 1889 sn:subscription-state-notif; 1890 description 1891 "This notification indicates that a subscription has been 1892 terminated."; 1893 leaf identifier { 1894 type subscription-id; 1895 mandatory true; 1896 description 1897 "This references the affected subscription."; 1898 } 1899 uses error-identifier; 1900 uses hints; 1901 } 1903 notification subscription-suspended { 1904 sn:subscription-state-notif; 1905 description 1906 "This notification indicates that a suspension of the 1907 subscription by the publisher has occurred. No further 1908 notifications will be sent until the subscription resumes. 1909 This notification shall only be sent to receivers of a 1910 subscription; it does not constitute a general-purpose 1911 notification."; 1912 leaf identifier { 1913 type subscription-id; 1914 mandatory true; 1915 description 1916 "This references the affected subscription."; 1917 } 1918 uses error-identifier; 1919 uses hints; 1920 } 1922 /* 1923 * DATA NODES 1924 */ 1926 container streams { 1927 config false; 1928 description 1929 "This container contains information on the built-in streams 1930 provided by the publisher."; 1931 list stream { 1932 key "name"; 1933 description 1934 "Identifies the built-in streams that are supported by the 1935 publisher."; 1936 leaf name { 1937 type stream; 1938 description 1939 "A handle for a sequential set of event records, each of which 1940 is characterized by its own domain and semantics."; 1941 } 1942 leaf description { 1943 type string; 1944 mandatory true; 1945 description 1946 "A description of the event stream, including such information 1947 as the type of event records that are available within this 1948 stream."; 1949 } 1950 leaf replay-support { 1951 if-feature "replay"; 1952 type empty; 1953 description 1954 "Indicates that event record replay is available on this 1955 stream."; 1956 } 1957 leaf replay-log-creation-time { 1958 if-feature "replay"; 1959 type yang:date-and-time; 1960 description 1961 "The timestamp of the creation of the log used to support the 1962 replay function on this stream. Note that this might be 1963 earlier then the earliest available information contained in 1964 the log. This object is updated if the log resets for some 1965 reason. This object MUST be present if replay is supported."; 1966 } 1967 leaf replay-log-aged-time { 1968 if-feature "replay"; 1969 type yang:date-and-time; 1970 description 1971 "The timestamp of the last event record aged out of the log. 1972 This object MUST be present if replay is supported and any 1973 event record have been aged out of the log."; 1974 } 1975 } 1976 } 1978 container filters { 1979 description 1980 "This container contains a list of configurable filters 1981 that can be applied to subscriptions. This facilitates 1982 the reuse of complex filters once defined."; 1983 list stream-filter { 1984 key "identifier"; 1985 description 1986 "A list of pre-positioned filters that can be applied to 1987 subscriptions."; 1988 leaf identifier { 1989 type filter-id; 1990 description 1991 "An identifier to differentiate between filters."; 1992 } 1993 uses stream-filter-elements; 1994 } 1995 } 1997 container subscription-config { 1998 if-feature "configured"; 1999 description 2000 "Contains the list of subscriptions that are configured, 2001 as opposed to established via RPC or other means."; 2002 list subscription { 2003 key "identifier"; 2004 description 2005 "The identity and specific parameters of a subscription."; 2006 leaf identifier { 2007 type subscription-id; 2008 description 2009 "Identifier to use for this subscription."; 2010 } 2011 uses subscription-policy; 2012 uses receiver-info { 2013 augment receivers/receiver { 2014 description 2015 "include operational data for receivers."; 2016 leaf status { 2017 type enumeration { 2018 enum connecting { 2019 value 5; 2020 description 2021 "A subscription has been configured, and a 2022 subscription-started state change notification should 2023 be sent as quickly as possible."; 2024 } 2025 enum suspended { 2026 value 3; 2027 description 2028 "The status is suspended, meaning that the publisher is 2029 currently will not provide notification messages for 2030 the subscription until some status change."; 2031 } 2032 } 2033 default "connecting"; 2034 description 2035 "Allows state initialization of a particular receiver."; 2036 } 2037 } 2038 } 2039 uses notification-origin-info; 2040 } 2041 } 2042 container subscriptions { 2043 config false; 2044 description 2045 "Contains the list of currently active subscriptions, i.e. 2046 subscriptions that are currently in effect, used for subscription 2047 management and monitoring purposes. This includes subscriptions 2048 that have been setup via RPC primitives as well as subscriptions 2049 that have been established via configuration."; 2050 list subscription { 2051 key "identifier"; 2052 description 2053 "The identity and specific parameterst of a subscription. 2054 Subscriptions within this list can be created using a control 2055 channel or RPC, or be established through configuration."; 2056 leaf identifier { 2057 type subscription-id; 2058 description 2059 "Identifier of a subscription; unique within a publisher"; 2060 } 2061 leaf configured-subscription { 2062 if-feature "configured"; 2063 type empty; 2064 description 2065 "The presence of this leaf indicates that the subscription 2066 originated from configuration, not through a control channel 2067 or RPC."; 2068 } 2069 uses subscription-policy; 2070 uses notification-origin-info { 2071 if-feature "configured"; 2072 } 2073 uses receiver-info { 2074 augment receivers/receiver { 2075 description 2076 "include operational data for receivers."; 2077 leaf pushed-notifications { 2078 type yang:counter64; 2079 description 2080 "Operational data which provides the number of update 2081 notification messages pushed to a receiver."; 2082 } 2083 leaf excluded-notifications { 2084 type yang:counter64; 2085 description 2086 "Operational data which provides the number of event 2087 records from a stream explicitly removed via filtering so 2088 that they are not sent to a receiver."; 2089 } 2090 leaf status { 2091 type enumeration { 2092 enum active { 2093 value 1; 2094 description 2095 "Connection is active and healthy."; 2097 } 2098 enum concluded { 2099 value 2; 2100 description 2101 "A subscription is inactive as it has hit a stop time, 2102 but not yet been removed."; 2103 } 2104 enum suspended { 2105 value 3; 2106 description 2107 "The status is suspended, meaning that the publisher 2108 is currently unable to provide notification messages 2109 for the subscription."; 2110 } 2111 enum in-error { 2112 value 4; 2113 description 2114 "The status is in error or degraded, meaning that a 2115 subscription is unsupportable with its current 2116 parameters."; 2117 } 2118 enum connecting { 2119 value 5; 2120 description 2121 "A subscription has been configured, but a 2122 subscription-started state change notification has not 2123 yet been succesfully received."; 2124 } 2125 } 2126 mandatory true; 2127 description 2128 "Specifies the status of a subscription from the 2129 perspective of a particular receiver. With this info it 2130 is possible to determine whether a subscriber is currently 2131 generating notification messages intended for that 2132 receiver."; 2133 } 2134 } 2135 } 2136 } 2137 } 2138 } 2139 2140 11. Considerations 2142 11.1. Implementation Considerations 2144 For a deployment including both configured and dynamic subscriptions, 2145 split subscription identifiers into static and dynamic halves. That 2146 way it is unlikely there will be collisions if the configured 2147 subscriptions attempt to set a subscription-id which might have 2148 already been dynamically allocated. The lower half SHOULD be used 2149 for subscriptions which will have subscription identifiers provided 2150 from outside the publisher, and upper half for subscription 2151 identifiers assigned by the publisher. 2153 No state change notification or nor subscribed event records within 2154 notification messages may be sent before the transport layer, 2155 including any requried capabilities exchange, has been established. 2157 An implementation may choose to transition between active and 2158 suspended subscription states more frequently than required by this 2159 specification. However if a subscription is unable to marshal all 2160 intended updates into a transmittable message in multiple successive 2161 intervals, the subscription SHOULD be suspended with the reason 2162 "unsupportable-volume". 2164 For configured subscriptions, operations are against the set of 2165 receivers using the subscription identifier as a handle for that set. 2166 But for streaming up dates, state change notifications are local to a 2167 receiver. In this specification it is the case that receivers get no 2168 information from the publisher about the existence of other 2169 receivers. But if an operator wants to let the receivers correlate 2170 results, it is useful to use the subscription identifier handle 2171 across the receivers to allow that correlation. 2173 11.2. Security Considerations 2175 For dynamic subscriptions the publisher MUST authenticate and 2176 authorize all RPC requests. 2178 Subscriptions could overload a publisher's CPU. For this reason, the 2179 publisher MUST have the ability to decline a dynamic subscription 2180 request, and provide the appropriate RPC error response to a 2181 subscriber should the proposed subscription overly deplete the 2182 publisher's resources. 2184 A publisher needs to be able to suspend an existing dynamic or 2185 configured subscription based on capacity constraints. When this 2186 occurs, the subscription status MUST be updated accordingly and the 2187 receivers notified with subscription state notifications. 2189 If a malicious or buggy subscriber sends an unexpectedly large number 2190 of RPCs, the result might be an excessive use of system resources. 2191 In such a situation, subscription interactions MAY be terminated by 2192 terminating the transport session. 2194 For both configured and dynamic subscriptions the publisher MUST 2195 authenticate and authorize a receiver via some transport level 2196 mechanism before sending any updates. 2198 A secure transport is highly recommended and the publisher MUST 2199 ensure that the user has sufficient authorization to perform the 2200 function they are requesting against the specific subset of content 2201 involved. 2203 A publisher MUST NOT include any content in a notification message 2204 for which the user has not been authorized. 2206 With configured subscriptions, one or more publishers could be used 2207 to overwhelm a receiver. No notification messages SHOULD be sent to 2208 any receiver which doesn't even support subscriptions. Subscribers 2209 that do not want notification messages need only terminate or refuse 2210 any transport sessions from the publisher. 2212 The NETCONF Authorization Control Model [RFC6536bis] SHOULD be used 2213 to control and restrict authorization of subscription configuration. 2214 This control models permits specifying per-user permissions to 2215 receive event records from specific streams. 2217 Where NACM is available, the NACM "very-secure" tag MUST be placed on 2218 the "kill-subscription" RPC so that only administrators have access 2219 to use this. 2221 One subscription id can be used for two or more receivers of the same 2222 configured subscription. But due to the possibility of different 2223 access control permissions per receiver, it SHOULD NOT be assumed 2224 that each receiver is getting identical updates. 2226 12. Acknowledgments 2228 For their valuable comments, discussions, and feedback, we wish to 2229 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen, 2230 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan 2231 Hares, Michael Scharf, and Guangying Zheng. 2233 13. References 2235 13.1. Normative References 2237 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2238 Requirement Levels", BCP 14, RFC 2119, 2239 DOI 10.17487/RFC2119, March 1997, 2240 . 2242 [RFC6536bis] 2243 Bierman, A. and M. Bjorklund, "Network Configuration 2244 Protocol (NETCONF) Access Control Model", draft-ietf- 2245 netconf-rfc6536bis-01 (work in progress), September 2017. 2247 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2248 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2249 . 2251 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 2252 Version 1.0", November 1999, 2253 . 2255 13.2. Informative References 2257 [I-D.draft-ietf-netconf-netconf-event-notifications] 2258 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 2259 Nilsen-Nygaard, E., Tripathy, A., Chisholm, S., and H. 2260 Trevino, "NETCONF support for event notifications", 2261 October 2016, . 2264 [I-D.draft-ietf-netconf-restconf-notif] 2265 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen- 2266 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and 2267 HTTP transport for event notifications", August 2016, 2268 . 2271 [I-D.ietf-netconf-yang-push] 2272 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 2273 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 2274 Lengyel, "YANG Datastore Subscription", October 2017, 2275 . 2278 [I.D.draft-ietf-netconf-notification-messages] 2279 Voit, Eric., Clemm, Alexander., Bierman, A., and T. 2280 Jenkins, "YANG Notification Headers and Bundles", 2281 September 2017, . 2284 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2285 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 2286 . 2288 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2289 and A. Bierman, Ed., "Network Configuration Protocol 2290 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2291 . 2293 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2294 for Subscription to YANG Datastores", RFC 7923, 2295 DOI 10.17487/RFC7923, June 2016, 2296 . 2298 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2299 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2300 . 2302 Appendix A. Changes between revisions 2304 (To be removed by RFC editor prior to publication) 2306 v06 - v07 2308 o Clarification on state machine for configured susbcriptions. 2310 v05 - v06 2312 o Made changes proposed by Martin, Kent, and others on the list. 2313 Most significant of these are Stream returned to string (with the 2314 SYSLOG identity removed), intro section on 5277 relationship, an 2315 identity set moved to an enumeration, clean up of definitions/ 2316 terminology, state machine proposed for configured subscriptions 2317 with a clean-up of susbcription state options. 2319 o JSON and XML become features. Also Xpath and subtree filtering 2320 become features 2322 o Terminology updates with event records, and refinement of filters 2323 to just stream filters. 2325 o Encoding refined in establish-subscription so it takes the RPC's 2326 encoding as the default. 2328 o Namespaces in examples fixed. 2330 v04 - v05 2332 o Returned to the explicit filter subtyping of v00 2334 o stream object changed to 'name' from 'stream' 2336 o Cleaned up examples 2338 o Clarified that JSON support needs notification-messages draft. 2340 v03 - v04 2342 o Moved back to the use of RFC5277 one-way notifications and 2343 encodings. 2345 v03 - v04 2347 o Replay updated 2349 v02 - v03 2351 o RPCs and Notification support is identified by the Notification 2352 2.0 capability. 2354 o Updates to filtering identities and text 2356 o New error type for unsupportable volume of updates 2358 o Text tweaks. 2360 v01 - v02 2362 o Subscription status moved under receiver. 2364 v00 - v01 2366 o Security considerations updated 2368 o Intro rewrite, as well as scattered text changes 2370 o Added Appendix A, to help match this to related drafts in progress 2371 o Updated filtering definitions, and filter types in yang file, and 2372 moved to identities for filter types 2374 o Added Syslog as a stream 2376 o HTTP2 moved in from YANG-Push as a transport option 2378 o Replay made an optional feature for events. Won't apply to 2379 datastores 2381 o Enabled notification timestamp to have different formats. 2383 o Two error codes added. 2385 v01 5277bis - v00 subscribed notifications 2387 o Kill subscription RPC added. 2389 o Renamed from 5277bis to Subscribed Notifications. 2391 o Changed the notification capabilities version from 1.1 to 2.0. 2393 o Extracted create-subscription and other elements of RFC5277. 2395 o Error conditions added, and made specific in return codes. 2397 o Simplified yang model structure for removal of 'basic' grouping. 2399 o Added a grouping for items which cannot be statically configured. 2401 o Operational counters per receiver. 2403 o Subscription-id and filter-id renamed to identifier 2405 o Section for replay added. Replay now cannot be configured. 2407 o Control plane notification renamed to subscription state 2408 notification 2410 o Source address: Source-vrf changed to string, default address 2411 option added 2413 o In yang model: 'info' changed to 'policy' 2415 o Scattered text clarifications 2417 v00 - v01 of 5277bis 2418 o YANG Model changes. New groupings for subscription info to allow 2419 restriction of what is changeable via RPC. Removed notifications 2420 for adding and removing receivers of configured subscriptions. 2422 o Expanded/renamed definitions from event server to publisher, and 2423 client to subscriber as applicable. Updated the definitions to 2424 include and expand on RFC 5277. 2426 o Removal of redundancy with other drafts 2428 o Many other clean-ups of wording and terminology 2430 Authors' Addresses 2432 Eric Voit 2433 Cisco Systems 2435 Email: evoit@cisco.com 2437 Alexander Clemm 2438 Huawei 2440 Email: ludwig@clemm.org 2442 Alberto Gonzalez Prieto 2443 VMWare 2445 Email: agonzalezpri@vmware.com 2447 Einar Nilsen-Nygaard 2448 Cisco Systems 2450 Email: einarnn@cisco.com 2452 Ambika Prasad Tripathy 2453 Cisco Systems 2455 Email: ambtripa@cisco.com