idnits 2.17.1 draft-ietf-netconf-subscribed-notifications-25.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1342 has weird spacing: '... reason ide...' == Line 1377 has weird spacing: '... reason ide...' == Line 1393 has weird spacing: '...--ro id sub...' == Line 1408 has weird spacing: '...--ro id sub...' == Line 1429 has weird spacing: '...--ro id sub...' == (3 more instances...) == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 01, 2019) is 1793 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 4 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: November 2, 2019 Huawei 6 A. Gonzalez Prieto 7 Microsoft 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 May 01, 2019 13 Subscription to YANG Event Notifications 14 draft-ietf-netconf-subscribed-notifications-25 16 Abstract 18 This document defines a YANG data model and associated mechanisms 19 enabling subscriber-specific subscriptions to a publisher's event 20 streams. Applying these elements allows a subscriber to request for 21 and receive a continuous, custom feed of publisher generated 22 information. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on November 2, 2019. 41 Copyright Notice 43 Copyright (c) 2019 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 This document may contain material from IETF Documents or IETF 57 Contributions published or made publicly available before November 58 10, 2008. The person(s) controlling the copyright in some of this 59 material may not have granted the IETF Trust the right to allow 60 modifications of such material outside the IETF Standards Process. 61 Without obtaining an adequate license from the person(s) controlling 62 the copyright in such materials, this document may not be modified 63 outside the IETF Standards Process, and derivative works of it may 64 not be created outside the IETF Standards Process, except to format 65 it for publication as an RFC or to translate it into languages other 66 than English. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 71 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 72 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 73 1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 5 74 1.4. Relationship to RFC 5277 . . . . . . . . . . . . . . . . 6 75 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 7 76 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 7 77 2.2. Event Stream Filters . . . . . . . . . . . . . . . . . . 8 78 2.3. QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 79 2.4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 9 80 2.5. Configured Subscriptions . . . . . . . . . . . . . . . . 17 81 2.6. Event Record Delivery . . . . . . . . . . . . . . . . . . 25 82 2.7. Subscription state change notifications . . . . . . . . . 26 83 2.8. Subscription Monitoring . . . . . . . . . . . . . . . . . 31 84 2.9. Advertisement . . . . . . . . . . . . . . . . . . . . . . 32 85 3. YANG Data Model Trees . . . . . . . . . . . . . . . . . . . . 32 86 3.1. Event Streams Container . . . . . . . . . . . . . . . . . 32 87 3.2. Filters Container . . . . . . . . . . . . . . . . . . . . 33 88 3.3. Subscriptions Container . . . . . . . . . . . . . . . . . 33 89 4. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 35 90 5. Considerations . . . . . . . . . . . . . . . . . . . . . . . 62 91 5.1. IANA Considerations . . . . . . . . . . . . . . . . . . . 62 92 5.2. Implementation Considerations . . . . . . . . . . . . . . 63 93 5.3. Transport Requirements . . . . . . . . . . . . . . . . . 64 94 5.4. Security Considerations . . . . . . . . . . . . . . . . . 64 95 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 68 96 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 97 7.1. Normative References . . . . . . . . . . . . . . . . . . 68 98 7.2. Informative References . . . . . . . . . . . . . . . . . 70 99 Appendix A. Example Configured Transport Augmentation . . . . . 71 100 Appendix B. Changes between revisions . . . . . . . . . . . . . 73 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 79 103 1. Introduction 105 This document defines a YANG data model and associated mechanisms 106 enabling subscriber-specific subscriptions to a publisher's event 107 streams. Effectively this enables a 'subscribe then publish' 108 capability where the customized information needs and access 109 permissions of each target receiver are understood by the publisher 110 before subscribed event records are marshaled and pushed. The 111 receiver then gets a continuous, custom feed of publisher generated 112 information. 114 While the functionality defined in this document is transport- 115 agnostic, transports like NETCONF [RFC6241] or RESTCONF [RFC8040] can 116 be used to configure or dynamically signal subscriptions, and there 117 are bindings defined for subscribed event record delivery for NETCONF 118 within [I-D.draft-ietf-netconf-netconf-event-notifications], and for 119 RESTCONF within [I-D.draft-ietf-netconf-restconf-notif]. 121 The YANG model in this document conforms to the Network Management 122 Datastore Architecture defined in [RFC8342]. 124 1.1. Motivation 126 Various limitations in [RFC5277] are discussed in [RFC7923]. 127 Resolving these issues is the primary motivation for this work. Key 128 capabilities supported by this document include: 130 o multiple subscriptions on a single transport session 132 o support for dynamic and configured subscriptions 134 o modification of an existing subscription in progress 136 o per-subscription operational counters 138 o negotiation of subscription parameters (through the use of hints 139 returned as part of declined subscription requests) 141 o subscription state change notifications (e.g., publisher driven 142 suspension, parameter modification) 144 o independence from transport 146 1.2. Terminology 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 150 "OPTIONAL" in this document are to be interpreted as described in BCP 151 14 [RFC2119] [RFC8174] when, and only when, they appear in all 152 capitals, as shown here. 154 Client: defined in [RFC8342]. 156 Configuration: defined in [RFC8342]. 158 Configuration datastore: defined in [RFC8342]. 160 Configured subscription: A subscription installed via configuration 161 into a configuration datastore. 163 Dynamic subscription: A subscription created dynamically by a 164 subscriber via a remote procedure call. 166 Event: An occurrence of something that may be of interest. Examples 167 include a configuration change, a fault, a change in status, crossing 168 a threshold, or an external input to the system. 170 Event occurrence time: a timestamp matching the time an originating 171 process identified as when an event happened. 173 Event record: A set of information detailing an event. 175 Event stream: A continuous, chronologically ordered set of events 176 aggregated under some context. 178 Event stream filter: Evaluation criteria which may be applied against 179 event records within an event stream. Event records pass the filter 180 when specified criteria are met. 182 Notification message: Information intended for a receiver indicating 183 that one or more events have occurred. 185 Publisher: An entity responsible for streaming notification messages 186 per the terms of a subscription. 188 Receiver: A target to which a publisher pushes subscribed event 189 records. For dynamic subscriptions, the receiver and subscriber are 190 the same entity. 192 Subscriber: A client able to request and negotiate a contract for the 193 generation and push of event records from a publisher. For dynamic 194 subscriptions, the receiver and subscriber are the same entity. 196 Subscription: A contract with a publisher, stipulating which 197 information one or more receivers wish to have pushed from the 198 publisher without the need for further solicitation. 200 All YANG tree diagrams used in this document follow the notation 201 defined in [RFC8340]. 203 1.3. Solution Overview 205 This document describes a transport agnostic mechanism for 206 subscribing to and receiving content from an event stream within a 207 publisher. This mechanism is through the use of a subscription. 209 Two types of subscriptions are supported: 211 1. Dynamic subscriptions, where a subscriber initiates a 212 subscription negotiation with a publisher via a Remote Procedure 213 Call (RPC). If the publisher is able to serve this request, it 214 accepts it, and then starts pushing notification messages back to 215 the subscriber. If the publisher is not able to serve it as 216 requested, then an error response is returned. This response MAY 217 include hints at subscription parameters that, had they been 218 present, may have enabled the dynamic subscription request to be 219 accepted. 221 2. Configured subscriptions, which allow the management of 222 subscriptions via a configuration so that a publisher can send 223 notification messages to a receiver. Support for configured 224 subscriptions is optional, with its availability advertised via a 225 YANG feature. 227 Additional characteristics differentiating configured from dynamic 228 subscriptions include: 230 o The lifetime of a dynamic subscription is bound by the transport 231 session used to establish it. For connection-oriented stateful 232 transports like NETCONF, the loss of the transport session will 233 result in the immediate termination of any associated dynamic 234 subscriptions. For connectionless or stateless transports like 235 HTTP, a lack of receipt acknowledgment of a sequential set of 236 notification messages and/or keep-alives can be used to trigger a 237 termination of a dynamic subscription. Contrast this to the 238 lifetime of a configured subscription. This lifetime is driven by 239 relevant configuration being present within the publisher's 240 applied configuration. Being tied to configuration operations 241 implies configured subscriptions can be configured to persist 242 across reboots, and implies a configured subscription can persist 243 even when its publisher is fully disconnected from any network. 245 o Configured subscriptions can be modified by any configuration 246 client with write permission on the configuration of the 247 subscription. Dynamic subscriptions can only be modified via an 248 RPC request made by the original subscriber, or a change to 249 configuration data referenced by the subscription. 251 Note that there is no mixing-and-matching of dynamic and configured 252 operations on a single subscription. Specifically, a configured 253 subscription cannot be modified or deleted using RPCs defined in this 254 document. Similarly, a dynamic subscription cannot be directly 255 modified or deleted by configuration operations. It is however 256 possible to perform a configuration operation which indirectly 257 impacts a dynamic subscription. By changing value of a pre- 258 configured filter referenced by an existing dynamic subscription, the 259 selected event records passed to a receiver might change. 261 Also note that transport specific transport specifications based on 262 this specification MUST detail the lifecycle of dynamic 263 subscriptions, as well as the lifecycle of configured subscriptions 264 (if supported). 266 A publisher MAY terminate a dynamic subscription at any time. 267 Similarly, it MAY decide to temporarily suspend the sending of 268 notification messages for any dynamic subscription, or for one or 269 more receivers of a configured subscription. Such termination or 270 suspension is driven by internal considerations of the publisher. 272 1.4. Relationship to RFC 5277 274 This document is intended to provide a superset of the subscription 275 capabilities initially defined within [RFC5277]. Especially when 276 extending an existing [RFC5277] implementation, it is important to 277 understand what has been reused and what has been replaced. Key 278 relationships between these two documents include: 280 o this document defines a transport independent capability, 281 [RFC5277] is specific to NETCONF. 283 o the data model in this document is used instead of the data model 284 in Section 3.4 of [RFC5277] for the new operations. 286 o the RPC operations in this draft replace the operation "create- 287 subscription" defined in [RFC5277], section 4. 289 o the message of [RFC5277], Section 4 is used. 291 o the included contents of the "NETCONF" event stream are identical 292 between this document and [RFC5277]. 294 o a publisher MAY implement both the Notification Management Schema 295 and RPCs defined in [RFC5277] and this new document concurrently. 297 o unlike [RFC5277], this document enables a single transport session 298 to intermix notification messages and RPCs for different 299 subscriptions. 301 o A subscription "stop-time" can be specified as part of a 302 notification replay. This supports an analogous capability to the 303 stopTime parameter of [RFC5277]. However in this specification, a 304 "stop-time" parameter can also be applied without replay. 306 2. Solution 308 Per the overview provided in Section 1.3, this section details the 309 overall context, state machines, and subsystems which may be 310 assembled to allow the subscription of events from a publisher. 312 2.1. Event Streams 314 An event stream is a named entity on a publisher which exposes a 315 continuously updating set of YANG defined event records. An event 316 record is an instantiation of a "notification" YANG statement. If 317 the "notification" is defined as a child to a data node, the 318 instantiation includes the hierarchy of nodes that identifies the 319 data node in the datastore (see Section 7.16.2 of [RFC7950]). Each 320 event stream is available for subscription. It is out of the scope 321 of this document to identify a) how event streams are defined (other 322 than the NETCONF stream), b) how event records are defined/generated, 323 and c) how event records are assigned to event streams. 325 There is only one reserved event stream name within this document: 326 "NETCONF". The "NETCONF" event stream contains all NETCONF event 327 record information supported by the publisher, except where an event 328 record has explicitly been excluded from the stream. Beyond the 329 "NETCONF" stream, implementations MAY define additional event 330 streams. 332 As YANG defined event records are created by a system, they may be 333 assigned to one or more streams. The event record is distributed to 334 a subscription's receiver(s) where: (1) a subscription includes the 335 identified stream, and (2) subscription filtering does not exclude 336 the event record from that receiver. 338 Access control permissions may be used to silently exclude event 339 records from within an event stream for which the receiver has no 340 read access. As an example of how this might be accomplished, see 341 [RFC8341] section 3.4.6. Note that per Section 2.7 of this document, 342 subscription state change notifications are never filtered out. 344 If no access control permissions are in place for event records on an 345 event stream, then a receiver MUST be allowed access to all the event 346 records. If subscriber permissions change during the lifecycle of a 347 subscription and event stream access is no longer permitted, then the 348 subscription MUST be terminated. 350 Event records MUST NOT be delivered to a receiver in a different 351 order than they were placed onto an event stream. 353 2.2. Event Stream Filters 355 This document defines an extensible filtering mechanism. The filter 356 itself is a boolean test which is placed on the content of an event 357 record. A 'false' filtering result causes the event record to be 358 excluded from delivery to a receiver. A filter never results in 359 information being stripped from within an event record prior to that 360 event record being encapsulated within a notification message. The 361 two optional event stream filtering syntaxes supported are [XPATH] 362 and subtree [RFC6241]. 364 If no event stream filter is provided within a subscription, all 365 event records on an event stream are to be sent. 367 2.3. QoS 369 This document provides for several Quality of Service (QoS) 370 parameters. These parameters indicate the treatment of a 371 subscription relative to other traffic between publisher and 372 receiver. Included are: 374 o A "dscp" marking to differentiate prioritization of notification 375 messages during network transit. 377 o A "weighting" so that bandwidth proportional to this weighting can 378 be allocated to this subscription relative to other subscriptions. 380 o a "dependency" upon another subscription. 382 If the publisher supports the "dscp" feature, then a subscription 383 with a "dscp" leaf MUST result in a corresponding [RFC2474] DSCP 384 marking being placed within the IP header of any resulting 385 notification messages and subscription state change notifications. 387 Where TCP is used, a publisher which supports the "dscp" feature 388 SHOULD ensure that a subscription's notification messages are 389 returned within a single TCP transport session where all traffic 390 shares the subscription's "dscp" leaf value. Where this cannot be 391 guaranteed, any "establish subscription" RPC request SHOULD be 392 rejected with a "dscp-unavailable" error. 394 For the "weighting" parameter, when concurrently dequeuing 395 notification messages from multiple subscriptions to a receiver, the 396 publisher MUST allocate bandwidth to each subscription proportionally 397 to the weights assigned to those subscriptions. "Weighting" is an 398 optional capability of the publisher; support for it is identified 399 via the "qos" feature. 401 If a subscription has the "dependency" parameter set, then any 402 buffered notification messages containing event records selected by 403 the parent subscription MUST be dequeued prior to the notification 404 messages of the dependent subscription. If notification messages 405 have dependencies on each other, the notification message queued the 406 longest MUST go first. If a "dependency" included within an RPC 407 references a subscription which does not exist or is no longer 408 accessible to that subscriber, that "dependency" MUST be silently 409 removed. "Dependency" is an optional capability of the publisher; 410 support for it is identified via the "qos" feature. 412 2.4. Dynamic Subscriptions 414 Dynamic subscriptions are managed via protocol operations (in the 415 form of [RFC7950], Section 7.14 RPCs) made against targets located 416 within the publisher. These RPCs have been designed extensibly so 417 that they may be augmented for subscription targets beyond event 418 streams. For examples of such augmentations, see the RPC 419 augmentations within [I-D.ietf-netconf-yang-push]'s YANG model. 421 2.4.1. Dynamic Subscription State Model 423 Below is the publisher's state machine for a dynamic subscription. 424 Each state is shown in its own box. It is important to note that 425 such a subscription doesn't exist at the publisher until an 426 "establish-subscription" RPC is accepted. The mere request by a 427 subscriber to establish a subscription is insufficient for that 428 subscription to be externally visible. Start and end states are 429 depicted to reflect subscription creation and deletion events. 431 ......... 432 : start : 433 :.......: 434 | 435 establish-subscription 436 | 437 | .-------modify-subscription--------. 438 v v | 439 .-----------. .-----------. 440 .--------. | receiver |--insufficient CPU, b/w-->| receiver | 441 modify- '| active | | suspended | 442 subscription | |<----CPU, b/w sufficient--| | 443 ---------->'-----------' '-----------' 444 | | 445 delete/kill-subscription delete/kill- 446 | subscription 447 v | 448 ......... | 449 : end :<---------------------------------' 450 :.......: 452 Figure 1: Publisher's state for a dynamic subscription 454 Of interest in this state machine are the following: 456 o Successful "establish-subscription" or "modify-subscription" RPCs 457 put the subscription into the active state. 459 o Failed "modify-subscription" RPCs will leave the subscription in 460 its previous state, with no visible change to any streaming 461 updates. 463 o A "delete-subscription" or "kill-subscription" RPC will end the 464 subscription, as will the reaching of a "stop-time". 466 o A publisher may choose to suspend a subscription when there is 467 insufficient CPU or bandwidth available to service the 468 subscription. This is notified to a subscriber with a 469 "subscription-suspended" subscription state change notification. 471 o A suspended subscription may be modified by the subscriber (for 472 example in an attempt to use fewer resources). Successful 473 modification returns the subscription to the active state. 475 o Even without a "modify-subscription" request, a publisher may 476 return a subscription to the active state should the resource 477 constraints become sufficient again. This is announced to the 478 subscriber via the "subscription-resumed" subscription state 479 change notification. 481 2.4.2. Establishing a Dynamic Subscription 483 The "establish-subscription" RPC allows a subscriber to request the 484 creation of a subscription. 486 The input parameters of the operation are: 488 o A "stream" name which identifies the targeted event stream against 489 which the subscription is applied. 491 o An event stream filter which may reduce the set of event records 492 pushed. 494 o Where the transport used by the RPC supports multiple encodings, 495 an optional "encoding" for the event records pushed. If no 496 "encoding" is included, the encoding of the RPC MUST be used. 498 o An optional "stop-time" for the subscription. If no "stop-time" 499 is present, notification messages will continue to be sent until 500 the subscription is terminated. 502 o An optional "replay-start-time" for the subscription. The 503 "replay-start-time" MUST be in the past and indicates that the 504 subscription is requesting a replay of previously generated 505 information from the event stream. For more on replay, see 506 Section 2.4.2.1. Where there is no "replay-start-time", the 507 subscription starts immediately. 509 If the publisher can satisfy the "establish-subscription" request, it 510 replies with an identifier for the subscription, and then immediately 511 starts streaming notification messages. 513 Below is a tree diagram for "establish-subscription". All objects 514 contained in this tree are described within the included YANG model 515 within Section 4. 517 +---x establish-subscription 518 +---w input 519 | +---w (target) 520 | | +--:(stream) 521 | | +---w (stream-filter)? 522 | | | +--:(by-reference) 523 | | | | +---w stream-filter-name 524 | | | | stream-filter-ref 525 | | | +--:(within-subscription) 526 | | | +---w (filter-spec)? 527 | | | +--:(stream-subtree-filter) 528 | | | | +---w stream-subtree-filter? 529 | | | | {subtree}? 530 | | | +--:(stream-xpath-filter) 531 | | | +---w stream-xpath-filter? 532 | | | yang:xpath1.0 {xpath}? 533 | | +---w stream stream-ref 534 | | +---w replay-start-time? 535 | | yang:date-and-time {replay}? 536 | +---w stop-time? 537 | | yang:date-and-time 538 | +---w dscp? inet:dscp 539 | | {dscp}? 540 | +---w weighting? uint8 541 | | {qos}? 542 | +---w dependency? 543 | | subscription-id {qos}? 544 | +---w encoding? encoding 545 +--ro output 546 +--ro id subscription-id 547 +--ro replay-start-time-revision? yang:date-and-time 548 {replay}? 550 Figure 2: establish-subscription RPC tree diagram 552 A publisher MAY reject the "establish-subscription" RPC for many 553 reasons as described in Section 2.4.6. The contents of the resulting 554 RPC error response MAY include details on input parameters which if 555 considered in a subsequent "establish-subscription" RPC, may result 556 in a successful subscription establishment. Any such hints MUST be 557 transported within a yang-data "establish-subscription-stream-error- 558 info" container included within the RPC error response. 560 yang-data establish-subscription-stream-error-info 561 +--ro establish-subscription-stream-error-info 562 +--ro reason? identityref 563 +--ro filter-failure-hint? string 565 Figure 3: establish-subscription RPC yang-data tree diagram 567 2.4.2.1. Requesting a replay of event records 569 Replay provides the ability to establish a subscription which is also 570 capable of passing event records generated in the recent past. In 571 other words, as the subscription initializes itself, it sends any 572 event records within the target event stream which meet the filter 573 criteria, which have an event time which is after the "replay-start- 574 time", and which have an event time before the "stop-time" should 575 this "stop-time" exist. The end of these historical event records is 576 identified via a "replay-completed" subscription state change 577 notification. Any event records generated since the subscription 578 establishment may then follow. For a particular subscription, all 579 event records will be delivered in the order they are placed into the 580 event stream. 582 Replay is an optional feature which is dependent on an event stream 583 supporting some form of logging. This document puts no restrictions 584 on the size or form of the log, where it resides within the 585 publisher, or when event record entries in the log are purged. 587 The inclusion of a "replay-start-time" within an "establish- 588 subscription" RPC indicates a replay request. If the "replay-start- 589 time" contains a value that is earlier than what a publisher's 590 retained history supports, then if the subscription is accepted, the 591 actual publisher's revised start time MUST be set in the returned 592 "replay-start-time-revision" object. 594 A "stop-time" parameter may be included in a replay subscription. 595 For a replay subscription, the "stop-time" MAY be earlier than the 596 current time, but MUST be later than the "replay-start-time". 598 If the given "replay-start-time" is later than the time marked within 599 any event records retained within the replay buffer, then the 600 publisher MUST send a "replay-completed" notification immediately 601 after a successful establish-subscription RPC response. 603 If an event stream supports replay, the "replay-support" leaf is 604 present in the "/streams/stream" list entry for the event stream. An 605 event stream that does support replay is not expected to have an 606 unlimited supply of saved notifications available to accommodate any 607 given replay request. To assess the timeframe available for replay, 608 subscribers can read the leafs "replay-log-creation-time" and 609 "replay-log-aged-time". See Figure 18 for the YANG tree, and 610 Section 4 for the YANG model describing these elements. The actual 611 size of the replay log at any given time is a publisher specific 612 matter. Control parameters for the replay log are outside the scope 613 of this document. 615 2.4.3. Modifying a Dynamic Subscription 617 The "modify-subscription" operation permits changing the terms of an 618 existing dynamic subscription. Dynamic subscriptions can be modified 619 any number of times. Dynamic subscriptions can only be modified via 620 this RPC using a transport session connecting to the subscriber. If 621 the publisher accepts the requested modifications, it acknowledges 622 success to the subscriber, then immediately starts sending event 623 records based on the new terms. 625 Subscriptions created by configuration cannot be modified via this 626 RPC. However configuration may be used to modify objects referenced 627 by the subscription (such as a referenced filter). 629 Below is a tree diagram for "modify-subscription". All objects 630 contained in this tree are described within the included YANG model 631 within Section 4. 633 +---x modify-subscription 634 +---w input 635 +---w id 636 | subscription-id 637 +---w (target) 638 | +--:(stream) 639 | +---w (stream-filter)? 640 | +--:(by-reference) 641 | | +---w stream-filter-name 642 | | stream-filter-ref 643 | +--:(within-subscription) 644 | +---w (filter-spec)? 645 | +--:(stream-subtree-filter) 646 | | +---w stream-subtree-filter? 647 | | {subtree}? 648 | +--:(stream-xpath-filter) 649 | +---w stream-xpath-filter? 650 | yang:xpath1.0 {xpath}? 651 +---w stop-time? 652 yang:date-and-time 654 Figure 4: modify-subscription RPC tree diagram 656 If the publisher accepts the requested modifications on a currently 657 suspended subscription, the subscription will immediately be resumed 658 (i.e., the modified subscription is returned to the active state.) 659 The publisher MAY immediately suspend this newly modified 660 subscription through the "subscription-suspended" notification before 661 any event records are sent. 663 If the publisher rejects the RPC request, the subscription remains as 664 prior to the request. That is, the request has no impact whatsoever. 665 Rejection of the RPC for any reason is indicated by via RPC error as 666 described in Section 2.4.6. The contents of such a rejected RPC MAY 667 include hints on inputs which (if considered) may result in a 668 successfully modified subscription. These hints MUST be transported 669 within a yang-data "modify-subscription-stream-error-info" container 670 inserted into the RPC error response. 672 Below is a tree diagram for "modify-subscription-RPC-yang-data". All 673 objects contained in this tree are described within the included YANG 674 model within Section 4. 676 yang-data modify-subscription-stream-error-info 677 +--ro modify-subscription-stream-error-info 678 +--ro reason? identityref 679 +--ro filter-failure-hint? string 681 Figure 5: modify-subscription RPC yang-data tree diagram 683 2.4.4. Deleting a Dynamic Subscription 685 The "delete-subscription" operation permits canceling an existing 686 subscription. If the publisher accepts the request, and the 687 publisher has indicated success, the publisher MUST NOT send any more 688 notification messages for this subscription. 690 Below is a tree diagram for "delete-subscription". All objects 691 contained in this tree are described within the included YANG model 692 within Section 4. 694 +---x delete-subscription 695 +---w input 696 +---w id subscription-id 698 Figure 6: delete-subscription RPC tree diagram 700 Dynamic subscriptions can only be deleted via this RPC using a 701 transport session connecting to the subscriber. Configured 702 subscriptions cannot be deleted using RPCs. 704 2.4.5. Killing a Dynamic Subscription 706 The "kill-subscription" operation permits an operator to end a 707 dynamic subscription which is not associated with the transport 708 session used for the RPC. A publisher MUST terminate any dynamic 709 subscription identified by the "id" parameter in the RPC request, if 710 such a subscription exists. 712 Configured subscriptions cannot be killed using this RPC. Instead, 713 configured subscriptions are deleted as part of regular configuration 714 operations. Publishers MUST reject any RPC attempt to kill a 715 configured subscription. 717 Below is a tree diagram for "kill-subscription". All objects 718 contained in this tree are described within the included YANG model 719 within Section 4. 721 +---x kill-subscription 722 +---w input 723 +---w id subscription-id 725 Figure 7: kill-subscription RPC tree diagram 727 2.4.6. RPC Failures 729 Whenever an RPC is unsuccessful, the publisher returns relevant 730 information as part of the RPC error response. Transport level error 731 processing MUST be done before RPC error processing described in this 732 section. In all cases, RPC error information returned will use 733 existing transport layer RPC structures, such as those seen with 734 NETCONF in [RFC6241] Appendix A, or with RESTCONF in [RFC8040] 735 Section 7.1. These structures MUST be able to encode subscription 736 specific errors identified below and defined within this document's 737 YANG model. 739 As a result of this variety, how subscription errors are encoded 740 within an RPC error response is transport dependent. Following are 741 valid errors which can occur for each RPC: 743 establish-subscription modify-subscription 744 ---------------------- ------------------- 745 dscp-unavailable filter-unsupported 746 encoding-unsupported insufficient-resources 747 filter-unsupported no-such-subscription 748 insufficient-resources 749 replay-unsupported 751 delete-subscription kill-subscription 752 ---------------------- ---------------------- 753 no-such-subscription no-such-subscription 755 To see a NETCONF based example of an error response from above, see 756 [I-D.draft-ietf-netconf-netconf-event-notifications], Figure 10. 758 There is one final set of transport independent RPC error elements 759 included in the YANG model. These are three yang-data structures 760 which enable the publisher to provide to the receiver that error 761 information which does not fit into existing transport layer RPC 762 structures. These three yang-data structures are: 764 1. "establish-subscription-stream-error-info": This MUST be returned 765 with the leaf "reason" populated if an RPC error reason has not 766 been placed elsewhere within the transport portion of a failed 767 "establish-subscription" RPC response. This MUST be sent if 768 hints on how to overcome the RPC error are included. 770 2. "modify-subscription-stream-error-info": This MUST be returned 771 with the leaf "reason" populated if an RPC error reason has not 772 been placed elsewhere within the transport portion of a failed 773 "modify-subscription" RPC response. This MUST be sent if hints 774 on how to overcome the RPC error are included. 776 3. "delete-subscription-error-info": This MUST be returned with the 777 leaf "reason" populated if an RPC error reason has not been 778 placed elsewhere within the transport portion of a failed 779 "delete-subscription" or "kill-subscription" RPC response. 781 2.5. Configured Subscriptions 783 A configured subscription is a subscription installed via 784 configuration. Configured subscriptions may be modified by any 785 configuration client with the proper permissions. Subscriptions can 786 be modified or terminated via configuration at any point of their 787 lifetime. Multiple configured subscriptions MUST be supportable over 788 a single transport session. 790 Configured subscriptions have several characteristics distinguishing 791 them from dynamic subscriptions: 793 o persistence across publisher reboots, 795 o persistence even when transport is unavailable, and 797 o an ability to send notification messages to more than one receiver 798 (note that receivers are unaware of the existence of any other 799 receivers.) 801 On the publisher, supporting configured subscriptions is optional and 802 advertised using the "configured" feature. On a receiver of a 803 configured subscription, support for dynamic subscriptions is 804 optional. However if replaying missed event records is required for 805 a configured subscription, support for dynamic subscription is highly 806 recommended. In this case, a separate dynamic subscription can be 807 established to retransmit the missing event records. 809 In addition to the subscription parameters available to dynamic 810 subscriptions described in Section 2.4.2, the following additional 811 parameters are also available to configured subscriptions: 813 o A "transport" which identifies the transport protocol to use to 814 connect with all subscription receivers. 816 o One or more receivers, each intended as the destination for event 817 records. Note that each individual receiver is identifiable by 818 its "name". 820 o Optional parameters to identify where traffic should egress a 821 publisher: 823 * A "source-interface" which identifies the egress interface to 824 use from the publisher. Publisher support for this is optional 825 and advertised using the "interface-designation" feature. 827 * A "source-address" address, which identifies the IP address to 828 stamp on notification messages destined for the receiver. 830 * A "source-vrf" which identifies the VRF on which to reach 831 receivers. This VRF is a network instance as defined within 832 [I-D.draft-ietf-rtgwg-ni-model]. Publisher support for VRFs is 833 optional and advertised using the "supports-vrf" feature. 835 If none of the above parameters are set, notification messages 836 MUST egress the publisher's default interface. 838 A tree diagram describing these parameters is shown in Figure 20 839 within Section 3.3. All parameters are described within the YANG 840 model in Section 4. 842 2.5.1. Configured Subscription State Model 844 Below is the state machine for a configured subscription on the 845 publisher. This state machine describes the three states (valid, 846 invalid, and concluded), as well as the transitions between these 847 states. Start and end states are depicted to reflect configured 848 subscription creation and deletion events. The creation or 849 modification of a configured subscription initiates an evaluation by 850 the publisher to determine if the subscription is in valid or invalid 851 states. The publisher uses its own criteria in making this 852 determination. If in the valid state, the subscription becomes 853 operational. See (1) in the diagram below. 855 ......... 856 : start :-. 857 :.......: | 858 create .---modify-----.----------------------------------. 859 | | | | 860 V V .-------. ....... .---------. 861 .----[evaluate]--no--->|invalid|-delete->: end :<-delete-|concluded| 862 | '-------' :.....: '---------' 863 |-[evaluate]--no-(2). ^ ^ ^ 864 | ^ | | | | 865 yes | '->unsupportable delete stop-time 866 | modify (subscription- (subscription- (subscription- 867 | | terminated*) terminated*) concluded*) 868 | | | | | 869 (1) | (3) (4) (5) 870 | .---------------------------------------------------------------. 871 '-->| valid | 872 '---------------------------------------------------------------' 874 Legend: 875 dotted boxes: subscription added or removed via configuration 876 dashed boxes: states for a subscription 877 [evaluate]: decision point on whether the subscription is supportable 878 (*): resulting subscription state change notification 880 Figure 8: Publisher state model for a configured subscription 882 A subscription in the valid state may move to the invalid state in 883 one of two ways. First, it may be modified in a way which fails a 884 re-evaluation. See (2) in the diagram. Second, the publisher might 885 determine that the subscription is no longer supportable. This could 886 be for reasons of an unexpected but sustained increase in an event 887 stream's event records, degraded CPU capacity, a more complex 888 referenced filter, or other higher priority subscriptions which have 889 usurped resources. See (3) in the diagram. No matter the case, a 890 "subscription-terminated" notification is sent to any receivers in an 891 active or suspended state. A subscription in the valid state may 892 also transition to the concluded state via (5) if a configured stop 893 time has been reached. In this case, a "subscription-concluded" 894 notification is sent to any receivers in active or suspended states. 895 Finally, a subscription may be deleted by configuration (4). 897 When a subscription is in the valid state, a publisher will attempt 898 to connect with all receivers of a configured subscription and 899 deliver notification messages. Below is the state machine for each 900 receiver of a configured subscription. This receiver state machine 901 is fully contained within the state machine of the configured 902 subscription, and is only relevant when the configured subscription 903 is in the valid state. 905 .-----------------------------------------------------------------. 906 | valid | 907 | .----------. .------------. | 908 | | receiver |---timeout---------------->| receiver | | 909 | |connecting|<----------------reset--(c)|disconnected| | 910 | | |<-transport '------------' | 911 | '----------' loss,reset------------------------------. | 912 | (a) | | | 913 | subscription- (b) (b) | 914 | started* .--------. .---------. | 915 | '----->| |(d)-insufficient CPU,------->| | | 916 | |receiver| buffer overflow |receiver | | 917 | subscription-| active | |suspended| | 918 | modified* | |<----CPU, b/w sufficient,-(e)| | | 919 | '---->'--------' subscription-modified* '---------' | 920 '-----------------------------------------------------------------' 922 Legend: 923 dashed boxes which include the word 'receiver' show the possible 924 states for an individual receiver of a valid configured subscription. 925 * indicates a subscription state change notification 927 Figure 9: Receiver state for a configured subscription on a Publisher 929 When a configured subscription first moves to the valid state, the 930 "state" leaf of each receiver is initialized to the connecting state. 931 If transport connectivity is not available to any receiver and there 932 are any notification messages to deliver, a transport session is 933 established (e.g., through [RFC8071]). Individual receivers are 934 moved to the active state when a "subscription-started" subscription 935 state change notification is successfully passed to that receiver 936 (a). Event records are only sent to active receivers. Receivers of 937 a configured subscription remain active if both transport 938 connectivity can be verified to the receiver, and event records are 939 not being dropped due to a publisher buffer capacity being reached. 940 The result is that a receiver will remain active on the publisher as 941 long as events aren't being lost, or the receiver cannot be reached. 942 In addition, a configured subscription's receiver MUST be moved to 943 the connecting state if the receiver is reset via the "reset" action 944 (b), (c). For more on reset, see Section 2.5.5. If transport 945 connectivity cannot be achieved while in the connecting state, the 946 receiver MAY be moved to the disconnected state. 948 A configured subscription's receiver MUST be moved to the suspended 949 state if there is transport connectivity between the publisher and 950 receiver, but notification messages are failing to be delivered due 951 to publisher buffer capacity being reached, or notification messages 952 are not able to be generated for that receiver due to insufficient 953 CPU (d). This is indicated to the receiver by the "subscription- 954 suspended" subscription state change notification. 956 A configured subscription receiver MUST be returned to the active 957 state from the suspended state when notification messages are able to 958 be generated, bandwidth is sufficient to handle the notification 959 messages, and a receiver has successfully been sent a "subscription- 960 resumed" or "subscription-modified" subscription state change 961 notification (e). The choice as to which of these two subscription 962 state change notifications is sent is determined by whether the 963 subscription was modified during the period of suspension. 965 Modification of a configured subscription is possible at any time. A 966 "subscription-modified" subscription state change notification will 967 be sent to all active receivers, immediately followed by notification 968 messages conforming to the new parameters. Suspended receivers will 969 also be informed of the modification. However this notification will 970 await the end of the suspension for that receiver (e). 972 The mechanisms described above are mirrored in the RPCs and 973 notifications within the document. It should be noted that these 974 RPCs and notifications have been designed to be extensible and allow 975 subscriptions into targets other than event streams. For instance, 976 the YANG module defined in Section 5 of [I-D.ietf-netconf-yang-push] 977 augments "/sn:modify-subscription/sn:input/sn:target". 979 2.5.2. Creating a Configured Subscription 981 Configured subscriptions are established using configuration 982 operations against the top-level "subscriptions" subtree. 984 Because there is no explicit association with an existing transport 985 session, configuration operations MUST include additional parameters 986 beyond those of dynamic subscriptions. These parameters identify 987 each receiver, how to connect with that receiver, and possibly 988 whether the notification messages need to come from a specific egress 989 interface on the publisher. Receiver specific transport connectivity 990 parameters MUST be configured via transport specific augmentations to 991 this specification. See Section 2.5.7 for details. 993 After a subscription is successfully established, the publisher 994 immediately sends a "subscription-started" subscription state change 995 notification to each receiver. It is quite possible that upon 996 configuration, reboot, or even steady-state operations, a transport 997 session may not be currently available to the receiver. In this 998 case, when there is something to transport for an active 999 subscription, transport specific call-home operations will be used to 1000 establish the connection. When transport connectivity is available, 1001 notification messages may then be pushed. 1003 With active configured subscriptions, it is allowable to buffer event 1004 records even after a "subscription-started" has been sent. However 1005 if events are lost (rather than just delayed) due to replay buffer 1006 capacity being reached, a new "subscription-started" must be sent. 1007 This new "subscription-started" indicates an event record 1008 discontinuity. 1010 To see an example of subscription creation using configuration 1011 operations over NETCONF, see Appendix A of 1012 [I-D.draft-ietf-netconf-netconf-event-notifications]. 1014 2.5.3. Modifying a Configured Subscription 1016 Configured subscriptions can be modified using configuration 1017 operations against the top-level "subscriptions" subtree. 1019 If the modification involves adding receivers, added receivers are 1020 placed in the connecting state. If a receiver is removed, the 1021 subscription state change notification "subscription-terminated" is 1022 sent to that receiver if that receiver is active or suspended. 1024 If the modification involves changing the policies for the 1025 subscription, the publisher sends to currently active receivers a 1026 "subscription-modified" notification. For any suspended receivers, a 1027 "subscription-modified" notification will be delayed until the 1028 receiver is resumed. (Note: in this case, the "subscription- 1029 modified" notification informs the receiver that the subscription has 1030 been resumed, so no additional "subscription-resumed" need be sent. 1031 Also note that if multiple modifications have occurred during the 1032 suspension, only the "subscription-modified" notification describing 1033 the latest one need be sent to the receiver.) 1035 2.5.4. Deleting a Configured Subscription 1037 Subscriptions can be deleted through configuration against the top- 1038 level "subscriptions" subtree. 1040 Immediately after a subscription is successfully deleted, the 1041 publisher sends to all receivers of that subscription a subscription 1042 state change notification stating the subscription has ended (i.e., 1043 "subscription-terminated"). 1045 2.5.5. Resetting a Configured Subscription Receiver 1047 It is possible that a configured subscription to a receiver needs to 1048 be reset. This is accomplished via the "reset" action within the 1049 YANG model at "/subscriptions/subscription/receivers/receiver/reset". 1050 This action may be useful in cases where a publisher has timed out 1051 trying to reach a receiver. When such a reset occurs, a transport 1052 session will be initiated if necessary, and a new "subscription- 1053 started" notification will be sent. This action does not have any 1054 effect on transport connectivity if the needed connectivity already 1055 exists. 1057 2.5.6. Replay for a Configured Subscription 1059 It is possible to do replay on a configured subscription. This is 1060 supported via the configuration of the "configured-replay" object on 1061 the subscription. The setting of this object enables the streaming 1062 of the buffered event records for the subscribed event stream. All 1063 buffered event records which have been retained since the last 1064 publisher restart will be sent to each configured receiver. 1066 Replay of events records created since restart is useful. It allows 1067 event records generated before transport connectivity establishment 1068 to be passed to a receiver. Setting the restart time as the earliest 1069 configured replay time precludes possibility of resending of event 1070 records logged prior to publisher restart. It also ensures the same 1071 records will be sent to each configured receiver, regardless of the 1072 speed of transport connectivity establishment to each receiver. 1073 Finally, establishing restart as the earliest potential time for 1074 event records to be included within notification messages, a well- 1075 understood timeframe for replay is defined. 1077 As a result, when any configured subscription receivers become 1078 active, buffered event records will be sent immediately after the 1079 "subscription-started" notification. If the publisher knows the last 1080 event record sent to a receiver, and the publisher has not rebooted, 1081 the next event record on the event stream which meets filtering 1082 criteria will be the leading event record sent. Otherwise, the 1083 leading event record will be the first event record meeting filtering 1084 criteria subsequent to the latest of three different times: the 1085 "replay-log-creation-time", "replay-log-aged-time", or the most 1086 recent publisher boot time. The "replay-log-creation-time" and 1087 "replay-log-aged-time" are discussed in Section 2.4.2.1. The most 1088 recent publisher boot time ensures that duplicate event records are 1089 not replayed from a previous time the publisher was booted. 1091 It is quite possible that a receiver might want to retrieve event 1092 records from an event stream prior to the latest boot. If such 1093 records exist where there is a configured replay, the publisher MUST 1094 send the time of the event record immediately preceding the "replay- 1095 start-time" within the "replay-previous-event-time" leaf. Through 1096 the existence of the "replay-previous-event-time", the receiver will 1097 know that earlier events prior to reboot exist. In addition, if the 1098 subscriber was previously receiving event records with the same 1099 subscription "id", the receiver can determine if there was a time gap 1100 where records generated on the publisher were not successfully 1101 received. And with this information, the receiver may choose to 1102 dynamically subscribe to retrieve any event records placed into the 1103 event stream before the most recent boot time. 1105 All other replay functionality remains the same as with dynamic 1106 subscriptions as described in Section 2.4.2.1. 1108 2.5.7. Transport Connectivity for a Configured Subscription 1110 This specification is transport independent. However supporting a 1111 configured subscription will often require the establishment of 1112 transport connectivity. And the parameters used for this transport 1113 connectivity establishment are transport specific. As a result, the 1114 YANG model defined within Section 4 is not able to directly define 1115 and expose these transport parameters. 1117 It is necessary for an implementation to support the connection 1118 establishment process. To support this function, the YANG model does 1119 include a node where transport specific parameters for a particular 1120 receiver may be augmented. This node is 1121 "/subscriptions/subscription/receivers/receiver". By augmenting 1122 transport parameters from this node, system developers are able to 1123 incorporate the YANG objects necessary to support the transport 1124 connectivity establishment process. 1126 The result of this is the following requirement. A publisher 1127 supporting the feature "configured" MUST also support least one YANG 1128 model which augments transport connectivity parameters on 1129 "/subscriptions/subscription/receivers/receiver". For an example of 1130 such an augmentation, see Appendix A. 1132 2.6. Event Record Delivery 1134 Whether dynamic or configured, once a subscription has been set up, 1135 the publisher streams event records via notification messages per the 1136 terms of the subscription. For dynamic subscriptions, notification 1137 messages are sent over the session used to establish the 1138 subscription. For configured subscriptions, notification messages 1139 are sent over the connections specified by the transport and each 1140 receiver of a configured subscription. 1142 A notification message is sent to a receiver when an event record is 1143 not blocked by either the specified filter criteria or receiver 1144 permissions. This notification message MUST include an "eventTime" 1145 object as defined per [RFC5277] Section 4. This "eventTime" MUST be 1146 at the top level of YANG structured event record. 1148 The following example within [RFC7950] section 7.16.3 is an example 1149 of a compliant message: 1151 1153 2007-09-01T10:00:00Z 1154 1155 so-1/2/3.0 1156 up 1157 down 1158 1159 1161 Figure 10: subscribed notification message 1163 When a dynamic subscription has been started or modified, with 1164 "establish-subscription" or "modify-subscription" respectively, event 1165 records matching the newly applied filter criteria MUST NOT be sent 1166 until after the RPC reply has been sent. 1168 When a configured subscription has been started or modified, event 1169 records matching the newly applied filter criteria MUST NOT be sent 1170 until after the "subscription-started" or "subscription-modified" 1171 notifications has been sent, respectively. 1173 2.7. Subscription state change notifications 1175 In addition to sending event records to receivers, a publisher MUST 1176 also send subscription state change notifications when events related 1177 to subscription management have occurred. 1179 Subscription state change notifications are unlike other 1180 notifications in that they are never included in any event stream. 1181 Instead, they are inserted (as defined in this section) within the 1182 sequence of notification messages sent to a particular receiver. 1183 subscription state change notifications cannot be dropped or filtered 1184 out, they cannot be stored in replay buffers, and they are delivered 1185 only to impacted receivers of a subscription. The identification of 1186 subscription state change notifications is easy to separate from 1187 other notification messages through the use of the YANG extension 1188 "subscription-state-notif". This extension tags a notification as a 1189 subscription state change notification. 1191 The complete set of subscription state change notifications is 1192 described in the following subsections. 1194 2.7.1. subscription-started 1196 This notification indicates that a configured subscription has 1197 started, and event records may be sent. Included in this 1198 subscription state change notification are all the parameters of the 1199 subscription, except for the receiver(s) transport connection 1200 information and origin information indicating where notification 1201 messages will egress the publisher. Note that if a referenced filter 1202 from the "filters" container has been used within the subscription, 1203 the notification still provides the contents of that referenced 1204 filter under the "within-subscription" subtree. 1206 Note that for dynamic subscriptions, no "subscription-started" 1207 notifications are ever sent. 1209 Below is a tree diagram for "subscription-started". All objects 1210 contained in this tree are described within the included YANG model 1211 within Section 4. 1213 +---n subscription-started {configured}? 1214 +--ro id 1215 | subscription-id 1216 +--ro (target) 1217 | +--:(stream) 1218 | +--ro (stream-filter)? 1219 | | +--:(by-reference) 1220 | | | +--ro stream-filter-name 1221 | | | stream-filter-ref 1222 | | +--:(within-subscription) 1223 | | +--ro (filter-spec)? 1224 | | +--:(stream-subtree-filter) 1225 | | | +--ro stream-subtree-filter? 1226 | | | {subtree}? 1227 | | +--:(stream-xpath-filter) 1228 | | +--ro stream-xpath-filter? yang:xpath1.0 1229 | | {xpath}? 1230 | +--ro stream stream-ref 1231 | +--ro replay-start-time? 1232 | | yang:date-and-time {replay}? 1233 | +--ro replay-previous-event-time? 1234 | yang:date-and-time {replay}? 1235 +--ro stop-time? 1236 | yang:date-and-time 1237 +--ro dscp? inet:dscp 1238 | {dscp}? 1239 +--ro weighting? uint8 {qos}? 1240 +--ro dependency? 1241 | subscription-id {qos}? 1242 +--ro transport? transport 1243 | {configured}? 1244 +--ro encoding? encoding 1245 +--ro purpose? string 1246 {configured}? 1248 Figure 11: subscription-started notification tree diagram 1250 2.7.2. subscription-modified 1252 This notification indicates that a subscription has been modified by 1253 configuration operations. It is delivered directly after the last 1254 event records processed using the previous subscription parameters, 1255 and before any event records processed after the modification. 1257 Below is a tree diagram for "subscription-modified". All objects 1258 contained in this tree are described within the included YANG model 1259 within Section 4. 1261 +---n subscription-modified 1262 +--ro id 1263 | subscription-id 1264 +--ro (target) 1265 | +--:(stream) 1266 | +--ro (stream-filter)? 1267 | | +--:(by-reference) 1268 | | | +--ro stream-filter-name 1269 | | | stream-filter-ref 1270 | | +--:(within-subscription) 1271 | | +--ro (filter-spec)? 1272 | | +--:(stream-subtree-filter) 1273 | | | +--ro stream-subtree-filter? 1274 | | | {subtree}? 1275 | | +--:(stream-xpath-filter) 1276 | | +--ro stream-xpath-filter? yang:xpath1.0 1277 | | {xpath}? 1278 | +--ro stream stream-ref 1279 | +--ro replay-start-time? 1280 | yang:date-and-time {replay}? 1281 +--ro stop-time? 1282 | yang:date-and-time 1283 +--ro dscp? inet:dscp 1284 | {dscp}? 1285 +--ro weighting? uint8 {qos}? 1286 +--ro dependency? 1287 | subscription-id {qos}? 1288 +--ro transport? transport 1289 | {configured}? 1290 +--ro encoding? encoding 1291 +--ro purpose? string 1292 {configured}? 1294 Figure 12: subscription-modified notification tree diagram 1296 A publisher most often sends this notification directly after the 1297 modification of any configuration parameters impacting a configured 1298 subscription. But it may also be sent at two other times: 1300 1. Where a configured subscription has been modified during the 1301 suspension of a receiver, the notification will be delayed until 1302 the receiver's suspension is lifted. In this situation, the 1303 notification indicates that the subscription has been both 1304 modified and resumed. 1306 2. A "subscription-modified" subscription state change notification 1307 MUST be sent if the contents of the filter identified by the 1308 subscription's "stream-filter-ref" leaf has changed. This state 1309 change notification is to be sent for a filter change impacting 1310 any active receiver of a configured or dynamic subscription. 1312 2.7.3. subscription-terminated 1314 This notification indicates that no further event records for this 1315 subscription should be expected from the publisher. A publisher may 1316 terminate the sending event records to a receiver for the following 1317 reasons: 1319 1. Configuration which removes a configured subscription, or a 1320 "kill-subscription" RPC which ends a dynamic subscription. These 1321 are identified via the reason "no-such-subscription". 1323 2. A referenced filter is no longer accessible. This is identified 1324 by "filter-unavailable". 1326 3. The event stream referenced by a subscription is no longer 1327 accessible by the receiver. This is identified by "stream- 1328 unavailable". 1330 4. A suspended subscription has exceeded some timeout. This is 1331 identified by "suspension-timeout". 1333 Each of the reasons above correspond one-to-one with a "reason" 1334 identityref specified within the YANG model. 1336 Below is a tree diagram for "subscription-terminated". All objects 1337 contained in this tree are described within the included YANG model 1338 within Section 4. 1340 +---n subscription-terminated 1341 +--ro id subscription-id 1342 +--ro reason identityref 1344 Figure 13: subscription-terminated notification tree diagram 1346 Note: this subscription state change notification MUST be sent to a 1347 dynamic subscription's receiver when the subscription ends 1348 unexpectedly. The cases when this might happen are when a "kill- 1349 subscription" RPC is successful, or when some other event not 1350 including the reaching the subscription's "stop-time" results in a 1351 publisher choosing to end the subscription. 1353 2.7.4. subscription-suspended 1355 This notification indicates that a publisher has suspended the 1356 sending of event records to a receiver, and also indicates the 1357 possible loss of events. Suspension happens when capacity 1358 constraints stop a publisher from serving a valid subscription. The 1359 two conditions where is this possible are: 1361 1. "insufficient-resources" when a publisher is unable to produce 1362 the requested event stream of notification messages, and 1364 2. "unsupportable-volume" when the bandwidth needed to get generated 1365 notification messages to a receiver exceeds a threshold. 1367 These conditions are encoded within the "reason" object. No further 1368 notification will be sent until the subscription resumes or is 1369 terminated. 1371 Below is a tree diagram for "subscription-suspended". All objects 1372 contained in this tree are described within the included YANG model 1373 within Section 4. 1375 +---n subscription-suspended 1376 +--ro id subscription-id 1377 +--ro reason identityref 1379 Figure 14: subscription-suspended notification tree diagram 1381 2.7.5. subscription-resumed 1383 This notification indicates that a previously suspended subscription 1384 has been resumed under the unmodified terms previously in place. 1385 Subscribed event records generated after the issuance of this 1386 subscription state change notification may now be sent. 1388 Below is the tree diagram for "subscription-resumed". All objects 1389 contained in this tree are described within the included YANG model 1390 within Section 4. 1392 +---n subscription-resumed 1393 +--ro id subscription-id 1395 Figure 15: subscription-resumed notification tree diagram 1397 2.7.6. subscription-completed 1399 This notification indicates that a subscription that includes a 1400 "stop-time" has successfully finished passing event records upon the 1401 reaching of that time. 1403 Below is a tree diagram for "subscription-completed". All objects 1404 contained in this tree are described within the included YANG model 1405 within Section 4. 1407 +---n subscription-completed {configured}? 1408 +--ro id subscription-id 1410 Figure 16: subscription-completed notification tree diagram 1412 2.7.7. replay-completed 1414 This notification indicates that all of the event records prior to 1415 the current time have been passed to a receiver. It is sent before 1416 any notification message containing an event record with a timestamp 1417 later than (1) the "stop-time" or (2) the subscription's start time. 1419 If a subscription contains no "stop-time", or has a "stop-time" that 1420 has not been reached, then after the "replay-completed" notification 1421 has been sent, additional event records will be sent in sequence as 1422 they arise naturally on the publisher. 1424 Below is a tree diagram for "replay-completed". All objects 1425 contained in this tree are described within the included YANG model 1426 within Section 4. 1428 +---n replay-completed {replay}? 1429 +--ro id subscription-id 1431 Figure 17: replay-completed notification tree diagram 1433 2.8. Subscription Monitoring 1435 In the operational state datastore, the container "subscriptions" 1436 maintains the state of all dynamic subscriptions, as well as all 1437 configured subscriptions. Using datastore retrieval operations, or 1438 subscribing to the "subscriptions" container 1439 [I-D.ietf-netconf-yang-push] allows the state of subscriptions and 1440 their connectivity to receivers to be monitored. 1442 Each subscription in the operational state datastore is represented 1443 as a list element. Included in this list are event counters for each 1444 receiver, the state of each receiver, as well as the subscription 1445 parameters currently in effect. The appearance of the leaf 1446 "configured-subscription-state" indicates that a particular 1447 subscription came into being via configuration. This leaf also 1448 indicates if the current state of that subscription is valid, 1449 invalid, and concluded. 1451 To understand the flow of event records within a subscription, there 1452 are two counters available for each receiver. The first counter is 1453 "sent-event-records" which shows the quantity of events actually 1454 identified for sending to a receiver. The second counter is 1455 "excluded-event-records" which shows event records not sent to 1456 receiver. "excluded-event-records" shows the combined results of 1457 both access control and per-subscription filtering. For configured 1458 subscriptions, counters are reset whenever the subscription is 1459 evaluated to valid (see (1) in Figure 8). 1461 Dynamic subscriptions are removed from the operational state 1462 datastore once they expire (reaching stop-time) or when they are 1463 terminated. While many subscription objects are shown as 1464 configurable, dynamic subscriptions are only included within the 1465 operational state datastore and as a result are not configurable. 1467 2.9. Advertisement 1469 Publishers supporting this document MUST indicate support of the YANG 1470 model "ietf-subscribed-notifications" within the YANG library of the 1471 publisher. In addition if supported, the optional features "encode- 1472 xml", "encode-json", "configured" "supports-vrf", "qos", "xpath", 1473 "subtree", "interface-designation", "dscp", and "replay" MUST be 1474 indicated. 1476 3. YANG Data Model Trees 1478 This section contains tree diagrams for nodes defined in Section 4. 1479 For tree diagrams of subscription state change notifications, see 1480 Section 2.7. For the tree diagrams for the RPCs, see Section 2.4. 1482 3.1. Event Streams Container 1484 A publisher maintains a list of available event streams as 1485 operational data. This list contains both standardized and vendor- 1486 specific event streams. This enables subscribers to discover what 1487 streams a publisher supports. 1489 +--ro streams 1490 +--ro stream* [name] 1491 +--ro name string 1492 +--ro description string 1493 +--ro replay-support? empty {replay}? 1494 +--ro replay-log-creation-time yang:date-and-time 1495 | {replay}? 1496 +--ro replay-log-aged-time? yang:date-and-time 1497 {replay}? 1499 Figure 18: Stream Container tree diagram 1501 Above is a tree diagram for the "streams" container. All objects 1502 contained in this tree are described within the included YANG model 1503 within Section 4. 1505 3.2. Filters Container 1507 The "filters" container maintains a list of all subscription filters 1508 that persist outside the life-cycle of a single subscription. This 1509 enables pre-defined filters which may be referenced by more than one 1510 subscription. 1512 +--rw filters 1513 +--rw stream-filter* [name] 1514 +--rw name string 1515 +--rw (filter-spec)? 1516 +--:(stream-subtree-filter) 1517 | +--rw stream-subtree-filter? {subtree}? 1518 +--:(stream-xpath-filter) 1519 +--rw stream-xpath-filter? yang:xpath1.0 {xpath}? 1521 Figure 19: Filter Container tree diagram 1523 Above is a tree diagram for the filters container. All objects 1524 contained in this tree are described within the included YANG model 1525 within Section 4. 1527 3.3. Subscriptions Container 1529 The "subscriptions" container maintains a list of all subscriptions 1530 on a publisher, both configured and dynamic. It can be used to 1531 retrieve information about the subscriptions which a publisher is 1532 serving. 1534 +--rw subscriptions 1535 +--rw subscription* [id] 1536 +--rw id 1537 | subscription-id 1538 +--rw (target) 1539 | +--:(stream) 1540 | +--rw (stream-filter)? 1541 | | +--:(by-reference) 1542 | | | +--rw stream-filter-name 1543 | | | stream-filter-ref 1544 | | +--:(within-subscription) 1545 | | +--rw (filter-spec)? 1546 | | +--:(stream-subtree-filter) 1547 | | | +--rw stream-subtree-filter? 1548 | | | {subtree}? 1549 | | +--:(stream-xpath-filter) 1550 | | +--rw stream-xpath-filter? 1551 | | yang:xpath1.0 {xpath}? 1552 | +--rw stream stream-ref 1553 | +--ro replay-start-time? 1554 | | yang:date-and-time {replay}? 1555 | +--rw configured-replay? empty 1556 | {configured,replay}? 1557 +--rw stop-time? 1558 | yang:date-and-time 1559 +--rw dscp? inet:dscp 1560 | {dscp}? 1561 +--rw weighting? uint8 {qos}? 1562 +--rw dependency? 1563 | subscription-id {qos}? 1564 +--rw transport? transport 1565 | {configured}? 1566 +--rw encoding? encoding 1567 +--rw purpose? string 1568 | {configured}? 1569 +--rw (notification-message-origin)? {configured}? 1570 | +--:(interface-originated) 1571 | | +--rw source-interface? 1572 | | if:interface-ref {interface-designation}? 1573 | +--:(address-originated) 1574 | +--rw source-vrf? 1575 | | -> /ni:network-instances/network-instance/name 1576 | | {supports-vrf}? 1577 | +--rw source-address? 1578 | inet:ip-address-no-zone 1579 +--ro configured-subscription-state? enumeration 1580 | {configured}? 1581 +--rw receivers 1582 +--rw receiver* [name] 1583 +--rw name string 1584 +--ro sent-event-records? 1585 | yang:zero-based-counter64 1586 +--ro excluded-event-records? 1587 | yang:zero-based-counter64 1588 +--ro state enumeration 1589 +---x reset {configured}? 1590 +--ro output 1591 +--ro time yang:date-and-time 1593 Figure 20: Subscriptions tree diagram 1595 Above is a tree diagram for the subscriptions container. All objects 1596 contained in this tree are described within the included YANG model 1597 within Section 4. 1599 4. Data Model 1601 This module imports typedefs from [RFC6991], [RFC8343], and 1602 [RFC8040], and it references [I-D.draft-ietf-rtgwg-ni-model], 1603 [XPATH], [RFC6241], [RFC7049], [RFC7540], [RFC7951] , [RFC7950] and 1604 [RFC8259]. 1606 [ note to the RFC Editor - please replace XXXX within this YANG model 1607 with the number of this document, and XXXY with the number of 1608 [I-D.draft-ietf-rtgwg-ni-model] ] 1610 [ note to the RFC Editor - please replace the two dates within the 1611 YANG module with the date of publication ] 1613 file "ietf-subscribed-notifications@2019-05-01.yang" 1614 module ietf-subscribed-notifications { 1615 yang-version 1.1; 1616 namespace 1617 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"; 1619 prefix sn; 1621 import ietf-inet-types { 1622 prefix inet; 1623 reference 1624 "RFC 6991: Common YANG Data Types"; 1625 } 1626 import ietf-interfaces { 1627 prefix if; 1628 reference 1629 "RFC 8343: A YANG Data Model for Interface Management"; 1631 } 1632 import ietf-netconf-acm { 1633 prefix nacm; 1634 reference 1635 "RFC 8341: Network Configuration Access Control Model"; 1636 } 1637 import ietf-network-instance { 1638 prefix ni; 1639 reference 1640 "draft-ietf-rtgwg-ni-model-12: YANG Model for Network Instances"; 1641 } 1642 import ietf-restconf { 1643 prefix rc; 1644 reference 1645 "RFC 8040: RESTCONF Protocol"; 1646 } 1647 import ietf-yang-types { 1648 prefix yang; 1649 reference 1650 "RFC 6991: Common YANG Data Types"; 1651 } 1653 organization "IETF NETCONF (Network Configuration) Working Group"; 1654 contact 1655 "WG Web: 1656 WG List: 1658 Author: Alexander Clemm 1659 1661 Author: Eric Voit 1662 1664 Author: Alberto Gonzalez Prieto 1665 1667 Author: Einar Nilsen-Nygaard 1668 1670 Author: Ambika Prasad Tripathy 1671 "; 1673 description 1674 "Contains a YANG specification for subscribing to event records 1675 and receiving matching content within notification messages. 1677 Copyright (c) 2018 IETF Trust and the persons identified as authors 1678 of the code. All rights reserved. 1680 Redistribution and use in source and binary forms, with or without 1681 modification, is permitted pursuant to, and subject to the license 1682 terms contained in, the Simplified BSD License set forth in Section 1683 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 1684 (https://trustee.ietf.org/license-info). 1686 This version of this YANG module is part of RFC XXXX; see the RFC 1687 itself for full legal notices."; 1689 revision 2019-05-01 { 1690 description 1691 "Initial version"; 1692 reference 1693 "RFC XXXX:Subscription to YANG Event Notifications"; 1694 } 1696 /* 1697 * FEATURES 1698 */ 1700 feature configured { 1701 description 1702 "This feature indicates that configuration of subscriptions is 1703 supported."; 1704 } 1706 feature dscp { 1707 description 1708 "This feature indicates that a publisher supports the ability to 1709 set the DiffServ Code Point (DSCP) value in outgoing packets."; 1710 } 1712 feature encode-json { 1713 description 1714 "This feature indicates that JSON encoding of notification 1715 messages is supported."; 1716 } 1718 feature encode-xml { 1719 description 1720 "This feature indicates that XML encoding of notification 1721 messages is supported."; 1722 } 1724 feature interface-designation { 1725 description 1726 "This feature indicates a publisher supports sourcing all 1727 receiver interactions for a configured subscription from a single 1728 designated egress interface."; 1729 } 1731 feature qos { 1732 description 1733 "This feature indicates a publisher supports absolute 1734 dependencies of one subscription's traffic over another, as well 1735 as weighted bandwidth sharing between subscriptions. Both of 1736 these are Quality of Service (QoS) features which allow 1737 differentiated treatment of notification messages between a 1738 publisher and a specific receiver."; 1739 } 1741 feature replay { 1742 description 1743 "This feature indicates that historical event record replay is 1744 supported. With replay, it is possible for past event records to 1745 be streamed in chronological order."; 1746 } 1748 feature subtree { 1749 description 1750 "This feature indicates support for YANG subtree filtering."; 1751 reference "RFC 6241, Section 6."; 1752 } 1754 feature supports-vrf { 1755 description 1756 "This feature indicates a publisher supports VRF configuration 1757 for configured subscriptions. VRF support for dynamic 1758 subscriptions does not require this feature."; 1759 reference "RFC XXXY, Section 6."; 1760 } 1762 feature xpath { 1763 description 1764 "This feature indicates support for XPath filtering."; 1765 reference "http://www.w3.org/TR/1999/REC-xpath-19991116"; 1766 } 1768 /* 1769 * EXTENSIONS 1770 */ 1772 extension subscription-state-notification { 1773 description 1774 "This statement applies only to notifications. It indicates that 1775 the notification is a subscription state change notification. 1777 Therefore it does not participate in a regular event stream and 1778 does not need to be specifically subscribed to in order to be 1779 received. This statement can only occur as a substatement to the 1780 YANG 'notification' statement. This statement is not for use 1781 outside of this YANG module."; 1782 } 1784 /* 1785 * IDENTITIES 1786 */ 1788 /* Identities for RPC and Notification errors */ 1790 identity delete-subscription-error { 1791 description 1792 "Problem found while attempting to fulfill either a 1793 'delete-subscription' RPC request or a 'kill-subscription' 1794 RPC request."; 1795 } 1797 identity establish-subscription-error { 1798 description 1799 "Problem found while attempting to fulfill an 1800 'establish-subscription' RPC request."; 1801 } 1803 identity modify-subscription-error { 1804 description 1805 "Problem found while attempting to fulfill a 1806 'modify-subscription' RPC request."; 1807 } 1809 identity subscription-suspended-reason { 1810 description 1811 "Problem condition communicated to a receiver as part of a 1812 'subscription-suspended' notification."; 1813 } 1815 identity subscription-terminated-reason { 1816 description 1817 "Problem condition communicated to a receiver as part of a 1818 'subscription-terminated' notification."; 1819 } 1821 identity dscp-unavailable { 1822 base establish-subscription-error; 1823 if-feature "dscp"; 1824 description 1825 "The publisher is unable mark notification messages with a 1826 prioritization information in a way which will be respected 1827 during network transit."; 1828 } 1830 identity encoding-unsupported { 1831 base establish-subscription-error; 1832 description 1833 "Unable to encode notification messages in the desired format."; 1834 } 1836 identity filter-unavailable { 1837 base subscription-terminated-reason; 1838 description 1839 "Referenced filter does not exist. This means a receiver is 1840 referencing a filter which doesn't exist, or to which they do not 1841 have access permissions."; 1842 } 1844 identity filter-unsupported { 1845 base establish-subscription-error; 1846 base modify-subscription-error; 1847 description 1848 "Cannot parse syntax within the filter. This failure can be from 1849 a syntax error, or a syntax too complex to be processed by the 1850 publisher."; 1851 } 1853 identity insufficient-resources { 1854 base establish-subscription-error; 1855 base modify-subscription-error; 1856 base subscription-suspended-reason; 1857 description 1858 "The publisher has insufficient resources to support the 1859 requested subscription. An example might be that allocated CPU 1860 is too limited to generate the desired set of notification 1861 messages."; 1862 } 1864 identity no-such-subscription { 1865 base modify-subscription-error; 1866 base delete-subscription-error; 1867 base subscription-terminated-reason; 1868 description 1869 "Referenced subscription doesn't exist. This may be as a result of 1870 a non-existent subscription id, an id which belongs to another 1871 subscriber, or an id for configured subscription."; 1872 } 1873 identity replay-unsupported { 1874 base establish-subscription-error; 1875 if-feature "replay"; 1876 description 1877 "Replay cannot be performed for this subscription. This means the 1878 publisher will not provide the requested historic information 1879 from the event stream via replay to this receiver."; 1880 } 1882 identity stream-unavailable { 1883 base subscription-terminated-reason; 1884 description 1885 "Not a subscribable event stream. This means the referenced event 1886 stream is not available for subscription by the receiver."; 1887 } 1889 identity suspension-timeout { 1890 base subscription-terminated-reason; 1891 description 1892 "Termination of previously suspended subscription. The publisher 1893 has eliminated the subscription as it exceeded a time limit for 1894 suspension."; 1895 } 1897 identity unsupportable-volume { 1898 base subscription-suspended-reason; 1899 description 1900 "The publisher does not have the network bandwidth needed to get 1901 the volume of generated information intended for a receiver."; 1902 } 1904 /* Identities for encodings */ 1906 identity configurable-encoding { 1907 description 1908 "If a transport identity derives from this identity, it means 1909 that it supports configurable encodings. An example of a 1910 configurable encoding might be a new identity such as 1911 'encode-cbor'. Such an identity could use 1912 'configurable-encoding' as its base. This would allow a 1913 dynamic subscription encoded in JSON [RFC-8259] to request 1914 notification messages be encoded via CBOR [RFC-7049]. Further 1915 details for any specific configurable encoding would be 1916 explored in a transport document based on this specification."; 1917 } 1919 identity encoding { 1920 description 1921 "Base identity to represent data encodings"; 1922 } 1924 identity encode-xml { 1925 base encoding; 1926 if-feature "encode-xml"; 1927 description 1928 "Encode data using XML as described in RFC 7950"; 1929 reference 1930 "RFC 7950 - The YANG 1.1 Data Modeling Language"; 1931 } 1933 identity encode-json { 1934 base encoding; 1935 if-feature "encode-json"; 1936 description 1937 "Encode data using JSON as described in RFC 7951"; 1938 reference 1939 "RFC 7951 - JSON Encoding of Data Modeled with YANG"; 1940 } 1942 /* Identities for transports */ 1943 identity transport { 1944 description 1945 "An identity that represents the underlying mechanism for 1946 passing notification messages."; 1947 } 1949 /* 1950 * TYPEDEFs 1951 */ 1953 typedef encoding { 1954 type identityref { 1955 base encoding; 1956 } 1957 description 1958 "Specifies a data encoding, e.g. for a data subscription."; 1959 } 1961 typedef stream-filter-ref { 1962 type leafref { 1963 path "/sn:filters/sn:stream-filter/sn:name"; 1964 } 1965 description 1966 "This type is used to reference an event stream filter."; 1967 } 1968 typedef stream-ref { 1969 type leafref { 1970 path "/sn:streams/sn:stream/sn:name"; 1971 } 1972 description 1973 "This type is used to reference a system-provided event stream."; 1974 } 1976 typedef subscription-id { 1977 type uint32; 1978 description 1979 "A type for subscription identifiers."; 1980 } 1982 typedef transport { 1983 type identityref { 1984 base transport; 1985 } 1986 description 1987 "Specifies transport used to send notification messages to a 1988 receiver."; 1989 } 1991 /* 1992 * GROUPINGS 1993 */ 1995 grouping stream-filter-elements { 1996 description 1997 "This grouping defines the base for filters applied to event 1998 streams."; 1999 choice filter-spec { 2000 description 2001 "The content filter specification for this request."; 2002 anydata stream-subtree-filter { 2003 if-feature "subtree"; 2004 description 2005 "Event stream evaluation criteria encoded in the syntax of a 2006 subtree filter as defined in RFC 6241, Section 6. 2008 The subtree filter is applied to the representation of 2009 individual, delineated event records as contained within the 2010 event stream. 2012 If the subtree filter returns a non-empty node set, the 2013 filter matches the event record, and the event record is 2014 included in the notification message sent to the receivers."; 2015 reference "RFC 6241, Section 6."; 2017 } 2018 leaf stream-xpath-filter { 2019 if-feature "xpath"; 2020 type yang:xpath1.0; 2021 description 2022 "Event stream evaluation criteria encoded in the syntax of 2023 an XPath 1.0 expression. 2025 The XPath expression is evaluated on the representation of 2026 individual, delineated event records as contained within 2027 the event stream. 2029 The result of the XPath expression is converted to a 2030 boolean value using the standard XPath 1.0 rules. If the 2031 boolean value is 'true', the filter matches the event 2032 record, and the event record is included in the notification 2033 message sent to the receivers. 2035 The expression is evaluated in the following XPath context: 2037 o The set of namespace declarations is the set of prefix 2038 and namespace pairs for all YANG modules implemented 2039 by the server, where the prefix is the YANG module 2040 name and the namespace is as defined by the 2041 'namespace' statement in the YANG module. 2043 If the leaf is encoded in XML, all namespace 2044 declarations in scope on the 'stream-xpath-filter' 2045 leaf element are added to the set of namespace 2046 declarations. If a prefix found in the XML is 2047 already present in the set of namespace declarations, 2048 the namespace in the XML is used. 2050 o The set of variable bindings is empty. 2052 o The function library is the core function library, and 2053 the XPath functions defined in section 10 in RFC 7950. 2055 o The context node is the root node."; 2056 reference 2057 "http://www.w3.org/TR/1999/REC-xpath-19991116 2058 RFC 7950, Section 10."; 2060 } 2061 } 2062 } 2064 grouping update-qos { 2065 description 2066 "This grouping describes Quality of Service information 2067 concerning a subscription. This information is passed to lower 2068 layers for transport prioritization and treatment"; 2069 leaf dscp { 2070 if-feature "dscp"; 2071 type inet:dscp; 2072 default "0"; 2073 description 2074 "The desired network transport priority level. This is the 2075 priority set on notification messages encapsulating the 2076 results of the subscription. This transport priority is 2077 shared for all receivers of a given subscription."; 2078 } 2079 leaf weighting { 2080 if-feature "qos"; 2081 type uint8 { 2082 range "0 .. 255"; 2083 } 2084 description 2085 "Relative weighting for a subscription. Larger weights get 2086 more resources. Allows an underlying transport layer perform 2087 informed load balance allocations between various 2088 subscriptions"; 2089 reference 2090 "RFC-7540, section 5.3.2"; 2091 } 2092 leaf dependency { 2093 if-feature "qos"; 2094 type subscription-id; 2095 description 2096 "Provides the 'subscription-id' of a parent subscription which 2097 has absolute precedence should that parent have push updates 2098 ready to egress the publisher. In other words, there should be 2099 no streaming of objects from the current subscription if 2100 the parent has something ready to push. 2102 If a dependency is asserted via configuration or via RPC, but 2103 the referenced 'subscription-id' does not exist, the 2104 dependency is silently discarded. If a referenced 2105 subscription is deleted this dependency is removed."; 2106 reference 2107 "RFC-7540, section 5.3.1"; 2108 } 2109 } 2111 grouping subscription-policy-modifiable { 2112 description 2113 "This grouping describes all objects which may be changed 2114 in a subscription."; 2115 choice target { 2116 mandatory true; 2117 description 2118 "Identifies the source of information against which a 2119 subscription is being applied, as well as specifics on the 2120 subset of information desired from that source."; 2121 case stream { 2122 choice stream-filter { 2123 description 2124 "An event stream filter can be applied to a subscription. 2125 That filter will come either referenced from a global list, 2126 or be provided within the subscription itself."; 2127 case by-reference { 2128 description 2129 "Apply a filter that has been configured separately."; 2130 leaf stream-filter-name { 2131 type stream-filter-ref; 2132 mandatory true; 2133 description 2134 "References an existing event stream filter which is to 2135 be applied to an event stream for the subscription."; 2136 } 2137 } 2138 case within-subscription { 2139 description 2140 "Local definition allows a filter to have the same 2141 lifecycle as the subscription."; 2142 uses stream-filter-elements; 2143 } 2144 } 2145 } 2146 } 2147 leaf stop-time { 2148 type yang:date-and-time; 2149 description 2150 "Identifies a time after which notification messages for a 2151 subscription should not be sent. If 'stop-time' is not 2152 present, the notification messages will continue until the 2153 subscription is terminated. If 'replay-start-time' exists, 2154 'stop-time' must be for a subsequent time. If 2155 'replay-start-time' doesn't exist, 'stop-time' when established 2156 must be for a future time."; 2157 } 2158 } 2160 grouping subscription-policy-dynamic { 2161 description 2162 "This grouping describes the only information concerning a 2163 subscription which can be passed over the RPCs defined in this 2164 model."; 2165 uses subscription-policy-modifiable { 2166 augment target/stream { 2167 description 2168 "Adds additional objects which can be modified by RPC."; 2169 leaf stream { 2170 type stream-ref { 2171 require-instance false; 2172 } 2173 mandatory true; 2174 description 2175 "Indicates the event stream to be considered for 2176 this subscription."; 2177 } 2178 leaf replay-start-time { 2179 if-feature "replay"; 2180 type yang:date-and-time; 2181 config false; 2182 description 2183 "Used to trigger the replay feature for a dynamic 2184 subscription, with event records being selected needing to 2185 be at or after the start at the time specified. If 2186 'replay-start-time' is not present, this is not a replay 2187 subscription and event record push should start 2188 immediately. It is never valid to specify start times that 2189 are later than or equal to the current time."; 2190 } 2191 } 2192 } 2193 uses update-qos; 2194 } 2196 grouping subscription-policy { 2197 description 2198 "This grouping describes the full set of policy information 2199 concerning both dynamic and configured subscriptions, with the 2200 exclusion of both receivers and networking information specific 2201 to the publisher such as what interface should be used to 2202 transmit notification messages."; 2203 uses subscription-policy-dynamic; 2204 leaf transport { 2205 if-feature "configured"; 2206 type transport; 2207 description 2208 "For a configured subscription, this leaf specifies the 2209 transport used to deliver messages destined to all receivers 2210 of that subscription."; 2211 } 2212 leaf encoding { 2213 when 'not(../transport) or derived-from(../transport, 2214 "sn:configurable-encoding")'; 2215 type encoding; 2216 description 2217 "The type of encoding for notification messages. For a 2218 dynamic subscription, if not included as part of an establish- 2219 subscription RPC, the encoding will be populated with the 2220 encoding used by that RPC. For a configured subscription, if 2221 not explicitly configured the encoding with be the default 2222 encoding for an underlying transport."; 2223 } 2224 leaf purpose { 2225 if-feature "configured"; 2226 type string; 2227 description 2228 "Open text allowing a configuring entity to embed the 2229 originator or other specifics of this subscription."; 2230 } 2231 } 2233 /* 2234 * RPCs 2235 */ 2237 rpc establish-subscription { 2238 description 2239 "This RPC allows a subscriber to create (and possibly negotiate) 2240 a subscription on its own behalf. If successful, the 2241 subscription remains in effect for the duration of the 2242 subscriber's association with the publisher, or until the 2243 subscription is terminated. In case an error occurs, or the 2244 publisher cannot meet the terms of a subscription, an RPC error 2245 is returned, the subscription is not created. In that case, the 2246 RPC reply's 'error-info' MAY include suggested parameter 2247 settings that would have a higher likelihood of succeeding in a 2248 subsequent 'establish-subscription' request."; 2249 input { 2250 uses subscription-policy-dynamic; 2251 leaf encoding { 2252 type encoding; 2253 description 2254 "The type of encoding for the subscribed data. If not 2255 included as part of the RPC, the encoding MUST be set by the 2256 publisher to be the encoding used by this RPC."; 2258 } 2259 } 2260 output { 2261 leaf id { 2262 type subscription-id; 2263 mandatory true; 2264 description 2265 "Identifier used for this subscription."; 2266 } 2267 leaf replay-start-time-revision { 2268 if-feature "replay"; 2269 type yang:date-and-time; 2270 description 2271 "If a replay has been requested, this represents the 2272 earliest time covered by the event buffer for the requested 2273 event stream. The value of this object is the 2274 'replay-log-aged-time' if it exists. Otherwise it is the 2275 'replay-log-creation-time'. All buffered event records 2276 after this time will be replayed to a receiver. This 2277 object will only be sent if the starting time has been 2278 revised to be later than the time requested by the 2279 subscriber."; 2280 } 2281 } 2282 } 2284 rc:yang-data establish-subscription-stream-error-info { 2285 container establish-subscription-stream-error-info { 2286 description 2287 "If any 'establish-subscription' RPC parameters are 2288 unsupportable against the event stream, a subscription is not 2289 created and the RPC error response MUST indicate the reason 2290 why the subscription failed to be created. This yang-data MAY 2291 be inserted as structured data within a subscription's RPC 2292 error response to indicate the failure reason. This yang-data 2293 MUST be inserted if hints are to be provided back to the 2294 subscriber."; 2295 leaf reason { 2296 type identityref { 2297 base establish-subscription-error; 2298 } 2299 description 2300 "Indicates the reason why the subscription has failed to 2301 be created to a targeted event stream."; 2302 } 2303 leaf filter-failure-hint { 2304 type string; 2305 description 2306 "Information describing where and/or why a provided filter 2307 was unsupportable for a subscription. The syntax and 2308 semantics of this hint are implementation-specific."; 2309 } 2310 } 2311 } 2313 rpc modify-subscription { 2314 description 2315 "This RPC allows a subscriber to modify a dynamic subscription's 2316 parameters. If successful, the changed subscription 2317 parameters remain in effect for the duration of the 2318 subscription, until the subscription is again modified, or until 2319 the subscription is terminated. In case of an error or an 2320 inability to meet the modified parameters, the subscription is 2321 not modified and the original subscription parameters remain in 2322 effect. In that case, the RPC error MAY include 'error-info' 2323 suggested parameter hints that would have a high likelihood of 2324 succeeding in a subsequent 'modify-subscription' request. A 2325 successful 'modify-subscription' will return a suspended 2326 subscription to an 'active' state."; 2327 input { 2328 leaf id { 2329 type subscription-id; 2330 mandatory true; 2331 description 2332 "Identifier to use for this subscription."; 2333 } 2334 uses subscription-policy-modifiable; 2335 } 2336 } 2338 rc:yang-data modify-subscription-stream-error-info { 2339 container modify-subscription-stream-error-info { 2340 description 2341 "This yang-data MAY be provided as part of a subscription's RPC 2342 error response when there is a failure of a 2343 'modify-subscription' RPC which has been made against an event 2344 stream. This yang-data MUST be used if hints are to be 2345 provided back to the subscriber."; 2346 leaf reason { 2347 type identityref { 2348 base modify-subscription-error; 2349 } 2350 description 2351 "Information in a 'modify-subscription' RPC error response 2352 which indicates the reason why the subscription to an event 2353 stream has failed to be modified."; 2355 } 2356 leaf filter-failure-hint { 2357 type string; 2358 description 2359 "Information describing where and/or why a provided filter 2360 was unsupportable for a subscription."; 2361 } 2362 } 2363 } 2365 rpc delete-subscription { 2366 description 2367 "This RPC allows a subscriber to delete a subscription that 2368 was previously created from by that same subscriber using the 2369 'establish-subscription' RPC. 2371 If an error occurs, the server replies with an 'rpc-error' where 2372 the 'error-info' field MAY contain an 2373 'delete-subscription-error-info' structure."; 2374 input { 2375 leaf id { 2376 type subscription-id; 2377 mandatory true; 2378 description 2379 "Identifier of the subscription that is to be deleted. 2380 Only subscriptions that were created using 2381 'establish-subscription' from the same origin as this RPC 2382 can be deleted via this RPC."; 2383 } 2384 } 2385 } 2387 rpc kill-subscription { 2388 nacm:default-deny-all; 2389 description 2390 "This RPC allows an operator to delete a dynamic subscription 2391 without restrictions on the originating subscriber or underlying 2392 transport session. 2394 If an error occurs, the server replies with an 'rpc-error' where 2395 the 'error-info' field MAY contain an 2396 'delete-subscription-error-info' structure."; 2397 input { 2398 leaf id { 2399 type subscription-id; 2400 mandatory true; 2401 description 2402 "Identifier of the subscription that is to be deleted. Only 2403 subscriptions that were created using 2404 'establish-subscription' can be deleted via this RPC."; 2405 } 2406 } 2407 } 2409 rc:yang-data delete-subscription-error-info { 2410 container delete-subscription-error-info { 2411 description 2412 "If a 'delete-subscription' RPC or a 'kill-subscription' RPC 2413 fails, the subscription is not deleted and the RPC error 2414 response MUST indicate the reason for this failure. This 2415 yang-data MAY be inserted as structured data within a 2416 subscription's RPC error response to indicate the failure 2417 reason."; 2418 leaf reason { 2419 type identityref { 2420 base delete-subscription-error; 2421 } 2422 mandatory true; 2423 description 2424 "Indicates the reason why the subscription has failed to be 2425 deleted."; 2426 } 2427 } 2428 } 2430 /* 2431 * NOTIFICATIONS 2432 */ 2434 notification replay-completed { 2435 sn:subscription-state-notification; 2436 if-feature "replay"; 2437 description 2438 "This notification is sent to indicate that all of the replay 2439 notifications have been sent."; 2440 leaf id { 2441 type subscription-id; 2442 mandatory true; 2443 description 2444 "This references the affected subscription."; 2445 } 2446 } 2448 notification subscription-completed { 2449 sn:subscription-state-notification; 2450 if-feature "configured"; 2451 description 2452 "This notification is sent to indicate that a subscription has 2453 finished passing event records, as the 'stop-time' has been 2454 reached."; 2455 leaf id { 2456 type subscription-id; 2457 mandatory true; 2458 description 2459 "This references the gracefully completed subscription."; 2460 } 2461 } 2463 notification subscription-modified { 2464 sn:subscription-state-notification; 2465 description 2466 "This notification indicates that a subscription has been 2467 modified. Notification messages sent from this point on will 2468 conform to the modified terms of the subscription. For 2469 completeness, this subscription state change notification 2470 includes both modified and non-modified aspects of a 2471 subscription."; 2472 leaf id { 2473 type subscription-id; 2474 mandatory true; 2475 description 2476 "This references the affected subscription."; 2477 } 2478 uses subscription-policy { 2479 refine "target/stream/stream-filter/within-subscription" { 2480 description 2481 "Filter applied to the subscription. If the 2482 'stream-filter-name' is populated, the filter within the 2483 subscription came from the 'filters' container. Otherwise it 2484 is populated in-line as part of the subscription."; 2485 } 2486 } 2487 } 2489 notification subscription-resumed { 2490 sn:subscription-state-notification; 2491 description 2492 "This notification indicates that a subscription that had 2493 previously been suspended has resumed. Notifications will once 2494 again be sent. In addition, a 'subscription-resumed' indicates 2495 that no modification of parameters has occurred since the last 2496 time event records have been sent."; 2497 leaf id { 2498 type subscription-id; 2499 mandatory true; 2500 description 2501 "This references the affected subscription."; 2502 } 2503 } 2505 notification subscription-started { 2506 sn:subscription-state-notification; 2507 if-feature "configured"; 2508 description 2509 "This notification indicates that a subscription has started and 2510 notifications are beginning to be sent."; 2511 leaf id { 2512 type subscription-id; 2513 mandatory true; 2514 description 2515 "This references the affected subscription."; 2516 } 2517 uses subscription-policy { 2518 refine "target/stream/replay-start-time" { 2519 description 2520 "Indicates the time that a replay is using for the streaming 2521 of buffered event records. This will be populated with the 2522 most recent of the following: the event time of the previous 2523 event record sent to a receiver, the 2524 'replay-log-creation-time', the 'replay-log-aged-time', 2525 or the most recent publisher boot time."; 2526 } 2527 refine "target/stream/stream-filter/within-subscription" { 2528 description 2529 "Filter applied to the subscription. If the 2530 'stream-filter-name' is populated, the filter within the 2531 subscription came from the 'filters' container. Otherwise it 2532 is populated in-line as part of the subscription."; 2533 } 2534 augment "target/stream" { 2535 description 2536 "This augmentation adds additional parameters specific to a 2537 subscription-started notification."; 2538 leaf replay-previous-event-time { 2539 when "../replay-start-time"; 2540 if-feature "replay"; 2541 type yang:date-and-time; 2542 description 2543 "If there is at least one event in the replay buffer prior 2544 to 'replay-start-time', this gives the time of the event 2545 generated immediately prior to the 'replay-start-time'. 2547 If a receiver previously received event records for this 2548 configured subscription, it can compare this time to the 2549 last event record previously received. If the two are not 2550 the same (perhaps due to a reboot), then a dynamic replay 2551 can be initiated to acquire any missing event records."; 2552 } 2553 } 2554 } 2555 } 2557 notification subscription-suspended { 2558 sn:subscription-state-notification; 2559 description 2560 "This notification indicates that a suspension of the 2561 subscription by the publisher has occurred. No further 2562 notifications will be sent until the subscription resumes. 2563 This notification shall only be sent to receivers of a 2564 subscription; it does not constitute a general-purpose 2565 notification."; 2566 leaf id { 2567 type subscription-id; 2568 mandatory true; 2569 description 2570 "This references the affected subscription."; 2571 } 2572 leaf reason { 2573 type identityref { 2574 base subscription-suspended-reason; 2575 } 2576 mandatory true; 2577 description 2578 "Identifies the condition which resulted in the suspension."; 2579 } 2580 } 2582 notification subscription-terminated { 2583 sn:subscription-state-notification; 2584 description 2585 "This notification indicates that a subscription has been 2586 terminated."; 2587 leaf id { 2588 type subscription-id; 2589 mandatory true; 2590 description 2591 "This references the affected subscription."; 2592 } 2593 leaf reason { 2594 type identityref { 2595 base subscription-terminated-reason; 2596 } 2597 mandatory true; 2598 description 2599 "Identifies the condition which resulted in the termination ."; 2600 } 2601 } 2603 /* 2604 * DATA NODES 2605 */ 2607 container streams { 2608 config false; 2609 description 2610 "This container contains information on the built-in event 2611 streams provided by the publisher."; 2612 list stream { 2613 key "name"; 2614 description 2615 "Identifies the built-in event streams that are supported by 2616 the publisher."; 2617 leaf name { 2618 type string; 2619 description 2620 "A handle for a system-provided event stream made up of a 2621 sequential set of event records, each of which is 2622 characterized by its own domain and semantics."; 2623 } 2624 leaf description { 2625 type string; 2626 description 2627 "A description of the event stream, including such 2628 information as the type of event records that are available 2629 within this event stream."; 2630 } 2631 leaf replay-support { 2632 if-feature "replay"; 2633 type empty; 2634 description 2635 "Indicates that event record replay is available on this 2636 event stream."; 2637 } 2638 leaf replay-log-creation-time { 2639 when "../replay-support"; 2640 if-feature "replay"; 2641 type yang:date-and-time; 2642 mandatory true; 2643 description 2644 "The timestamp of the creation of the log used to support the 2645 replay function on this event stream. This time might be 2646 earlier than the earliest available information contained in 2647 the log. This object is updated if the log resets for some 2648 reason."; 2649 } 2650 leaf replay-log-aged-time { 2651 when "../replay-support"; 2652 if-feature "replay"; 2653 type yang:date-and-time; 2654 description 2655 "The timestamp associated with last event record which has 2656 been aged out of the log. This timestamp identifies how far 2657 back into history this replay log extends, if it doesn't 2658 extend back to the 'replay-log-creation-time'. This object 2659 MUST be present if replay is supported and any event records 2660 have been aged out of the log."; 2661 } 2662 } 2663 } 2665 container filters { 2666 description 2667 "This container contains a list of configurable filters 2668 that can be applied to subscriptions. This facilitates 2669 the reuse of complex filters once defined."; 2670 list stream-filter { 2671 key "name"; 2672 description 2673 "A list of pre-configured filters that can be applied to 2674 subscriptions."; 2675 leaf name { 2676 type string; 2677 description 2678 "An name to differentiate between filters."; 2679 } 2680 uses stream-filter-elements; 2681 } 2682 } 2684 container subscriptions { 2685 description 2686 "Contains the list of currently active subscriptions, i.e. 2687 subscriptions that are currently in effect, used for 2688 subscription management and monitoring purposes. This includes 2689 subscriptions that have been setup via RPC primitives as well as 2690 subscriptions that have been established via configuration."; 2691 list subscription { 2692 key "id"; 2693 description 2694 "The identity and specific parameters of a subscription. 2695 Subscriptions within this list can be created using a control 2696 channel or RPC, or be established through configuration. 2698 If configuration operations or the 'kill-subscription' RPC are 2699 used to delete a subscription, a 'subscription-terminated' 2700 message is sent to any active or suspended receivers."; 2701 leaf id { 2702 type subscription-id; 2703 description 2704 "Identifier of a subscription; unique within a publisher"; 2705 } 2706 uses subscription-policy { 2707 refine "target/stream/stream" { 2708 description 2709 "Indicates the event stream to be considered for this 2710 subscription. If an event stream has been removed, 2711 and no longer can be referenced by an active subscription, 2712 send a 'subscription-terminated' notification with 2713 'stream-unavailable' as the reason. If a configured 2714 subscription refers to a non-existent event stream, move 2715 that subscription to the 'invalid' state."; 2716 } 2717 refine "transport" { 2718 description 2719 "For a configured subscription, this leaf specifies the 2720 transport used to deliver messages destined to all 2721 receivers of that subscription. This object is mandatory 2722 for subscriptions in the configuration datastore. This 2723 object is not mandatory for dynamic subscriptions within 2724 the operational state datastore. The object should not 2725 be present for dynamic subscriptions."; 2726 } 2727 augment "target/stream" { 2728 description 2729 "Enables objects to added to a configured stream 2730 subscription"; 2731 leaf configured-replay { 2732 if-feature "configured"; 2733 if-feature "replay"; 2734 type empty; 2735 description 2736 "The presence of this leaf indicates that replay for the 2737 configured subscription should start at the earliest time 2738 in the event log, or at the publisher boot time, which 2739 ever is later."; 2740 } 2741 } 2742 } 2743 choice notification-message-origin { 2744 if-feature "configured"; 2745 description 2746 "Identifies the egress interface on the publisher from which 2747 notification messages are to be sent."; 2748 case interface-originated { 2749 description 2750 "When notification messages to egress a specific, 2751 designated interface on the publisher."; 2752 leaf source-interface { 2753 if-feature "interface-designation"; 2754 type if:interface-ref; 2755 description 2756 "References the interface for notification messages."; 2757 } 2758 } 2759 case address-originated { 2760 description 2761 "When notification messages are to depart from a publisher 2762 using specific originating address and/or routing context 2763 information."; 2764 leaf source-vrf { 2765 if-feature "supports-vrf"; 2766 type leafref { 2767 path "/ni:network-instances/ni:network-instance/ni:name"; 2768 } 2769 description 2770 "VRF from which notification messages should egress a 2771 publisher."; 2772 } 2773 leaf source-address { 2774 type inet:ip-address-no-zone; 2775 description 2776 "The source address for the notification messages. If a 2777 source VRF exists, but this object doesn't, a publisher's 2778 default address for that VRF must be used."; 2779 } 2780 } 2781 } 2782 leaf configured-subscription-state { 2783 if-feature "configured"; 2784 type enumeration { 2785 enum valid { 2786 value 1; 2787 description 2788 "Subscription is supportable with current parameters."; 2789 } 2790 enum invalid { 2791 value 2; 2792 description 2793 "The subscription as a whole is unsupportable with its 2794 current parameters."; 2795 } 2796 enum concluded { 2797 value 3; 2798 description 2799 "A subscription is inactive as it has hit a stop time, 2800 it no longer has receivers in the 'receiver active' or 2801 'receiver suspended' state, but not yet been 2802 removed from configuration."; 2803 } 2804 } 2805 config false; 2806 description 2807 "The presence of this leaf indicates that the subscription 2808 originated from configuration, not through a control channel 2809 or RPC. The value indicates the system established state 2810 of the subscription."; 2811 } 2812 container receivers { 2813 description 2814 "Set of receivers in a subscription."; 2815 list receiver { 2816 key "name"; 2817 min-elements 1; 2818 description 2819 "A host intended as a recipient for the notification 2820 messages of a subscription. For configured subscriptions, 2821 transport specific network parameters (or a leafref to 2822 those parameters) may augmentated to a specific receiver 2823 within this list."; 2824 leaf name { 2825 type string; 2826 description 2827 "Identifies a unique receiver for a subscription."; 2828 } 2829 leaf sent-event-records { 2830 type yang:zero-based-counter64; 2831 config false; 2832 description 2833 "The number of event records sent to the receiver. The 2834 count is initialized when a dynamic subscription is 2835 established, or when a configured receiver 2836 transitions to the valid state."; 2837 } 2838 leaf excluded-event-records { 2839 type yang:zero-based-counter64; 2840 config false; 2841 description 2842 "The number of event records explicitly removed either 2843 via an event stream filter or an access control filter so 2844 that they are not passed to a receiver. This count is 2845 set to zero each time 'sent-event-records' is 2846 initialized."; 2847 } 2848 leaf state { 2849 type enumeration { 2850 enum active { 2851 value 1; 2852 description 2853 "Receiver is currently being sent any applicable 2854 notification messages for the subscription."; 2855 } 2856 enum suspended { 2857 value 2; 2858 description 2859 "Receiver state is 'suspended', so the publisher 2860 is currently unable to provide notification messages 2861 for the subscription."; 2862 } 2863 enum connecting { 2864 value 3; 2865 if-feature "configured"; 2866 description 2867 "A subscription has been configured, but a 2868 'subscription-started' subscription state change 2869 notification needs to be successfully received before 2870 notification messages are sent. 2872 If the 'reset' action is invoked for a receiver of an 2873 active configured subscription, the state must be 2874 moved to 'connecting'."; 2875 } 2876 enum disconnected { 2877 value 4; 2878 if-feature "configured"; 2879 description 2880 "A subscription has failed in sending a subscription 2881 started state change to the receiver. 2883 Additional attempts at connection attempts are not 2884 currently being made."; 2885 } 2886 } 2887 config false; 2888 mandatory true; 2889 description 2890 "Specifies the state of a subscription from the 2891 perspective of a particular receiver. With this info it 2892 is possible to determine whether a publisher is 2893 currently generating notification messages intended for 2894 that receiver."; 2895 } 2896 action reset { 2897 if-feature "configured"; 2898 description 2899 "Allows the reset of this configured subscription 2900 receiver to the 'connecting' state. This enables the 2901 connection process to be re-initiated."; 2902 output { 2903 leaf time { 2904 type yang:date-and-time; 2905 mandatory true; 2906 description 2907 "Time a publisher returned the receiver to a 2908 'connecting' state."; 2909 } 2910 } 2911 } 2912 } 2913 } 2914 } 2915 } 2916 } 2917 2919 5. Considerations 2921 5.1. IANA Considerations 2923 This document registers the following namespace URI in the "IETF XML 2924 Registry" [RFC3688]: 2926 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2927 Registrant Contact: The IESG. 2928 XML: N/A; the requested URI is an XML namespace. 2930 This document registers the following YANG module in the "YANG Module 2931 Names" registry [RFC6020]: 2933 Name: ietf-subscribed-notifications 2934 Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2935 Prefix: sn 2936 Reference: draft-ietf-netconf-ietf-subscribed-notifications-11.txt 2937 (RFC form) 2939 5.2. Implementation Considerations 2941 To support deployments including both configured and dynamic 2942 subscriptions, it is recommended to split the subscription "id" 2943 domain into static and dynamic halves. That way it eliminates the 2944 possibility of collisions if the configured subscriptions attempt to 2945 set a subscription-id which might have already been dynamically 2946 allocated. A best practice is to use lower half the "id" object's 2947 integer space when that "id" is assigned by an external entity (such 2948 as with a configured subscription). This leaves the upper half of 2949 subscription integer space available to be dynamically assigned by 2950 the publisher. 2952 If a subscription is unable to marshal a series of filtered event 2953 records into transmittable notification messages, the receiver should 2954 be suspended with the reason "unsupportable-volume". 2956 For configured subscriptions, operations are against the set of 2957 receivers using the subscription "id" as a handle for that set. But 2958 for streaming updates, subscription state change notifications are 2959 local to a receiver. In this specification it is the case that 2960 receivers get no information from the publisher about the existence 2961 of other receivers. But if a network operator wants to let the 2962 receivers correlate results, it is useful to use the subscription 2963 "id" across the receivers to allow that correlation. Note that due 2964 to the possibility of different access control permissions per 2965 receiver, each receiver may actually get a different set of event 2966 records. 2968 For configured replay subscriptions, the receiver is protected from 2969 duplicated events being pushed after a publisher is rebooted. 2970 However it is possible that a receiver might want to acquire event 2971 records which failed to be delivered just prior to the reboot. 2972 Delivering these event records be accomplished by leveraging the 2973 "eventTime" from the last event record received prior to the receipt 2974 of a "subscription-started" subscription state change notification. 2975 With this "eventTime" and the "replay-start-time" from the 2976 "subscription-started" notification, an independent dynamic 2977 subscription can be established which retrieves any event records 2978 which may have been generated but not sent to the receiver. 2980 5.3. Transport Requirements 2982 This section provides requirements for any subscribed notification 2983 transport supporting the solution presented in this document. 2985 The transport selected by the subscriber to reach the publisher MUST 2986 be able to support multiple "establish-subscription" requests made 2987 within the same transport session. 2989 For both configured and dynamic subscriptions the publisher MUST 2990 authenticate a receiver via some transport level mechanism before 2991 sending any event records for which they are authorized to see. In 2992 addition, the receiver MUST authenticate the publisher at the 2993 transport level. The result is mutual authentication between the 2994 two. 2996 A secure transport is highly recommended. Beyond this, the publisher 2997 MUST ensure that the receiver has sufficient authorization to perform 2998 the function they are requesting against the specific subset of 2999 content involved. 3001 A specific transport specification built upon this document may or 3002 may not choose to require the use of the same logical channel for the 3003 RPCs and the event records. However the event records and the 3004 subscription state change notifications MUST be sent on the same 3005 transport session to ensure the properly ordered delivery. 3007 A specific transport specification MUST identity any encoding 3008 supported. Where a configured subscription's transport allows 3009 different encodings, the specification MUST identify the default 3010 encoding. 3012 Additional transport requirements will be dictated by the choice of 3013 transport used with a subscription. For an example of such 3014 requirements with NETCONF transport, see 3015 [I-D.draft-ietf-netconf-netconf-event-notifications]. 3017 5.4. Security Considerations 3019 The YANG module specified in this document defines a schema for data 3020 that is designed to be accessed via network management transports 3021 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 3022 layer is the secure transport layer, and the mandatory-to-implement 3023 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 3024 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 3025 transport is TLS [RFC5246]. 3027 The NETCONF Access Control Model (NACM) [RFC8341] provides the means 3028 to restrict access for particular NETCONF or RESTCONF users to a 3029 preconfigured subset of all available NETCONF or RESTCONF operations 3030 and content. 3032 With configured subscriptions, one or more publishers could be used 3033 to overwhelm a receiver. To counter this, notification messages 3034 SHOULD NOT be sent to any receiver which does not support this 3035 specification. Receivers that do not want notification messages need 3036 only terminate or refuse any transport sessions from the publisher. 3038 When a receiver of a configured subscription gets a new 3039 "subscription-started" message for a known subscription where it is 3040 already consuming events, it may indicate that an attacker has done 3041 something that has momentarily disrupted receiver connectivity. To 3042 acquire events lost during this interval, the receiver SHOULD 3043 retrieve any event records generated since the last event record was 3044 received. This can be accomplished by establishing a separate 3045 dynamic replay subscription with the same filtering criteria with the 3046 publisher, assuming the publisher supports the "replay" feature. 3048 For dynamic subscriptions, implementations need to protect against 3049 malicious or buggy subscribers which may send a large number 3050 "establish-subscription" requests, thereby using up system resources. 3051 To cover this possibility operators SHOULD monitor for such cases 3052 and, if discovered, take remedial action to limit the resources used, 3053 such as suspending or terminating a subset of the subscriptions or, 3054 if the underlying transport is session based, terminate the 3055 underlying transport session. 3057 The replay mechanisms described in Sections Section 2.4.2.1 and 3058 Section 2.5.6 provides access to historical event records. By 3059 design, the access control model that protects these records could 3060 enable subscribers to view data to which they were not authorized at 3061 the time of collection. 3063 Using DNS names for configured subscription receiver "name" lookup 3064 can cause situations where the name resolves unexpectedly differently 3065 on the publisher, so the recipient would be different than expected. 3067 An attacker that can cause the publisher to use an incorrect time can 3068 induce message replay by setting the time in the past, and introduce 3069 a risk of message loss by setting the time in the future. 3071 There are a number of data nodes defined in this YANG module that are 3072 writable/creatable/deletable (i.e., config true, which is the 3073 default). These data nodes may be considered sensitive or vulnerable 3074 in some network environments. Write operations (e.g., edit-config) 3075 to these data nodes without proper protection can have a negative 3076 effect on network operations. These are the subtrees and data nodes 3077 where there is a specific sensitivity/vulnerability: 3079 Container: "/filters" 3081 o "stream-subtree-filter": updating a filter could increase the 3082 computational complexity of all referencing subscriptions. 3084 o "stream-xpath-filter": updating a filter could increase the 3085 computational complexity of all referencing subscriptions. 3087 Container: "/subscriptions" 3089 The following considerations are only relevant for configuration 3090 operations made upon configured subscriptions: 3092 o "configured-replay": can be used to send a large number of event 3093 records to a receiver. 3095 o "dependency": can be used to force important traffic to be queued 3096 behind less important updates. 3098 o "dscp": if unvalidated, can result in the sending of traffic with 3099 a higher priority marking than warranted. 3101 o "id": can overwrite an existing subscription, perhaps one 3102 configured by another entity. 3104 o "name": adding a new key entry can be used to attempt to send 3105 traffic to an unwilling receiver. 3107 o "replay-start-time": can be used to push very large logs, wasting 3108 resources. 3110 o "source-address": the configured address might not be able to 3111 reach a desired receiver. 3113 o "source-interface": the configured interface might not be able to 3114 reach a desired receiver. 3116 o "source-vrf": can place a subscription into a virtual network 3117 where receivers are not entitled to view the subscribed content. 3119 o "stop-time": could be used to terminate content at an inopportune 3120 time. 3122 o "stream": could set a subscription to an event stream containing 3123 no content permitted for the targeted receivers. 3125 o "stream-filter-name": could be set to a filter which is irrelevant 3126 to the event stream. 3128 o "stream-subtree-filter": a complex filter can increase the 3129 computational resources for this subscription. 3131 o "stream-xpath-filter": a complex filter can increase the 3132 computational resources for this subscription. 3134 o "weighting": placing a large weight can overwhelm the dequeuing of 3135 other subscriptions. 3137 Some of the readable data nodes in this YANG module may be considered 3138 sensitive or vulnerable in some network environments. It is thus 3139 important to control read access (e.g., via get, get-config, or 3140 notification) to these data nodes. These are the subtrees and data 3141 nodes and their sensitivity/vulnerability: 3143 Container: "/streams" 3145 o "name": if access control is not properly configured, can expose 3146 system internals to those who should have no access to this 3147 information. 3149 o "replay-support": if access control is not properly configured, 3150 can expose logs to those who should have no access. 3152 Container: "/subscriptions" 3154 o "excluded-event-records": leaf can provide information about 3155 filtered event records. A network operator should have 3156 permissions to know about such filtering. Improper configuration 3157 could provide a receiver with information leakage consisting of 3158 the dropping of event records. 3160 o "subscription": different operational teams might have a desire to 3161 set varying subsets of subscriptions. Access control should be 3162 designed to permit read access to just the allowed set. 3164 Some of the RPC operations in this YANG module may be considered 3165 sensitive or vulnerable in some network environments. It is thus 3166 important to control access to these operations. These are the 3167 operations and their sensitivity/vulnerability: 3169 RPC: all 3171 o If a malicious or buggy subscriber sends an unexpectedly large 3172 number of RPCs, the result might be an excessive use of system 3173 resources on the publisher just to determine that these 3174 subscriptions should be declined. In such a situation, 3175 subscription interactions MAY be terminated by terminating the 3176 transport session. 3178 RPC: "delete-subscription" 3180 o No special considerations. 3182 RPC: "establish-subscription" 3184 o Subscriptions could overload a publisher's resources. For this 3185 reason, publishers MUST ensure that they have sufficient resources 3186 to fulfill this request or otherwise reject the request. 3188 RPC: "kill-subscription" 3190 o The "kill-subscription" RPC MUST be secured so that only 3191 connections with administrative rights are able to invoke this 3192 RPC. 3194 RPC: "modify-subscription" 3196 o Subscriptions could overload a publisher's resources. For this 3197 reason, publishers MUST ensure that they have sufficient resources 3198 to fulfill this request or otherwise reject the request. 3200 6. Acknowledgments 3202 For their valuable comments, discussions, and feedback, we wish to 3203 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen, 3204 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan 3205 Hares, Michael Scharf, and Guangying Zheng. 3207 7. References 3209 7.1. Normative References 3211 [I-D.draft-ietf-rtgwg-ni-model] 3212 Berger, L., Hopps, C., and A. Lindem, "YANG Network 3213 Instances", draft-ietf-rtgwg-ni-model-12 (work in 3214 progress), March 2018. 3216 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3217 Requirement Levels", BCP 14, RFC 2119, 3218 DOI 10.17487/RFC2119, March 1997, 3219 . 3221 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 3222 "Definition of the Differentiated Services Field (DS 3223 Field) in the IPv4 and IPv6 Headers", RFC 2474, 3224 DOI 10.17487/RFC2474, December 1998, 3225 . 3227 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3228 DOI 10.17487/RFC3688, January 2004, 3229 . 3231 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3232 (TLS) Protocol Version 1.2", RFC 5246, 3233 DOI 10.17487/RFC5246, August 2008, 3234 . 3236 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3237 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 3238 . 3240 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 3241 the Network Configuration Protocol (NETCONF)", RFC 6020, 3242 DOI 10.17487/RFC6020, October 2010, 3243 . 3245 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3246 and A. Bierman, Ed., "Network Configuration Protocol 3247 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 3248 . 3250 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 3251 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 3252 . 3254 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 3255 RFC 6991, DOI 10.17487/RFC6991, July 2013, 3256 . 3258 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3259 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3260 . 3262 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3263 RFC 7951, DOI 10.17487/RFC7951, August 2016, 3264 . 3266 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 3267 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 3268 . 3270 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3271 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3272 May 2017, . 3274 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 3275 Access Control Model", STD 91, RFC 8341, 3276 DOI 10.17487/RFC8341, March 2018, 3277 . 3279 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 3280 and R. Wilton, "Network Management Datastore Architecture 3281 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 3282 . 3284 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 3285 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 3286 . 3288 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 3289 Version 1.0", November 1999, 3290 . 3292 7.2. Informative References 3294 [I-D.draft-ietf-netconf-netconf-event-notifications] 3295 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3296 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 3297 event notifications", May 2018, 3298 . 3301 [I-D.draft-ietf-netconf-restconf-notif] 3302 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen- 3303 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and 3304 HTTP transport for event notifications", May 2018, 3305 . 3308 [I-D.ietf-netconf-yang-push] 3309 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3310 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 3311 Lengyel, "YANG Datastore Subscription", May 2018, 3312 . 3315 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3316 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3317 October 2013, . 3319 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 3320 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 3321 DOI 10.17487/RFC7540, May 2015, 3322 . 3324 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 3325 for Subscription to YANG Datastores", RFC 7923, 3326 DOI 10.17487/RFC7923, June 2016, 3327 . 3329 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 3330 RFC 8071, DOI 10.17487/RFC8071, February 2017, 3331 . 3333 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3334 Interchange Format", STD 90, RFC 8259, 3335 DOI 10.17487/RFC8259, December 2017, 3336 . 3338 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3339 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3340 . 3342 Appendix A. Example Configured Transport Augmentation 3344 This appendix provides a non-normative example of how the YANG model 3345 defined in Section 4 may be enhanced to incorporate the configuration 3346 parameters needed to support the transport connectivity process. 3347 This example is not intended to be a complete transport model. In 3348 this example, connectivity via an imaginary transport type of "foo" 3349 is explored. For more on the overall need, see Section 2.5.7. 3351 The YANG model defined in this section contains two main elements. 3352 First is a transport identity "foo". This transport identity allows 3353 a configuration agent to define "foo" as the selected type of 3354 transport for a subscription. Second is a YANG case augmentation 3355 "foo" which is made to the "/subscriptions/subscription/receivers/ 3356 receiver" node of Section 4. Within this augmentation are the 3357 transport configuration parameters "address" and "port" which are 3358 necessary to make the connect to the receiver. 3360 module example-foo-subscribed-notifications { 3361 yang-version 1.1; 3362 namespace 3363 "urn:example:foo-subscribed-notifications"; 3365 prefix fsn; 3367 import ietf-subscribed-notifications { 3368 prefix sn; 3369 } 3370 import ietf-inet-types { 3371 prefix inet; 3372 } 3374 description 3375 "Defines 'foo' as a supported type of configured transport for 3376 subscribed event notifications."; 3378 identity foo { 3379 base sn:transport; 3380 description 3381 "Transport type 'foo' is available for use as a configured 3382 subscription transport protocol for subscribed notifications."; 3383 } 3385 augment 3386 "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { 3387 when 'derived-from(../../../transport, "fsn:foo")'; 3388 description 3389 "This augmentation makes 'foo' specific transport parameters 3390 available for a receiver."; 3391 leaf address { 3392 type inet:host; 3393 mandatory true; 3394 description 3395 "Specifies the address to use for messages destined to a 3396 receiver."; 3397 } 3398 leaf port { 3399 type inet:port-number; 3400 mandatory true; 3401 description 3402 "Specifies the port number to use for messages destined to a 3403 receiver."; 3404 } 3405 } 3406 } 3408 Figure 21: Example Transport Augmentation for the fictitious protocol 3409 foo 3411 This example YANG model for transport "foo" will not be seen in a 3412 real world deployment. For a real world deployment supporting an 3413 actual transport technology, a similar YANG model must be defined. 3415 Appendix B. Changes between revisions 3417 (To be removed by RFC editor prior to publication) 3419 v24 - v25 3421 o Replay security consideration added based on Roman Danyliw's 3422 discuss 3424 o Spelling fixes, acronyms expanded 3426 o Tweaks and updates based Benjamin Kaduk's comments. This includes 3427 the adding of clarifying security considerations, a couple of 3428 claifications in the YANG definitions, and ensuring a fuller set 3429 of transport specification requirements are defined in 5.3. 3431 v23 - v24 3433 o Per Benjamin Kaduk's discuss, adjusted IPR to pre5378Trust200902 3435 o Tweaks from Chris Lonvick's IESG review. This includes moving a 3436 paragraph from Security Considerations into a sentence within 3437 Implementation Considerations. 3439 o Tweaks from Wesley Eddy DSCP description 3441 v22 - v23 3442 o During the YANG Doctor review, feature dscp support was refined to 3443 avoid the out-of-order delivery of packets in a single TCP 3444 session. 3446 v21 - v22 3448 o YANG Dr definition clarifications. This includes refined text on: 3449 (a) stop-time can be used without replay, (b) a separate dynamic 3450 subscription for replay, (c) subscription state change 3451 notifications can't be dropped, more details on "enum concluded" 3452 and (d) more text on configurable-encoding leaf (which adds two 3453 informative references). There also was one minor tweak in the 3454 YANG model. The stream description leaf had "mandatory true" 3455 removed. 3457 v20 - v21 3459 o Editorial change in Section 1.3 requested by Qin's Shepherd review 3460 of NETCONF-Notif and RESTCONF-Notif. Basically extra text was 3461 added further describing that dynamic subscriptions can have state 3462 change notifications. 3464 v18 - v20 3466 o XPath-stream-filter YANG object definition updated based on NETMOD 3467 discussions. 3469 v17 - v18 3471 o Transport optional in YANG model. 3473 o Modify subscription must come from the originator of the 3474 subscription. (Text got dropped somewhere previously.) 3476 o Title change. 3478 v16 - v17 3480 o YANG renaming: Subscription identifier renamed to id. Counters 3481 renamed. Filters id made into name. 3483 o Text tweaks. 3485 v15 - v16 3487 o Mandatory empty case "transport" removed. 3489 o Appendix case turned from "netconf" to "foo". 3491 v14 - v15 3493 o Text tweaks. 3495 o Mandatory empty case "transport" added for transport parameters. 3496 This includes a new section and an appendix explaining it. 3498 v13 - v14 3500 o Removed the 'address' leaf. 3502 o Replay is now of type 'empty' for configured. 3504 v12 - v13 3506 o Tweaks from Kent's comments 3508 o Referenced in YANG model updated per Tom Petch's comments 3510 o Added leaf replay-previous-event-time 3512 o Renamed the event counters, downshifted the subscription states 3514 v11 - v12 3516 o Tweaks from Kent's, Tim's, and Martin's comments 3518 o Clarified dscp text, and made its own feature 3520 o YANG model tweaks alphabetizing, features. 3522 v10 - v11 3524 o access control filtering of events in streams included to match 3525 RFC5277 behavior 3527 o security considerations updated based on YANG template. 3529 o dependency QoS made non-normative on HTTP2 QoS 3531 o tree diagrams referenced for each figure using them 3533 o reference numbers placed into state machine figures 3535 o broke configured replay into its own section 3537 o many tweaks updates based on LC and YANG doctor reviews 3538 o trees and YANG model reconciled were deltas existed 3540 o new feature for interface originated. 3542 o dscp removed from the qos feature 3544 o YANG model updated in a way which collapses groups only used once 3545 so that they are part of the 'subscriptions' container. 3547 o alternative encodings only allowed for transports which support 3548 them. 3550 v09 - v10 3552 o Typos and tweaks 3554 v08 - v09 3556 o NMDA model supported. Non NMDA version at https://github.com/ 3557 netconf-wg/rfc5277bis/ 3559 o Error mechanism revamped to match to embedded implementations. 3561 o Explicitly identified error codes relevant to each RPC/ 3562 Notification 3564 v07 - v08 3566 o Split YANG trees to separate document subsections. 3568 o Clarified configured state machine based on Balazs comments, and 3569 moved it into the configured subscription subsections. 3571 o Normative reference to Network Instance model for VRF 3573 o One transport for all receivers of configured subscriptions. 3575 o QoS section moved in from yang-push 3577 v06 - v07 3579 o Clarification on state machine for configured subscriptions. 3581 v05 - v06 3583 o Made changes proposed by Martin, Kent, and others on the list. 3584 Most significant of these are stream returned to string (with the 3585 SYSLOG identity removed), intro section on 5277 relationship, an 3586 identity set moved to an enumeration, clean up of definitions/ 3587 terminology, state machine proposed for configured subscriptions 3588 with a clean-up of subscription state options. 3590 o JSON and XML become features. Also Xpath and subtree filtering 3591 become features 3593 o Terminology updates with event records, and refinement of filters 3594 to just event stream filters. 3596 o Encoding refined in establish-subscription so it takes the RPC's 3597 encoding as the default. 3599 o Namespaces in examples fixed. 3601 v04 - v05 3603 o Returned to the explicit filter subtyping of v00 3605 o stream object changed to 'name' from 'stream' 3607 o Cleaned up examples 3609 o Clarified that JSON support needs notification-messages draft. 3611 v03 - v04 3613 o Moved back to the use of RFC5277 one-way notifications and 3614 encodings. 3616 v03 - v04 3618 o Replay updated 3620 v02 - v03 3622 o RPCs and Notification support is identified by the Notification 3623 2.0 capability. 3625 o Updates to filtering identities and text 3627 o New error type for unsupportable volume of updates 3629 o Text tweaks. 3631 v01 - v02 3633 o Subscription status moved under receiver. 3635 v00 - v01 3637 o Security considerations updated 3639 o Intro rewrite, as well as scattered text changes 3641 o Added Appendix A, to help match this to related drafts in progress 3643 o Updated filtering definitions, and filter types in yang file, and 3644 moved to identities for filter types 3646 o Added Syslog as an event stream 3648 o HTTP2 moved in from YANG-Push as a transport option 3650 o Replay made an optional feature for events. Won't apply to 3651 datastores 3653 o Enabled notification timestamp to have different formats. 3655 o Two error codes added. 3657 v01 5277bis - v00 subscribed notifications 3659 o Kill subscription RPC added. 3661 o Renamed from 5277bis to Subscribed Notifications. 3663 o Changed the notification capabilities version from 1.1 to 2.0. 3665 o Extracted create-subscription and other elements of RFC5277. 3667 o Error conditions added, and made specific in return codes. 3669 o Simplified yang model structure for removal of 'basic' grouping. 3671 o Added a grouping for items which cannot be statically configured. 3673 o Operational counters per receiver. 3675 o Subscription-id and filter-id renamed to identifier 3677 o Section for replay added. Replay now cannot be configured. 3679 o Control plane notification renamed to subscription state change 3680 notification 3682 o Source address: Source-vrf changed to string, default address 3683 option added 3685 o In yang model: 'info' changed to 'policy' 3687 o Scattered text clarifications 3689 v00 - v01 of 5277bis 3691 o YANG Model changes. New groupings for subscription info to allow 3692 restriction of what is changeable via RPC. Removed notifications 3693 for adding and removing receivers of configured subscriptions. 3695 o Expanded/renamed definitions from event server to publisher, and 3696 client to subscriber as applicable. Updated the definitions to 3697 include and expand on RFC 5277. 3699 o Removal of redundancy with other drafts 3701 o Many other clean-ups of wording and terminology 3703 Authors' Addresses 3705 Eric Voit 3706 Cisco Systems 3708 Email: evoit@cisco.com 3710 Alexander Clemm 3711 Huawei 3713 Email: ludwig@clemm.org 3715 Alberto Gonzalez Prieto 3716 Microsoft 3718 Email: alberto.gonzalez@microsoft.com 3720 Einar Nilsen-Nygaard 3721 Cisco Systems 3723 Email: einarnn@cisco.com 3724 Ambika Prasad Tripathy 3725 Cisco Systems 3727 Email: ambtripa@cisco.com