idnits 2.17.1 draft-ietf-netconf-subscribed-notifications-23.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 1324 has weird spacing: '... reason ide...' == Line 1359 has weird spacing: '... reason ide...' == Line 1375 has weird spacing: '...--ro id sub...' == Line 1390 has weird spacing: '...--ro id sub...' == Line 1411 has weird spacing: '...--ro id sub...' == (3 more instances...) -- The document date (February 13, 2019) is 1899 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 (~~), 7 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: August 17, 2019 Huawei 6 A. Gonzalez Prieto 7 Microsoft 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 February 13, 2019 13 Subscription to YANG Event Notifications 14 draft-ietf-netconf-subscribed-notifications-23 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 August 17, 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 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 5 62 1.4. Relationship to RFC 5277 . . . . . . . . . . . . . . . . 6 63 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 7 65 2.2. Event Stream Filters . . . . . . . . . . . . . . . . . . 8 66 2.3. QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 2.4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 9 68 2.5. Configured Subscriptions . . . . . . . . . . . . . . . . 17 69 2.6. Event Record Delivery . . . . . . . . . . . . . . . . . . 25 70 2.7. Subscription state change notifications . . . . . . . . . 26 71 2.8. Subscription Monitoring . . . . . . . . . . . . . . . . . 31 72 2.9. Advertisement . . . . . . . . . . . . . . . . . . . . . . 32 73 3. YANG Data Model Trees . . . . . . . . . . . . . . . . . . . . 32 74 3.1. Event Streams Container . . . . . . . . . . . . . . . . . 32 75 3.2. Filters Container . . . . . . . . . . . . . . . . . . . . 33 76 3.3. Subscriptions Container . . . . . . . . . . . . . . . . . 33 77 4. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 35 78 5. Considerations . . . . . . . . . . . . . . . . . . . . . . . 62 79 5.1. IANA Considerations . . . . . . . . . . . . . . . . . . . 62 80 5.2. Implementation Considerations . . . . . . . . . . . . . . 63 81 5.3. Transport Requirements . . . . . . . . . . . . . . . . . 64 82 5.4. Security Considerations . . . . . . . . . . . . . . . . . 64 83 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 68 84 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 85 7.1. Normative References . . . . . . . . . . . . . . . . . . 68 86 7.2. Informative References . . . . . . . . . . . . . . . . . 70 87 Appendix A. Example Configured Transport Augmentation . . . . . 71 88 Appendix B. Changes between revisions . . . . . . . . . . . . . 72 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78 91 1. Introduction 93 This document defines a YANG data model and associated mechanisms 94 enabling subscriber-specific subscriptions to a publisher's event 95 streams. Effectively this enables a 'subscribe then publish' 96 capability where the customized information needs and access 97 permissions of each target receiver are understood by the publisher 98 before subscribed event records are marshaled and pushed. The 99 receiver then gets a continuous, custom feed of publisher generated 100 information. 102 While the functionality defined in this document is transport- 103 agnostic, transports like NETCONF [RFC6241] or RESTCONF [RFC8040] can 104 be used to configure or dynamically signal subscriptions, and there 105 are bindings defined for subscribed event record delivery for NETCONF 106 within [I-D.draft-ietf-netconf-netconf-event-notifications], and for 107 RESTCONF within [I-D.draft-ietf-netconf-restconf-notif]. 109 The YANG model in this document conforms to the Network Management 110 Datastore Architecture defined in [RFC8342]. 112 1.1. Motivation 114 Various limitations in [RFC5277] are discussed in [RFC7923]. 115 Resolving these issues is the primary motivation for this work. Key 116 capabilities supported by this document include: 118 o multiple subscriptions on a single transport session 120 o support for dynamic and configured subscriptions 122 o modification of an existing subscription in progress 124 o per-subscription operational counters 126 o negotiation of subscription parameters (through the use of hints 127 returned as part of declined subscription requests) 129 o subscription state change notifications (e.g., publisher driven 130 suspension, parameter modification) 132 o independence from transport 134 1.2. Terminology 136 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 137 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 138 "OPTIONAL" in this document are to be interpreted as described in BCP 139 14 [RFC2119] [RFC8174] when, and only when, they appear in all 140 capitals, as shown here. 142 Client: defined in [RFC8342]. 144 Configuration: defined in [RFC8342]. 146 Configuration datastore: defined in [RFC8342]. 148 Configured subscription: A subscription installed via configuration 149 into a configuration datastore. 151 Dynamic subscription: A subscription created dynamically by a 152 subscriber via a remote procedure call. 154 Event: An occurrence of something that may be of interest. Examples 155 include a configuration change, a fault, a change in status, crossing 156 a threshold, or an external input to the system. 158 Event occurrence time: a timestamp matching the time an originating 159 process identified as when an event happened. 161 Event record: A set of information detailing an event. 163 Event stream: A continuous, chronologically ordered set of events 164 aggregated under some context. 166 Event stream filter: Evaluation criteria which may be applied against 167 event records within an event stream. Event records pass the filter 168 when specified criteria are met. 170 Notification message: Information intended for a receiver indicating 171 that one or more events have occurred. 173 Publisher: An entity responsible for streaming notification messages 174 per the terms of a subscription. 176 Receiver: A target to which a publisher pushes subscribed event 177 records. For dynamic subscriptions, the receiver and subscriber are 178 the same entity. 180 Subscriber: A client able to request and negotiate a contract for the 181 generation and push of event records from a publisher. For dynamic 182 subscriptions, the receiver and subscriber are the same entity. 184 Subscription: A contract with a publisher, stipulating which 185 information one or more receivers wish to have pushed from the 186 publisher without the need for further solicitation. 188 All YANG tree diagrams used in this document follow the notation 189 defined in [RFC8340]. 191 1.3. Solution Overview 193 This document describes a transport agnostic mechanism for 194 subscribing to and receiving content from an event stream within a 195 publisher. This mechanism is through the use of a subscription. 197 Two types of subscriptions are supported: 199 1. Dynamic subscriptions, where a subscriber initiates a 200 subscription negotiation with a publisher via an RPC. If the 201 publisher is able to serve this request, it accepts it, and then 202 starts pushing notification messages back to the subscriber. If 203 the publisher is not able to serve it as requested, then an error 204 response is returned. This response MAY include hints at 205 subscription parameters that, had they been present, may have 206 enabled the dynamic subscription request to be accepted. 208 2. Configured subscriptions, which allow the management of 209 subscriptions via a configuration so that a publisher can send 210 notification messages to a receiver. Support for configured 211 subscriptions is optional, with its availability advertised via a 212 YANG feature. 214 Additional characteristics differentiating configured from dynamic 215 subscriptions include: 217 o The lifetime of a dynamic subscription is bound by the transport 218 session used to establish it. For connection-oriented stateful 219 transports like NETCONF, the loss of the transport session will 220 result in the immediate termination of any associated dynamic 221 subscriptions. For connectionless or stateless transports like 222 HTTP, a lack of receipt acknowledgment of a sequential set of 223 notification messages and/or keep-alives can be used to trigger a 224 termination of a dynamic subscription. Contrast this to the 225 lifetime of a configured subscription. This lifetime is driven by 226 relevant configuration being present within the publisher's 227 applied configuration. Being tied to configuration operations 228 implies configured subscriptions can be configured to persist 229 across reboots, and implies a configured subscription can persist 230 even when its publisher is fully disconnected from any network. 232 o Configured subscriptions can be modified by any configuration 233 client with write permission on the configuration of the 234 subscription. Dynamic subscriptions can only be modified via an 235 RPC request made by the original subscriber, or a change to 236 configuration data referenced by the subscription. 238 Note that there is no mixing-and-matching of dynamic and configured 239 operations on a single subscription. Specifically, a configured 240 subscription cannot be modified or deleted using RPCs defined in this 241 document. Similarly, a dynamic subscription cannot be directly 242 modified or deleted by configuration operations. It is however 243 possible to perform a configuration operation which indirectly 244 impacts a dynamic subscription. By changing value of a pre- 245 configured filter referenced by an existing dynamic subscription, the 246 selected event records passed to a receiver might change. 248 Also note that transport specific transport drafts based on this 249 specification MUST detail the life cycle of dynamic subscriptions, as 250 well as the lifecycle of configured subscriptions (if supported). 252 A publisher MAY terminate a dynamic subscription at any time. 253 Similarly, it MAY decide to temporarily suspend the sending of 254 notification messages for any dynamic subscription, or for one or 255 more receivers of a configured subscription. Such termination or 256 suspension is driven by internal considerations of the publisher. 258 1.4. Relationship to RFC 5277 260 This document is intended to provide a superset of the subscription 261 capabilities initially defined within [RFC5277]. Especially when 262 extending an existing [RFC5277] implementation, it is important to 263 understand what has been reused and what has been replaced. Key 264 relationships between these two documents include: 266 o this document defines a transport independent capability, 267 [RFC5277] is specific to NETCONF. 269 o the data model in this document is used instead of the data model 270 in Section 3.4 of [RFC5277] for the new operations. 272 o the RPC operations in this draft replace the operation "create- 273 subscription" defined in [RFC5277], section 4. 275 o the message of [RFC5277], Section 4 is used. 277 o the included contents of the "NETCONF" event stream are identical 278 between this document and [RFC5277]. 280 o a publisher MAY implement both the Notification Management Schema 281 and RPCs defined in [RFC5277] and this new document concurrently. 283 o unlike [RFC5277], this document enables a single transport session 284 to intermix notification messages and RPCs for different 285 subscriptions. 287 o A subscription "stop-time" can be specified as part of a 288 notification replay. This supports an analogous capability to the 289 stopTime parameter of [RFC5277]. However in this specification, a 290 "stop-time" parameter can also be applied without replay. 292 2. Solution 294 Per the overview provided in Section 1.3, this section details the 295 overall context, state machines, and subsystems which may be 296 assembled to allow the subscription of events from a publisher. 298 2.1. Event Streams 300 An event stream is a named entity on a publisher which exposes a 301 continuously updating set of YANG encoded event records. An event 302 record is an instantiation of a "notification" YANG statement. If 303 the "notification" is defined as a child to a data node, the 304 instantiation includes the hierarchy of nodes that identifies the 305 data node in the datastore (see Section 7.16.2 of [RFC7950]). Each 306 event stream is available for subscription. It is out of the scope 307 of this document to identify a) how event streams are defined (other 308 than the NETCONF stream), b) how event records are defined/generated, 309 and c) how event records are assigned to event streams. 311 There is only one reserved event stream name within this document: 312 "NETCONF". The "NETCONF" event stream contains all NETCONF event 313 record information supported by the publisher, except where an event 314 record has explicitly been excluded from the stream. Beyond the 315 "NETCONF" stream, implementations MAY define additional event 316 streams. 318 As YANG encoded event records are created by a system, they may be 319 assigned to one or more streams. The event record is distributed to 320 a subscription's receiver(s) where: (1) a subscription includes the 321 identified stream, and (2) subscription filtering does not exclude 322 the event record from that receiver. 324 Access control permissions may be used to silently exclude event 325 records from within an event stream for which the receiver has no 326 read access. As an example of how this might be accomplished, see 327 [RFC8341] section 3.4.6. Note that per Section 2.7 of this document, 328 subscription state change notifications are never filtered out. 330 If no access control permissions are in place for event records on an 331 event stream, then a receiver MUST be allowed access to all the event 332 records. If subscriber permissions change during the lifecycle of a 333 subscription and event stream access is no longer permitted, then the 334 subscription MUST be terminated. 336 Event records MUST NOT be delivered to a receiver in a different 337 order than they were placed onto an event stream. 339 2.2. Event Stream Filters 341 This document defines an extensible filtering mechanism. The filter 342 itself is a boolean test which is placed on the content of an event 343 record. A 'false' filtering result causes the event record to be 344 excluded from delivery to a receiver. A filter never results in 345 information being stripped from within an event record prior to that 346 event record being encapsulated within a notification message. The 347 two optional event stream filtering syntaxes supported are [XPATH] 348 and subtree [RFC6241]. 350 If no event stream filter is provided within a subscription, all 351 event records on an event stream are to be sent. 353 2.3. QoS 355 This document provides for several QoS parameters. These parameters 356 indicate the treatment of a subscription relative to other traffic 357 between publisher and receiver. Included are: 359 o A "dscp" marking to differentiate prioritization of notification 360 messages during network transit. 362 o A "weighting" so that bandwidth proportional to this weighting can 363 be allocated to this subscription relative to other subscriptions. 365 o a "dependency" upon another subscription. 367 If the publisher supports the "dscp" feature, then a subscription 368 with a "dscp" leaf MUST result in a corresponding [RFC2474] DSCP 369 marking being placed within the IP header of any resulting 370 notification messages and subscription state change notifications. 371 Where TCP is used, a publisher which supports the "dscp" feature 372 SHOULD ensure that a subscription's notification messages are 373 returned within a single TCP transport session where all traffic 374 shares the subscription's "dscp" leaf value. Where this cannot be 375 guaranteed, any "establish subscription" RPC request SHOULD be 376 rejected with a "dscp-unavailable" error 378 For the "weighting" parameter, when concurrently dequeuing 379 notification messages from multiple subscriptions to a receiver, the 380 publisher MUST allocate bandwidth to each subscription proportionally 381 to the weights assigned to those subscriptions. "Weighting" is an 382 optional capability of the publisher; support for it is identified 383 via the "qos" feature. 385 If a subscription has the "dependency" parameter set, then any 386 buffered notification messages containing event records selected by 387 the parent subscription MUST be dequeued prior to the notification 388 messages of the dependent subscription. If notification messages 389 have dependencies on each other, the notification message queued the 390 longest MUST go first. If a "dependency" included within an RPC 391 references a subscription which does not exist or is no longer 392 accessible to that subscriber, that "dependency" MUST be silently 393 removed. "Dependency" is an optional capability of the publisher; 394 support for it is identified via the "qos" feature. 396 2.4. Dynamic Subscriptions 398 Dynamic subscriptions are managed via protocol operations (in the 399 form of [RFC7950], Section 7.14 RPCs) made against targets located 400 within the publisher. These RPCs have been designed extensibly so 401 that they may be augmented for subscription targets beyond event 402 streams. For examples of such augmentations, see the RPC 403 augmentations within [I-D.ietf-netconf-yang-push]'s YANG model. 405 2.4.1. Dynamic Subscription State Model 407 Below is the publisher's state machine for a dynamic subscription. 408 Each state is shown in its own box. It is important to note that 409 such a subscription doesn't exist at the publisher until an 410 "establish-subscription" RPC is accepted. The mere request by a 411 subscriber to establish a subscription is insufficient for that 412 subscription to be externally visible. Start and end states are 413 depicted to reflect subscription creation and deletion events. 415 ......... 416 : start : 417 :.......: 418 | 419 establish-subscription 420 | 421 | .-------modify-subscription--------. 422 v v | 423 .-----------. .-----------. 424 .--------. | receiver |--insufficient CPU, b/w-->| receiver | 425 modify- '| active | | suspended | 426 subscription | |<----CPU, b/w sufficient--| | 427 ---------->'-----------' '-----------' 428 | | 429 delete/kill-subscription delete/kill- 430 | subscription 431 v | 432 ......... | 433 : end :<---------------------------------' 434 :.......: 436 Figure 1: Publisher's state for a dynamic subscription 438 Of interest in this state machine are the following: 440 o Successful "establish-subscription" or "modify-subscription" RPCs 441 put the subscription into the active state. 443 o Failed "modify-subscription" RPCs will leave the subscription in 444 its previous state, with no visible change to any streaming 445 updates. 447 o A "delete-subscription" or "kill-subscription" RPC will end the 448 subscription, as will the reaching of a "stop-time". 450 o A publisher may choose to suspend a subscription when there is 451 insufficient CPU or bandwidth available to service the 452 subscription. This is notified to a subscriber with a 453 "subscription-suspended" subscription state change notification. 455 o A suspended subscription may be modified by the subscriber (for 456 example in an attempt to use fewer resources). Successful 457 modification returns the subscription to the active state. 459 o Even without a "modify-subscription" request, a publisher may 460 return a subscription to the active state should the resource 461 constraints become sufficient again. This is announced to the 462 subscriber via the "subscription-resumed" subscription state 463 change notification. 465 2.4.2. Establishing a Dynamic Subscription 467 The "establish-subscription" RPC allows a subscriber to request the 468 creation of a subscription. 470 The input parameters of the operation are: 472 o A "stream" name which identifies the targeted event stream against 473 which the subscription is applied. 475 o An event stream filter which may reduce the set of event records 476 pushed. 478 o Where the transport used by the RPC supports multiple encodings, 479 an optional "encoding" for the event records pushed. If no 480 "encoding" is included, the encoding of the RPC MUST be used. 482 o An optional "stop-time" for the subscription. If no "stop-time" 483 is present, notification messages will continue to be sent until 484 the subscription is terminated. 486 o An optional "replay-start-time" for the subscription. The 487 "replay-start-time" MUST be in the past and indicates that the 488 subscription is requesting a replay of previously generated 489 information from the event stream. For more on replay, see 490 Section 2.4.2.1. Where there is no "replay-start-time", the 491 subscription starts immediately. 493 If the publisher can satisfy the "establish-subscription" request, it 494 replies with an identifier for the subscription, and then immediately 495 starts streaming notification messages. 497 Below is a tree diagram for "establish-subscription". All objects 498 contained in this tree are described within the included YANG model 499 within Section 4. 501 +---x establish-subscription 502 +---w input 503 | +---w (target) 504 | | +--:(stream) 505 | | +---w (stream-filter)? 506 | | | +--:(by-reference) 507 | | | | +---w stream-filter-name 508 | | | | stream-filter-ref 509 | | | +--:(within-subscription) 510 | | | +---w (filter-spec)? 511 | | | +--:(stream-subtree-filter) 512 | | | | +---w stream-subtree-filter? 513 | | | | {subtree}? 514 | | | +--:(stream-xpath-filter) 515 | | | +---w stream-xpath-filter? 516 | | | yang:xpath1.0 {xpath}? 517 | | +---w stream stream-ref 518 | | +---w replay-start-time? 519 | | yang:date-and-time {replay}? 520 | +---w stop-time? 521 | | yang:date-and-time 522 | +---w dscp? inet:dscp 523 | | {dscp}? 524 | +---w weighting? uint8 525 | | {qos}? 526 | +---w dependency? 527 | | subscription-id {qos}? 528 | +---w encoding? encoding 529 +--ro output 530 +--ro id subscription-id 531 +--ro replay-start-time-revision? yang:date-and-time 532 {replay}? 534 Figure 2: establish-subscription RPC tree diagram 536 A publisher MAY reject the "establish-subscription" RPC for many 537 reasons as described in Section 2.4.6. The contents of the resulting 538 RPC error response MAY include details on input parameters which if 539 considered in a subsequent "establish-subscription" RPC, may result 540 in a successful subscription establishment. Any such hints MUST be 541 transported within a yang-data "establish-subscription-stream-error- 542 info" container included within the RPC error response. 544 yang-data establish-subscription-stream-error-info 545 +--ro establish-subscription-stream-error-info 546 +--ro reason? identityref 547 +--ro filter-failure-hint? string 549 Figure 3: establish-subscription RPC yang-data tree diagram 551 2.4.2.1. Requesting a replay of event records 553 Replay provides the ability to establish a subscription which is also 554 capable of passing recently generated event records. In other words, 555 as the subscription initializes itself, it sends any event records 556 within the target event stream which meet the filter criteria, which 557 have an event time which is after the "replay-start-time", and which 558 have an event time before the "stop-time" should this "stop-time" 559 exist. The end of these historical event records is identified via a 560 "replay-completed" subscription state change notification. Any event 561 records generated since the subscription establishment may then 562 follow. For a particular subscription, all event records will be 563 delivered in the order they are placed into the event stream. 565 Replay is an optional feature which is dependent on an event stream 566 supporting some form of logging. This document puts no restrictions 567 on the size or form of the log, where it resides within the 568 publisher, or when event record entries in the log are purged. 570 The inclusion of a "replay-start-time" within an "establish- 571 subscription" RPC indicates a replay request. If the "replay-start- 572 time" contains a value that is earlier than what a publisher's 573 retained history supports, then if the subscription is accepted, the 574 actual publisher's revised start time MUST be set in the returned 575 "replay-start-time-revision" object. 577 A "stop-time" parameter may be included in a replay subscription. 578 For a replay subscription, the "stop-time" MAY be earlier than the 579 current time, but MUST be later than the "replay-start-time". 581 If the given "replay-start-time" is later than the time marked within 582 any event records retained within the replay buffer, then the 583 publisher MUST send a "replay-completed" notification immediately 584 after a successful establish-subscription RPC response. 586 If an event stream supports replay, the "replay-support" leaf is 587 present in the "/streams/stream" list entry for the event stream. An 588 event stream that does support replay is not expected to have an 589 unlimited supply of saved notifications available to accommodate any 590 given replay request. To assess the timeframe available for replay, 591 subscribers can read the leafs "replay-log-creation-time" and 592 "replay-log-aged-time". See Figure 18 for the YANG tree, and 593 Section 4 for the YANG model describing these elements. The actual 594 size of the replay log at any given time is a publisher specific 595 matter. Control parameters for the replay log are outside the scope 596 of this document. 598 2.4.3. Modifying a Dynamic Subscription 600 The "modify-subscription" operation permits changing the terms of an 601 existing dynamic subscription. Dynamic subscriptions can be modified 602 any number of times. Dynamic subscriptions can only be modified via 603 this RPC using a transport session connecting to the subscriber. If 604 the publisher accepts the requested modifications, it acknowledges 605 success to the subscriber, then immediately starts sending event 606 records based on the new terms. 608 Subscriptions created by configuration cannot be modified via this 609 RPC. However configuration may be used to modify objects referenced 610 by the subscription (such as a referenced filter). 612 Below is a tree diagram for "modify-subscription". All objects 613 contained in this tree are described within the included YANG model 614 within Section 4. 616 +---x modify-subscription 617 +---w input 618 +---w id 619 | subscription-id 620 +---w (target) 621 | +--:(stream) 622 | +---w (stream-filter)? 623 | +--:(by-reference) 624 | | +---w stream-filter-name 625 | | stream-filter-ref 626 | +--:(within-subscription) 627 | +---w (filter-spec)? 628 | +--:(stream-subtree-filter) 629 | | +---w stream-subtree-filter? 630 | | {subtree}? 631 | +--:(stream-xpath-filter) 632 | +---w stream-xpath-filter? 633 | yang:xpath1.0 {xpath}? 634 +---w stop-time? 635 yang:date-and-time 637 Figure 4: modify-subscription RPC tree diagram 639 If the publisher accepts the requested modifications on a currently 640 suspended subscription, the subscription will immediately be resumed 641 (i.e., the modified subscription is returned to the active state.) 642 The publisher MAY immediately suspend this newly modified 643 subscription through the "subscription-suspended" notification before 644 any event records are sent. 646 If the publisher rejects the RPC request, the subscription remains as 647 prior to the request. That is, the request has no impact whatsoever. 648 Rejection of the RPC for any reason is indicated by via RPC error as 649 described in Section 2.4.6. The contents of such a rejected RPC MAY 650 include hints on inputs which (if considered) may result in a 651 successfully modified subscription. These hints MUST be transported 652 within a yang-data "modify-subscription-stream-error-info" container 653 inserted into the RPC error response. 655 Below is a tree diagram for "modify-subscription-RPC-yang-data". All 656 objects contained in this tree are described within the included YANG 657 model within Section 4. 659 yang-data modify-subscription-stream-error-info 660 +--ro modify-subscription-stream-error-info 661 +--ro reason? identityref 662 +--ro filter-failure-hint? string 664 Figure 5: modify-subscription RPC yang-data tree diagram 666 2.4.4. Deleting a Dynamic Subscription 668 The "delete-subscription" operation permits canceling an existing 669 subscription. If the publisher accepts the request, and the 670 publisher has indicated success, the publisher MUST NOT send any more 671 notification messages for this subscription. 673 Below is a tree diagram for "delete-subscription". All objects 674 contained in this tree are described within the included YANG model 675 within Section 4. 677 +---x delete-subscription 678 +---w input 679 +---w id subscription-id 681 Figure 6: delete-subscription RPC tree diagram 683 Dynamic subscriptions can only be deleted via this RPC using a 684 transport session connecting to the subscriber. Configured 685 subscriptions cannot be deleted using RPCs. 687 2.4.5. Killing a Dynamic Subscription 689 The "kill-subscription" operation permits an operator to end a 690 dynamic subscription which is not associated with the transport 691 session used for the RPC. A publisher MUST terminate any dynamic 692 subscription identified by the "id" parameter in the RPC request, if 693 such a subscription exists. 695 Configured subscriptions cannot be killed using this RPC. Instead, 696 configured subscriptions are deleted as part of regular configuration 697 operations. Publishers MUST reject any RPC attempt to kill a 698 configured subscription. 700 Below is a tree diagram for "kill-subscription". All objects 701 contained in this tree are described within the included YANG model 702 within Section 4. 704 +---x kill-subscription 705 +---w input 706 +---w id subscription-id 708 Figure 7: kill-subscription RPC tree diagram 710 2.4.6. RPC Failures 712 Whenever an RPC is unsuccessful, the publisher returns relevant 713 information as part of the RPC error response. Transport level error 714 processing MUST be done before RPC error processing described in this 715 section. In all cases, RPC error information returned will use 716 existing transport layer RPC structures, such as those seen with 717 NETCONF in [RFC6241] Appendix A, or with RESTCONF in [RFC8040] 718 Section 7.1. These structures MUST be able to encode subscription 719 specific errors identified below and defined within this document's 720 YANG model. 722 As a result of this mixture, how subscription errors are encoded 723 within an RPC error response is transport dependent. Following are 724 valid errors which can occur for each RPC: 726 establish-subscription modify-subscription 727 ---------------------- ------------------- 728 dscp-unavailable filter-unsupported 729 encoding-unsupported insufficient-resources 730 filter-unsupported no-such-subscription 731 insufficient-resources 732 replay-unsupported 734 delete-subscription kill-subscription 735 ---------------------- ---------------------- 736 no-such-subscription no-such-subscription 738 To see a NETCONF based example of an error response from above, see 739 [I-D.draft-ietf-netconf-netconf-event-notifications], Figure 10. 741 There is one final set of transport independent RPC error elements 742 included in the YANG model. These are three yang-data structures 743 which enable the publisher to provide to the receiver that error 744 information which does not fit into existing transport layer RPC 745 structures. These three yang-data structures are: 747 1. "establish-subscription-stream-error-info": This MUST be returned 748 with the leaf "reason" populated if an RPC error reason has not 749 been placed elsewhere within the transport portion of a failed 750 "establish-subscription" RPC response. This MUST be sent if 751 hints on how to overcome the RPC error are included. 753 2. "modify-subscription-stream-error-info": This MUST be returned 754 with the leaf "reason" populated if an RPC error reason has not 755 been placed elsewhere within the transport portion of a failed 756 "modify-subscription" RPC response. This MUST be sent if hints 757 on how to overcome the RPC error are included. 759 3. "delete-subscription-error-info": This MUST be returned with the 760 leaf "reason" populated if an RPC error reason has not been 761 placed elsewhere within the transport portion of a failed 762 "delete-subscription" or "kill-subscription" RPC response. 764 2.5. Configured Subscriptions 766 A configured subscription is a subscription installed via 767 configuration. Configured subscriptions may be modified by any 768 configuration client with the proper permissions. Subscriptions can 769 be modified or terminated via configuration at any point of their 770 lifetime. Multiple configured subscriptions MUST be supportable over 771 a single transport session. 773 Configured subscriptions have several characteristics distinguishing 774 them from dynamic subscriptions: 776 o persistence across publisher reboots, 778 o persistence even when transport is unavailable, and 780 o an ability to send notification messages to more than one receiver 781 (note that receivers are unaware of the existence of any other 782 receivers.) 784 On the publisher, supporting configured subscriptions is optional and 785 advertised using the "configured" feature. On a receiver of a 786 configured subscription, support for dynamic subscriptions is 787 optional. However if replaying missed event records is required for 788 a configured subscription, support for dynamic subscription is highly 789 recommended. In this case, a separate dynamic subscription can be 790 established to retransmit the missing event records. 792 In addition to the subscription parameters available to dynamic 793 subscriptions described in Section 2.4.2, the following additional 794 parameters are also available to configured subscriptions: 796 o A "transport" which identifies the transport protocol to use to 797 connect with all subscription receivers. 799 o One or more receivers, each intended as the destination for event 800 records. Note that each individual receiver is identifiable by 801 its "name". 803 o Optional parameters to identify where traffic should egress a 804 publisher: 806 * A "source-interface" which identifies the egress interface to 807 use from the publisher. Publisher support for this is optional 808 and advertised using the "interface-designation" feature. 810 * A "source-address" address, which identifies the IP address to 811 stamp on notification messages destined for the receiver. 813 * A "source-vrf" which identifies the VRF on which to reach 814 receivers. This VRF is a network instance as defined within 815 [I-D.draft-ietf-rtgwg-ni-model]. Publisher support for VRFs is 816 optional and advertised using the "supports-vrf" feature. 818 If none of the above parameters are set, notification messages 819 MUST egress the publisher's default interface. 821 A tree diagram describing these parameters is shown in Figure 20 822 within Section 3.3. All parameters are described within the YANG 823 model in Section 4. 825 2.5.1. Configured Subscription State Model 827 Below is the state machine for a configured subscription on the 828 publisher. This state machine describes the three states (valid, 829 invalid, and concluded), as well as the transitions between these 830 states. Start and end states are depicted to reflect configured 831 subscription creation and deletion events. The creation or 832 modification of a configured subscription initiates an evaluation by 833 the publisher to determine if the subscription is in valid or invalid 834 states. The publisher uses its own criteria in making this 835 determination. If in the valid state, the subscription becomes 836 operational. See (1) in the diagram below. 838 ......... 839 : start :-. 840 :.......: | 841 create .---modify-----.----------------------------------. 842 | | | | 843 V V .-------. ....... .---------. 844 .----[evaluate]--no--->|invalid|-delete->: end :<-delete-|concluded| 845 | '-------' :.....: '---------' 846 |-[evaluate]--no-(2). ^ ^ ^ 847 | ^ | | | | 848 yes | '->unsupportable delete stop-time 849 | modify (subscription- (subscription- (subscription- 850 | | terminated*) terminated*) concluded*) 851 | | | | | 852 (1) | (3) (4) (5) 853 | .---------------------------------------------------------------. 854 '-->| valid | 855 '---------------------------------------------------------------' 857 Legend: 858 dotted boxes: subscription added or removed via configuration 859 dashed boxes: states for a subscription 860 [evaluate]: decision point on whether the subscription is supportable 861 (*): resulting subscription state change notification 863 Figure 8: Publisher state model for a configured subscription 865 A subscription in the valid state may move to the invalid state in 866 one of two ways. First, it may be modified in a way which fails a 867 re-evaluation. See (2) in the diagram. Second, the publisher might 868 determine that the subscription is no longer supportable. This could 869 be for reasons of an unexpected but sustained increase in an event 870 stream's event records, degraded CPU capacity, a more complex 871 referenced filter, or other higher priority subscriptions which have 872 usurped resources. See (3) in the diagram. No matter the case, a 873 "subscription-terminated" notification is sent to any receivers in an 874 active or suspended state. A subscription in the valid state may 875 also transition to the concluded state via (5) if a configured stop 876 time has been reached. In this case, a "subscription-concluded" 877 notification is sent to any receivers in active or suspended states. 878 Finally, a subscription may be deleted by configuration (4). 880 When a subscription is in the valid state, a publisher will attempt 881 to connect with all receivers of a configured subscription and 882 deliver notification messages. Below is the state machine for each 883 receiver of a configured subscription. This receiver state machine 884 is fully contained within the state machine of the configured 885 subscription, and is only relevant when the configured subscription 886 is in the valid state. 888 .-----------------------------------------------------------------. 889 | valid | 890 | .----------. .------------. | 891 | | receiver |---timeout---------------->| receiver | | 892 | |connecting|<----------------reset--(c)|disconnected| | 893 | | |<-transport '------------' | 894 | '----------' loss,reset------------------------------. | 895 | (a) | | | 896 | subscription- (b) (b) | 897 | started* .--------. .---------. | 898 | '----->| |(d)-insufficient CPU,------->| | | 899 | |receiver| buffer overflow |receiver | | 900 | subscription-| active | |suspended| | 901 | modified* | |<----CPU, b/w sufficient,-(e)| | | 902 | '---->'--------' subscription-modified* '---------' | 903 '-----------------------------------------------------------------' 905 Legend: 906 dashed boxes which include the word 'receiver' show the possible 907 states for an individual receiver of a valid configured subscription. 908 * indicates a subscription state change notification 910 Figure 9: Receiver state for a configured subscription on a Publisher 912 When a configured subscription first moves to the valid state, the 913 "state" leaf of each receiver is initialized to the connecting state. 914 If transport connectivity is not available to any receiver and there 915 are any notification messages to deliver, a transport session is 916 established (e.g., through [RFC8071]). Individual receivers are 917 moved to the active state when a "subscription-started" subscription 918 state change notification is successfully passed to that receiver 919 (a). Event records are only sent to active receivers. Receivers of 920 a configured subscription remain active if both transport 921 connectivity can be verified to the receiver, and event records are 922 not being dropped due to a publisher buffer overflow. The result is 923 that a receiver will remain active on the publisher as long as events 924 aren't being lost, or the receiver cannot be reached. In addition, a 925 configured subscription's receiver MUST be moved to the connecting 926 state if the receiver is reset via the "reset" action (b), (c). For 927 more on reset, see Section 2.5.5. If transport connectivity cannot 928 be achieved while in the connecting state, the receiver MAY be moved 929 to the disconnected state. 931 A configured subscription's receiver MUST be moved to the suspended 932 state if there is transport connectivity between the publisher and 933 receiver, but notification messages are failing to be delivered due 934 to publisher buffer overflow, or notification messages are not able 935 to be generated for that receiver due to insufficient CPU (d). This 936 is indicated to the receiver by the "subscription-suspended" 937 subscription state change notification. 939 A configured subscription receiver MUST be returned to the active 940 state from the suspended state when notification messages are able to 941 be generated, bandwidth is sufficient to handle the notification 942 messages, and a receiver has successfully been sent a "subscription- 943 resumed" or "subscription-modified" subscription state change 944 notification (e). The choice as to which of these two subscription 945 state change notifications is sent is determined by whether the 946 subscription was modified during the period of suspension. 948 Modification of a configured subscription is possible at any time. A 949 "subscription-modified" subscription state change notification will 950 be sent to all active receivers, immediately followed by notification 951 messages conforming to the new parameters. Suspended receivers will 952 also be informed of the modification. However this notification will 953 await the end of the suspension for that receiver (e). 955 The mechanisms described above are mirrored in the RPCs and 956 notifications within the document. It should be noted that these 957 RPCs and notifications have been designed to be extensible and allow 958 subscriptions into targets other than event streams. For instance, 959 the YANG module defined in Section 5 of [I-D.ietf-netconf-yang-push] 960 augments "/sn:modify-subscription/sn:input/sn:target". 962 2.5.2. Creating a Configured Subscription 964 Configured subscriptions are established using configuration 965 operations against the top-level "subscriptions" subtree. 967 Because there is no explicit association with an existing transport 968 session, configuration operations MUST include additional parameters 969 beyond those of dynamic subscriptions. These parameters identify 970 each receiver, how to connect with that receiver, and possibly 971 whether the notification messages need to come from a specific egress 972 interface on the publisher. Receiver specific transport connectivity 973 parameters MUST be configured via transport specific augmentations to 974 this specification. See Section 2.5.7 for details. 976 After a subscription is successfully established, the publisher 977 immediately sends a "subscription-started" subscription state change 978 notification to each receiver. It is quite possible that upon 979 configuration, reboot, or even steady-state operations, a transport 980 session may not be currently available to the receiver. In this 981 case, when there is something to transport for an active 982 subscription, transport specific call-home operations will be used to 983 establish the connection. When transport connectivity is available, 984 notification messages may then be pushed. 986 With active configured subscriptions, it is allowable to buffer event 987 records even after a "subscription-started" has been sent. However 988 if events are lost (rather than just delayed) due to replay buffer 989 overflow, a new "subscription-started" must be sent. This new 990 "subscription-started" indicates an event record discontinuity. 992 To see an example of subscription creation using configuration 993 operations over NETCONF, see Appendix A of 994 [I-D.draft-ietf-netconf-netconf-event-notifications]. 996 2.5.3. Modifying a Configured Subscription 998 Configured subscriptions can be modified using configuration 999 operations against the top-level "subscriptions" subtree. 1001 If the modification involves adding receivers, added receivers are 1002 placed in the connecting state. If a receiver is removed, the 1003 subscription state change notification "subscription-terminated" is 1004 sent to that receiver if that receiver is active or suspended. 1006 If the modification involves changing the policies for the 1007 subscription, the publisher sends to currently active receivers a 1008 "subscription-modified" notification. For any suspended receivers, a 1009 "subscription-modified" notification will be delayed until the 1010 receiver is resumed. (Note: in this case, the "subscription- 1011 modified" notification informs the receiver that the subscription has 1012 been resumed, so no additional "subscription-resumed" need be sent. 1013 Also note that if multiple modifications have occurred during the 1014 suspension, only the "subscription-modified" notification describing 1015 the latest one need be sent to the receiver.) 1017 2.5.4. Deleting a Configured Subscription 1019 Subscriptions can be deleted through configuration against the top- 1020 level "subscriptions" subtree. 1022 Immediately after a subscription is successfully deleted, the 1023 publisher sends to all receivers of that subscription a subscription 1024 state change notification stating the subscription has ended (i.e., 1025 "subscription-terminated"). 1027 2.5.5. Resetting a Configured Subscription Receiver 1029 It is possible that a configured subscription to a receiver needs to 1030 be reset. This is accomplished via the "reset" action within the 1031 YANG model at "/subscriptions/subscription/receivers/receiver/reset". 1032 This action may be useful in cases where a publisher has timed out 1033 trying to reach a receiver. When such a reset occurs, a transport 1034 session will be initiated if necessary, and a new "subscription- 1035 started" notification will be sent. This action does not have any 1036 effect on transport connectivity if the needed connectivity already 1037 exists. 1039 2.5.6. Replay for a Configured Subscription 1041 It is possible to do replay on a configured subscription. This is 1042 supported via the configuration of the "configured-replay" object on 1043 the subscription. The setting of this object enables the streaming 1044 of the buffered event records for the subscribed event stream. All 1045 buffered event records which have been retained since the last 1046 publisher restart will be sent to each configured receiver. 1048 Replay of events records created since restart is useful. It allows 1049 event records generated before transport connectivity establishment 1050 to be passed to a receiver. Setting the restart time as the earliest 1051 configured replay time precludes possibility of resending of event 1052 records logged prior to publisher restart. It also ensures the same 1053 records will be sent to each configured receiver, regardless of the 1054 speed of transport connectivity establishment to each receiver. 1055 Finally, establishing restart as the earliest potential time for 1056 event records to be included within notification messages, a well- 1057 understood timeframe for replay is defined. 1059 As a result, when any configured subscription receivers become 1060 active, buffered event records will be sent immediately after the 1061 "subscription-started" notification. If the publisher knows the last 1062 event record sent to a receiver, and the publisher has not rebooted, 1063 the next event record on the event stream which meets filtering 1064 criteria will be the leading event record sent. Otherwise, the 1065 leading event record will be the first event record meeting filtering 1066 criteria subsequent to the latest of three different times: the 1067 "replay-log-creation-time", "replay-log-aged-time", or the most 1068 recent publisher boot time. The "replay-log-creation-time" and 1069 "replay-log-aged-time" are discussed in Section 2.4.2.1. The most 1070 recent publisher boot time ensures that duplicate event records are 1071 not replayed from a previous time the publisher was booted. 1073 It is quite possible that a receiver might want to retrieve event 1074 records from an event stream prior to the latest boot. If such 1075 records exist where there is a configured replay, the publisher MUST 1076 send the time of the event record immediately preceding the "replay- 1077 start-time" within the "replay-previous-event-time" leaf. Through 1078 the existence of the "replay-previous-event-time", the receiver will 1079 know that earlier events prior to reboot exist. In addition, if the 1080 subscriber was previously receiving event records with the same 1081 subscription "id", the receiver can determine if there was a timegap 1082 where records generated on the publisher were not successully 1083 received. And with this information, the receiver may choose to 1084 dynamically subscribe to retrieve any event records placed into the 1085 event stream before the most recent boot time. 1087 All other replay functionality remains the same as with dynamic 1088 subscriptions as described in Section 2.4.2.1. 1090 2.5.7. Transport Connectivity for a Configured Subscription 1092 This specification is transport independent. However supporting a 1093 configured subscription will often require the establishment of 1094 transport connectivity. And the parameters used for this transport 1095 connectivity establishment are transport specific. As a result, the 1096 YANG model defined within Section 4 is not able to directly define 1097 and expose these transport parameters. 1099 It is necessary for an implementation to support the connection 1100 establishment process. To support this function, the YANG model does 1101 include a node where transport specific parameters for a particular 1102 receiver may be augmented. This node is 1103 "/subscriptions/subscription/receivers/receiver". By augmenting 1104 transport parameters from this node, system developers are able to 1105 incorporate the YANG objects necessary to support the transport 1106 connectivity establishment process. 1108 The result of this is the following requirement. A publisher 1109 supporting the feature "configured" MUST also support least one YANG 1110 model which augments transport connectivity parameters on 1111 "/subscriptions/subscription/receivers/receiver". For an example of 1112 such an augmentation, see Appendix A. 1114 2.6. Event Record Delivery 1116 Whether dynamic or configured, once a subscription has been set up, 1117 the publisher streams event records via notification messages per the 1118 terms of the subscription. For dynamic subscriptions, notification 1119 messages are sent over the session used to establish the 1120 subscription. For configured subscriptions, notification messages 1121 are sent over the connections specified by the transport and each 1122 receiver of a configured subscription. 1124 A notification message is sent to a receiver when an event record is 1125 not blocked by either the specified filter criteria or receiver 1126 permissions. This notification message MUST include an "eventTime" 1127 object as defined per [RFC5277] Section 4. This "eventTime" MUST be 1128 at the top level of YANG structured event record. 1130 The following example within [RFC7950] section 7.16.3 is an example 1131 of a compliant message: 1133 1135 2007-09-01T10:00:00Z 1136 1137 so-1/2/3.0 1138 up 1139 down 1140 1141 1143 Figure 10: subscribed notification message 1145 When a dynamic subscription has been started or modified, with 1146 "establish-subscription" or "modify-subscription" respectively, event 1147 records matching the newly applied filter criteria MUST NOT be sent 1148 until after the RPC reply has been sent. 1150 When a configured subscription has been started or modified, event 1151 records matching the newly applied filter criteria MUST NOT be sent 1152 until after the "subscription-started" or "subscription-modified" 1153 notifications has been sent, respectively. 1155 2.7. Subscription state change notifications 1157 In addition to sending event records to receivers, a publisher MUST 1158 also send subscription state change notifications when events related 1159 to subscription management have occurred. 1161 Subscription state change notifications are unlike other 1162 notifications in that they are never included in any event stream. 1163 Instead, they are inserted (as defined in this section) within the 1164 sequence of notification messages sent to a particular receiver. 1165 subscription state change notifications cannot be dropped or filtered 1166 out, they cannot be stored in replay buffers, and they are delivered 1167 only to impacted receivers of a subscription. The identification of 1168 subscription state change notifications is easy to separate from 1169 other notification messages through the use of the YANG extension 1170 "subscription-state-notif". This extension tags a notification as a 1171 subscription state change notification. 1173 The complete set of subscription state change notifications is 1174 described in the following subsections. 1176 2.7.1. subscription-started 1178 This notification indicates that a configured subscription has 1179 started, and event records may be sent. Included in this 1180 subscription state change notification are all the parameters of the 1181 subscription, except for the receiver(s) transport connection 1182 information and origin information indicating where notification 1183 messages will egress the publisher. Note that if a referenced filter 1184 from the "filters" container has been used within the subscription, 1185 the notification still provides the contents of that referenced 1186 filter under the "within-subscription" subtree. 1188 Note that for dynamic subscriptions, no "subscription-started" 1189 notifications are ever sent. 1191 Below is a tree diagram for "subscription-started". All objects 1192 contained in this tree are described within the included YANG model 1193 within Section 4. 1195 +---n subscription-started {configured}? 1196 +--ro id 1197 | subscription-id 1198 +--ro (target) 1199 | +--:(stream) 1200 | +--ro (stream-filter)? 1201 | | +--:(by-reference) 1202 | | | +--ro stream-filter-name 1203 | | | stream-filter-ref 1204 | | +--:(within-subscription) 1205 | | +--ro (filter-spec)? 1206 | | +--:(stream-subtree-filter) 1207 | | | +--ro stream-subtree-filter? 1208 | | | {subtree}? 1209 | | +--:(stream-xpath-filter) 1210 | | +--ro stream-xpath-filter? yang:xpath1.0 1211 | | {xpath}? 1212 | +--ro stream stream-ref 1213 | +--ro replay-start-time? 1214 | | yang:date-and-time {replay}? 1215 | +--ro replay-previous-event-time? 1216 | yang:date-and-time {replay}? 1217 +--ro stop-time? 1218 | yang:date-and-time 1219 +--ro dscp? inet:dscp 1220 | {dscp}? 1221 +--ro weighting? uint8 {qos}? 1222 +--ro dependency? 1223 | subscription-id {qos}? 1224 +--ro transport? transport 1225 | {configured}? 1226 +--ro encoding? encoding 1227 +--ro purpose? string 1228 {configured}? 1230 Figure 11: subscription-started notification tree diagram 1232 2.7.2. subscription-modified 1234 This notification indicates that a subscription has been modified by 1235 configuration operations. It is delivered directly after the last 1236 event records processed using the previous subscription parameters, 1237 and before any event records processed after the modification. 1239 Below is a tree diagram for "subscription-modified". All objects 1240 contained in this tree are described within the included YANG model 1241 within Section 4. 1243 +---n subscription-modified 1244 +--ro id 1245 | subscription-id 1246 +--ro (target) 1247 | +--:(stream) 1248 | +--ro (stream-filter)? 1249 | | +--:(by-reference) 1250 | | | +--ro stream-filter-name 1251 | | | stream-filter-ref 1252 | | +--:(within-subscription) 1253 | | +--ro (filter-spec)? 1254 | | +--:(stream-subtree-filter) 1255 | | | +--ro stream-subtree-filter? 1256 | | | {subtree}? 1257 | | +--:(stream-xpath-filter) 1258 | | +--ro stream-xpath-filter? yang:xpath1.0 1259 | | {xpath}? 1260 | +--ro stream stream-ref 1261 | +--ro replay-start-time? 1262 | yang:date-and-time {replay}? 1263 +--ro stop-time? 1264 | yang:date-and-time 1265 +--ro dscp? inet:dscp 1266 | {dscp}? 1267 +--ro weighting? uint8 {qos}? 1268 +--ro dependency? 1269 | subscription-id {qos}? 1270 +--ro transport? transport 1271 | {configured}? 1272 +--ro encoding? encoding 1273 +--ro purpose? string 1274 {configured}? 1276 Figure 12: subscription-modified notification tree diagram 1278 A publisher most often sends this notification directly after the 1279 modification of any configuration parameters impacting a configured 1280 subscription. But it may also be sent at two other times: 1282 1. Where a configured subscription has been modified during the 1283 suspension of a receiver, the notification will be delayed until 1284 the receiver's suspension is lifted. In this situation, the 1285 notification indicates that the subscription has been both 1286 modified and resumed. 1288 2. A "subscription-modified" subscription state change notification 1289 MUST be sent if the contents of the filter identified by the 1290 subscription's "stream-filter-ref" leaf has changed. This state 1291 change notification is to be sent for a filter change impacting 1292 any active receiver of a configured or dynamic subscription. 1294 2.7.3. subscription-terminated 1296 This notification indicates that no further event records for this 1297 subscription should be expected from the publisher. A publisher may 1298 terminate the sending event records to a receiver for the following 1299 reasons: 1301 1. Configuration which removes a configured subscription, or a 1302 "kill-subscription" RPC which ends a dynamic subscription. These 1303 are identified via the reason "no-such-subscription". 1305 2. A referenced filter is no longer accessible. This is identified 1306 by "filter-unavailable". 1308 3. The event stream referenced by a subscription is no longer 1309 accessible by the receiver. This is identified by "stream- 1310 unavailable". 1312 4. A suspended subscription has exceeded some timeout. This is 1313 identified by "suspension-timeout". 1315 Each of the reasons above correspond one-to-one with a "reason" 1316 identityref specified within the YANG model. 1318 Below is a tree diagram for "subscription-terminated". All objects 1319 contained in this tree are described within the included YANG model 1320 within Section 4. 1322 +---n subscription-terminated 1323 +--ro id subscription-id 1324 +--ro reason identityref 1326 Figure 13: subscription-terminated notification tree diagram 1328 Note: this subscription state change notification MUST be sent to a 1329 dynamic subscription's receiver when the subscription ends 1330 unexpectedly. The cases when this might happen are when a "kill- 1331 subscription" RPC is successful, or when some other event not 1332 including the reaching the subscription's "stop-time" results in a 1333 publisher choosing to end the subscription. 1335 2.7.4. subscription-suspended 1337 This notification indicates that a publisher has suspended the 1338 sending of event records to a receiver, and also indicates the 1339 possible loss of events. Suspension happens when capacity 1340 constraints stop a publisher from serving a valid subscription. The 1341 two conditions where is this possible are: 1343 1. "insufficient-resources" when a publisher is unable to produce 1344 the requested event stream of notification messages, and 1346 2. "unsupportable-volume" when the bandwidth needed to get generated 1347 notification messages to a receiver exceeds a threshold. 1349 These conditions are encoded within the "reason" object. No further 1350 notification will be sent until the subscription resumes or is 1351 terminated. 1353 Below is a tree diagram for "subscription-suspended". All objects 1354 contained in this tree are described within the included YANG model 1355 within Section 4. 1357 +---n subscription-suspended 1358 +--ro id subscription-id 1359 +--ro reason identityref 1361 Figure 14: subscription-suspended notification tree diagram 1363 2.7.5. subscription-resumed 1365 This notification indicates that a previously suspended subscription 1366 has been resumed under the unmodified terms previously in place. 1367 Subscribed event records generated after the issuance of this 1368 subscription state change notification may now be sent. 1370 Below is the tree diagram for "subscription-resumed". All objects 1371 contained in this tree are described within the included YANG model 1372 within Section 4. 1374 +---n subscription-resumed 1375 +--ro id subscription-id 1377 Figure 15: subscription-resumed notification tree diagram 1379 2.7.6. subscription-completed 1381 This notification indicates that a subscription that includes a 1382 "stop-time" has successfully finished passing event records upon the 1383 reaching of that time. 1385 Below is a tree diagram for "subscription-completed". All objects 1386 contained in this tree are described within the included YANG model 1387 within Section 4. 1389 +---n subscription-completed {configured}? 1390 +--ro id subscription-id 1392 Figure 16: subscription-completed notification tree diagram 1394 2.7.7. replay-completed 1396 This notification indicates that all of the event records prior to 1397 the current time have been passed to a receiver. It is sent before 1398 any notification message containing an event record with a timestamp 1399 later than (1) the "stop-time" or (2) the subscription's start time. 1401 If a subscription contains no "stop-time", or has a "stop-time" that 1402 has not been reached, then after the "replay-completed" notification 1403 has been sent, additional event records will be sent in sequence as 1404 they arise naturally on the publisher. 1406 Below is a tree diagram for "replay-completed". All objects 1407 contained in this tree are described within the included YANG model 1408 within Section 4. 1410 +---n replay-completed {replay}? 1411 +--ro id subscription-id 1413 Figure 17: replay-completed notification tree diagram 1415 2.8. Subscription Monitoring 1417 In the operational state datastore, the container "subscriptions" 1418 maintains the state of all dynamic subscriptions, as well as all 1419 configured subscriptions. Using datastore retrieval operations, or 1420 subscribing to the "subscriptions" container 1421 [I-D.ietf-netconf-yang-push] allows the state of subscriptions and 1422 their connectivity to receivers to be monitored. 1424 Each subscription in the operational state datastore is represented 1425 as a list element. Included in this list are event counters for each 1426 receiver, the state of each receiver, as well as the subscription 1427 parameters currently in effect. The appearance of the leaf 1428 "configured-subscription-state" indicates that a particular 1429 subscription came into being via configuration. This leaf also 1430 indicates if the current state of that subscription is valid, 1431 invalid, and concluded. 1433 To understand the flow of event records within a subscription, there 1434 are two counters available for each receiver. The first counter is 1435 "sent-event-records" which shows the quantity of events actually 1436 identified for sending to a receiver. The second counter is 1437 "excluded-event-records" which shows event records not sent to 1438 receiver. "excluded-event-records" shows the combined results of 1439 both access control and per-subscription filtering. For configured 1440 subscriptions, counters are reset whenever the subscription is 1441 evaluated to valid (see (1) in Figure 8). 1443 Dynamic subscriptions are removed from the operational state 1444 datastore once they expire (reaching stop-time) or when they are 1445 terminated. While many subscription objects are shown as 1446 configurable, dynamic subscriptions are only included within the 1447 operational state datastore and as a result are not configurable. 1449 2.9. Advertisement 1451 Publishers supporting this document MUST indicate support of the YANG 1452 model "ietf-subscribed-notifications" within the YANG library of the 1453 publisher. In addition if supported, the optional features "encode- 1454 xml", "encode-json", "configured" "supports-vrf", "qos", "xpath", 1455 "subtree", "interface-designation", "dscp", and "replay" MUST be 1456 indicated. 1458 3. YANG Data Model Trees 1460 This section contains tree diagrams for nodes defined in Section 4. 1461 For tree diagrams of subscription state change notifications, see 1462 Section 2.7. For the tree diagrams for the RPCs, see Section 2.4. 1464 3.1. Event Streams Container 1466 A publisher maintains a list of available event streams as 1467 operational data. This list contains both standardized and vendor- 1468 specific event streams. This enables subscribers to discover what 1469 streams a publisher supports. 1471 +--ro streams 1472 +--ro stream* [name] 1473 +--ro name string 1474 +--ro description string 1475 +--ro replay-support? empty {replay}? 1476 +--ro replay-log-creation-time yang:date-and-time 1477 | {replay}? 1478 +--ro replay-log-aged-time? yang:date-and-time 1479 {replay}? 1481 Figure 18: Stream Container tree diagram 1483 Above is a tree diagram for the "streams" container. All objects 1484 contained in this tree are described within the included YANG model 1485 within Section 4. 1487 3.2. Filters Container 1489 The "filters" container maintains a list of all subscription filters 1490 that persist outside the life-cycle of a single subscription. This 1491 enables pre-defined filters which may be referenced by more than one 1492 subscription. 1494 +--rw filters 1495 +--rw stream-filter* [name] 1496 +--rw name string 1497 +--rw (filter-spec)? 1498 +--:(stream-subtree-filter) 1499 | +--rw stream-subtree-filter? {subtree}? 1500 +--:(stream-xpath-filter) 1501 +--rw stream-xpath-filter? yang:xpath1.0 {xpath}? 1503 Figure 19: Filter Container tree diagram 1505 Above is a tree diagram for the filters container. All objects 1506 contained in this tree are described within the included YANG model 1507 within Section 4. 1509 3.3. Subscriptions Container 1511 The "subscriptions" container maintains a list of all subscriptions 1512 on a publisher, both configured and dynamic. It can be used to 1513 retrieve information about the subscriptions which a publisher is 1514 serving. 1516 +--rw subscriptions 1517 +--rw subscription* [id] 1518 +--rw id 1519 | subscription-id 1520 +--rw (target) 1521 | +--:(stream) 1522 | +--rw (stream-filter)? 1523 | | +--:(by-reference) 1524 | | | +--rw stream-filter-name 1525 | | | stream-filter-ref 1526 | | +--:(within-subscription) 1527 | | +--rw (filter-spec)? 1528 | | +--:(stream-subtree-filter) 1529 | | | +--rw stream-subtree-filter? 1530 | | | {subtree}? 1531 | | +--:(stream-xpath-filter) 1532 | | +--rw stream-xpath-filter? 1533 | | yang:xpath1.0 {xpath}? 1534 | +--rw stream stream-ref 1535 | +--ro replay-start-time? 1536 | | yang:date-and-time {replay}? 1537 | +--rw configured-replay? empty 1538 | {configured,replay}? 1539 +--rw stop-time? 1540 | yang:date-and-time 1541 +--rw dscp? inet:dscp 1542 | {dscp}? 1543 +--rw weighting? uint8 {qos}? 1544 +--rw dependency? 1545 | subscription-id {qos}? 1546 +--rw transport? transport 1547 | {configured}? 1548 +--rw encoding? encoding 1549 +--rw purpose? string 1550 | {configured}? 1551 +--rw (notification-message-origin)? {configured}? 1552 | +--:(interface-originated) 1553 | | +--rw source-interface? 1554 | | if:interface-ref {interface-designation}? 1555 | +--:(address-originated) 1556 | +--rw source-vrf? 1557 | | -> /ni:network-instances/network-instance/name 1558 | | {supports-vrf}? 1559 | +--rw source-address? 1560 | inet:ip-address-no-zone 1561 +--ro configured-subscription-state? enumeration 1562 | {configured}? 1563 +--rw receivers 1564 +--rw receiver* [name] 1565 +--rw name string 1566 +--ro sent-event-records? 1567 | yang:zero-based-counter64 1568 +--ro excluded-event-records? 1569 | yang:zero-based-counter64 1570 +--ro state enumeration 1571 +---x reset {configured}? 1572 +--ro output 1573 +--ro time yang:date-and-time 1575 Figure 20: Subscriptions tree diagram 1577 Above is a tree diagram for the subscriptions container. All objects 1578 contained in this tree are described within the included YANG model 1579 within Section 4. 1581 4. Data Model 1583 This module imports typedefs from [RFC6991], [RFC8343], and 1584 [RFC8040], and it references [I-D.draft-ietf-rtgwg-ni-model], 1585 [XPATH], [RFC6241], [RFC7049], [RFC7540], [RFC7951] , [RFC7950] and 1586 [RFC8259]. 1588 [ note to the RFC Editor - please replace XXXX within this YANG model 1589 with the number of this document, and XXXY with the number of 1590 [I-D.draft-ietf-rtgwg-ni-model] ] 1592 [ note to the RFC Editor - please replace the two dates within the 1593 YANG module with the date of publication ] 1595 file "ietf-subscribed-notifications@2019-01-16.yang" 1596 module ietf-subscribed-notifications { 1597 yang-version 1.1; 1598 namespace 1599 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"; 1601 prefix sn; 1603 import ietf-inet-types { 1604 prefix inet; 1605 reference 1606 "RFC 6991: Common YANG Data Types"; 1607 } 1608 import ietf-interfaces { 1609 prefix if; 1610 reference 1611 "RFC 8343: A YANG Data Model for Interface Management"; 1613 } 1614 import ietf-netconf-acm { 1615 prefix nacm; 1616 reference 1617 "RFC 8341: Network Configuration Access Control Model"; 1618 } 1619 import ietf-network-instance { 1620 prefix ni; 1621 reference 1622 "draft-ietf-rtgwg-ni-model-12: YANG Model for Network Instances"; 1623 } 1624 import ietf-restconf { 1625 prefix rc; 1626 reference 1627 "RFC 8040: RESTCONF Protocol"; 1628 } 1629 import ietf-yang-types { 1630 prefix yang; 1631 reference 1632 "RFC 6991: Common YANG Data Types"; 1633 } 1635 organization "IETF NETCONF (Network Configuration) Working Group"; 1636 contact 1637 "WG Web: 1638 WG List: 1640 Author: Alexander Clemm 1641 1643 Author: Eric Voit 1644 1646 Author: Alberto Gonzalez Prieto 1647 1649 Author: Einar Nilsen-Nygaard 1650 1652 Author: Ambika Prasad Tripathy 1653 "; 1655 description 1656 "Contains a YANG specification for subscribing to event records 1657 and receiving matching content within notification messages. 1659 Copyright (c) 2018 IETF Trust and the persons identified as authors 1660 of the code. All rights reserved. 1662 Redistribution and use in source and binary forms, with or without 1663 modification, is permitted pursuant to, and subject to the license 1664 terms contained in, the Simplified BSD License set forth in Section 1665 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 1666 (https://trustee.ietf.org/license-info). 1668 This version of this YANG module is part of RFC XXXX; see the RFC 1669 itself for full legal notices."; 1671 revision 2019-01-16 { 1672 description 1673 "Initial version"; 1674 reference 1675 "RFC XXXX:Subscription to YANG Event Notifications"; 1676 } 1678 /* 1679 * FEATURES 1680 */ 1682 feature configured { 1683 description 1684 "This feature indicates that configuration of subscriptions is 1685 supported."; 1686 } 1688 feature dscp { 1689 description 1690 "This feature indicates a publisher supports the placement of 1691 suggested prioritization levels for network transport within 1692 notification messages."; 1693 } 1695 feature encode-json { 1696 description 1697 "This feature indicates that JSON encoding of notification 1698 messages is supported."; 1699 } 1701 feature encode-xml { 1702 description 1703 "This feature indicates that XML encoding of notification 1704 messages is supported."; 1705 } 1707 feature interface-designation { 1708 description 1709 "This feature indicates a publisher supports sourcing all 1710 receiver interactions for a configured subscription from a single 1711 designated egress interface."; 1712 } 1714 feature qos { 1715 description 1716 "This feature indicates a publisher supports absolute 1717 dependencies of one subscription's traffic over another, as well 1718 as weighted bandwidth sharing between subscriptions. Both of 1719 these are Quality of Service (QoS) features which allow 1720 differentiated treatment of notification messages between a 1721 publisher and a specific receiver."; 1722 } 1724 feature replay { 1725 description 1726 "This feature indicates that historical event record replay is 1727 supported. With replay, it is possible for past event records to 1728 be streamed in chronological order."; 1729 } 1731 feature subtree { 1732 description 1733 "This feature indicates support for YANG subtree filtering."; 1734 reference "RFC 6241, Section 6."; 1735 } 1737 feature supports-vrf { 1738 description 1739 "This feature indicates a publisher supports VRF configuration 1740 for configured subscriptions. VRF support for dynamic 1741 subscriptions does not require this feature."; 1742 reference "RFC XXXY, Section 6."; 1743 } 1745 feature xpath { 1746 description 1747 "This feature indicates support for XPath filtering."; 1748 reference "http://www.w3.org/TR/1999/REC-xpath-19991116"; 1749 } 1751 /* 1752 * EXTENSIONS 1753 */ 1755 extension subscription-state-notification { 1756 description 1757 "This statement applies only to notifications. It indicates that 1758 the notification is a subscription state change notification. 1759 Therefore it does not participate in a regular event stream and 1760 does not need to be specifically subscribed to in order to be 1761 received. This statement can only occur as a substatement to the 1762 YANG 'notification' statement. This statement is not for use 1763 outside of this YANG module."; 1764 } 1766 /* 1767 * IDENTITIES 1768 */ 1770 /* Identities for RPC and Notification errors */ 1772 identity delete-subscription-error { 1773 description 1774 "Problem found while attempting to fulfill either a 1775 'delete-subscription' RPC request or a 'kill-subscription' 1776 RPC request."; 1777 } 1779 identity establish-subscription-error { 1780 description 1781 "Problem found while attempting to fulfill an 1782 'establish-subscription' RPC request."; 1783 } 1785 identity modify-subscription-error { 1786 description 1787 "Problem found while attempting to fulfill a 1788 'modify-subscription' RPC request."; 1789 } 1791 identity subscription-suspended-reason { 1792 description 1793 "Problem condition communicated to a receiver as part of a 1794 'subscription-terminated' notification."; 1795 } 1797 identity subscription-terminated-reason { 1798 description 1799 "Problem condition communicated to a receiver as part of a 1800 'subscription-terminated' notification."; 1801 } 1803 identity dscp-unavailable { 1804 base establish-subscription-error; 1805 if-feature "dscp"; 1806 description 1807 "The publisher is unable mark notification messages with a 1808 prioritization information in a way which will be respected 1809 during network transit."; 1810 } 1812 identity encoding-unsupported { 1813 base establish-subscription-error; 1814 description 1815 "Unable to encode notification messages in the desired format."; 1816 } 1818 identity filter-unavailable { 1819 base subscription-terminated-reason; 1820 description 1821 "Referenced filter does not exist. This means a receiver is 1822 referencing a filter which doesn't exist, or to which they do not 1823 have access permissions."; 1824 } 1826 identity filter-unsupported { 1827 base establish-subscription-error; 1828 base modify-subscription-error; 1829 description 1830 "Cannot parse syntax within the filter. This failure can be from 1831 a syntax error, or a syntax too complex to be processed by the 1832 publisher."; 1833 } 1835 identity insufficient-resources { 1836 base establish-subscription-error; 1837 base modify-subscription-error; 1838 base subscription-suspended-reason; 1839 description 1840 "The publisher has insufficient resources to support the 1841 requested subscription. An example might be that allocated CPU 1842 is too limited to generate the desired set of notification 1843 messages."; 1844 } 1846 identity no-such-subscription { 1847 base modify-subscription-error; 1848 base delete-subscription-error; 1849 base subscription-terminated-reason; 1850 description 1851 "Referenced subscription doesn't exist. This may be as a result of 1852 a non-existent subscription id, an id which belongs to another 1853 subscriber, or an id for configured subscription."; 1855 } 1857 identity replay-unsupported { 1858 base establish-subscription-error; 1859 if-feature "replay"; 1860 description 1861 "Replay cannot be performed for this subscription. This means the 1862 publisher will not provide the requested historic information 1863 from the event stream via replay to this receiver."; 1864 } 1866 identity stream-unavailable { 1867 base subscription-terminated-reason; 1868 description 1869 "Not a subscribable event stream. This means the referenced event 1870 stream is not available for subscription by the receiver."; 1871 } 1873 identity suspension-timeout { 1874 base subscription-terminated-reason; 1875 description 1876 "Termination of previously suspended subscription. The publisher 1877 has eliminated the subscription as it exceeded a time limit for 1878 suspension."; 1879 } 1881 identity unsupportable-volume { 1882 base subscription-suspended-reason; 1883 description 1884 "The publisher does not have the network bandwidth needed to get 1885 the volume of generated information intended for a receiver."; 1886 } 1888 /* Identities for encodings */ 1890 identity configurable-encoding { 1891 description 1892 "If a transport identity derives from this identity, it means 1893 that it supports configurable encodings. An example of a 1894 configurable encoding might be a new identity such as 1895 'encode-cbor'. Such an identity could use 1896 'configurable-encoding' as its base. This would allow a 1897 dynamic subscription encoded in JSON [RFC-8259] to request 1898 notification messages be encoded via CBOR [RFC-7049]. Further 1899 details for any specific configurable encoding would be 1900 explored in a transport document based on this specification."; 1901 } 1902 identity encoding { 1903 description 1904 "Base identity to represent data encodings"; 1905 } 1907 identity encode-xml { 1908 base encoding; 1909 if-feature "encode-xml"; 1910 description 1911 "Encode data using XML as described in RFC 7950"; 1912 reference 1913 "RFC 7950 - The YANG 1.1 Data Modeling Language"; 1914 } 1916 identity encode-json { 1917 base encoding; 1918 if-feature "encode-json"; 1919 description 1920 "Encode data using JSON as described in RFC 7951"; 1921 reference 1922 "RFC 7951 - JSON Encoding of Data Modeled with YANG"; 1923 } 1925 /* Identities for transports */ 1926 identity transport { 1927 description 1928 "An identity that represents the underlying mechanism for 1929 passing notification messages."; 1930 } 1932 /* 1933 * TYPEDEFs 1934 */ 1936 typedef encoding { 1937 type identityref { 1938 base encoding; 1939 } 1940 description 1941 "Specifies a data encoding, e.g. for a data subscription."; 1942 } 1944 typedef stream-filter-ref { 1945 type leafref { 1946 path "/sn:filters/sn:stream-filter/sn:name"; 1947 } 1948 description 1949 "This type is used to reference an event stream filter."; 1951 } 1953 typedef stream-ref { 1954 type leafref { 1955 path "/sn:streams/sn:stream/sn:name"; 1956 } 1957 description 1958 "This type is used to reference a system-provided event stream."; 1959 } 1961 typedef subscription-id { 1962 type uint32; 1963 description 1964 "A type for subscription identifiers."; 1965 } 1967 typedef transport { 1968 type identityref { 1969 base transport; 1970 } 1971 description 1972 "Specifies transport used to send notification messages to a 1973 receiver."; 1974 } 1976 /* 1977 * GROUPINGS 1978 */ 1980 grouping stream-filter-elements { 1981 description 1982 "This grouping defines the base for filters applied to event 1983 streams."; 1984 choice filter-spec { 1985 description 1986 "The content filter specification for this request."; 1987 anydata stream-subtree-filter { 1988 if-feature "subtree"; 1989 description 1990 "Event stream evaluation criteria encoded in the syntax of a 1991 subtree filter as defined in RFC 6241, Section 6. 1993 The subtree filter is applied to the representation of 1994 individual, delineated event records as contained within the 1995 event stream. 1997 If the subtree filter returns a non-empty node set, the 1998 filter matches the event record, and the event record is 1999 included in the notification message sent to the receivers."; 2000 reference "RFC 6241, Section 6."; 2001 } 2002 leaf stream-xpath-filter { 2003 if-feature "xpath"; 2004 type yang:xpath1.0; 2005 description 2006 "Event stream evaluation criteria encoded in the syntax of 2007 an XPath 1.0 expression. 2009 The XPath expression is evaluated on the representation of 2010 individual, delineated event records as contained within 2011 the event stream. 2013 The result of the XPath expression is converted to a 2014 boolean value using the standard XPath 1.0 rules. If the 2015 boolean value is 'true', the filter matches the event 2016 record, and the event record is included in the notification 2017 message sent to the receivers. 2019 The expression is evaluated in the following XPath context: 2021 o The set of namespace declarations is the set of prefix 2022 and namespace pairs for all YANG modules implemented 2023 by the server, where the prefix is the YANG module 2024 name and the namespace is as defined by the 2025 'namespace' statement in the YANG module. 2027 If the leaf is encoded in XML, all namespace 2028 declarations in scope on the 'stream-xpath-filter' 2029 leaf element are added to the set of namespace 2030 declarations. If a prefix found in the XML is 2031 already present in the set of namespace declarations, 2032 the namespace in the XML is used. 2034 o The set of variable bindings is empty. 2036 o The function library is the core function library, and 2037 the XPath functions defined in section 10 in RFC 7950. 2039 o The context node is the root node."; 2040 reference 2041 "http://www.w3.org/TR/1999/REC-xpath-19991116 2042 RFC 7950, Section 10."; 2044 } 2045 } 2046 } 2047 grouping update-qos { 2048 description 2049 "This grouping describes Quality of Service information 2050 concerning a subscription. This information is passed to lower 2051 layers for transport prioritization and treatment"; 2052 leaf dscp { 2053 if-feature "dscp"; 2054 type inet:dscp; 2055 default "0"; 2056 description 2057 "The desired network transport priority level. This is the 2058 priority set on notification messages encapsulating the 2059 results of the subscription. This transport priority is 2060 shared for all receivers of a given subscription."; 2061 } 2062 leaf weighting { 2063 if-feature "qos"; 2064 type uint8 { 2065 range "0 .. 255"; 2066 } 2067 description 2068 "Relative weighting for a subscription. Allows an underlying 2069 transport layer perform informed load balance allocations 2070 between various subscriptions"; 2071 reference 2072 "RFC-7540, section 5.3.2"; 2073 } 2074 leaf dependency { 2075 if-feature "qos"; 2076 type subscription-id; 2077 description 2078 "Provides the 'subscription-id' of a parent subscription which 2079 has absolute precedence should that parent have push updates 2080 ready to egress the publisher. In other words, there should be 2081 no streaming of objects from the current subscription if 2082 the parent has something ready to push. 2084 If a dependency is asserted via configuration or via RPC, but 2085 the referenced 'subscription-id' does not exist, the 2086 dependency is silently discarded. If a referenced 2087 subscription is deleted this dependency is removed."; 2088 reference 2089 "RFC-7540, section 5.3.1"; 2090 } 2091 } 2093 grouping subscription-policy-modifiable { 2094 description 2095 "This grouping describes all objects which may be changed 2096 in a subscription."; 2097 choice target { 2098 mandatory true; 2099 description 2100 "Identifies the source of information against which a 2101 subscription is being applied, as well as specifics on the 2102 subset of information desired from that source."; 2103 case stream { 2104 choice stream-filter { 2105 description 2106 "An event stream filter can be applied to a subscription. 2107 That filter will come either referenced from a global list, 2108 or be provided within the subscription itself."; 2109 case by-reference { 2110 description 2111 "Apply a filter that has been configured separately."; 2112 leaf stream-filter-name { 2113 type stream-filter-ref; 2114 mandatory true; 2115 description 2116 "References an existing event stream filter which is to 2117 be applied to an event stream for the subscription."; 2118 } 2119 } 2120 case within-subscription { 2121 description 2122 "Local definition allows a filter to have the same 2123 lifecycle as the subscription."; 2124 uses stream-filter-elements; 2125 } 2126 } 2127 } 2128 } 2129 leaf stop-time { 2130 type yang:date-and-time; 2131 description 2132 "Identifies a time after which notification messages for a 2133 subscription should not be sent. If 'stop-time' is not 2134 present, the notification messages will continue until the 2135 subscription is terminated. If 'replay-start-time' exists, 2136 'stop-time' must be for a subsequent time. If 2137 'replay-start-time' doesn't exist, 'stop-time' when established 2138 must be for a future time."; 2139 } 2140 } 2142 grouping subscription-policy-dynamic { 2143 description 2144 "This grouping describes the only information concerning a 2145 subscription which can be passed over the RPCs defined in this 2146 model."; 2147 uses subscription-policy-modifiable { 2148 augment target/stream { 2149 description 2150 "Adds additional objects which can be modified by RPC."; 2151 leaf stream { 2152 type stream-ref { 2153 require-instance false; 2154 } 2155 mandatory true; 2156 description 2157 "Indicates the event stream to be considered for 2158 this subscription."; 2159 } 2160 leaf replay-start-time { 2161 if-feature "replay"; 2162 type yang:date-and-time; 2163 config false; 2164 description 2165 "Used to trigger the replay feature for a dynamic 2166 subscription, with event records being selected needing to 2167 be at or after the start at the time specified. If 2168 'replay-start-time' is not present, this is not a replay 2169 subscription and event record push should start 2170 immediately. It is never valid to specify start times that 2171 are later than or equal to the current time."; 2172 } 2173 } 2174 } 2175 uses update-qos; 2176 } 2178 grouping subscription-policy { 2179 description 2180 "This grouping describes the full set of policy information 2181 concerning both dynamic and configured subscriptions, with the 2182 exclusion of both receivers and networking information specific 2183 to the publisher such as what interface should be used to 2184 transmit notification messages."; 2185 uses subscription-policy-dynamic; 2186 leaf transport { 2187 if-feature "configured"; 2188 type transport; 2189 description 2190 "For a configured subscription, this leaf specifies the 2191 transport used to deliver messages destined to all receivers 2192 of that subscription."; 2193 } 2194 leaf encoding { 2195 when 'not(../transport) or derived-from(../transport, 2196 "sn:configurable-encoding")'; 2197 type encoding; 2198 description 2199 "The type of encoding for notification messages. For a 2200 dynamic subscription, if not included as part of an establish- 2201 subscription RPC, the encoding will be populated with the 2202 encoding used by that RPC. For a configured subscription, if 2203 not explicitly configured the encoding with be the default 2204 encoding for an underlying transport."; 2205 } 2206 leaf purpose { 2207 if-feature "configured"; 2208 type string; 2209 description 2210 "Open text allowing a configuring entity to embed the 2211 originator or other specifics of this subscription."; 2212 } 2213 } 2215 /* 2216 * RPCs 2217 */ 2219 rpc establish-subscription { 2220 description 2221 "This RPC allows a subscriber to create (and possibly negotiate) 2222 a subscription on its own behalf. If successful, the 2223 subscription remains in effect for the duration of the 2224 subscriber's association with the publisher, or until the 2225 subscription is terminated. In case an error occurs, or the 2226 publisher cannot meet the terms of a subscription, an RPC error 2227 is returned, the subscription is not created. In that case, the 2228 RPC reply's 'error-info' MAY include suggested parameter 2229 settings that would have a higher likelihood of succeeding in a 2230 subsequent 'establish-subscription' request."; 2231 input { 2232 uses subscription-policy-dynamic; 2233 leaf encoding { 2234 type encoding; 2235 description 2236 "The type of encoding for the subscribed data. If not 2237 included as part of the RPC, the encoding MUST be set by the 2238 publisher to be the encoding used by this RPC."; 2240 } 2241 } 2242 output { 2243 leaf id { 2244 type subscription-id; 2245 mandatory true; 2246 description 2247 "Identifier used for this subscription."; 2248 } 2249 leaf replay-start-time-revision { 2250 if-feature "replay"; 2251 type yang:date-and-time; 2252 description 2253 "If a replay has been requested, this represents the 2254 earliest time covered by the event buffer for the requested 2255 event stream. The value of this object is the 2256 'replay-log-aged-time' if it exists. Otherwise it is the 2257 'replay-log-creation-time'. All buffered event records 2258 after this time will be replayed to a receiver. This 2259 object will only be sent if the starting time has been 2260 revised to be later than the time requested by the 2261 subscriber."; 2262 } 2263 } 2264 } 2266 rc:yang-data establish-subscription-stream-error-info { 2267 container establish-subscription-stream-error-info { 2268 description 2269 "If any 'establish-subscription' RPC parameters are 2270 unsupportable against the event stream, a subscription is not 2271 created and the RPC error response MUST indicate the reason 2272 why the subscription failed to be created. This yang-data MAY 2273 be inserted as structured data within a subscription's RPC 2274 error response to indicate the failure reason. This yang-data 2275 MUST be inserted if hints are to be provided back to the 2276 subscriber."; 2277 leaf reason { 2278 type identityref { 2279 base establish-subscription-error; 2280 } 2281 description 2282 "Indicates the reason why the subscription has failed to 2283 be created to a targeted event stream."; 2284 } 2285 leaf filter-failure-hint { 2286 type string; 2287 description 2288 "Information describing where and/or why a provided filter 2289 was unsupportable for a subscription."; 2290 } 2291 } 2292 } 2294 rpc modify-subscription { 2295 description 2296 "This RPC allows a subscriber to modify a dynamic subscription's 2297 parameters. If successful, the changed subscription 2298 parameters remain in effect for the duration of the 2299 subscription, until the subscription is again modified, or until 2300 the subscription is terminated. In case of an error or an 2301 inability to meet the modified parameters, the subscription is 2302 not modified and the original subscription parameters remain in 2303 effect. In that case, the RPC error MAY include 'error-info' 2304 suggested parameter hints that would have a high likelihood of 2305 succeeding in a subsequent 'modify-subscription' request. A 2306 successful 'modify-subscription' will return a suspended 2307 subscription to an 'active' state."; 2308 input { 2309 leaf id { 2310 type subscription-id; 2311 mandatory true; 2312 description 2313 "Identifier to use for this subscription."; 2314 } 2315 uses subscription-policy-modifiable; 2316 } 2317 } 2319 rc:yang-data modify-subscription-stream-error-info { 2320 container modify-subscription-stream-error-info { 2321 description 2322 "This yang-data MAY be provided as part of a subscription's RPC 2323 error response when there is a failure of a 2324 'modify-subscription' RPC which has been made against an event 2325 stream. This yang-data MUST be used if hints are to be 2326 provided back to the subscriber."; 2327 leaf reason { 2328 type identityref { 2329 base modify-subscription-error; 2330 } 2331 description 2332 "Information in a 'modify-subscription' RPC error response 2333 which indicates the reason why the subscription to an event 2334 stream has failed to be modified."; 2335 } 2336 leaf filter-failure-hint { 2337 type string; 2338 description 2339 "Information describing where and/or why a provided filter 2340 was unsupportable for a subscription."; 2341 } 2342 } 2343 } 2345 rpc delete-subscription { 2346 description 2347 "This RPC allows a subscriber to delete a subscription that 2348 was previously created from by that same subscriber using the 2349 'establish-subscription' RPC. 2351 If an error occurs, the server replies with an 'rpc-error' where 2352 the 'error-info' field MAY contain an 2353 'delete-subscription-error-info' structure."; 2354 input { 2355 leaf id { 2356 type subscription-id; 2357 mandatory true; 2358 description 2359 "Identifier of the subscription that is to be deleted. 2360 Only subscriptions that were created using 2361 'establish-subscription' from the same origin as this RPC 2362 can be deleted via this RPC."; 2363 } 2364 } 2365 } 2367 rpc kill-subscription { 2368 nacm:default-deny-all; 2369 description 2370 "This RPC allows an operator to delete a dynamic subscription 2371 without restrictions on the originating subscriber or underlying 2372 transport session. 2374 If an error occurs, the server replies with an 'rpc-error' where 2375 the 'error-info' field MAY contain an 2376 'delete-subscription-error-info' structure."; 2377 input { 2378 leaf id { 2379 type subscription-id; 2380 mandatory true; 2381 description 2382 "Identifier of the subscription that is to be deleted. Only 2383 subscriptions that were created using 2384 'establish-subscription' can be deleted via this RPC."; 2385 } 2386 } 2387 } 2389 rc:yang-data delete-subscription-error-info { 2390 container delete-subscription-error-info { 2391 description 2392 "If a 'delete-subscription' RPC or a 'kill-subscription' RPC 2393 fails, the subscription is not deleted and the RPC error 2394 response MUST indicate the reason for this failure. This 2395 yang-data MAY be inserted as structured data within a 2396 subscription's RPC error response to indicate the failure 2397 reason."; 2398 leaf reason { 2399 type identityref { 2400 base delete-subscription-error; 2401 } 2402 mandatory true; 2403 description 2404 "Indicates the reason why the subscription has failed to be 2405 deleted."; 2406 } 2407 } 2408 } 2410 /* 2411 * NOTIFICATIONS 2412 */ 2414 notification replay-completed { 2415 sn:subscription-state-notification; 2416 if-feature "replay"; 2417 description 2418 "This notification is sent to indicate that all of the replay 2419 notifications have been sent."; 2420 leaf id { 2421 type subscription-id; 2422 mandatory true; 2423 description 2424 "This references the affected subscription."; 2425 } 2426 } 2428 notification subscription-completed { 2429 sn:subscription-state-notification; 2430 if-feature "configured"; 2431 description 2432 "This notification is sent to indicate that a subscription has 2433 finished passing event records, as the 'stop-time' has been 2434 reached."; 2435 leaf id { 2436 type subscription-id; 2437 mandatory true; 2438 description 2439 "This references the gracefully completed subscription."; 2440 } 2441 } 2443 notification subscription-modified { 2444 sn:subscription-state-notification; 2445 description 2446 "This notification indicates that a subscription has been 2447 modified. Notification messages sent from this point on will 2448 conform to the modified terms of the subscription. For 2449 completeness, this subscription state change notification 2450 includes both modified and non-modified aspects of a 2451 subscription."; 2452 leaf id { 2453 type subscription-id; 2454 mandatory true; 2455 description 2456 "This references the affected subscription."; 2457 } 2458 uses subscription-policy { 2459 refine "target/stream/stream-filter/within-subscription" { 2460 description 2461 "Filter applied to the subscription. If the 2462 'stream-filter-name' is populated, the filter within the 2463 subscription came from the 'filters' container. Otherwise it 2464 is populated in-line as part of the subscription."; 2465 } 2466 } 2467 } 2469 notification subscription-resumed { 2470 sn:subscription-state-notification; 2471 description 2472 "This notification indicates that a subscription that had 2473 previously been suspended has resumed. Notifications will once 2474 again be sent. In addition, a 'subscription-resumed' indicates 2475 that no modification of parameters has occurred since the last 2476 time event records have been sent."; 2477 leaf id { 2478 type subscription-id; 2479 mandatory true; 2480 description 2481 "This references the affected subscription."; 2482 } 2483 } 2485 notification subscription-started { 2486 sn:subscription-state-notification; 2487 if-feature "configured"; 2488 description 2489 "This notification indicates that a subscription has started and 2490 notifications are beginning to be sent."; 2491 leaf id { 2492 type subscription-id; 2493 mandatory true; 2494 description 2495 "This references the affected subscription."; 2496 } 2497 uses subscription-policy { 2498 refine "target/stream/replay-start-time" { 2499 description 2500 "Indicates the time that a replay is using for the streaming 2501 of buffered event records. This will be populated with the 2502 most recent of the following: the event time of the previous 2503 event record sent to a receiver, the 2504 'replay-log-creation-time', the 'replay-log-aged-time', 2505 or the most recent publisher boot time."; 2506 } 2507 refine "target/stream/stream-filter/within-subscription" { 2508 description 2509 "Filter applied to the subscription. If the 2510 'stream-filter-name' is populated, the filter within the 2511 subscription came from the 'filters' container. Otherwise it 2512 is populated in-line as part of the subscription."; 2513 } 2514 augment "target/stream" { 2515 description 2516 "This augmentation adds additional parameters specific to a 2517 subscription-started notification."; 2518 leaf replay-previous-event-time { 2519 when "../replay-start-time"; 2520 if-feature "replay"; 2521 type yang:date-and-time; 2522 description 2523 "If there is at least one event in the replay buffer prior 2524 to 'replay-start-time', this gives the time of the event 2525 generated immediately prior to the 'replay-start-time'. 2527 If a receiver previously received event records for this 2528 configured subscription, it can compare this time to the 2529 last event record previously received. If the two are not 2530 the same (perhaps due to a reboot), then a dynamic replay 2531 can be initiated to acquire any missing event records."; 2532 } 2533 } 2534 } 2535 } 2537 notification subscription-suspended { 2538 sn:subscription-state-notification; 2539 description 2540 "This notification indicates that a suspension of the 2541 subscription by the publisher has occurred. No further 2542 notifications will be sent until the subscription resumes. 2543 This notification shall only be sent to receivers of a 2544 subscription; it does not constitute a general-purpose 2545 notification."; 2546 leaf id { 2547 type subscription-id; 2548 mandatory true; 2549 description 2550 "This references the affected subscription."; 2551 } 2552 leaf reason { 2553 type identityref { 2554 base subscription-suspended-reason; 2555 } 2556 mandatory true; 2557 description 2558 "Identifies the condition which resulted in the suspension."; 2559 } 2560 } 2562 notification subscription-terminated { 2563 sn:subscription-state-notification; 2564 description 2565 "This notification indicates that a subscription has been 2566 terminated."; 2567 leaf id { 2568 type subscription-id; 2569 mandatory true; 2570 description 2571 "This references the affected subscription."; 2572 } 2573 leaf reason { 2574 type identityref { 2575 base subscription-terminated-reason; 2577 } 2578 mandatory true; 2579 description 2580 "Identifies the condition which resulted in the termination ."; 2581 } 2582 } 2584 /* 2585 * DATA NODES 2586 */ 2588 container streams { 2589 config false; 2590 description 2591 "This container contains information on the built-in event 2592 streams provided by the publisher."; 2593 list stream { 2594 key "name"; 2595 description 2596 "Identifies the built-in event streams that are supported by 2597 the publisher."; 2598 leaf name { 2599 type string; 2600 description 2601 "A handle for a system-provided event stream made up of a 2602 sequential set of event records, each of which is 2603 characterized by its own domain and semantics."; 2604 } 2605 leaf description { 2606 type string; 2607 description 2608 "A description of the event stream, including such 2609 information as the type of event records that are available 2610 within this event stream."; 2611 } 2612 leaf replay-support { 2613 if-feature "replay"; 2614 type empty; 2615 description 2616 "Indicates that event record replay is available on this 2617 event stream."; 2618 } 2619 leaf replay-log-creation-time { 2620 when "../replay-support"; 2621 if-feature "replay"; 2622 type yang:date-and-time; 2623 mandatory true; 2624 description 2625 "The timestamp of the creation of the log used to support the 2626 replay function on this event stream. This time might be 2627 earlier than the earliest available information contained in 2628 the log. This object is updated if the log resets for some 2629 reason."; 2630 } 2631 leaf replay-log-aged-time { 2632 when "../replay-support"; 2633 if-feature "replay"; 2634 type yang:date-and-time; 2635 description 2636 "The timestamp associated with last event record which has 2637 been aged out of the log. This timestamp identifies how far 2638 back into history this replay log extends, if it doesn't 2639 extend back to the 'replay-log-creation-time'. This object 2640 MUST be present if replay is supported and any event records 2641 have been aged out of the log."; 2642 } 2643 } 2644 } 2646 container filters { 2647 description 2648 "This container contains a list of configurable filters 2649 that can be applied to subscriptions. This facilitates 2650 the reuse of complex filters once defined."; 2651 list stream-filter { 2652 key "name"; 2653 description 2654 "A list of pre-configured filters that can be applied to 2655 subscriptions."; 2656 leaf name { 2657 type string; 2658 description 2659 "An name to differentiate between filters."; 2660 } 2661 uses stream-filter-elements; 2662 } 2663 } 2665 container subscriptions { 2666 description 2667 "Contains the list of currently active subscriptions, i.e. 2668 subscriptions that are currently in effect, used for 2669 subscription management and monitoring purposes. This includes 2670 subscriptions that have been setup via RPC primitives as well as 2671 subscriptions that have been established via configuration."; 2673 list subscription { 2674 key "id"; 2675 description 2676 "The identity and specific parameters of a subscription. 2677 Subscriptions within this list can be created using a control 2678 channel or RPC, or be established through configuration. 2680 If configuration operations or the 'kill-subscription' RPC are 2681 used to delete a subscription, a 'subscription-terminated' 2682 message is sent to any active or suspended receivers."; 2683 leaf id { 2684 type subscription-id; 2685 description 2686 "Identifier of a subscription; unique within a publisher"; 2687 } 2688 uses subscription-policy { 2689 refine "target/stream/stream" { 2690 description 2691 "Indicates the event stream to be considered for this 2692 subscription. If an event stream has been removed, 2693 and no longer can be referenced by an active subscription, 2694 send a 'subscription-terminated' notification with 2695 'stream-unavailable' as the reason. If a configured 2696 subscription refers to a non-existent event stream, move 2697 that subscription to the 'invalid' state."; 2698 } 2699 refine "transport" { 2700 description 2701 "For a configured subscription, this leaf specifies the 2702 transport used to deliver messages destined to all 2703 receivers of that subscription. This object is mandatory 2704 for subscriptions in the configuration datastore. This 2705 object is not mandatory for dynamic subscriptions within 2706 the operational state datastore. The object should not 2707 be present for dynamic subscriptions."; 2708 } 2709 augment "target/stream" { 2710 description 2711 "Enables objects to added to a configured stream 2712 subscription"; 2713 leaf configured-replay { 2714 if-feature "configured"; 2715 if-feature "replay"; 2716 type empty; 2717 description 2718 "The presence of this leaf indicates that replay for the 2719 configured subscription should start at the earliest time 2720 in the event log, or at the publisher boot time, which 2721 ever is later."; 2722 } 2723 } 2724 } 2725 choice notification-message-origin { 2726 if-feature "configured"; 2727 description 2728 "Identifies the egress interface on the publisher from which 2729 notification messages are to be sent."; 2730 case interface-originated { 2731 description 2732 "When notification messages to egress a specific, 2733 designated interface on the publisher."; 2734 leaf source-interface { 2735 if-feature "interface-designation"; 2736 type if:interface-ref; 2737 description 2738 "References the interface for notification messages."; 2739 } 2740 } 2741 case address-originated { 2742 description 2743 "When notification messages are to depart from a publisher 2744 using specific originating address and/or routing context 2745 information."; 2746 leaf source-vrf { 2747 if-feature "supports-vrf"; 2748 type leafref { 2749 path "/ni:network-instances/ni:network-instance/ni:name"; 2750 } 2751 description 2752 "VRF from which notification messages should egress a 2753 publisher."; 2754 } 2755 leaf source-address { 2756 type inet:ip-address-no-zone; 2757 description 2758 "The source address for the notification messages. If a 2759 source VRF exists, but this object doesn't, a publisher's 2760 default address for that VRF must be used."; 2761 } 2762 } 2763 } 2764 leaf configured-subscription-state { 2765 if-feature "configured"; 2766 type enumeration { 2767 enum valid { 2768 value 1; 2769 description 2770 "Subscription is supportable with current parameters."; 2771 } 2772 enum invalid { 2773 value 2; 2774 description 2775 "The subscription as a whole is unsupportable with its 2776 current parameters."; 2777 } 2778 enum concluded { 2779 value 3; 2780 description 2781 "A subscription is inactive as it has hit a stop time, 2782 it no longer has receivers in the 'receiver active' or 2783 'receiver suspended' state, but not yet been 2784 removed from configuration."; 2785 } 2786 } 2787 config false; 2788 description 2789 "The presence of this leaf indicates that the subscription 2790 originated from configuration, not through a control channel 2791 or RPC. The value indicates the system established state 2792 of the subscription."; 2793 } 2794 container receivers { 2795 description 2796 "Set of receivers in a subscription."; 2797 list receiver { 2798 key "name"; 2799 min-elements 1; 2800 description 2801 "A host intended as a recipient for the notification 2802 messages of a subscription. For configured subscriptions, 2803 transport specific network parameters (or a leafref to 2804 those parameters) may augmentated to a specific receiver 2805 within this list."; 2806 leaf name { 2807 type string; 2808 description 2809 "Identifies a unique receiver for a subscription."; 2810 } 2811 leaf sent-event-records { 2812 type yang:zero-based-counter64; 2813 config false; 2814 description 2815 "The number of event records sent to the receiver. The 2816 count is initialized when a dynamic subscription is 2817 established, or when a configured receiver 2818 transitions to the valid state."; 2819 } 2820 leaf excluded-event-records { 2821 type yang:zero-based-counter64; 2822 config false; 2823 description 2824 "The number of event records explicitly removed either 2825 via an event stream filter or an access control filter so 2826 that they are not passed to a receiver. This count is 2827 set to zero each time 'sent-event-records' is 2828 initialized."; 2829 } 2830 leaf state { 2831 type enumeration { 2832 enum active { 2833 value 1; 2834 description 2835 "Receiver is currently being sent any applicable 2836 notification messages for the subscription."; 2837 } 2838 enum suspended { 2839 value 2; 2840 description 2841 "Receiver state is 'suspended', so the publisher 2842 is currently unable to provide notification messages 2843 for the subscription."; 2844 } 2845 enum connecting { 2846 value 3; 2847 if-feature "configured"; 2848 description 2849 "A subscription has been configured, but a 2850 'subscription-started' subscription state change 2851 notification needs to be successfully received before 2852 notification messages are sent. 2854 If the 'reset' action is invoked for a receiver of an 2855 active configured subscription, the state must be 2856 moved to 'connecting'."; 2857 } 2858 enum disconnected { 2859 value 4; 2860 if-feature "configured"; 2861 description 2862 "A subscription has failed in sending a subscription 2863 started state change to the receiver. 2864 Additional attempts at connection attempts are not 2865 currently being made."; 2866 } 2867 } 2868 config false; 2869 mandatory true; 2870 description 2871 "Specifies the state of a subscription from the 2872 perspective of a particular receiver. With this info it 2873 is possible to determine whether a subscriber is 2874 currently generating notification messages intended for 2875 that receiver."; 2876 } 2877 action reset { 2878 if-feature "configured"; 2879 description 2880 "Allows the reset of this configured subscription 2881 receiver to the 'connecting' state. This enables the 2882 connection process to be re-initiated."; 2883 output { 2884 leaf time { 2885 type yang:date-and-time; 2886 mandatory true; 2887 description 2888 "Time a publisher returned the receiver to a 2889 'connecting' state."; 2890 } 2891 } 2892 } 2893 } 2894 } 2895 } 2896 } 2897 } 2898 2900 5. Considerations 2902 5.1. IANA Considerations 2904 This document registers the following namespace URI in the "IETF XML 2905 Registry" [RFC3688]: 2907 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2908 Registrant Contact: The IESG. 2909 XML: N/A; the requested URI is an XML namespace. 2911 This document registers the following YANG module in the "YANG Module 2912 Names" registry [RFC6020]: 2914 Name: ietf-subscribed-notifications 2915 Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2916 Prefix: sn 2917 Reference: draft-ietf-netconf-ietf-subscribed-notifications-11.txt 2918 (RFC form) 2920 5.2. Implementation Considerations 2922 To support deployments including both configured and dynamic 2923 subscriptions, it is recommended to split the subscription "id" 2924 domain into static and dynamic halves. That way it eliminates the 2925 possibility of collisions if the configured subscriptions attempt to 2926 set a subscription-id which might have already been dynamically 2927 allocated. A best practice is to use lower half the "id" object's 2928 integer space when that "id" is assigned by an external entity (such 2929 as with a configured subscription). This leaves the upper half of 2930 subscription integer space available to be dynamically assigned by 2931 the publisher. 2933 If a subscription is unable to marshal a series of filtered event 2934 records into transmittable notification messages, the receiver should 2935 be suspended with the reason "unsupportable-volume". 2937 For configured subscriptions, operations are against the set of 2938 receivers using the subscription "id" as a handle for that set. But 2939 for streaming updates, subscription state change notifications are 2940 local to a receiver. In this specification it is the case that 2941 receivers get no information from the publisher about the existence 2942 of other receivers. But if a network operator wants to let the 2943 receivers correlate results, it is useful to use the subscription 2944 "id" across the receivers to allow that correlation. 2946 For configured replay subscriptions, the receiver is protected from 2947 duplicated events being pushed after a publisher is rebooted. 2948 However it is possible that a receiver might want to acquire event 2949 records which failed to be delivered just prior to the reboot. 2950 Delivering these event records be accomplished by leveraging the 2951 "eventTime" from the last event record received prior to the receipt 2952 of a "subscription-started" subscription state change notification. 2953 With this "eventTime" and the "replay-start-time" from the 2954 "subscription-started" notification, an independent dynamic 2955 subscription can be established which retrieves any event records 2956 which may have been generated but not sent to the receiver. 2958 5.3. Transport Requirements 2960 This section provides requirements for any subscribed notification 2961 transport supporting the solution presented in this document. 2963 The transport selected by the subscriber to reach the publisher MUST 2964 be able to support multiple "establish-subscription" requests made 2965 within the same transport session. 2967 For both configured and dynamic subscriptions the publisher MUST 2968 authenticate a receiver via some transport level mechanism before 2969 sending any event records for which they are authorized to see. In 2970 addition, the receiver MUST authenticate the publisher at the 2971 transport level. The result is mutual authentication between the 2972 two. 2974 A secure transport is highly recommended and the publisher MUST 2975 ensure that the receiver has sufficient authorization to perform the 2976 function they are requesting against the specific subset of content 2977 involved. 2979 A specific transport specification built upon this document may or 2980 may not choose to require the use of the same logical channel for the 2981 RPCs and the event records. However the event records and the 2982 subscription state change notifications MUST be sent on the same 2983 transport session to ensure the properly ordered delivery. 2985 Additional transport requirements will be dictated by the choice of 2986 transport used with a subscription. For an example of such 2987 requirements with NETCONF transport, see 2988 [I-D.draft-ietf-netconf-netconf-event-notifications]. 2990 5.4. Security Considerations 2992 The YANG module specified in this document defines a schema for data 2993 that is designed to be accessed via network management transports 2994 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 2995 layer is the secure transport layer, and the mandatory-to-implement 2996 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 2997 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 2998 transport is TLS [RFC5246]. 3000 The NETCONF Access Control Model (NACM) [RFC8341] provides the means 3001 to restrict access for particular NETCONF or RESTCONF users to a 3002 preconfigured subset of all available NETCONF or RESTCONF operations 3003 and content. 3005 One subscription "id" can be used for two or more receivers of the 3006 same configured subscription. But due to the possibility of 3007 different access control permissions per receiver, it cannot be 3008 assumed that each receiver is getting identical updates. 3010 With configured subscriptions, one or more publishers could be used 3011 to overwhelm a receiver. Notification messages SHOULD NOT be sent to 3012 any receiver which does not support this specification. Receivers 3013 that do not want notification messages need only terminate or refuse 3014 any transport sessions from the publisher. 3016 When a receiver of a configured subscription gets a new 3017 "subscription-started" message for a known subscription where it is 3018 already consuming events, the receiver SHOULD retrieve any event 3019 records generated since the last event record was received. This can 3020 be accomplish by establishing a separate dynamic replay subscription 3021 with the same filtering criteria with the publisher, assuming the 3022 publisher supports the "replay" feature. 3024 For dynamic subscriptions, implementations need to protect against 3025 malicious or buggy subscribers which may send a large number 3026 "establish-subscription" requests, thereby using up system resources. 3027 To cover this possibility operators SHOULD monitor for such cases 3028 and, if discovered, take remedial action to limit the resources used, 3029 such as suspending or terminating a subset of the subscriptions or, 3030 if the underlying transport is session based, terminate the 3031 underlying transport session. 3033 There are a number of data nodes defined in this YANG module that are 3034 writable/creatable/deletable (i.e., config true, which is the 3035 default). These data nodes may be considered sensitive or vulnerable 3036 in some network environments. Write operations (e.g., edit-config) 3037 to these data nodes without proper protection can have a negative 3038 effect on network operations. These are the subtrees and data nodes 3039 where there is a specific sensitivity/vulnerability: 3041 Container: "/filters" 3043 o "stream-subtree-filter": updating a filter could increase the 3044 computational complexity of all referencing subscriptions. 3046 o "stream-xpath-filter": updating a filter could increase the 3047 computational complexity of all referencing subscriptions. 3049 Container: "/subscriptions" 3051 The following considerations are only relevant for configuration 3052 operations made upon configured subscriptions: 3054 o "configured-replay": can be used to send a large number of event 3055 records to a receiver. 3057 o "dependency": can be used to force important traffic to be queued 3058 behind less important updates. 3060 o "dscp": if unvalidated, can result in the sending of traffic with 3061 a higher priority marking than warranted. 3063 o "id": can overwrite an existing subscription, perhaps one 3064 configured by another entity. 3066 o "name": adding a new key entry can be used to attempt to send 3067 traffic to an unwilling receiver. 3069 o "replay-start-time": can be used to push very large logs, wasting 3070 resources. 3072 o "source-address": the configured address might not be able to 3073 reach a desired receiver. 3075 o "source-interface": the configured interface might not be able to 3076 reach a desired receiver. 3078 o "source-vrf": can place a subscription into a virtual network 3079 where receivers are not entitled to view the subscribed content. 3081 o "stop-time": could be used to terminate content at an inopportune 3082 time. 3084 o "stream": could set a subscription to an event stream containing 3085 no content permitted for the targeted receivers. 3087 o "stream-filter-name": could be set to a filter which is irrelevant 3088 to the event stream. 3090 o "stream-subtree-filter": a complex filter can increase the 3091 computational resources for this subscription. 3093 o "stream-xpath-filter": a complex filter can increase the 3094 computational resources for this subscription. 3096 o "weighting": placing a large weight can overwhelm the dequeuing of 3097 other subscriptions. 3099 Some of the readable data nodes in this YANG module may be considered 3100 sensitive or vulnerable in some network environments. It is thus 3101 important to control read access (e.g., via get, get-config, or 3102 notification) to these data nodes. These are the subtrees and data 3103 nodes and their sensitivity/vulnerability: 3105 Container: "/streams" 3107 o "name": if access control is not properly configured, can expose 3108 system internals to those who should have no access to this 3109 information. 3111 o "replay-support": if access control is not properly configured, 3112 can expose logs to those who should have no access. 3114 Container: "/subscriptions" 3116 o "excluded-event-records": leaf can provide information about 3117 filtered event records. A network operator should have 3118 permissions to know about such filtering. 3120 o "subscription": different operational teams might have a desire to 3121 set varying subsets of subscriptions. Access control should be 3122 designed to permit read access to just the allowed set. 3124 Some of the RPC operations in this YANG module may be considered 3125 sensitive or vulnerable in some network environments. It is thus 3126 important to control access to these operations. These are the 3127 operations and their sensitivity/vulnerability: 3129 RPC: all 3131 o If a malicious or buggy subscriber sends an unexpectedly large 3132 number of RPCs, the result might be an excessive use of system 3133 resources on the publisher just to determine that these 3134 subscriptions should be declined. In such a situation, 3135 subscription interactions MAY be terminated by terminating the 3136 transport session. 3138 RPC: "delete-subscription" 3140 o No special considerations. 3142 RPC: "establish-subscription" 3144 o Subscriptions could overload a publisher's resources. For this 3145 reason, publishers MUST ensure that they have sufficient resources 3146 to fulfill this request or otherwise reject the request. 3148 RPC: "kill-subscription" 3149 o The "kill-subscription" RPC MUST be secured so that only 3150 connections with administrative rights are able to invoke this 3151 RPC. 3153 RPC: "modify-subscription" 3155 o Subscriptions could overload a publisher's resources. For this 3156 reason, publishers MUST ensure that they have sufficient resources 3157 to fulfill this request or otherwise reject the request. 3159 6. Acknowledgments 3161 For their valuable comments, discussions, and feedback, we wish to 3162 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen, 3163 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan 3164 Hares, Michael Scharf, and Guangying Zheng. 3166 7. References 3168 7.1. Normative References 3170 [I-D.draft-ietf-rtgwg-ni-model] 3171 Berger, L., Hopps, C., and A. Lindem, "YANG Network 3172 Instances", draft-ietf-rtgwg-ni-model-12 (work in 3173 progress), March 2018. 3175 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3176 Requirement Levels", BCP 14, RFC 2119, 3177 DOI 10.17487/RFC2119, March 1997, 3178 . 3180 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 3181 "Definition of the Differentiated Services Field (DS 3182 Field) in the IPv4 and IPv6 Headers", RFC 2474, 3183 DOI 10.17487/RFC2474, December 1998, 3184 . 3186 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3187 DOI 10.17487/RFC3688, January 2004, 3188 . 3190 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3191 (TLS) Protocol Version 1.2", RFC 5246, 3192 DOI 10.17487/RFC5246, August 2008, 3193 . 3195 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3196 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 3197 . 3199 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 3200 the Network Configuration Protocol (NETCONF)", RFC 6020, 3201 DOI 10.17487/RFC6020, October 2010, 3202 . 3204 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3205 and A. Bierman, Ed., "Network Configuration Protocol 3206 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 3207 . 3209 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 3210 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 3211 . 3213 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 3214 RFC 6991, DOI 10.17487/RFC6991, July 2013, 3215 . 3217 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3218 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3219 . 3221 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3222 RFC 7951, DOI 10.17487/RFC7951, August 2016, 3223 . 3225 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 3226 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 3227 . 3229 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3230 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3231 May 2017, . 3233 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 3234 Access Control Model", STD 91, RFC 8341, 3235 DOI 10.17487/RFC8341, March 2018, 3236 . 3238 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 3239 and R. Wilton, "Network Management Datastore Architecture 3240 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 3241 . 3243 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 3244 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 3245 . 3247 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 3248 Version 1.0", November 1999, 3249 . 3251 7.2. Informative References 3253 [I-D.draft-ietf-netconf-netconf-event-notifications] 3254 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3255 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 3256 event notifications", May 2018, 3257 . 3260 [I-D.draft-ietf-netconf-restconf-notif] 3261 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen- 3262 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and 3263 HTTP transport for event notifications", May 2018, 3264 . 3267 [I-D.ietf-netconf-yang-push] 3268 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3269 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 3270 Lengyel, "YANG Datastore Subscription", May 2018, 3271 . 3274 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3275 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3276 October 2013, . 3278 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 3279 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 3280 DOI 10.17487/RFC7540, May 2015, 3281 . 3283 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 3284 for Subscription to YANG Datastores", RFC 7923, 3285 DOI 10.17487/RFC7923, June 2016, 3286 . 3288 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 3289 RFC 8071, DOI 10.17487/RFC8071, February 2017, 3290 . 3292 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3293 Interchange Format", STD 90, RFC 8259, 3294 DOI 10.17487/RFC8259, December 2017, 3295 . 3297 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3298 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3299 . 3301 Appendix A. Example Configured Transport Augmentation 3303 This appendix provides a non-normative example of how the YANG model 3304 defined in Section 4 may be enhanced to incorporate the configuration 3305 parameters needed to support the transport connectivity process. In 3306 this example, connectivity via an imaginary transport type of "foo" 3307 is explored. For more on the overall need, see Section 2.5.7. 3309 The YANG model defined in this section contains two main elements. 3310 First is a transport identity "foo". This transport identity allows 3311 a configuration agent to define "foo" as the selected type of 3312 transport for a subscription. Second is a YANG case augmentation 3313 "foo" which is made to the "/subscriptions/subscription/receivers/ 3314 receiver" node of Section 4. Within this augmentation are the 3315 transport configuration parameters "address" and "port" which are 3316 necessary to make the connect to the receiver. 3318 module example-foo-subscribed-notifications { 3319 yang-version 1.1; 3320 namespace 3321 "urn:example:foo-subscribed-notifications"; 3323 prefix fsn; 3325 import ietf-subscribed-notifications { 3326 prefix sn; 3327 } 3328 import ietf-inet-types { 3329 prefix inet; 3330 } 3332 description 3333 "Defines 'foo' as a supported type of configured transport for 3334 subscribed event notifications."; 3336 identity foo { 3337 base sn:transport; 3338 description 3339 "Transport type 'foo' is available for use as a configured 3340 subscription transport protocol for subscribed notifications."; 3341 } 3343 augment 3344 "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { 3345 when 'derived-from(../../../transport, "fsn:foo")'; 3346 description 3347 "This augmentation makes 'foo' specific transport parameters 3348 available for a receiver."; 3349 leaf address { 3350 type inet:host; 3351 mandatory true; 3352 description 3353 "Specifies the address to use for messages destined to a 3354 receiver."; 3355 } 3356 leaf port { 3357 type inet:port-number; 3358 mandatory true; 3359 description 3360 "Specifies the port number to use for messages destined to a 3361 receiver."; 3362 } 3363 } 3364 } 3366 Figure 21: Example Transport Augmentation for the fictitious protocol 3367 foo 3369 This example YANG model for transport "foo" will not be seen in a 3370 real world deployment. For a real world deployment supporting an 3371 actual transport technology, a similar YANG model must be defined. 3373 Appendix B. Changes between revisions 3375 (To be removed by RFC editor prior to publication) 3377 v22 - v23 3379 o During the YANG Doctor review, feature dscp support was refined to 3380 avoid the out-of-order delivery of packets in a single TCP 3381 session. 3383 v21 - v22 3385 o YANG Dr definition clarifications. This includes refined text on: 3386 (a) stop-time can be used without replay, (b) a separate dynamic 3387 subscription for replay, (c) subscription state change 3388 notifications can't be dropped, more details on "enum concluded" 3389 and (d) more text on configurable-encoding leaf (which adds two 3390 informative references). There also was one minor tweak in the 3391 YANG model. The stream description leaf had "mandatory true" 3392 removed. 3394 v20 - v21 3396 o Editorial change in Section 1.3 requested by Qin's Shepherd review 3397 of NETCONF-Notif and RESTCONF-Notif. Basically extra text was 3398 added further describing that dynamic subscriptions can have state 3399 change notifications. 3401 v18 - v20 3403 o XPath-stream-filter YANG object definition updated based on NETMOD 3404 discussions. 3406 v17 - v18 3408 o Transport optional in YANG model. 3410 o Modify subscription must come from the originator of the 3411 subscription. (Text got dropped somewhere previously.) 3413 o Title change. 3415 v16 - v17 3417 o YANG renaming: Subscription identifier renamed to id. Counters 3418 renamed. Filters id made into name. 3420 o Text tweaks. 3422 v15 - v16 3424 o Mandatory empty case "transport" removed. 3426 o Appendix case turned from "netconf" to "foo". 3428 v14 - v15 3430 o Text tweaks. 3432 o Mandatory empty case "transport" added for transport parameters. 3433 This includes a new section and an appendix explaining it. 3435 v13 - v14 3436 o Removed the 'address' leaf. 3438 o Replay is now of type 'empty' for configured. 3440 v12 - v13 3442 o Tweaks from Kent's comments 3444 o Referenced in YANG model updated per Tom Petch's comments 3446 o Added leaf replay-previous-event-time 3448 o Renamed the event counters, downshifted the subscription states 3450 v11 - v12 3452 o Tweaks from Kent's, Tim's, and Martin's comments 3454 o Clarified dscp text, and made its own feature 3456 o YANG model tweaks alphabetizing, features. 3458 v10 - v11 3460 o access control filtering of events in streams included to match 3461 RFC5277 behavior 3463 o security considerations updated based on YANG template. 3465 o dependency QoS made non-normative on HTTP2 QoS 3467 o tree diagrams referenced for each figure using them 3469 o reference numbers placed into state machine figures 3471 o broke configured replay into its own section 3473 o many tweaks updates based on LC and YANG doctor reviews 3475 o trees and YANG model reconciled were deltas existed 3477 o new feature for interface originated. 3479 o dscp removed from the qos feature 3481 o YANG model updated in a way which collapses groups only used once 3482 so that they are part of the 'subscriptions' container. 3484 o alternative encodings only allowed for transports which support 3485 them. 3487 v09 - v10 3489 o Typos and tweaks 3491 v08 - v09 3493 o NMDA model supported. Non NMDA version at https://github.com/ 3494 netconf-wg/rfc5277bis/ 3496 o Error mechanism revamped to match to embedded implementations. 3498 o Explicitly identified error codes relevant to each RPC/ 3499 Notification 3501 v07 - v08 3503 o Split YANG trees to separate document subsections. 3505 o Clarified configured state machine based on Balazs comments, and 3506 moved it into the configured subscription subsections. 3508 o Normative reference to Network Instance model for VRF 3510 o One transport for all receivers of configured subscriptions. 3512 o QoS section moved in from yang-push 3514 v06 - v07 3516 o Clarification on state machine for configured subscriptions. 3518 v05 - v06 3520 o Made changes proposed by Martin, Kent, and others on the list. 3521 Most significant of these are stream returned to string (with the 3522 SYSLOG identity removed), intro section on 5277 relationship, an 3523 identity set moved to an enumeration, clean up of definitions/ 3524 terminology, state machine proposed for configured subscriptions 3525 with a clean-up of subscription state options. 3527 o JSON and XML become features. Also Xpath and subtree filtering 3528 become features 3530 o Terminology updates with event records, and refinement of filters 3531 to just event stream filters. 3533 o Encoding refined in establish-subscription so it takes the RPC's 3534 encoding as the default. 3536 o Namespaces in examples fixed. 3538 v04 - v05 3540 o Returned to the explicit filter subtyping of v00 3542 o stream object changed to 'name' from 'stream' 3544 o Cleaned up examples 3546 o Clarified that JSON support needs notification-messages draft. 3548 v03 - v04 3550 o Moved back to the use of RFC5277 one-way notifications and 3551 encodings. 3553 v03 - v04 3555 o Replay updated 3557 v02 - v03 3559 o RPCs and Notification support is identified by the Notification 3560 2.0 capability. 3562 o Updates to filtering identities and text 3564 o New error type for unsupportable volume of updates 3566 o Text tweaks. 3568 v01 - v02 3570 o Subscription status moved under receiver. 3572 v00 - v01 3574 o Security considerations updated 3576 o Intro rewrite, as well as scattered text changes 3578 o Added Appendix A, to help match this to related drafts in progress 3579 o Updated filtering definitions, and filter types in yang file, and 3580 moved to identities for filter types 3582 o Added Syslog as an event stream 3584 o HTTP2 moved in from YANG-Push as a transport option 3586 o Replay made an optional feature for events. Won't apply to 3587 datastores 3589 o Enabled notification timestamp to have different formats. 3591 o Two error codes added. 3593 v01 5277bis - v00 subscribed notifications 3595 o Kill subscription RPC added. 3597 o Renamed from 5277bis to Subscribed Notifications. 3599 o Changed the notification capabilities version from 1.1 to 2.0. 3601 o Extracted create-subscription and other elements of RFC5277. 3603 o Error conditions added, and made specific in return codes. 3605 o Simplified yang model structure for removal of 'basic' grouping. 3607 o Added a grouping for items which cannot be statically configured. 3609 o Operational counters per receiver. 3611 o Subscription-id and filter-id renamed to identifier 3613 o Section for replay added. Replay now cannot be configured. 3615 o Control plane notification renamed to subscription state change 3616 notification 3618 o Source address: Source-vrf changed to string, default address 3619 option added 3621 o In yang model: 'info' changed to 'policy' 3623 o Scattered text clarifications 3625 v00 - v01 of 5277bis 3626 o YANG Model changes. New groupings for subscription info to allow 3627 restriction of what is changeable via RPC. Removed notifications 3628 for adding and removing receivers of configured subscriptions. 3630 o Expanded/renamed definitions from event server to publisher, and 3631 client to subscriber as applicable. Updated the definitions to 3632 include and expand on RFC 5277. 3634 o Removal of redundancy with other drafts 3636 o Many other clean-ups of wording and terminology 3638 Authors' Addresses 3640 Eric Voit 3641 Cisco Systems 3643 Email: evoit@cisco.com 3645 Alexander Clemm 3646 Huawei 3648 Email: ludwig@clemm.org 3650 Alberto Gonzalez Prieto 3651 Microsoft 3653 Email: alberto.gonzalez@microsoft.com 3655 Einar Nilsen-Nygaard 3656 Cisco Systems 3658 Email: einarnn@cisco.com 3660 Ambika Prasad Tripathy 3661 Cisco Systems 3663 Email: ambtripa@cisco.com