idnits 2.17.1 draft-ietf-netconf-subscribed-notifications-18.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 1306 has weird spacing: '... reason ide...' == Line 1341 has weird spacing: '... reason ide...' == Line 1357 has weird spacing: '...--ro id sub...' == Line 1372 has weird spacing: '...--ro id sub...' == Line 1393 has weird spacing: '...--ro id sub...' == (3 more instances...) -- The document date (October 23, 2018) is 2005 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 7540 (Obsoleted by RFC 9113) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF E. Voit 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track A. Clemm 5 Expires: April 26, 2019 Huawei 6 A. Gonzalez Prieto 7 Microsoft 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 October 23, 2018 13 Subscription to YANG Event Notifications 14 draft-ietf-netconf-subscribed-notifications-18 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 April 26, 2019. 41 Copyright Notice 43 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 7 65 2.2. Event Stream Filters . . . . . . . . . . . . . . . . . . 7 66 2.3. QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 2.4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 9 68 2.5. Configured Subscriptions . . . . . . . . . . . . . . . . 17 69 2.6. Event Record Delivery . . . . . . . . . . . . . . . . . . 24 70 2.7. subscription state change notifications . . . . . . . . . 25 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 . . . . . . . . . . . . . . 62 81 5.3. Transport Requirements . . . . . . . . . . . . . . . . . 63 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 . . . . . 70 88 Appendix B. Changes between revisions . . . . . . . . . . . . . 72 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 77 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 HTTP2 or HTTP1.1 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. Also note that transport specific transport drafts based 242 on this specification MUST detail the life cycles of both dynamic and 243 configured subscriptions. 245 A publisher MAY terminate a dynamic subscription at any time. 246 Similarly, it MAY decide to temporarily suspend the sending of 247 notification messages for any dynamic subscription, or for one or 248 more receivers of a configured subscription. Such termination or 249 suspension is driven by internal considerations of the publisher. 251 1.4. Relationship to RFC 5277 253 This document is intended to provide a superset of the subscription 254 capabilities initially defined within [RFC5277]. Especially when 255 extending an existing [RFC5277] implementation, it is important to 256 understand what has been reused and what has been replaced. Key 257 relationships between these two documents include: 259 o this document defines a transport independent capability, 260 [RFC5277] is specific to NETCONF. 262 o the data model in this document is used instead of the data model 263 in Section 3.4 of [RFC5277] for the new operations. 265 o the RPC operations in this draft replace the operation "create- 266 subscription" defined in [RFC5277], section 4. 268 o the message of [RFC5277], Section 4 is used. 270 o the included contents of the "NETCONF" event stream are identical 271 between this document and [RFC5277]. 273 o a publisher MAY implement both the Notification Management Schema 274 and RPCs defined in [RFC5277] and this new document concurrently. 276 o unlike [RFC5277], this document enables a single transport session 277 to intermix notification messages and RPCs for different 278 subscriptions. 280 2. Solution 282 Per the overview provided in Section 1.3, this section details the 283 overall context, state machines, and subsystems which may be 284 assembled to allow the subscription of events from a publisher. 286 2.1. Event Streams 288 An event stream is a named entity on a publisher which exposes a 289 continuously updating set of YANG encoded event records. An event 290 record is an intantiation of a "notification" YANG statement. If the 291 "notification" is defined as a child to a data node, the intantiation 292 includes the hierarchy of nodes that identifies the data node in the 293 datastore (see Section 7.16.2 of [RFC7950]). Each event stream is 294 available for subscription. It is out of the scope of this document 295 to identify a) how event streams are defined (other than the NETCONF 296 stream), b) how event records are defined/generated, and c) how event 297 records are assigned to event streams. 299 There is only one reserved event stream name within this document: 300 "NETCONF". The "NETCONF" event stream contains all NETCONF event 301 record information supported by the publisher, except where an event 302 record has explicitly been excluded from the stream. Beyond the 303 "NETCONF" stream, implementations MAY define additional event 304 streams. 306 As YANG encoded event records are created by a system, they may be 307 assigned to one or more streams. The event record is distributed to 308 a subscription's receiver(s) where: (1) a subscription includes the 309 identified stream, and (2) subscription filtering does not exclude 310 the event record from that receiver. 312 Access control permissions may be used to silently exclude event 313 records from within an event stream for which the receiver has no 314 read access. As an example of how this might be accomplished, see 315 [RFC8341] section 3.4.6. Note that per Section 2.7 of this document, 316 subscription state change notifications are never filtered out. 318 If no access control permissions are in place for event records on an 319 event stream, then a receiver MUST be allowed access to all the event 320 records. If subscriber permissions change during the lifecycle of a 321 subscription and event stream access is no longer permitted, then the 322 subscription MUST be terminated. 324 Event records MUST NOT be delivered to a receiver in a different 325 order than they were placed onto an event stream. 327 2.2. Event Stream Filters 329 This document defines an extensible filtering mechanism. The filter 330 itself is a boolean test which is placed on the content of an event 331 record. A 'false' filtering result causes the event message to be 332 excluded from delivery to a receiver. A filter never results in 333 information being stripped from within an event record prior to that 334 event record being encapsulated within a notification message. The 335 two optional event stream filtering syntaxes supported are [XPATH] 336 and subtree [RFC6241]. 338 If no event stream filter is provided within a subscription, all 339 event records on an event stream are to be sent. 341 2.3. QoS 343 This document provide for several QoS parameters. These parameters 344 indicate the treatment of a subscription relative to other traffic 345 between publisher and receiver. Included are: 347 o A "dscp" marking to differentiate prioritization of notification 348 messages during network transit. 350 o A "weighting" so that bandwidth proportional to this weighting can 351 be allocated to this subscription relative to other subscriptions. 353 o a "dependency" upon another subscription. 355 If the publisher supports the "dscp" feature, then a subscription 356 with a "dscp" leaf MUST result in a corresponding [RFC2474] DSCP 357 marking being placed within the IP header of any resulting 358 notification messages and subscription state change notifications. 360 For the "weighting" parameter, when concurrently dequeuing 361 notification messages from multiple subscriptions to a receiver, the 362 publisher MUST allocate bandwidth to each subscription proportionally 363 to the weights assigned to those subscriptions. "Weighting" is an 364 optional capability of the publisher; support for it is identified 365 via the "qos" feature. 367 If a subscription has the "dependency" parameter set, then any 368 buffered notification messages containing event records selected by 369 the parent subscription MUST be dequeued prior to the notification 370 messages of the dependent subscription. If notification messages 371 have dependencies on each other, the notification message queued the 372 longest MUST go first. If a "dependency" included within an RPC 373 references a subscription which does not exist or is no longer 374 accessible to that subscriber, that "dependency" MUST be silently 375 removed. "Dependency" is an optional capability of the publisher; 376 support for it is identified via the "qos" feature. 378 2.4. Dynamic Subscriptions 380 Dynamic subscriptions are managed via protocol operations (in the 381 form of [RFC7950], Section 7.14 RPCs) made against targets located 382 within the publisher. These RPCs have been designed extensibly so 383 that they may be augmented for subscription targets beyond event 384 streams. For examples of such augmentations, see the RPC 385 augmentations within [I-D.ietf-netconf-yang-push]'s YANG model. 387 2.4.1. Dynamic Subscription State Model 389 Below is the publisher's state machine for a dynamic subscription. 390 Each state is shown in its own box. It is important to note that 391 such a subscription doesn't exist at the publisher until an 392 "establish-subscription" RPC is accepted. The mere request by a 393 subscriber to establish a subscription is insufficient for that 394 subscription to be externally visible. Start and end states are 395 depicted to reflect subscription creation and deletion events. 397 ......... 398 : start : 399 :.......: 400 | 401 establish-subscription 402 | 403 | .-------modify-subscription--------. 404 v v | 405 .-----------. .-----------. 406 .--------. | receiver |--insufficient CPU, b/w-->| receiver | 407 modify- '| active | | suspended | 408 subscription | |<----CPU, b/w sufficient--| | 409 ---------->'-----------' '-----------' 410 | | 411 delete/kill-subscription delete/kill- 412 | subscription 413 v | 414 ......... | 415 : end :<---------------------------------' 416 :.......: 418 Figure 1: Publisher's state for a dynamic subscription 420 Of interest in this state machine are the following: 422 o Successful "establish-subscription" or "modify-subscription" RPCs 423 put the subscription into the active state. 425 o Failed "modify-subscription" RPCs will leave the subscription in 426 its previous state, with no visible change to any streaming 427 updates. 429 o A "delete-subscription" or "kill-subscription" RPC will end the 430 subscription, as will the reaching of a "stop-time". 432 o A publisher may choose to suspend a subscription when there is 433 insufficient CPU or bandwidth available to service the 434 subscription. This is notified to a subscriber with a 435 "subscription-suspended" subscription state change notification. 437 o A suspended subscription may be modified by the subscriber (for 438 example in an attempt to use fewer resources). Successful 439 modification returns the subscription to the active state. 441 o Even without a "modify-subscription" request, a publisher may 442 return a subscription to the active state should the resource 443 constraints become sufficient again. This is announced to the 444 subscriber via the "subscription-resumed" subscription state 445 change notification. 447 2.4.2. Establishing a Dynamic Subscription 449 The "establish-subscription" RPC allows a subscriber to request the 450 creation of a subscription. 452 The input parameters of the operation are: 454 o A "stream" name which identifies the targeted event stream against 455 which the subscription is applied. 457 o An event stream filter which may reduce the set of event records 458 pushed. 460 o Where the transport used by the RPC supports multiple encodings, 461 an optional "encoding" for the event records pushed. If no 462 "encoding" is included, the encoding of the RPC MUST be used. 464 o An optional "stop-time" for the subscription. If no "stop-time" 465 is present, notification messages will continue to be sent until 466 the subscription is terminated. 468 o An optional "replay-start-time" for the subscription. The 469 "replay-start-time" MUST be in the past and indicates that the 470 subscription is requesting a replay of previously generated 471 information from the event stream. For more on replay, see 472 Section 2.4.2.1. Where there is no "replay-start-time", the 473 subscription starts immediately. 475 If the publisher can satisfy the "establish-subscription" request, it 476 replies with an identifier for the subscription, and then immediately 477 starts streaming notification messages. 479 Below is a tree diagram for "establish-subscription". All objects 480 contained in this tree are described within the included YANG model 481 within Section 4. 483 +---x establish-subscription 484 +---w input 485 | +---w (target) 486 | | +--:(stream) 487 | | +---w (stream-filter)? 488 | | | +--:(by-reference) 489 | | | | +---w stream-filter-name 490 | | | | stream-filter-ref 491 | | | +--:(within-subscription) 492 | | | +---w (filter-spec)? 493 | | | +--:(stream-subtree-filter) 494 | | | | +---w stream-subtree-filter? 495 | | | | {subtree}? 496 | | | +--:(stream-xpath-filter) 497 | | | +---w stream-xpath-filter? 498 | | | yang:xpath1.0 {xpath}? 499 | | +---w stream stream-ref 500 | | +---w replay-start-time? 501 | | yang:date-and-time {replay}? 502 | +---w stop-time? 503 | | yang:date-and-time 504 | +---w dscp? inet:dscp 505 | | {dscp}? 506 | +---w weighting? uint8 507 | | {qos}? 508 | +---w dependency? 509 | | subscription-id {qos}? 510 | +---w encoding? encoding 511 +--ro output 512 +--ro id subscription-id 513 +--ro replay-start-time-revision? yang:date-and-time 514 {replay}? 516 Figure 2: establish-subscription RPC tree diagram 518 A publisher MAY reject the "establish-subscription" RPC for many 519 reasons as described in Section 2.4.6. The contents of the resulting 520 RPC error response MAY include details on input parameters which if 521 considered in a subsequent "establish-subscription" RPC, may result 522 in a successful subscription establishment. Any such hints MUST be 523 transported within a yang-data "establish-subscription-stream-error- 524 info" container included within the RPC error response. 526 yang-data establish-subscription-stream-error-info 527 +--ro establish-subscription-stream-error-info 528 +--ro reason? identityref 529 +--ro filter-failure-hint? string 531 Figure 3: establish-subscription RPC yang-data tree diagram 533 2.4.2.1. Requesting a replay of event records 535 Replay provides the ability to establish a subscription which is also 536 capable of passing recently generated event records. In other words, 537 as the subscription initializes itself, it sends any event records 538 within the target event stream which meet the filter criteria, which 539 have an event time which is after the "replay-start-time", and which 540 have an event time before the "stop-time" should this "stop-time" 541 exist. The end of these historical event records is identified via a 542 "replay-completed" subscription state change notification. Any event 543 records generated since the subscription establishment may then 544 follow. For a particular subscription, all event records will be 545 delivered in the order they are placed into the event stream. 547 Replay is an optional feature which is dependent on an event stream 548 supporting some form of logging. This document puts no restrictions 549 on the size or form of the log, where it resides within the 550 publisher, or when event record entries in the log are purged. 552 The inclusion of a "replay-start-time" within an "establish- 553 subscription" RPC indicates a replay request. If the "replay-start- 554 time" contains a value that is earlier than what a publisher's 555 retained history supports, then if the subscription is accepted, the 556 actual publisher's revised start time MUST be set in the returned 557 "replay-start-time-revision" object. 559 A "stop-time" parameter may be included in a replay subscription. 560 For a replay subscription, the "stop-time" MAY be earlier than the 561 current time, but MUST be later than the "replay-start-time". 563 If the given "replay-start-time" is later than the time marked within 564 any event records retained within the replay buffer, then the 565 publisher MUST send a "replay-completed" notification immediately 566 after a successful establish-subscription RPC response. 568 If an event stream supports replay, the "replay-support" leaf is 569 present in the "/streams/stream" list entry for the event stream. An 570 event stream that does support replay is not expected to have an 571 unlimited supply of saved notifications available to accommodate any 572 given replay request. To assess the timeframe available for replay, 573 subscribers can read the leafs "replay-log-creation-time" and 574 "replay-log-aged-time". See Figure 18 for the YANG tree, and 575 Section 4 for the YANG model describing these elements. The actual 576 size of the replay log at any given time is a publisher specific 577 matter. Control parameters for the replay log are outside the scope 578 of this document. 580 2.4.3. Modifying a Dynamic Subscription 582 The "modify-subscription" operation permits changing the terms of an 583 existing dynamic subscription. Dynamic subscriptions can be modified 584 any number of times. Dynamic subscriptions can only be modified via 585 this RPC using a transport session connecting to the subscriber. If 586 the publisher accepts the requested modifications, it acknowledges 587 success to the subscriber, then immediately starts sending event 588 records based on the new terms. 590 Subscriptions created by configuration cannot be modified via this 591 RPC. However configuration may be used to modify objects referenced 592 by the subscription (such as a referenced filter). 594 Below is a tree diagram for "modify-subscription". All objects 595 contained in this tree are described within the included YANG model 596 within Section 4. 598 +---x modify-subscription 599 +---w input 600 +---w id 601 | subscription-id 602 +---w (target) 603 | +--:(stream) 604 | +---w (stream-filter)? 605 | +--:(by-reference) 606 | | +---w stream-filter-name 607 | | stream-filter-ref 608 | +--:(within-subscription) 609 | +---w (filter-spec)? 610 | +--:(stream-subtree-filter) 611 | | +---w stream-subtree-filter? 612 | | {subtree}? 613 | +--:(stream-xpath-filter) 614 | +---w stream-xpath-filter? 615 | yang:xpath1.0 {xpath}? 616 +---w stop-time? 617 yang:date-and-time 619 Figure 4: modify-subscription RPC tree diagram 621 If the publisher accepts the requested modifications on a currently 622 suspended subscription, the subscription will immediately be resumed 623 (i.e., the modified subscription is returned to the active state.) 624 The publisher MAY immediately suspend this newly modified 625 subscription through the "subscription-suspended" notification before 626 any event records are sent. 628 If the publisher rejects the RPC request, the subscription remains as 629 prior to the request. That is, the request has no impact whatsoever. 630 Rejection of the RPC for any reason is indicated by via RPC error as 631 described in Section 2.4.6. The contents of such a rejected RPC MAY 632 include hints on inputs which (if considered) may result in a 633 successfully modified subscription. These hints MUST be transported 634 within a yang-data "modify-subscription-stream-error-info" container 635 inserted into the RPC error response. 637 Below is a tree diagram for "modify-subscription-RPC-yang-data". All 638 objects contained in this tree are described within the included YANG 639 model within Section 4. 641 yang-data modify-subscription-stream-error-info 642 +--ro modify-subscription-stream-error-info 643 +--ro reason? identityref 644 +--ro filter-failure-hint? string 646 Figure 5: modify-subscription RPC yang-data tree diagram 648 2.4.4. Deleting a Dynamic Subscription 650 The "delete-subscription" operation permits canceling an existing 651 subscription. If the publisher accepts the request, and the 652 publisher has indicated success, the publisher MUST NOT send any more 653 notification messages for this subscription. If the delete request 654 matches a known subscription established on the same transport 655 session, then it MUST be deleted; otherwise it MUST be rejected with 656 no changes to the publisher. 658 Below is a tree diagram for "delete-subscription". All objects 659 contained in this tree are described within the included YANG model 660 within Section 4. 662 +---x delete-subscription 663 +---w input 664 +---w id subscription-id 666 Figure 6: delete-subscription RPC tree diagram 668 Dynamic subscriptions can only be deleted via this RPC using a 669 transport session connecting to the subscriber. Configured 670 subscriptions cannot be deleted using RPCs. 672 2.4.5. Killing a Dynamic Subscription 674 The "kill-subscription" operation permits an operator to end a 675 dynamic subscription which is not associated with the transport 676 session used for the RPC. A publisher MUST terminate any dynamic 677 subscription identified by the "id" parameter in the RPC request, if 678 such a subscription exists. 680 Configured subscriptions cannot be killed using this RPC. Instead, 681 configured subscriptions are deleted as part of regular configuration 682 operations. Publishers MUST reject any RPC attempt to kill a 683 configured subscription. 685 Below is a tree diagram for "kill-subscription". All objects 686 contained in this tree are described within the included YANG model 687 within Section 4. 689 +---x kill-subscription 690 +---w input 691 +---w id subscription-id 693 Figure 7: kill-subscription RPC tree diagram 695 2.4.6. RPC Failures 697 Whenever an RPC is unsuccessful, the publisher returns relevant 698 information as part of the RPC error response. Transport level error 699 processing MUST be done before RPC error processing described in this 700 section. In all cases, RPC error information returned will use 701 existing transport layer RPC structures, such as those seen with 702 NETCONF in [RFC6241] Appendix A, or with RESTCONF in [RFC8040] 703 Section 7.1. These structures MUST be able to encode subscription 704 specific errors identified below and defined within this document's 705 YANG model. 707 As a result of this mixture, how subscription errors are encoded 708 within an RPC error response is transport dependent. Following are 709 valid errors which can occur for each RPC: 711 establish-subscription modify-subscription 712 ---------------------- ------------------- 713 dscp-unavailable filter-unsupported 714 encoding-unsupported insufficient-resources 715 filter-unsupported no-such-subscription 716 insufficient-resources 717 replay-unsupported 719 delete-subscription kill-subscription 720 ---------------------- ---------------------- 721 no-such-subscription no-such-subscription 723 To see a NETCONF based example of an error response from above, see 724 [I-D.draft-ietf-netconf-netconf-event-notifications], Figure 10. 726 There is one final set of transport independent RPC error elements 727 included in the YANG model. These are three yang-data structures 728 which enable the publisher to provide to the receiver that error 729 information which does not fit into existing transport layer RPC 730 structures. These three yang-data structures are: 732 1. "establish-subscription-stream-error-info": This MUST be returned 733 with the leaf "reason" populated if an RPC error reason has not 734 been placed elsewhere within the transport portion of a failed 735 "establish-subscription" RPC response. This MUST be sent if 736 hints on how to overcome the RPC error are included. 738 2. "modify-subscription-stream-error-info": This MUST be returned 739 with the leaf "reason" populated if an RPC error reason has not 740 been placed elsewhere within the transport portion of a failed 741 "modify-subscription" RPC response. This MUST be sent if hints 742 on how to overcome the RPC error are included. 744 3. "delete-subscription-error-info": This MUST be returned with the 745 leaf "reason" populated if an RPC error reason has not been 746 placed elsewhere within the transport portion of a failed 747 "delete-subscription" or "kill-subscription" RPC response. 749 2.5. Configured Subscriptions 751 A configured subscription is a subscription installed via 752 configuration. Configured subscriptions may be modified by any 753 configuration client with the proper permissions. Subscriptions can 754 be modified or terminated via configuration at any point of their 755 lifetime. Multiple configured subscriptions MUST be supportable over 756 a single transport session. 758 Configured subscriptions have several characteristics distinguishing 759 them from dynamic subscriptions: 761 o persistence across publisher reboots, 763 o persistence even when transport is unavailable, and 765 o an ability to send notification messages to more than one receiver 766 (note that receivers are unaware of the existence of any other 767 receivers.) 769 On the publisher, supporting configured subscriptions is optional and 770 advertised using the "configured" feature. On a receiver of a 771 configured subscription, support for dynamic subscriptions is 772 optional except where replaying missed event records is required. 774 In addition to the subscription parameters available to dynamic 775 subscriptions described in Section 2.4.2, the following additional 776 parameters are also available to configured subscriptions: 778 o A "transport" which identifies the transport protocol to use to 779 connect with all subscription receivers. 781 o One or more receivers, each intended as the destination for event 782 records. Note that each individual receiver is identifiable by 783 its "name". 785 o Optional parameters to identify where traffic should egress a 786 publisher: 788 * A "source-interface" which identifies the egress interface to 789 use from the publisher. Publisher support for this is optional 790 and advertised using the "interface-designation" feature. 792 * A "source-address" address, which identifies the IP address to 793 stamp on notification messages destined for the receiver. 795 * A "source-vrf" which identifies the VRF on which to reach 796 receivers. This VRF is a network instance as defined within 797 [I-D.draft-ietf-rtgwg-ni-model]. Publisher support for VRFs is 798 optional and advertised using the "supports-vrf" feature. 800 If none of the above parameters are set, notification messages 801 MUST egress the publisher's default interface. 803 A tree diagram describing these parameters is shown in Figure 20 804 within Section 3.3. All parameters are described within the YANG 805 model in Section 4. 807 2.5.1. Configured Subscription State Model 809 Below is the state machine for a configured subscription on the 810 publisher. This state machine describes the three states (valid, 811 invalid, and concluded), as well as the transitions between these 812 states. Start and end states are depicted to reflect configured 813 subscription creation and deletion events. The creation or 814 modification of a configured subscription initiates an evaluation by 815 the publisher to determine if the subscription is in valid or invalid 816 states. The publisher uses its own criteria in making this 817 determination. If in the valid state, the subscription becomes 818 operational. See (1) in the diagram below. 820 ......... 821 : start :-. 822 :.......: | 823 create .---modify-----.----------------------------------. 824 | | | | 825 V V .-------. ....... .---------. 826 .----[evaluate]--no--->|invalid|-delete->: end :<-delete-|concluded| 827 | '-------' :.....: '---------' 828 |-[evaluate]--no-(2). ^ ^ ^ 829 | ^ | | | | 830 yes | '->unsupportable delete stop-time 831 | modify (subscription- (subscription- (subscription- 832 | | terminated*) terminated*) concluded*) 833 | | | | | 834 (1) | (3) (4) (5) 835 | .---------------------------------------------------------------. 836 '-->| valid | 837 '---------------------------------------------------------------' 839 Legend: 840 dotted boxes: subscription added or removed via configuration 841 dashed boxes: states for a subscription 842 [evaluate]: decision point on whether the subscription is supportable 843 (*): resulting subscription state change notification 845 Figure 8: Publisher state model for a configured subscription 847 A subscription in the valid state may move to the invalid state in 848 one of two ways. First, it may be modified in a way which fails a 849 re-evaluation. See (2) in the diagram. Second, the publisher might 850 determine that the subscription is no longer supportable. This could 851 be for reasons of an unexpected but sustained increase in an event 852 stream's event records, degraded CPU capacity, a more complex 853 referenced filter, or other higher priority subscriptions which have 854 usurped resources. See (3) in the diagram. No matter the case, a 855 "subscription-terminated" notification is sent to any receivers in an 856 active or suspended state. A subscription in the valid state may 857 also transition to the concluded state via (5) if a configured stop 858 time has been reached. In this case, a "subscription-concluded" 859 notification is sent to any receivers in active or suspended states. 860 Finally, a subscription may be deleted by configuration (4). 862 When a subscription is in the valid state, a publisher will attempt 863 to connect with all receivers of a configured subscription and 864 deliver notification messages. Below is the state machine for each 865 receiver of a configured subscription. This receiver state machine 866 is fully contained within the state machine of the configured 867 subscription, and is only relevant when the configured subscription 868 is in the valid state. 870 .-----------------------------------------------------------------. 871 | valid | 872 | .----------. .------------. | 873 | | receiver |---timeout---------------->| receiver | | 874 | |connecting|<----------------reset--(c)|disconnected| | 875 | | |<-transport '------------' | 876 | '----------' loss,reset------------------------------. | 877 | (a) | | | 878 | subscription- (b) (b) | 879 | started* .--------. .---------. | 880 | '----->| |(d)-insufficient CPU,------->| | | 881 | |receiver| buffer overflow |receiver | | 882 | subscription-| active | |suspended| | 883 | modified* | |<----CPU, b/w sufficient,-(e)| | | 884 | '---->'--------' subscription-modified* '---------' | 885 '-----------------------------------------------------------------' 887 Legend: 888 dashed boxes which include the word 'receiver' show the possible 889 states for an individual receiver of a valid configured subscription. 890 * indicates a subscription state change notification 892 Figure 9: Receiver state for a configured subscription on a Publisher 894 When a configured subscription first moves to the valid state, the 895 "state" leaf of each receiver is initialized to the connecting state. 896 If transport connectivity is not available to any receiver and there 897 are any notification messages to deliver, a transport session is 898 established (e.g., through [RFC8071]). Individual receivers are 899 moved to the active state when a "subscription-started" subscription 900 state change notification is successfully passed to that receiver 901 (a). Event records are only sent to active receivers. Receivers of 902 a configured subscription remain active if both transport 903 connectivity can be verified to the receiver, and event records are 904 not being dropped due to a publisher buffer overflow. The result is 905 that a receiver will remain active on the publisher as long as events 906 aren't being lost, or the receiver cannot be reached. In addition, a 907 configured subscription's receiver MUST be moved to the connecting 908 state if the receiver is reset via the "reset" action (b), (c). For 909 more on reset, see Section 2.5.5. If transport connectivity cannot 910 be achieved while in the connecting state, the receiver MAY be moved 911 to the disconnected state. 913 A configured subscription's receiver MUST be moved to the suspended 914 state if there is transport connectivity between the publisher and 915 receiver, but notification messages are failing to be delivered due 916 to publisher buffer overflow, or notification messages are not able 917 to be generated for that receiver due to insufficient CPU (d). This 918 is indicated to the receiver by the "subscription-suspended" 919 subscription state change notification. 921 A configured subscription receiver MUST be returned to the active 922 state from the suspended state when notification messages are able to 923 be generated, bandwidth is sufficient to handle the notification 924 messages, and a receiver has successfully been sent a "subscription- 925 resumed" or "subscription-modified" subscription state change 926 notification (e). The choice as to which of these two subscription 927 state change notifications is sent is determined by whether the 928 subscription was modified during the period of suspension. 930 Modification of a configured subscription is possible at any time. A 931 "subscription-modified" subscription state change notification will 932 be sent to all active receivers, immediately followed by notification 933 messages conforming to the new parameters. Suspended receivers will 934 also be informed of the modification. However this notification will 935 await the end of the suspension for that receiver (e). 937 The mechanisms described above are mirrored in the RPCs and 938 notifications within the document. It should be noted that these 939 RPCs and notifications have been designed to be extensible and allow 940 subscriptions into targets other than event streams. For instance, 941 the YANG module defined in Section 5 of [I-D.ietf-netconf-yang-push] 942 augments "/sn:modify-subscription/sn:input/sn:target". 944 2.5.2. Creating a Configured Subscription 946 Configured subscriptions are established using configuration 947 operations against the top-level "subscriptions" subtree. 949 Because there is no explicit association with an existing transport 950 session, configuration operations MUST include additional parameters 951 beyond those of dynamic subscriptions. These parameters identify 952 each receiver, how to connect with that receiver, and possibly 953 whether the notification messages need to come from a specific egress 954 interface on the publisher. Receiver specific transport connectivity 955 parameters MUST be configured via transport specific augmentations to 956 this specification. See Section 2.5.7 for details. 958 After a subscription is successfully established, the publisher 959 immediately sends a "subscription-started" subscription state change 960 notification to each receiver. It is quite possible that upon 961 configuration, reboot, or even steady-state operations, a transport 962 session may not be currently available to the receiver. In this 963 case, when there is something to transport for an active 964 subscription, transport specific call-home operations will be used to 965 establish the connection. When transport connectivity is available, 966 notification messages may then be pushed. 968 With active configured subscriptions, it is allowable to buffer event 969 records even after a "subscription-started" has been sent. However 970 if events are lost (rather than just delayed) due to replay buffer 971 overflow, a new "subscription-started" must be sent. This new 972 "subscription-started" indicates an event record discontinuity. 974 To see an example of subscription creation using configuration 975 operations over NETCONF, see Appendix A of 976 [I-D.draft-ietf-netconf-netconf-event-notifications]. 978 2.5.3. Modifying a Configured Subscription 980 Configured subscriptions can be modified using configuration 981 operations against the top-level "subscriptions" subtree. 983 If the modification involves adding receivers, added receivers are 984 placed in the connecting state. If a receiver is removed, the 985 subscription state change notification "subscription-terminated" is 986 sent to that receiver if that receiver is active or suspended. 988 If the modification involves changing the policies for the 989 subscription, the publisher sends to currently active receivers a 990 "subscription-modified" notification. For any suspended receivers, a 991 "subscription-modified" notification will be delayed until the 992 receiver is resumed. (Note: in this case, the "subscription- 993 modified" notification informs the receiver that the subscription has 994 been resumed, so no additional "subscription-resumed" need be sent. 995 Also note that if multiple modifications have occurred during the 996 suspension, only the "subscription-modified" notification describing 997 the latest one need be sent to the receiver.) 999 2.5.4. Deleting a Configured Subscription 1001 Subscriptions can be deleted through configuration against the top- 1002 level "subscriptions" subtree. 1004 Immediately after a subscription is successfully deleted, the 1005 publisher sends to all receivers of that subscription a subscription 1006 state change notification stating the subscription has ended (i.e., 1007 "subscription-terminated"). 1009 2.5.5. Resetting a Configured Subscription Receiver 1011 It is possible that a configured subscription to a receiver needs to 1012 be reset. This is accomplished via the "reset" action within the 1013 YANG model at "/subscriptions/subscription/receivers/receiver/reset". 1014 This action may be useful in cases where a publisher has timed out 1015 trying to reach a receiver. When such a reset occurs, a transport 1016 session will be initiated if necessary, and a new "subscription- 1017 started" notification will be sent. This action does not have any 1018 effect on transport connectivity if the needed connectivity already 1019 exists. 1021 2.5.6. Replay for a Configured Subscription 1023 It is possible to do replay on a configured subscription. This is 1024 supported via the configuration of the "configured-replay" object on 1025 the subscription. The setting of this object enables the streaming 1026 of the buffered event records for the subscribed event stream. All 1027 buffered event records which have been retained since the last 1028 publisher restart will be sent to each configured receiver. 1030 Replay of events records created since restart is useful. It allows 1031 event records generated before transport connectivity establishment 1032 to be passed to a receiver. Setting the restart time as the earliest 1033 configured replay time precludes possibility of resending of event 1034 records logged prior to publisher restart. It also ensures the same 1035 records will be sent to each configured receiver, regardless of the 1036 speed of transport connectivity establishment to each receiver. 1037 Finally, establishing restart as the earliest potential time for 1038 event records to be included within notification messages, a well- 1039 understood timeframe for replay is defined. 1041 As a result, when any configured subscription receivers become 1042 active, buffered event records will be sent immediately after the 1043 "subscription-started" notification. If the publisher knows the last 1044 event record sent to a receiver, and the publisher has not rebooted, 1045 the next event record on the event stream which meets filtering 1046 criteria will be the leading event record sent. Otherwise, the 1047 leading event record will be the first event record meeting filtering 1048 criteria subsequent to the latest of three different times: the 1049 "replay-log-creation-time", "replay-log-aged-time", or the most 1050 recent publisher boot time. The "replay-log-creation-time" and 1051 "replay-log-aged-time" are discussed in Section 2.4.2.1. The most 1052 recent publisher boot time ensures that duplicate event records are 1053 not replayed from a previous time the publisher was booted. 1055 It is quite possible that a receiver might want to retrieve event 1056 records from an event stream prior to the latest boot. If such 1057 records exist where there is a configured replay, the publisher MUST 1058 send the time of the event record immediately preceding the "replay- 1059 start-time" within the "replay-previous-event-time" leaf. Through 1060 the existence of the "replay-previous-event-time", the receiver will 1061 know that earlier events prior to reboot exist. In addition, if the 1062 subscriber was previously receiving event records with the same 1063 subscription "id", the receiver can determine if there was a timegap 1064 where records generated on the publisher were not successully 1065 received. And with this information, the receiver may choose to 1066 dynamically subscribe to retrieve any event records placed into the 1067 event stream before the most recent boot time. 1069 All other replay functionality remains the same as with dynamic 1070 subscriptions as described in Section 2.4.2.1. 1072 2.5.7. Transport Connectivity for a Configured Subscription 1074 This specification is transport independent. However supporting a 1075 configured subscription will often require the establishment of 1076 transport connectivity. And the parameters used for this transport 1077 connectivity establishment are transport specific. As a result, the 1078 YANG model defined within Section 4 is not able to directly define 1079 and expose these transport parameters. 1081 It is necessary for an implementation to support the connection 1082 establishment process. To support this function, the YANG model does 1083 include a node where transport specific parameters for a particular 1084 receiver may be augmented. This node is 1085 "/subscriptions/subscription/receivers/receiver". By augmenting 1086 transport parameters from this node, system developers are able to 1087 incorporate the YANG objects necessary to support the transport 1088 connectivity establishment process. 1090 The result of this is the following requirement. A publisher 1091 supporting the feature "configured" MUST also support least one YANG 1092 model which augments transport connectivity parameters on 1093 "/subscriptions/subscription/receivers/receiver". For an example of 1094 such an augmentation, see Appendix A. 1096 2.6. Event Record Delivery 1098 Whether dynamic or configured, once a subscription has been set up, 1099 the publisher streams event records via notification messages per the 1100 terms of the subscription. For dynamic subscriptions, notification 1101 messages are sent over the session used to establish the 1102 subscription. For configured subscriptions, notification messages 1103 are sent over the connections specified by the transport and each 1104 receiver of a configured subscription. 1106 A notification message is sent to a receiver when an event record is 1107 not blocked by either the specified filter criteria or receiver 1108 permissions. This notification message MUST include an "eventTime" 1109 object as defined per [RFC5277] Section 4. This "eventTime" MUST be 1110 at the top level of YANG structured event record. 1112 The following example within [RFC7950] section 7.16.3 is an example 1113 of a compliant message: 1115 1117 2007-09-01T10:00:00Z 1118 1119 so-1/2/3.0 1120 up 1121 down 1122 1123 1125 Figure 10: subscribed notification message 1127 When a dynamic subscription has been started or modified, with 1128 "establish-subscription" or "modify-subscription" respectively, event 1129 records matching the newly applied filter criteria MUST NOT be sent 1130 until after the RPC reply has been sent. 1132 When a configured subscription has been started or modified, event 1133 records matching the newly applied filter criteria MUST NOT be sent 1134 until after the "subscription-started" or "subscription-modified" 1135 notifications has been sent, respectively. 1137 2.7. subscription state change notifications 1139 In addition to sending event records to receivers, a publisher MUST 1140 also send subscription state change notifications when events related 1141 to subscription management have occurred. 1143 subscription state change notifications are unlike other 1144 notifications in that they are never included in any event stream. 1145 Instead, they are inserted (as defined in this section) within the 1146 sequence of notification messages sent to a particular receiver. 1147 subscription state change notifications cannot be filtered out, they 1148 cannot be stored in replay buffers, and they are delivered only to 1149 impacted receivers of a subscription. The identification of 1150 subscription state change notifications is easy to separate from 1151 other notification messages through the use of the YANG extension 1152 "subscription-state-notif". This extension tags a notification as a 1153 subscription state change notification. 1155 The complete set of subscription state change notifications is 1156 described in the following subsections. 1158 2.7.1. subscription-started 1160 This notification indicates that a configured subscription has 1161 started, and event records may be sent. Included in this 1162 subscription state change notification are all the parameters of the 1163 subscription, except for the receiver(s) transport connection 1164 information and origin information indicating where notification 1165 messages will egress the publisher. Note that if a referenced filter 1166 from the "filters" container has been used within the subscription, 1167 the notification still provides the contents of that referenced 1168 filter under the "within-subscription" subtree. 1170 Note that for dynamic subscriptions, no "subscription-started" 1171 notifications are ever sent. 1173 Below is a tree diagram for "subscription-started". All objects 1174 contained in this tree are described within the included YANG model 1175 within Section 4. 1177 +---n subscription-started {configured}? 1178 +--ro id 1179 | subscription-id 1180 +--ro (target) 1181 | +--:(stream) 1182 | +--ro (stream-filter)? 1183 | | +--:(by-reference) 1184 | | | +--ro stream-filter-name 1185 | | | stream-filter-ref 1186 | | +--:(within-subscription) 1187 | | +--ro (filter-spec)? 1188 | | +--:(stream-subtree-filter) 1189 | | | +--ro stream-subtree-filter? 1190 | | | {subtree}? 1191 | | +--:(stream-xpath-filter) 1192 | | +--ro stream-xpath-filter? yang:xpath1.0 1193 | | {xpath}? 1194 | +--ro stream stream-ref 1195 | +--ro replay-start-time? 1196 | | yang:date-and-time {replay}? 1197 | +--ro replay-previous-event-time? 1198 | yang:date-and-time {replay}? 1199 +--ro stop-time? 1200 | yang:date-and-time 1201 +--ro dscp? inet:dscp 1202 | {dscp}? 1203 +--ro weighting? uint8 {qos}? 1204 +--ro dependency? 1205 | subscription-id {qos}? 1206 +--ro transport? transport 1207 | {configured}? 1208 +--ro encoding? encoding 1209 +--ro purpose? string 1210 {configured}? 1212 Figure 11: subscription-started notification tree diagram 1214 2.7.2. subscription-modified 1216 This notification indicates that a subscription has been modified by 1217 configuration operations. It is delivered directly after the last 1218 event records processed using the previous subscription parameters, 1219 and before any event records processed after the modification. 1221 Below is a tree diagram for "subscription-modified". All objects 1222 contained in this tree are described within the included YANG model 1223 within Section 4. 1225 +---n subscription-modified 1226 +--ro id 1227 | subscription-id 1228 +--ro (target) 1229 | +--:(stream) 1230 | +--ro (stream-filter)? 1231 | | +--:(by-reference) 1232 | | | +--ro stream-filter-name 1233 | | | stream-filter-ref 1234 | | +--:(within-subscription) 1235 | | +--ro (filter-spec)? 1236 | | +--:(stream-subtree-filter) 1237 | | | +--ro stream-subtree-filter? 1238 | | | {subtree}? 1239 | | +--:(stream-xpath-filter) 1240 | | +--ro stream-xpath-filter? yang:xpath1.0 1241 | | {xpath}? 1242 | +--ro stream stream-ref 1243 | +--ro replay-start-time? 1244 | yang:date-and-time {replay}? 1245 +--ro stop-time? 1246 | yang:date-and-time 1247 +--ro dscp? inet:dscp 1248 | {dscp}? 1249 +--ro weighting? uint8 {qos}? 1250 +--ro dependency? 1251 | subscription-id {qos}? 1252 +--ro transport? transport 1253 | {configured}? 1254 +--ro encoding? encoding 1255 +--ro purpose? string 1256 {configured}? 1258 Figure 12: subscription-modified notification tree diagram 1260 A publisher most often sends this notification directly after the 1261 modification of any configuration parameters impacting a configured 1262 subscription. But it may also be sent at two other times: 1264 1. Where a configured subscription has been modified during the 1265 suspension of a receiver, the notification will be delayed until 1266 the receiver's suspension is lifted. In this situation, the 1267 notification indicates that the subscription has been both 1268 modified and resumed. 1270 2. A "subscription-modified" subscription state change notification 1271 MUST be sent if the contents of the filter identified by the 1272 subscription's "stream-filter-ref" leaf has changed. This state 1273 change notification is to be sent for a filter change impacting 1274 any active receiver of a configured or dynamic subscription. 1276 2.7.3. subscription-terminated 1278 This notification indicates that no further event records for this 1279 subscription should be expected from the publisher. A publisher may 1280 terminate the sending event records to a receiver for the following 1281 reasons: 1283 1. Configuration which removes a configured subscription, or a 1284 "kill-subscription" RPC which ends a dynamic subscription. These 1285 are identified via the reason "no-such-subscription". 1287 2. A referenced filter is no longer accessible. This is identified 1288 by "filter-unavailable". 1290 3. The event stream referenced by a subscription is no longer 1291 accessible by the receiver. This is identified by "stream- 1292 unavailable". 1294 4. A suspended subscription has exceeded some timeout. This is 1295 identified by "suspension-timeout". 1297 Each of the reasons above correspond one-to-one with a "reason" 1298 identityref specified within the YANG model. 1300 Below is a tree diagram for "subscription-terminated". All objects 1301 contained in this tree are described within the included YANG model 1302 within Section 4. 1304 +---n subscription-terminated 1305 +--ro id subscription-id 1306 +--ro reason identityref 1308 Figure 13: subscription-terminated notification tree diagram 1310 Note: this subscription state change notification MUST be sent to a 1311 dynamic subscription's receiver when the subscription ends 1312 unexpectedly. The cases when this might happen are when a "kill- 1313 subscription" RPC is successful, or when some other event not 1314 including the reaching the subscription's "stop-time" results in a 1315 publisher choosing to end the subscription. 1317 2.7.4. subscription-suspended 1319 This notification indicates that a publisher has suspended the 1320 sending of event records to a receiver, and also indicates the 1321 possible loss of events. Suspension happens when capacity 1322 constraints stop a publisher from serving a valid subscription. The 1323 two conditions where is this possible are: 1325 1. "insufficient-resources" when a publisher is unable to produce 1326 the requested event stream of notification messages, and 1328 2. "unsupportable-volume" when the bandwidth needed to get generated 1329 notification messages to a receiver exceeds a threshold. 1331 These conditions are encoded within the "reason" object. No further 1332 notification will be sent until the subscription resumes or is 1333 terminated. 1335 Below is a tree diagram for "subscription-suspended". All objects 1336 contained in this tree are described within the included YANG model 1337 within Section 4. 1339 +---n subscription-suspended 1340 +--ro id subscription-id 1341 +--ro reason identityref 1343 Figure 14: subscription-suspended notification tree diagram 1345 2.7.5. subscription-resumed 1347 This notification indicates that a previously suspended subscription 1348 has been resumed under the unmodified terms previously in place. 1349 Subscribed event records generated after the issuance of this 1350 subscription state change notification may now be sent. 1352 Below is the tree diagram for "subscription-resumed". All objects 1353 contained in this tree are described within the included YANG model 1354 within Section 4. 1356 +---n subscription-resumed 1357 +--ro id subscription-id 1359 Figure 15: subscription-resumed notification tree diagram 1361 2.7.6. subscription-completed 1363 This notification indicates that a subscription that includes a 1364 "stop-time" has successfully finished passing event records upon the 1365 reaching of that time. 1367 Below is a tree diagram for "subscription-completed". All objects 1368 contained in this tree are described within the included YANG model 1369 within Section 4. 1371 +---n subscription-completed {configured}? 1372 +--ro id subscription-id 1374 Figure 16: subscription-completed notification tree diagram 1376 2.7.7. replay-completed 1378 This notification indicates that all of the event records prior to 1379 the current time have been passed to a receiver. It is sent before 1380 any notification message containing an event record with a timestamp 1381 later than (1) the "stop-time" or (2) the subscription's start time. 1383 If a subscription contains no "stop-time", or has a "stop-time" that 1384 has not been reached, then after the "replay-completed" notification 1385 has been sent, additional event records will be sent in sequence as 1386 they arise naturally on the publisher. 1388 Below is a tree diagram for "replay-completed". All objects 1389 contained in this tree are described within the included YANG model 1390 within Section 4. 1392 +---n replay-completed {replay}? 1393 +--ro id subscription-id 1395 Figure 17: replay-completed notification tree diagram 1397 2.8. Subscription Monitoring 1399 In the operational state datastore, the container "subscriptions" 1400 maintains the state of all dynamic subscriptions, as well as all 1401 configured subscriptions. Using datastore retrieval operations, or 1402 subscribing to the "subscriptions" container 1403 [I-D.ietf-netconf-yang-push] allows the state of subscriptions and 1404 their connectivity to receivers to be monitored. 1406 Each subscription in the operational state datastore is represented 1407 as a list element. Included in this list are event counters for each 1408 receiver, the state of each receiver, as well as the subscription 1409 parameters currently in effect. The appearance of the leaf 1410 "configured-subscription-state" indicates that a particular 1411 subscription came into being via configuration. This leaf also 1412 indicates if the current state of that subscription is valid, 1413 invalid, and concluded. 1415 To understand the flow of event records within a subscription, there 1416 are two counters available for each receiver. The first counter is 1417 "sent-event-records" which shows the quantity of events actually 1418 identified for sending to a receiver. The second counter is 1419 "excluded-event-records" which shows event records not sent to 1420 receiver. "excluded-event-records" shows the combined results of 1421 both access control and per-subscription filtering. For configured 1422 subscriptions, counters are reset whenever the subscription is 1423 evaluated to valid (see (1) in Figure 8). 1425 Dynamic subscriptions are removed from the operational state 1426 datastore once they expire (reaching stop-time) or when they are 1427 terminated. While many subscription objects are shown as 1428 configurable, dynamic subscriptions are only included within the 1429 operational state datastore and as a result are not configurable. 1431 2.9. Advertisement 1433 Publishers supporting this document MUST indicate support of the YANG 1434 model "ietf-subscribed-notifications" within the YANG library of the 1435 publisher. In addition if supported, the optional features "encode- 1436 xml", "encode-json", "configured" "supports-vrf", "qos", "xpath", 1437 "subtree", "interface-designation", "dscp", and "replay" MUST be 1438 indicated. 1440 3. YANG Data Model Trees 1442 This section contains tree diagrams for nodes defined in Section 4. 1443 For tree diagrams of subscription state change notifications, see 1444 Section 2.7. For the tree diagrams for the RPCs, see Section 2.4. 1446 3.1. Event Streams Container 1448 A publisher maintains a list of available event streams as 1449 operational data. This list contains both standardized and vendor- 1450 specific event streams. This enables subscribers to discover what 1451 streams a publisher supports. 1453 +--ro streams 1454 +--ro stream* [name] 1455 +--ro name string 1456 +--ro description string 1457 +--ro replay-support? empty {replay}? 1458 +--ro replay-log-creation-time yang:date-and-time 1459 | {replay}? 1460 +--ro replay-log-aged-time? yang:date-and-time 1461 {replay}? 1463 Figure 18: Stream Container tree diagram 1465 Above is a tree diagram for the "streams" container. All objects 1466 contained in this tree are described within the included YANG model 1467 within Section 4. 1469 3.2. Filters Container 1471 The "filters" container maintains a list of all subscription filters 1472 that persist outside the life-cycle of a single subscription. This 1473 enables pre-defined filters which may be referenced by more than one 1474 subscription. 1476 +--rw filters 1477 +--rw stream-filter* [name] 1478 +--rw name string 1479 +--rw (filter-spec)? 1480 +--:(stream-subtree-filter) 1481 | +--rw stream-subtree-filter? {subtree}? 1482 +--:(stream-xpath-filter) 1483 +--rw stream-xpath-filter? yang:xpath1.0 {xpath}? 1485 Figure 19: Filter Container tree diagram 1487 Above is a tree diagram for the filters container. All objects 1488 contained in this tree are described within the included YANG model 1489 within Section 4. 1491 3.3. Subscriptions Container 1493 The "subscriptions" container maintains a list of all subscriptions 1494 on a publisher, both configured and dynamic. It can be used to 1495 retrieve information about the subscriptions which a publisher is 1496 serving. 1498 +--rw subscriptions 1499 +--rw subscription* [id] 1500 +--rw id 1501 | subscription-id 1502 +--rw (target) 1503 | +--:(stream) 1504 | +--rw (stream-filter)? 1505 | | +--:(by-reference) 1506 | | | +--rw stream-filter-name 1507 | | | stream-filter-ref 1508 | | +--:(within-subscription) 1509 | | +--rw (filter-spec)? 1510 | | +--:(stream-subtree-filter) 1511 | | | +--rw stream-subtree-filter? 1512 | | | {subtree}? 1513 | | +--:(stream-xpath-filter) 1514 | | +--rw stream-xpath-filter? 1515 | | yang:xpath1.0 {xpath}? 1516 | +--rw stream stream-ref 1517 | +--ro replay-start-time? 1518 | | yang:date-and-time {replay}? 1519 | +--rw configured-replay? empty 1520 | {configured,replay}? 1521 +--rw stop-time? 1522 | yang:date-and-time 1523 +--rw dscp? inet:dscp 1524 | {dscp}? 1525 +--rw weighting? uint8 {qos}? 1526 +--rw dependency? 1527 | subscription-id {qos}? 1528 +--rw transport? transport 1529 | {configured}? 1530 +--rw encoding? encoding 1531 +--rw purpose? string 1532 | {configured}? 1533 +--rw (notification-message-origin)? {configured}? 1534 | +--:(interface-originated) 1535 | | +--rw source-interface? 1536 | | if:interface-ref {interface-designation}? 1537 | +--:(address-originated) 1538 | +--rw source-vrf? 1539 | | -> /ni:network-instances/network-instance/name 1540 | | {supports-vrf}? 1541 | +--rw source-address? 1542 | inet:ip-address-no-zone 1543 +--ro configured-subscription-state? enumeration 1544 | {configured}? 1545 +--rw receivers 1546 +--rw receiver* [name] 1547 +--rw name string 1548 +--ro sent-event-records? 1549 | yang:zero-based-counter64 1550 +--ro excluded-event-records? 1551 | yang:zero-based-counter64 1552 +--ro state enumeration 1553 +---x reset {configured}? 1554 +--ro output 1555 +--ro time yang:date-and-time 1557 Figure 20: Subscriptions tree diagram 1559 Above is a tree diagram for the subscriptions container. All objects 1560 contained in this tree are described within the included YANG model 1561 within Section 4. 1563 4. Data Model 1565 This module imports typedefs from [RFC6991], [RFC8343], and 1566 [RFC8040], and it references [I-D.draft-ietf-rtgwg-ni-model], 1567 [XPATH], [RFC6241], [RFC7540], [RFC7951] and [RFC7950]. 1569 [ note to the RFC Editor - please replace XXXX within this YANG model 1570 with the number of this document, and XXXY with the number of 1571 [I-D.draft-ietf-rtgwg-ni-model] ] 1573 [ note to the RFC Editor - please replace the two dates within the 1574 YANG module with the date of publication ] 1576 file "ietf-subscribed-notifications@2018-10-11.yang" 1577 module ietf-subscribed-notifications { 1578 yang-version 1.1; 1579 namespace 1580 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"; 1582 prefix sn; 1584 import ietf-inet-types { 1585 prefix inet; 1586 reference 1587 "RFC 6991: Common YANG Data Types"; 1588 } 1589 import ietf-interfaces { 1590 prefix if; 1591 reference 1592 "RFC 8343: A YANG Data Model for Interface Management"; 1593 } 1594 import ietf-netconf-acm { 1595 prefix nacm; 1596 reference 1597 "RFC 8341: Network Configuration Access Control Model"; 1598 } 1599 import ietf-network-instance { 1600 prefix ni; 1601 reference 1602 "draft-ietf-rtgwg-ni-model-12: YANG Model for Network Instances"; 1603 } 1604 import ietf-restconf { 1605 prefix rc; 1606 reference 1607 "RFC 8040: RESTCONF Protocol"; 1608 } 1609 import ietf-yang-types { 1610 prefix yang; 1611 reference 1612 "RFC 6991: Common YANG Data Types"; 1613 } 1615 organization "IETF NETCONF (Network Configuration) Working Group"; 1616 contact 1617 "WG Web: 1618 WG List: 1620 Author: Alexander Clemm 1621 1623 Author: Eric Voit 1624 1626 Author: Alberto Gonzalez Prieto 1627 1629 Author: Einar Nilsen-Nygaard 1630 1632 Author: Ambika Prasad Tripathy 1633 "; 1635 description 1636 "Contains a YANG specification for subscribing to event records 1637 and receiving matching content within notification messages. 1639 Copyright (c) 2018 IETF Trust and the persons identified as authors 1640 of the code. All rights reserved. 1642 Redistribution and use in source and binary forms, with or without 1643 modification, is permitted pursuant to, and subject to the license 1644 terms contained in, the Simplified BSD License set forth in Section 1645 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 1646 (https://trustee.ietf.org/license-info). 1648 This version of this YANG module is part of RFC XXXX; see the RFC 1649 itself for full legal notices."; 1651 revision 2018-10-11 { 1652 description 1653 "Initial version"; 1654 reference 1655 "RFC XXXX:Customized Subscriptions to a Publisher's Event Streams"; 1656 } 1658 /* 1659 * FEATURES 1660 */ 1662 feature configured { 1663 description 1664 "This feature indicates that configuration of subscription is 1665 supported."; 1666 } 1668 feature dscp { 1669 description 1670 "This feature indicates a publisher supports the placement of 1671 suggested prioritization levels for network transport within 1672 notification messages."; 1673 } 1675 feature encode-json { 1676 description 1677 "This feature indicates that JSON encoding of notification 1678 messages is supported."; 1679 } 1681 feature encode-xml { 1682 description 1683 "This feature indicates that XML encoding of notification 1684 messages is supported."; 1685 } 1687 feature interface-designation { 1688 description 1689 "This feature indicates a publisher supports sourcing all 1690 receiver interactions for a configured subscription from a single 1691 designated egress interface."; 1692 } 1694 feature qos { 1695 description 1696 "This feature indicates a publisher supports absolute 1697 dependencies of one subscription's traffic over another, as well 1698 as weighted bandwidth sharing between subscriptions. Both of 1699 these are Quality of Service (QoS) features which allow 1700 differentiated treatment of notification messages between a 1701 publisher and a specific receiver."; 1702 } 1704 feature replay { 1705 description 1706 "This feature indicates that historical event record replay is 1707 supported. With replay, it is possible for past event records to 1708 be streamed in chronological order."; 1709 } 1711 feature subtree { 1712 description 1713 "This feature indicates support for YANG subtree filtering."; 1714 reference "RFC 6241, Section 6."; 1715 } 1717 feature supports-vrf { 1718 description 1719 "This feature indicates a publisher supports VRF configuration 1720 for configured subscriptions. VRF support for dynamic 1721 subscriptions does not require this feature."; 1722 reference "RFC XXXY, Section 6."; 1723 } 1725 feature xpath { 1726 description 1727 "This feature indicates support for XPath filtering."; 1728 reference "http://www.w3.org/TR/1999/REC-xpath-19991116"; 1729 } 1731 /* 1732 * EXTENSIONS 1733 */ 1735 extension subscription-state-notification { 1736 description 1737 "This statement applies only to notifications. It indicates that 1738 the notification is a subscription state change notification. 1739 Therefore it does not participate in a regular event stream and 1740 does not need to be specifically subscribed to in order to be 1741 received. This statement can only occur as a substatement to the 1742 YANG 'notification' statement. This statement is not for use 1743 outside of this YANG module."; 1744 } 1746 /* 1747 * IDENTITIES 1748 */ 1750 /* Identities for RPC and Notification errors */ 1752 identity delete-subscription-error { 1753 description 1754 "Problem found while attempting to fulfill either a 1755 'delete-subscription' RPC request or a 'kill-subscription' 1756 RPC request."; 1757 } 1759 identity establish-subscription-error { 1760 description 1761 "Problem found while attempting to fulfill an 1762 'establish-subscription' RPC request."; 1763 } 1765 identity modify-subscription-error { 1766 description 1767 "Problem found while attempting to fulfill a 1768 'modify-subscription' RPC request."; 1769 } 1771 identity subscription-suspended-reason { 1772 description 1773 "Problem condition communicated to a receiver as part of a 1774 'subscription-terminated' notification."; 1775 } 1777 identity subscription-terminated-reason { 1778 description 1779 "Problem condition communicated to a receiver as part of a 1780 'subscription-terminated' notification."; 1781 } 1783 identity dscp-unavailable { 1784 base establish-subscription-error; 1785 if-feature "dscp"; 1786 description 1787 "The publisher is unable mark notification messages with a 1788 prioritization information in a way which will be respected 1789 during network transit."; 1790 } 1792 identity encoding-unsupported { 1793 base establish-subscription-error; 1794 description 1795 "Unable to encode notification messages in the desired format."; 1796 } 1798 identity filter-unavailable { 1799 base subscription-terminated-reason; 1800 description 1801 "Referenced filter does not exist. This means a receiver is 1802 referencing a filter which doesn't exist, or to which they do not 1803 have access permissions."; 1804 } 1806 identity filter-unsupported { 1807 base establish-subscription-error; 1808 base modify-subscription-error; 1809 description 1810 "Cannot parse syntax within the filter. This failure can be from 1811 a syntax error, or a syntax too complex to be processed by the 1812 publisher."; 1813 } 1815 identity insufficient-resources { 1816 base establish-subscription-error; 1817 base modify-subscription-error; 1818 base subscription-suspended-reason; 1819 description 1820 "The publisher has insufficient resources to support the 1821 requested subscription. An example might be that allocated CPU 1822 is too limited to generate the desired set of notification 1823 messages."; 1824 } 1826 identity no-such-subscription { 1827 base modify-subscription-error; 1828 base delete-subscription-error; 1829 base subscription-terminated-reason; 1830 description 1831 "Referenced subscription doesn't exist. This may be as a result of 1832 a non-existent subscription id, an id which belongs to another 1833 subscriber, or an id for configured subscription."; 1835 } 1837 identity replay-unsupported { 1838 base establish-subscription-error; 1839 if-feature "replay"; 1840 description 1841 "Replay cannot be performed for this subscription. This means the 1842 publisher will not provide the requested historic information 1843 from the event stream via replay to this receiver."; 1844 } 1846 identity stream-unavailable { 1847 base subscription-terminated-reason; 1848 description 1849 "Not a subscribable event stream. This means the referenced event 1850 stream is not available for subscription by the receiver."; 1851 } 1853 identity suspension-timeout { 1854 base subscription-terminated-reason; 1855 description 1856 "Termination of previously suspended subscription. The publisher 1857 has eliminated the subscription as it exceeded a time limit for 1858 suspension."; 1859 } 1861 identity unsupportable-volume { 1862 base subscription-suspended-reason; 1863 description 1864 "The publisher does not have the network bandwidth needed to get 1865 the volume of generated information intended for a receiver."; 1866 } 1868 /* Identities for encodings */ 1870 identity configurable-encoding { 1871 description 1872 "If a transport identity derives from this identity, it means 1873 that it supports configurable encodings."; 1874 } 1876 identity encoding { 1877 description 1878 "Base identity to represent data encodings"; 1879 } 1881 identity encode-xml { 1882 base encoding; 1883 if-feature "encode-xml"; 1884 description 1885 "Encode data using XML as described in RFC 7950"; 1886 reference 1887 "RFC 7950 - The YANG 1.1 Data Modeling Language"; 1888 } 1890 identity encode-json { 1891 base encoding; 1892 if-feature "encode-json"; 1893 description 1894 "Encode data using JSON as described in RFC 7951"; 1895 reference 1896 "RFC 7951 - JSON Encoding of Data Modeled with YANG"; 1897 } 1899 /* Identities for transports */ 1900 identity transport { 1901 description 1902 "An identity that represents the underlying mechanism for 1903 passing notification messages."; 1904 } 1906 /* 1907 * TYPEDEFs 1908 */ 1910 typedef encoding { 1911 type identityref { 1912 base encoding; 1913 } 1914 description 1915 "Specifies a data encoding, e.g. for a data subscription."; 1916 } 1918 typedef stream-filter-ref { 1919 type leafref { 1920 path "/sn:filters/sn:stream-filter/sn:name"; 1921 } 1922 description 1923 "This type is used to reference an event stream filter."; 1924 } 1926 typedef stream-ref { 1927 type leafref { 1928 path "/sn:streams/sn:stream/sn:name"; 1929 } 1930 description 1931 "This type is used to reference a system-provided event stream."; 1932 } 1934 typedef subscription-id { 1935 type uint32; 1936 description 1937 "A type for subscription identifiers."; 1938 } 1940 typedef transport { 1941 type identityref { 1942 base transport; 1943 } 1944 description 1945 "Specifies transport used to send notification messages to a 1946 receiver."; 1947 } 1949 /* 1950 * GROUPINGS 1951 */ 1953 grouping stream-filter-elements { 1954 description 1955 "This grouping defines the base for filters applied to event 1956 streams."; 1957 choice filter-spec { 1958 description 1959 "The content filter specification for this request."; 1960 anydata stream-subtree-filter { 1961 if-feature "subtree"; 1962 description 1963 "Event stream evaluation criteria encoded in the syntax of a 1964 subtree filter as defined in RFC 6241, Section 6. 1966 The subtree filter is applied to the representation of 1967 individual, delineated event records as contained within the 1968 event stream. 1970 If the subtree filter returns a non-empty node set, the 1971 filter matches the event record, and the event record is 1972 included in the notification message sent to the receivers."; 1973 reference "RFC 6241, Section 6."; 1974 } 1975 leaf stream-xpath-filter { 1976 if-feature "xpath"; 1977 type yang:xpath1.0; 1978 description 1979 "Event stream evaluation criteria encoded in the syntax of 1980 an XPath 1.0 expression. 1982 The XPath expression is evaluated on the representation of 1983 individual, delineated event records as contained within 1984 the event stream. 1986 The result of the XPath expression is converted to a 1987 boolean value using the standard XPath 1.0 rules. If the 1988 boolean value is 'true', the filter matches the event 1989 record, and the event record is included in the notification 1990 message sent to the receivers. 1992 The expression is evaluated in the following XPath context: 1994 o The set of namespace declarations are those in scope on 1995 the 'stream-xpath-filter' leaf element. 1997 o The set of variable bindings is empty. 1999 o The function library is the core function library, and 2000 the XPath functions defined in section 10 in RFC 7950. 2002 o The context node is the root node."; 2003 reference 2004 "http://www.w3.org/TR/1999/REC-xpath-19991116 2005 RFC 7950, Section 10."; 2007 } 2008 } 2009 } 2011 grouping update-qos { 2012 description 2013 "This grouping describes Quality of Service information 2014 concerning a subscription. This information is passed to lower 2015 layers for transport prioritization and treatment"; 2016 leaf dscp { 2017 if-feature "dscp"; 2018 type inet:dscp; 2019 default "0"; 2020 description 2021 "The desired network transport priority level. This is the 2022 priority set on notification messages encapsulating the 2023 results of the subscription. This transport priority is 2024 shared for all receivers of a given subscription."; 2025 } 2026 leaf weighting { 2027 if-feature "qos"; 2028 type uint8 { 2029 range "0 .. 255"; 2030 } 2031 description 2032 "Relative weighting for a subscription. Allows an underlying 2033 transport layer perform informed load balance allocations 2034 between various subscriptions"; 2035 reference 2036 "RFC-7540, section 5.3.2"; 2037 } 2038 leaf dependency { 2039 if-feature "qos"; 2040 type subscription-id; 2041 description 2042 "Provides the 'subscription-id' of a parent subscription which 2043 has absolute precedence should that parent have push updates 2044 ready to egress the publisher. In other words, there should be 2045 no streaming of objects from the current subscription if 2046 the parent has something ready to push. 2048 If a dependency is asserted via configuration or via RPC, but 2049 the referenced 'subscription-id' does not exist, the 2050 dependency is silently discarded. If a referenced 2051 subscription is deleted this dependency is removed."; 2052 reference 2053 "RFC-7540, section 5.3.1"; 2054 } 2055 } 2057 grouping subscription-policy-modifiable { 2058 description 2059 "This grouping describes all objects which may be changed 2060 in a subscription."; 2061 choice target { 2062 mandatory true; 2063 description 2064 "Identifies the source of information against which a 2065 subscription is being applied, as well as specifics on the 2066 subset of information desired from that source."; 2067 case stream { 2068 choice stream-filter { 2069 description 2070 "An event stream filter can be applied to a subscription. 2071 That filter will come either referenced from a global list, 2072 or be provided within the subscription itself."; 2073 case by-reference { 2074 description 2075 "Apply a filter that has been configured separately."; 2076 leaf stream-filter-name { 2077 type stream-filter-ref; 2078 mandatory true; 2079 description 2080 "References an existing event stream filter which is to 2081 be applied to an event stream for the subscription."; 2082 } 2083 } 2084 case within-subscription { 2085 description 2086 "Local definition allows a filter to have the same 2087 lifecycle as the subscription."; 2088 uses stream-filter-elements; 2089 } 2090 } 2091 } 2092 } 2093 leaf stop-time { 2094 type yang:date-and-time; 2095 description 2096 "Identifies a time after which notification messages for a 2097 subscription should not be sent. If 'stop-time' is not 2098 present, the notification messages will continue until the 2099 subscription is terminated. If 'replay-start-time' exists, 2100 'stop-time' must be for a subsequent time. If 2101 'replay-start-time' doesn't exist, 'stop-time' when established 2102 must be for a future time."; 2103 } 2104 } 2106 grouping subscription-policy-dynamic { 2107 description 2108 "This grouping describes the only information concerning a 2109 subscription which can be passed over the RPCs defined in this 2110 model."; 2111 uses subscription-policy-modifiable { 2112 augment target/stream { 2113 description 2114 "Adds additional objects which can be modified by RPC."; 2115 leaf stream { 2116 type stream-ref { 2117 require-instance false; 2118 } 2119 mandatory true; 2120 description 2121 "Indicates the event stream to be considered for 2122 this subscription."; 2124 } 2125 leaf replay-start-time { 2126 if-feature "replay"; 2127 type yang:date-and-time; 2128 config false; 2129 description 2130 "Used to trigger the replay feature for a dynamic 2131 subscription, with event records being selected needing to 2132 be at or after the start at the time specified. If 2133 'replay-start-time' is not present, this is not a replay 2134 subscription and event record push should start 2135 immediately. It is never valid to specify start times that 2136 are later than or equal to the current time."; 2137 } 2138 } 2139 } 2140 uses update-qos; 2141 } 2143 grouping subscription-policy { 2144 description 2145 "This grouping describes the full set of policy information 2146 concerning both dynamic and configured subscriptions, with the 2147 exclusion of both receivers and networking information specific 2148 to the publisher such as what interface should be used to 2149 transmit notification messages."; 2150 uses subscription-policy-dynamic; 2151 leaf transport { 2152 if-feature "configured"; 2153 type transport; 2154 description 2155 "For a configured subscription, this leaf specifies the 2156 transport used to deliver messages destined to all receivers 2157 of that subscription."; 2158 } 2159 leaf encoding { 2160 when 'not(../transport) or derived-from(../transport, 2161 "sn:configurable-encoding")'; 2162 type encoding; 2163 description 2164 "The type of encoding for notification messages. For a 2165 dynamic subscription, if not included as part of an establish- 2166 subscription RPC, the encoding will be populated with the 2167 encoding used by that RPC. For a configured subscription, if 2168 not explicitly configured the encoding with be the default 2169 encoding for an underlying transport."; 2170 } 2171 leaf purpose { 2172 if-feature "configured"; 2173 type string; 2174 description 2175 "Open text allowing a configuring entity to embed the 2176 originator or other specifics of this subscription."; 2177 } 2178 } 2180 /* 2181 * RPCs 2182 */ 2184 rpc establish-subscription { 2185 description 2186 "This RPC allows a subscriber to create (and possibly negotiate) 2187 a subscription on its own behalf. If successful, the 2188 subscription remains in effect for the duration of the 2189 subscriber's association with the publisher, or until the 2190 subscription is terminated. In case an error occurs, or the 2191 publisher cannot meet the terms of a subscription, an RPC error 2192 is returned, the subscription is not created. In that case, the 2193 RPC reply's 'error-info' MAY include suggested parameter 2194 settings that would have a higher likelihood of succeeding in a 2195 subsequent 'establish-subscription' request."; 2196 input { 2197 uses subscription-policy-dynamic; 2198 leaf encoding { 2199 type encoding; 2200 description 2201 "The type of encoding for the subscribed data. If not 2202 included as part of the RPC, the encoding MUST be set by the 2203 publisher to be the encoding used by this RPC."; 2204 } 2205 } 2206 output { 2207 leaf id { 2208 type subscription-id; 2209 mandatory true; 2210 description 2211 "Identifier used for this subscription."; 2212 } 2213 leaf replay-start-time-revision { 2214 if-feature "replay"; 2215 type yang:date-and-time; 2216 description 2217 "If a replay has been requested, this represents the 2218 earliest time covered by the event buffer for the requested 2219 event stream. The value of this object is the 2220 'replay-log-aged-time' if it exists. Otherwise it is the 2221 'replay-log-creation-time'. All buffered event records 2222 after this time will be replayed to a receiver. This 2223 object will only be sent if the starting time has been 2224 revised to be later than the time requested by the 2225 subscriber."; 2226 } 2227 } 2228 } 2230 rc:yang-data establish-subscription-stream-error-info { 2231 container establish-subscription-stream-error-info { 2232 description 2233 "If any 'establish-subscription' RPC parameters are 2234 unsupportable against the event stream, a subscription is not 2235 created and the RPC error response MUST indicate the reason 2236 why the subscription failed to be created. This yang-data MAY 2237 be inserted as structured data within a subscription's RPC 2238 error response to indicate the failure reason. This yang-data 2239 MUST be inserted if hints are to be provided back to the 2240 subscriber."; 2241 leaf reason { 2242 type identityref { 2243 base establish-subscription-error; 2244 } 2245 description 2246 "Indicates the reason why the subscription has failed to 2247 be created to a targeted event stream."; 2248 } 2249 leaf filter-failure-hint { 2250 type string; 2251 description 2252 "Information describing where and/or why a provided filter 2253 was unsupportable for a subscription."; 2254 } 2255 } 2256 } 2258 rpc modify-subscription { 2259 description 2260 "This RPC allows a subscriber to modify a dynamic subscription's 2261 parameters. If successful, the changed subscription 2262 parameters remain in effect for the duration of the 2263 subscription, until the subscription is again modified, or until 2264 the subscription is terminated. In case of an error or an 2265 inability to meet the modified parameters, the subscription is 2266 not modified and the original subscription parameters remain in 2267 effect. In that case, the RPC error MAY include 'error-info' 2268 suggested parameter hints that would have a high likelihood of 2269 succeeding in a subsequent 'modify-subscription' request. A 2270 successful 'modify-subscription' will return a suspended 2271 subscription to an 'active' state."; 2272 input { 2273 leaf id { 2274 type subscription-id; 2275 mandatory true; 2276 description 2277 "Identifier to use for this subscription."; 2278 } 2279 uses subscription-policy-modifiable; 2280 } 2281 } 2283 rc:yang-data modify-subscription-stream-error-info { 2284 container modify-subscription-stream-error-info { 2285 description 2286 "This yang-data MAY be provided as part of a subscription's RPC 2287 error response when there is a failure of a 2288 'modify-subscription' RPC which has been made against an event 2289 stream. This yang-data MUST be used if hints are to be 2290 provided back to the subscriber."; 2291 leaf reason { 2292 type identityref { 2293 base modify-subscription-error; 2294 } 2295 description 2296 "Information in a 'modify-subscription' RPC error response 2297 which indicates the reason why the subscription to an event 2298 stream has failed to be modified."; 2299 } 2300 leaf filter-failure-hint { 2301 type string; 2302 description 2303 "Information describing where and/or why a provided filter 2304 was unsupportable for a subscription."; 2305 } 2306 } 2307 } 2309 rpc delete-subscription { 2310 description 2311 "This RPC allows a subscriber to delete a subscription that 2312 was previously created from by that same subscriber using the 2313 'establish-subscription' RPC. 2315 If an error occurs, the server replies with an 'rpc-error' where 2316 the 'error-info' field MAY contain an 2317 'delete-subscription-error-info' structure."; 2318 input { 2319 leaf id { 2320 type subscription-id; 2321 mandatory true; 2322 description 2323 "Identifier of the subscription that is to be deleted. 2324 Only subscriptions that were created using 2325 'establish-subscription' from the same origin as this RPC 2326 can be deleted via this RPC."; 2327 } 2328 } 2329 } 2331 rpc kill-subscription { 2332 nacm:default-deny-all; 2333 description 2334 "This RPC allows an operator to delete a dynamic subscription 2335 without restrictions on the originating subscriber or underlying 2336 transport session. 2338 If an error occurs, the server replies with an 'rpc-error' where 2339 the 'error-info' field MAY contain an 2340 'delete-subscription-error-info' structure."; 2341 input { 2342 leaf id { 2343 type subscription-id; 2344 mandatory true; 2345 description 2346 "Identifier of the subscription that is to be deleted. Only 2347 subscriptions that were created using 2348 'establish-subscription' can be deleted via this RPC."; 2349 } 2350 } 2351 } 2353 rc:yang-data delete-subscription-error-info { 2354 container delete-subscription-error-info { 2355 description 2356 "If a 'delete-subscription' RPC or a 'kill-subscription' RPC 2357 fails, the subscription is not deleted and the RPC error 2358 response MUST indicate the reason for this failure. This 2359 yang-data MAY be inserted as structured data within a 2360 subscription's RPC error response to indicate the failure 2361 reason."; 2362 leaf reason { 2363 type identityref { 2364 base delete-subscription-error; 2365 } 2366 mandatory true; 2367 description 2368 "Indicates the reason why the subscription has failed to be 2369 deleted."; 2370 } 2371 } 2372 } 2374 /* 2375 * NOTIFICATIONS 2376 */ 2378 notification replay-completed { 2379 sn:subscription-state-notification; 2380 if-feature "replay"; 2381 description 2382 "This notification is sent to indicate that all of the replay 2383 notifications have been sent. It must not be sent for any other 2384 reason."; 2385 leaf id { 2386 type subscription-id; 2387 mandatory true; 2388 description 2389 "This references the affected subscription."; 2390 } 2391 } 2393 notification subscription-completed { 2394 sn:subscription-state-notification; 2395 if-feature "configured"; 2396 description 2397 "This notification is sent to indicate that a subscription has 2398 finished passing event records, as the 'stop-time' has been 2399 reached."; 2400 leaf id { 2401 type subscription-id; 2402 mandatory true; 2403 description 2404 "This references the gracefully completed subscription."; 2405 } 2406 } 2408 notification subscription-modified { 2409 sn:subscription-state-notification; 2410 description 2411 "This notification indicates that a subscription has been 2412 modified. Notification messages sent from this point on will 2413 conform to the modified terms of the subscription. For 2414 completeness, this subscription state change notification 2415 includes both modified and non-modified aspects of a 2416 subscription."; 2417 leaf id { 2418 type subscription-id; 2419 mandatory true; 2420 description 2421 "This references the affected subscription."; 2422 } 2423 uses subscription-policy { 2424 refine "target/stream/stream-filter/within-subscription" { 2425 description 2426 "Filter applied to the subscription. If the 2427 'stream-filter-name' is populated, the filter within the 2428 subscription came from the 'filters' container. Otherwise it 2429 is populated in-line as part of the subscription."; 2430 } 2431 } 2432 } 2434 notification subscription-resumed { 2435 sn:subscription-state-notification; 2436 description 2437 "This notification indicates that a subscription that had 2438 previously been suspended has resumed. Notifications will once 2439 again be sent. In addition, a 'subscription-resumed' indicates 2440 that no modification of parameters has occurred since the last 2441 time event records have been sent."; 2442 leaf id { 2443 type subscription-id; 2444 mandatory true; 2445 description 2446 "This references the affected subscription."; 2447 } 2448 } 2450 notification subscription-started { 2451 sn:subscription-state-notification; 2452 if-feature "configured"; 2453 description 2454 "This notification indicates that a subscription has started and 2455 notifications are beginning to be sent. This notification shall 2456 only be sent to receivers of a subscription; it does not 2457 constitute a general-purpose notification."; 2458 leaf id { 2459 type subscription-id; 2460 mandatory true; 2461 description 2462 "This references the affected subscription."; 2463 } 2464 uses subscription-policy { 2465 refine "target/stream/replay-start-time" { 2466 description 2467 "Indicates the time that a replay using for the streaming of 2468 buffered event records. This will be populated with the 2469 most recent of the following: the event time of the previous 2470 event record sent to a receiver, the 2471 'replay-log-creation-time', the 'replay-log-aged-time', 2472 or the most recent publisher boot time."; 2473 } 2474 refine "target/stream/stream-filter/within-subscription" { 2475 description 2476 "Filter applied to the subscription. If the 2477 'stream-filter-name' is populated, the filter within the 2478 subscription came from the 'filters' container. Otherwise it 2479 is populated in-line as part of the subscription."; 2480 } 2481 augment "target/stream" { 2482 description 2483 "This augmentation adds additional parameters specific to a 2484 subscription-started notification."; 2485 leaf replay-previous-event-time { 2486 when "../replay-start-time"; 2487 if-feature "replay"; 2488 type yang:date-and-time; 2489 description 2490 "If there is at least one event in the replay buffer prior 2491 to 'replay-start-time', this gives the time of the event 2492 generated immediately prior to the 'replay-start-time'. 2494 If a receiver previously received event records for this 2495 configured subscription, it can compare this time to the 2496 last event record previously received. If the two are not 2497 the same (perhaps due to a reboot), then a dynamic replay 2498 can be initiated to acquire any missing event records."; 2499 } 2500 } 2501 } 2502 } 2504 notification subscription-suspended { 2505 sn:subscription-state-notification; 2506 description 2507 "This notification indicates that a suspension of the 2508 subscription by the publisher has occurred. No further 2509 notifications will be sent until the subscription resumes. 2510 This notification shall only be sent to receivers of a 2511 subscription; it does not constitute a general-purpose 2512 notification."; 2513 leaf id { 2514 type subscription-id; 2515 mandatory true; 2516 description 2517 "This references the affected subscription."; 2518 } 2519 leaf reason { 2520 type identityref { 2521 base subscription-suspended-reason; 2522 } 2523 mandatory true; 2524 description 2525 "Identifies the condition which resulted in the suspension."; 2526 } 2527 } 2529 notification subscription-terminated { 2530 sn:subscription-state-notification; 2531 description 2532 "This notification indicates that a subscription has been 2533 terminated."; 2534 leaf id { 2535 type subscription-id; 2536 mandatory true; 2537 description 2538 "This references the affected subscription."; 2539 } 2540 leaf reason { 2541 type identityref { 2542 base subscription-terminated-reason; 2543 } 2544 mandatory true; 2545 description 2546 "Identifies the condition which resulted in the termination ."; 2547 } 2548 } 2550 /* 2551 * DATA NODES 2552 */ 2554 container streams { 2555 config false; 2556 description 2557 "This container contains information on the built-in event 2558 streams provided by the publisher."; 2559 list stream { 2560 key "name"; 2561 description 2562 "Identifies the built-in event streams that are supported by 2563 the publisher."; 2564 leaf name { 2565 type string; 2566 description 2567 "A handle for a system-provided event stream made up of a 2568 sequential set of event records, each of which is 2569 characterized by its own domain and semantics."; 2570 } 2571 leaf description { 2572 type string; 2573 mandatory true; 2574 description 2575 "A description of the event stream, including such 2576 information as the type of event records that are available 2577 within this event stream."; 2578 } 2579 leaf replay-support { 2580 if-feature "replay"; 2581 type empty; 2582 description 2583 "Indicates that event record replay is available on this 2584 event stream."; 2585 } 2586 leaf replay-log-creation-time { 2587 when "../replay-support"; 2588 if-feature "replay"; 2589 type yang:date-and-time; 2590 mandatory true; 2591 description 2592 "The timestamp of the creation of the log used to support the 2593 replay function on this event stream. This time might be 2594 earlier than the earliest available information contained in 2595 the log. This object is updated if the log resets for some 2596 reason."; 2597 } 2598 leaf replay-log-aged-time { 2599 when "../replay-support"; 2600 if-feature "replay"; 2601 type yang:date-and-time; 2602 description 2603 "The timestamp associated with last event record which has 2604 been aged out of the log. This timestamp identifies how far 2605 back into history this replay log extends, if it doesn't 2606 extend back to the 'replay-log-creation-time'. This object 2607 MUST be present if replay is supported and any event records 2608 have been aged out of the log."; 2609 } 2610 } 2611 } 2613 container filters { 2614 description 2615 "This container contains a list of configurable filters 2616 that can be applied to subscriptions. This facilitates 2617 the reuse of complex filters once defined."; 2618 list stream-filter { 2619 key "name"; 2620 description 2621 "A list of pre-configured filters that can be applied to 2622 subscriptions."; 2623 leaf name { 2624 type string; 2625 description 2626 "An name to differentiate between filters."; 2627 } 2628 uses stream-filter-elements; 2629 } 2630 } 2632 container subscriptions { 2633 description 2634 "Contains the list of currently active subscriptions, i.e. 2635 subscriptions that are currently in effect, used for 2636 subscription management and monitoring purposes. This includes 2637 subscriptions that have been setup via RPC primitives as well as 2638 subscriptions that have been established via configuration."; 2639 list subscription { 2640 key "id"; 2641 description 2642 "The identity and specific parameters of a subscription. 2643 Subscriptions within this list can be created using a control 2644 channel or RPC, or be established through configuration. 2646 If configuration operations or the 'kill-subscription' RPC are 2647 used to delete a subscription, a 'subscription-terminated' 2648 message is sent to any active or suspended receivers."; 2649 leaf id { 2650 type subscription-id; 2651 description 2652 "Identifier of a subscription; unique within a publisher"; 2653 } 2654 uses subscription-policy { 2655 refine "target/stream/stream" { 2656 description 2657 "Indicates the event stream to be considered for this 2658 subscription. If an event stream has been removed, 2659 and no longer can be referenced by an active subscription, 2660 send a 'subscription-terminated' notification with 2661 'stream-unavailable' as the reason. If a configured 2662 subscription refers to a non-existent event stream, move 2663 that subscription to the 'invalid' state."; 2664 } 2665 refine "transport" { 2666 description 2667 "For a configured subscription, this leaf specifies the 2668 transport used to deliver messages destined to all 2669 receivers of that subscription. This object is mandatory 2670 for subscriptions in the configuration datastore. This 2671 object is not mandatory for dynamic subscriptions within 2672 the operational state datastore. The object should not 2673 be present for dynamic subscriptions."; 2674 } 2675 augment "target/stream" { 2676 description 2677 "Enables objects to added to a configured stream 2678 subscription"; 2679 leaf configured-replay { 2680 if-feature "configured"; 2681 if-feature "replay"; 2682 type empty; 2683 description 2684 "The presence of this leaf indicates that replay for the 2685 configured subscription should start at the earliest time 2686 in the event log, or at the publisher boot time, which 2687 ever is later."; 2688 } 2689 } 2690 } 2691 choice notification-message-origin { 2692 if-feature "configured"; 2693 description 2694 "Identifies the egress interface on the publisher from which 2695 notification messages are to be sent."; 2696 case interface-originated { 2697 description 2698 "When notification messages to egress a specific, 2699 designated interface on the publisher."; 2700 leaf source-interface { 2701 if-feature "interface-designation"; 2702 type if:interface-ref; 2703 description 2704 "References the interface for notification messages."; 2705 } 2706 } 2707 case address-originated { 2708 description 2709 "When notification messages are to depart from a publisher 2710 using specific originating address and/or routing context 2711 information."; 2712 leaf source-vrf { 2713 if-feature "supports-vrf"; 2714 type leafref { 2715 path "/ni:network-instances/ni:network-instance/ni:name"; 2716 } 2717 description 2718 "VRF from which notification messages should egress a 2719 publisher."; 2720 } 2721 leaf source-address { 2722 type inet:ip-address-no-zone; 2723 description 2724 "The source address for the notification messages. If a 2725 source VRF exists, but this object doesn't, a publisher's 2726 default address for that VRF must be used."; 2727 } 2728 } 2729 } 2730 leaf configured-subscription-state { 2731 if-feature "configured"; 2732 type enumeration { 2733 enum valid { 2734 value 1; 2735 description 2736 "Subscription is supportable with current parameters."; 2737 } 2738 enum invalid { 2739 value 2; 2740 description 2741 "The subscription as a whole is unsupportable with its 2742 current parameters."; 2743 } 2744 enum concluded { 2745 value 3; 2746 description 2747 "A subscription is inactive as it has hit a stop time, 2748 but not yet been removed from configuration."; 2749 } 2750 } 2751 config false; 2752 description 2753 "The presence of this leaf indicates that the subscription 2754 originated from configuration, not through a control channel 2755 or RPC. The value indicates the system established state 2756 of the subscription."; 2757 } 2758 container receivers { 2759 description 2760 "Set of receivers in a subscription."; 2761 list receiver { 2762 key "name"; 2763 min-elements 1; 2764 description 2765 "A host intended as a recipient for the notification 2766 messages of a subscription. For configured subscriptions, 2767 transport specific network parameters (or a leafref to 2768 those parameters) may augmentated to a specific receiver 2769 within this list."; 2770 leaf name { 2771 type string; 2772 description 2773 "Identifies a unique receiver for a subscription."; 2774 } 2775 leaf sent-event-records { 2776 type yang:zero-based-counter64; 2777 config false; 2778 description 2779 "The number of event records sent to the receiver. The 2780 count is initialized when a dynamic subscription is 2781 established, or when a configured receiver 2782 transitions to the valid state."; 2783 } 2784 leaf excluded-event-records { 2785 type yang:zero-based-counter64; 2786 config false; 2787 description 2788 "The number of event records explicitly removed either 2789 via an event stream filter or an access control filter so 2790 that they are not passed to a receiver. This count is 2791 set to zero each time 'sent-event-records' is 2792 initialized."; 2793 } 2794 leaf state { 2795 type enumeration { 2796 enum active { 2797 value 1; 2798 description 2799 "Receiver is currently being sent any applicable 2800 notification messages for the subscription."; 2801 } 2802 enum suspended { 2803 value 2; 2804 description 2805 "Receiver state is 'suspended', so the publisher 2806 is currently unable to provide notification messages 2807 for the subscription."; 2808 } 2809 enum connecting { 2810 value 3; 2811 if-feature "configured"; 2812 description 2813 "A subscription has been configured, but a 2814 'subscription-started' subscription state change 2815 notification needs to be successfully received before 2816 notification messages are sent. 2818 If the 'reset' action is invoked for a receiver of an 2819 active configured subscription, the state must be 2820 moved to 'connecting'."; 2821 } 2822 enum disconnected { 2823 value 4; 2824 if-feature "configured"; 2825 description 2826 "A subscription has failed in sending a subscription 2827 started state change to the receiver. 2828 Additional attempts at connection attempts are not 2829 currently being made."; 2830 } 2831 } 2832 config false; 2833 mandatory true; 2834 description 2835 "Specifies the state of a subscription from the 2836 perspective of a particular receiver. With this info it 2837 is possible to determine whether a subscriber is 2838 currently generating notification messages intended for 2839 that receiver."; 2840 } 2841 action reset { 2842 if-feature "configured"; 2843 description 2844 "Allows the reset of this configured subscription 2845 receiver to the 'connecting' state. This enables the 2846 connection process to be re-initiated."; 2847 output { 2848 leaf time { 2849 type yang:date-and-time; 2850 mandatory true; 2851 description 2852 "Time a publisher returned the receiver to a 2853 'connecting' state."; 2854 } 2855 } 2856 } 2857 } 2858 } 2859 } 2860 } 2861 } 2862 2864 5. Considerations 2866 5.1. IANA Considerations 2868 This document registers the following namespace URI in the "IETF XML 2869 Registry" [RFC3688]: 2871 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2872 Registrant Contact: The IESG. 2873 XML: N/A; the requested URI is an XML namespace. 2875 This document registers the following YANG module in the "YANG Module 2876 Names" registry [RFC6020]: 2878 Name: ietf-subscribed-notifications 2879 Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2880 Prefix: sn 2881 Reference: draft-ietf-netconf-ietf-subscribed-notifications-11.txt 2882 (RFC form) 2884 5.2. Implementation Considerations 2886 To support deployments including both configured and dynamic 2887 subscriptions, it is recommended to split the subscription "id" 2888 domain into static and dynamic halves. That way it eliminates the 2889 possibility of collisions if the configured subscriptions attempt to 2890 set a subscription-id which might have already been dynamically 2891 allocated. A best practice is to use lower half the "id" object's 2892 integer space when that "id" is assigned by an external entity (such 2893 as with a configured subscription). This leaves the upper half of 2894 subscription integer space available to be dynamically assigned by 2895 the publisher. 2897 If a subscription is unable to marshal a series of filtered event 2898 records into transmittable notification messages, the receiver should 2899 be suspended with the reason "unsupportable-volume". 2901 For configured subscriptions, operations are against the set of 2902 receivers using the subscription "id" as a handle for that set. But 2903 for streaming updates, subscription state change notifications are 2904 local to a receiver. In this specification it is the case that 2905 receivers get no information from the publisher about the existence 2906 of other receivers. But if a network operator wants to let the 2907 receivers correlate results, it is useful to use the subscription 2908 "id" across the receivers to allow that correlation. 2910 For configured replay subscriptions, the receiver is protected from 2911 duplicated events being pushed after a publisher is rebooted. 2912 However it is possible that a receiver might want to acquire event 2913 records which failed to be delivered just prior to the reboot. 2914 Delivering these event records be accomplished by leveraging the 2915 "eventTime" from the last event record received prior to the receipt 2916 of a "subscription-started" subscription state change notification. 2917 With this "eventTime" and the "replay-start-time" from the 2918 "subscription-started" notification, an independent dynamic 2919 subscription can be established which retrieves any event records 2920 which may have been generated but not sent to the receiver. 2922 5.3. Transport Requirements 2924 This section provides requirements for any subscribed notification 2925 transport supporting the solution presented in this document. 2927 The transport selected by the subscriber to reach the publisher MUST 2928 be able to support multiple "establish-subscription" requests made 2929 within the same transport session. 2931 For both configured and dynamic subscriptions the publisher MUST 2932 authenticate a receiver via some transport level mechanism before 2933 sending any event records for which they are authorized to see. In 2934 addition, the receiver MUST authenticate the publisher at the 2935 transport level. The result is mutual authentication between the 2936 two. 2938 A secure transport is highly recommended and the publisher MUST 2939 ensure that the receiver has sufficient authorization to perform the 2940 function they are requesting against the specific subset of content 2941 involved. 2943 A specific transport specification built upon this document may or 2944 may not choose to require the use of the same logical channel for the 2945 RPCs and the event records. However the event records and the 2946 subscription state change notifications MUST be sent on the same 2947 transport session to ensure the properly ordered delivery. 2949 Additional transport requirements will be dictated by the choice of 2950 transport used with a subscription. For an example of such 2951 requirements with NETCONF transport, see 2952 [I-D.draft-ietf-netconf-netconf-event-notifications]. 2954 5.4. Security Considerations 2956 The YANG module specified in this document defines a schema for data 2957 that is designed to be accessed via network management transports 2958 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 2959 layer is the secure transport layer, and the mandatory-to-implement 2960 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 2961 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 2962 transport is TLS [RFC5246]. 2964 The NETCONF Access Control Model (NACM) [RFC8341] provides the means 2965 to restrict access for particular NETCONF or RESTCONF users to a 2966 preconfigured subset of all available NETCONF or RESTCONF operations 2967 and content. 2969 One subscription "id" can be used for two or more receivers of the 2970 same configured subscription. But due to the possibility of 2971 different access control permissions per receiver, it cannot be 2972 assumed that each receiver is getting identical updates. 2974 With configured subscriptions, one or more publishers could be used 2975 to overwhelm a receiver. Notification messages SHOULD NOT be sent to 2976 any receiver which does not support this specification. Receivers 2977 that do not want notification messages need only terminate or refuse 2978 any transport sessions from the publisher. 2980 When a receiver of a configured subscription gets a new 2981 "subscription-started" message for a known subscription where it is 2982 already consuming events, the receiver SHOULD retrieve any event 2983 records generated since the last event record was received. This can 2984 be accomplish by establishing a separate dynamic replay subscription 2985 with the same filtering criteria with the publisher, assuming the 2986 publisher supports the "replay" feature. 2988 For dynamic subscriptions, implementations need to protect against 2989 malicious or buggy subscribers which may send a large number 2990 "establish-subscription" requests, thereby using up system resources. 2991 To cover this possibility operators SHOULD monitor for such cases 2992 and, if discovered, take remedial action to limit the resources used, 2993 such as suspending or terminating a subset of the subscriptions or, 2994 if the underlying transport is session based, terminate the 2995 underlying transport session. 2997 There are a number of data nodes defined in this YANG module that are 2998 writable/creatable/deletable (i.e., config true, which is the 2999 default). These data nodes may be considered sensitive or vulnerable 3000 in some network environments. Write operations (e.g., edit-config) 3001 to these data nodes without proper protection can have a negative 3002 effect on network operations. These are the subtrees and data nodes 3003 where there is a specific sensitivity/vulnerability: 3005 Container: "/filters" 3007 o "stream-subtree-filter": updating a filter could increase the 3008 computational complexity of all referencing subscriptions. 3010 o "stream-xpath-filter": updating a filter could increase the 3011 computational complexity of all referencing subscriptions. 3013 Container: "/subscriptions" 3015 The following considerations are only relevant for configuration 3016 operations made upon configured subscriptions: 3018 o "configured-replay": can be used to send a large number of event 3019 records to a receiver. 3021 o "dependency": can be used to force important traffic to be queued 3022 behind less important updates. 3024 o "dscp": if unvalidated, can result in the sending of traffic with 3025 a higher priority marking than warranted. 3027 o "id": can overwrite an existing subscription, perhaps one 3028 configured by another entity. 3030 o "name": adding a new key entry can be used to attempt to send 3031 traffic to an unwilling receiver. 3033 o "replay-start-time": can be used to push very large logs, wasting 3034 resources. 3036 o "source-address": the configured address might not be able to 3037 reach a desired receiver. 3039 o "source-interface": the configured interface might not be able to 3040 reach a desired receiver. 3042 o "source-vrf": can place a subscription into a virtual network 3043 where receivers are not entitled to view the subscribed content. 3045 o "stop-time": could be used to terminate content at an inopportune 3046 time. 3048 o "stream": could set a subscription to an event stream containing 3049 no content permitted for the targeted receivers. 3051 o "stream-filter-name": could be set to a filter which is irrelevant 3052 to the event stream. 3054 o "stream-subtree-filter": a complex filter can increase the 3055 computational resources for this subscription. 3057 o "stream-xpath-filter": a complex filter can increase the 3058 computational resources for this subscription. 3060 o "weighting": placing a large weight can overwhelm the dequeuing of 3061 other subscriptions. 3063 Some of the readable data nodes in this YANG module may be considered 3064 sensitive or vulnerable in some network environments. It is thus 3065 important to control read access (e.g., via get, get-config, or 3066 notification) to these data nodes. These are the subtrees and data 3067 nodes and their sensitivity/vulnerability: 3069 Container: "/streams" 3071 o "name": if access control is not properly configured, can expose 3072 system internals to those who should have no access to this 3073 information. 3075 o "replay-support": if access control is not properly configured, 3076 can expose logs to those who should have no access. 3078 Container: "/subscriptions" 3079 o "excluded-event-records": leaf can provide information about 3080 filtered event records. A network operator should have 3081 permissions to know about such filtering. 3083 o "subscription": different operational teams might have a desire to 3084 set varying subsets of subscriptions. Access control should be 3085 designed to permit read access to just the allowed set. 3087 Some of the RPC operations in this YANG module may be considered 3088 sensitive or vulnerable in some network environments. It is thus 3089 important to control access to these operations. These are the 3090 operations and their sensitivity/vulnerability: 3092 RPC: all 3094 o If a malicious or buggy subscriber sends an unexpectedly large 3095 number of RPCs, the result might be an excessive use of system 3096 resources on the publisher just to determine that these 3097 subscriptions should be declined. In such a situation, 3098 subscription interactions MAY be terminated by terminating the 3099 transport session. 3101 RPC: "delete-subscription" 3103 o No special considerations. 3105 RPC: "establish-subscription" 3107 o Subscriptions could overload a publisher's resources. For this 3108 reason, publishers MUST ensure that they have sufficient resources 3109 to fulfill this request or otherwise reject the request. 3111 RPC: "kill-subscription" 3113 o The "kill-subscription" RPC MUST be secured so that only 3114 connections with administrative rights are able to invoke this 3115 RPC. 3117 RPC: "modify-subscription" 3119 o Subscriptions could overload a publisher's resources. For this 3120 reason, publishers MUST ensure that they have sufficient resources 3121 to fulfill this request or otherwise reject the request. 3123 6. Acknowledgments 3125 For their valuable comments, discussions, and feedback, we wish to 3126 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen, 3127 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan 3128 Hares, Michael Scharf, and Guangying Zheng. 3130 7. References 3132 7.1. Normative References 3134 [I-D.draft-ietf-rtgwg-ni-model] 3135 Berger, L., Hopps, C., and A. Lindem, "YANG Network 3136 Instances", draft-ietf-rtgwg-ni-model-12 (work in 3137 progress), March 2018. 3139 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3140 Requirement Levels", BCP 14, RFC 2119, 3141 DOI 10.17487/RFC2119, March 1997, 3142 . 3144 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 3145 "Definition of the Differentiated Services Field (DS 3146 Field) in the IPv4 and IPv6 Headers", RFC 2474, 3147 DOI 10.17487/RFC2474, December 1998, 3148 . 3150 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3151 DOI 10.17487/RFC3688, January 2004, 3152 . 3154 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3155 (TLS) Protocol Version 1.2", RFC 5246, 3156 DOI 10.17487/RFC5246, August 2008, 3157 . 3159 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3160 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 3161 . 3163 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 3164 the Network Configuration Protocol (NETCONF)", RFC 6020, 3165 DOI 10.17487/RFC6020, October 2010, 3166 . 3168 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3169 and A. Bierman, Ed., "Network Configuration Protocol 3170 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 3171 . 3173 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 3174 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 3175 . 3177 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 3178 RFC 6991, DOI 10.17487/RFC6991, July 2013, 3179 . 3181 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3182 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3183 . 3185 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3186 RFC 7951, DOI 10.17487/RFC7951, August 2016, 3187 . 3189 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 3190 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 3191 . 3193 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3194 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3195 May 2017, . 3197 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 3198 Access Control Model", STD 91, RFC 8341, 3199 DOI 10.17487/RFC8341, March 2018, 3200 . 3202 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 3203 and R. Wilton, "Network Management Datastore Architecture 3204 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 3205 . 3207 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 3208 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 3209 . 3211 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 3212 Version 1.0", November 1999, 3213 . 3215 7.2. Informative References 3217 [I-D.draft-ietf-netconf-netconf-event-notifications] 3218 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3219 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 3220 event notifications", May 2018, 3221 . 3224 [I-D.draft-ietf-netconf-restconf-notif] 3225 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen- 3226 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and 3227 HTTP transport for event notifications", May 2018, 3228 . 3231 [I-D.ietf-netconf-yang-push] 3232 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3233 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 3234 Lengyel, "YANG Datastore Subscription", May 2018, 3235 . 3238 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 3239 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 3240 DOI 10.17487/RFC7540, May 2015, 3241 . 3243 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 3244 for Subscription to YANG Datastores", RFC 7923, 3245 DOI 10.17487/RFC7923, June 2016, 3246 . 3248 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 3249 RFC 8071, DOI 10.17487/RFC8071, February 2017, 3250 . 3252 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3253 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3254 . 3256 Appendix A. Example Configured Transport Augmentation 3258 This appendix provides a non-normative example of how the YANG model 3259 defined in Section 4 may be enhanced to incorporate the configuration 3260 parameters needed to support the transport connectivity process. In 3261 this example, connectivity via an imaginary transport type of "foo" 3262 is explored. For more on the overall need, see Section 2.5.7. 3264 The YANG model defined in this section contains two main elements. 3265 First is a transport identity "foo". This transport identity allows 3266 a configuration agent to define "foo" as the selected type of 3267 transport for a subscription. Second is a YANG case augmentation 3268 "foo" which is made to the "/subscriptions/subscription/receivers/ 3269 receiver" node of Section 4. Within this augmentation are the 3270 transport configuration parameters "address" and "port" which are 3271 necessary to make the connect to the receiver. 3273 module example-foo-subscribed-notifications { 3274 yang-version 1.1; 3275 namespace 3276 "urn:example:foo-subscribed-notifications"; 3278 prefix fsn; 3280 import ietf-subscribed-notifications { 3281 prefix sn; 3282 } 3283 import ietf-inet-types { 3284 prefix inet; 3285 } 3287 description 3288 "Defines 'foo' as a supported type of configured transport for 3289 subscribed event notifications."; 3291 identity foo { 3292 base sn:transport; 3293 description 3294 "Transport type 'foo' is available for use as a configured 3295 subscription transport protocol for subscribed notifications."; 3296 } 3298 augment 3299 "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { 3300 when 'derived-from(../../../transport, "fsn:foo")'; 3301 description 3302 "This augmentation makes 'foo' specific transport parameters 3303 available for a receiver."; 3304 leaf address { 3305 type inet:host; 3306 mandatory true; 3307 description 3308 "Specifies the address to use for messages destined to a 3309 receiver."; 3310 } 3311 leaf port { 3312 type inet:port-number; 3313 mandatory true; 3314 description 3315 "Specifies the port number to use for messages destined to a 3316 receiver."; 3317 } 3318 } 3319 } 3321 Figure 21: Example Transport Augmentation for the fictitious protocol 3322 foo 3324 This example YANG model for transport "foo" will not be seen in a 3325 real world deployment. For a real world deployment supporting an 3326 actual transport technology, a similar YANG model must be defined. 3328 Appendix B. Changes between revisions 3330 (To be removed by RFC editor prior to publication) 3332 v17 - v18 3334 o Transport optional in YANG model. 3336 o Modify subscription must come from the originator of the 3337 subscription. (Text got dropped somewhere previously.) 3339 o Title change. 3341 v16 - v17 3343 o YANG renaming: Subscription identifier renamed to id. Counters 3344 renamed. Filters id made into name. 3346 o Text tweaks. 3348 v15 - v16 3350 o Mandatory empty case "transport" removed. 3352 o Appendix case turned from "netconf" to "foo". 3354 v14 - v15 3356 o Text tweaks. 3358 o Mandatory empty case "transport" added for transport parameters. 3359 This includes a new section and an appendix explaining it. 3361 v13 - v14 3363 o Removed the 'address' leaf. 3365 o Replay is now of type 'empty' for configured. 3367 v12 - v13 3369 o Tweaks from Kent's comments 3371 o Referenced in YANG model updated per Tom Petch's comments 3373 o Added leaf replay-previous-event-time 3375 o Renamed the event counters, downshifted the subscription states 3377 v11 - v12 3379 o Tweaks from Kent's, Tim's, and Martin's comments 3381 o Clarified dscp text, and made its own feature 3383 o YANG model tweaks alphabetizing, features. 3385 v10 - v11 3387 o access control filtering of events in streams included to match 3388 RFC5277 behavior 3390 o security considerations updated based on YANG template. 3392 o dependency QoS made non-normative on HTTP2 QoS 3394 o tree diagrams referenced for each figure using them 3396 o reference numbers placed into state machine figures 3398 o broke configured replay into its own section 3400 o many tweaks updates based on LC and YANG doctor reviews 3402 o trees and YANG model reconciled were deltas existed 3404 o new feature for interface originated. 3406 o dscp removed from the qos feature 3407 o YANG model updated in a way which collapses groups only used once 3408 so that they are part of the 'subscriptions' container. 3410 o alternative encodings only allowed for transports which support 3411 them. 3413 v09 - v10 3415 o Typos and tweaks 3417 v08 - v09 3419 o NMDA model supported. Non NMDA version at https://github.com/ 3420 netconf-wg/rfc5277bis/ 3422 o Error mechanism revamped to match to embedded implementations. 3424 o Explicitly identified error codes relevant to each RPC/ 3425 Notification 3427 v07 - v08 3429 o Split YANG trees to separate document subsections. 3431 o Clarified configured state machine based on Balazs comments, and 3432 moved it into the configured subscription subsections. 3434 o Normative reference to Network Instance model for VRF 3436 o One transport for all receivers of configured subscriptions. 3438 o QoS section moved in from yang-push 3440 v06 - v07 3442 o Clarification on state machine for configured subscriptions. 3444 v05 - v06 3446 o Made changes proposed by Martin, Kent, and others on the list. 3447 Most significant of these are stream returned to string (with the 3448 SYSLOG identity removed), intro section on 5277 relationship, an 3449 identity set moved to an enumeration, clean up of definitions/ 3450 terminology, state machine proposed for configured subscriptions 3451 with a clean-up of subscription state options. 3453 o JSON and XML become features. Also Xpath and subtree filtering 3454 become features 3456 o Terminology updates with event records, and refinement of filters 3457 to just event stream filters. 3459 o Encoding refined in establish-subscription so it takes the RPC's 3460 encoding as the default. 3462 o Namespaces in examples fixed. 3464 v04 - v05 3466 o Returned to the explicit filter subtyping of v00 3468 o stream object changed to 'name' from 'stream' 3470 o Cleaned up examples 3472 o Clarified that JSON support needs notification-messages draft. 3474 v03 - v04 3476 o Moved back to the use of RFC5277 one-way notifications and 3477 encodings. 3479 v03 - v04 3481 o Replay updated 3483 v02 - v03 3485 o RPCs and Notification support is identified by the Notification 3486 2.0 capability. 3488 o Updates to filtering identities and text 3490 o New error type for unsupportable volume of updates 3492 o Text tweaks. 3494 v01 - v02 3496 o Subscription status moved under receiver. 3498 v00 - v01 3500 o Security considerations updated 3502 o Intro rewrite, as well as scattered text changes 3503 o Added Appendix A, to help match this to related drafts in progress 3505 o Updated filtering definitions, and filter types in yang file, and 3506 moved to identities for filter types 3508 o Added Syslog as an event stream 3510 o HTTP2 moved in from YANG-Push as a transport option 3512 o Replay made an optional feature for events. Won't apply to 3513 datastores 3515 o Enabled notification timestamp to have different formats. 3517 o Two error codes added. 3519 v01 5277bis - v00 subscribed notifications 3521 o Kill subscription RPC added. 3523 o Renamed from 5277bis to Subscribed Notifications. 3525 o Changed the notification capabilities version from 1.1 to 2.0. 3527 o Extracted create-subscription and other elements of RFC5277. 3529 o Error conditions added, and made specific in return codes. 3531 o Simplified yang model structure for removal of 'basic' grouping. 3533 o Added a grouping for items which cannot be statically configured. 3535 o Operational counters per receiver. 3537 o Subscription-id and filter-id renamed to identifier 3539 o Section for replay added. Replay now cannot be configured. 3541 o Control plane notification renamed to subscription state change 3542 notification 3544 o Source address: Source-vrf changed to string, default address 3545 option added 3547 o In yang model: 'info' changed to 'policy' 3549 o Scattered text clarifications 3550 v00 - v01 of 5277bis 3552 o YANG Model changes. New groupings for subscription info to allow 3553 restriction of what is changeable via RPC. Removed notifications 3554 for adding and removing receivers of configured subscriptions. 3556 o Expanded/renamed definitions from event server to publisher, and 3557 client to subscriber as applicable. Updated the definitions to 3558 include and expand on RFC 5277. 3560 o Removal of redundancy with other drafts 3562 o Many other clean-ups of wording and terminology 3564 Authors' Addresses 3566 Eric Voit 3567 Cisco Systems 3569 Email: evoit@cisco.com 3571 Alexander Clemm 3572 Huawei 3574 Email: ludwig@clemm.org 3576 Alberto Gonzalez Prieto 3577 Microsoft 3579 Email: alberto.gonzalez@microsoft.com 3581 Einar Nilsen-Nygaard 3582 Cisco Systems 3584 Email: einarnn@cisco.com 3586 Ambika Prasad Tripathy 3587 Cisco Systems 3589 Email: ambtripa@cisco.com