idnits 2.17.1 draft-ietf-netconf-subscribed-notifications-19.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 1303 has weird spacing: '... reason ide...' == Line 1338 has weird spacing: '... reason ide...' == Line 1354 has weird spacing: '...--ro id sub...' == Line 1369 has weird spacing: '...--ro id sub...' == Line 1390 has weird spacing: '...--ro id sub...' == (3 more instances...) -- The document date (December 18, 2018) is 1948 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: June 21, 2019 Huawei 6 A. Gonzalez Prieto 7 Microsoft 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 December 18, 2018 13 Subscription to YANG Event Notifications 14 draft-ietf-netconf-subscribed-notifications-19 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 June 21, 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 . . . . . . . . . . . . . . 63 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 . . . . . 71 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. 655 Below is a tree diagram for "delete-subscription". All objects 656 contained in this tree are described within the included YANG model 657 within Section 4. 659 +---x delete-subscription 660 +---w input 661 +---w id subscription-id 663 Figure 6: delete-subscription RPC tree diagram 665 Dynamic subscriptions can only be deleted via this RPC using a 666 transport session connecting to the subscriber. Configured 667 subscriptions cannot be deleted using RPCs. 669 2.4.5. Killing a Dynamic Subscription 671 The "kill-subscription" operation permits an operator to end a 672 dynamic subscription which is not associated with the transport 673 session used for the RPC. A publisher MUST terminate any dynamic 674 subscription identified by the "id" parameter in the RPC request, if 675 such a subscription exists. 677 Configured subscriptions cannot be killed using this RPC. Instead, 678 configured subscriptions are deleted as part of regular configuration 679 operations. Publishers MUST reject any RPC attempt to kill a 680 configured subscription. 682 Below is a tree diagram for "kill-subscription". All objects 683 contained in this tree are described within the included YANG model 684 within Section 4. 686 +---x kill-subscription 687 +---w input 688 +---w id subscription-id 690 Figure 7: kill-subscription RPC tree diagram 692 2.4.6. RPC Failures 694 Whenever an RPC is unsuccessful, the publisher returns relevant 695 information as part of the RPC error response. Transport level error 696 processing MUST be done before RPC error processing described in this 697 section. In all cases, RPC error information returned will use 698 existing transport layer RPC structures, such as those seen with 699 NETCONF in [RFC6241] Appendix A, or with RESTCONF in [RFC8040] 700 Section 7.1. These structures MUST be able to encode subscription 701 specific errors identified below and defined within this document's 702 YANG model. 704 As a result of this mixture, how subscription errors are encoded 705 within an RPC error response is transport dependent. Following are 706 valid errors which can occur for each RPC: 708 establish-subscription modify-subscription 709 ---------------------- ------------------- 710 dscp-unavailable filter-unsupported 711 encoding-unsupported insufficient-resources 712 filter-unsupported no-such-subscription 713 insufficient-resources 714 replay-unsupported 716 delete-subscription kill-subscription 717 ---------------------- ---------------------- 718 no-such-subscription no-such-subscription 720 To see a NETCONF based example of an error response from above, see 721 [I-D.draft-ietf-netconf-netconf-event-notifications], Figure 10. 723 There is one final set of transport independent RPC error elements 724 included in the YANG model. These are three yang-data structures 725 which enable the publisher to provide to the receiver that error 726 information which does not fit into existing transport layer RPC 727 structures. These three yang-data structures are: 729 1. "establish-subscription-stream-error-info": This MUST be returned 730 with the leaf "reason" populated if an RPC error reason has not 731 been placed elsewhere within the transport portion of a failed 732 "establish-subscription" RPC response. This MUST be sent if 733 hints on how to overcome the RPC error are included. 735 2. "modify-subscription-stream-error-info": This MUST be returned 736 with the leaf "reason" populated if an RPC error reason has not 737 been placed elsewhere within the transport portion of a failed 738 "modify-subscription" RPC response. This MUST be sent if hints 739 on how to overcome the RPC error are included. 741 3. "delete-subscription-error-info": This MUST be returned with the 742 leaf "reason" populated if an RPC error reason has not been 743 placed elsewhere within the transport portion of a failed 744 "delete-subscription" or "kill-subscription" RPC response. 746 2.5. Configured Subscriptions 748 A configured subscription is a subscription installed via 749 configuration. Configured subscriptions may be modified by any 750 configuration client with the proper permissions. Subscriptions can 751 be modified or terminated via configuration at any point of their 752 lifetime. Multiple configured subscriptions MUST be supportable over 753 a single transport session. 755 Configured subscriptions have several characteristics distinguishing 756 them from dynamic subscriptions: 758 o persistence across publisher reboots, 760 o persistence even when transport is unavailable, and 762 o an ability to send notification messages to more than one receiver 763 (note that receivers are unaware of the existence of any other 764 receivers.) 766 On the publisher, supporting configured subscriptions is optional and 767 advertised using the "configured" feature. On a receiver of a 768 configured subscription, support for dynamic subscriptions is 769 optional except where replaying missed event records is required. 771 In addition to the subscription parameters available to dynamic 772 subscriptions described in Section 2.4.2, the following additional 773 parameters are also available to configured subscriptions: 775 o A "transport" which identifies the transport protocol to use to 776 connect with all subscription receivers. 778 o One or more receivers, each intended as the destination for event 779 records. Note that each individual receiver is identifiable by 780 its "name". 782 o Optional parameters to identify where traffic should egress a 783 publisher: 785 * A "source-interface" which identifies the egress interface to 786 use from the publisher. Publisher support for this is optional 787 and advertised using the "interface-designation" feature. 789 * A "source-address" address, which identifies the IP address to 790 stamp on notification messages destined for the receiver. 792 * A "source-vrf" which identifies the VRF on which to reach 793 receivers. This VRF is a network instance as defined within 794 [I-D.draft-ietf-rtgwg-ni-model]. Publisher support for VRFs is 795 optional and advertised using the "supports-vrf" feature. 797 If none of the above parameters are set, notification messages 798 MUST egress the publisher's default interface. 800 A tree diagram describing these parameters is shown in Figure 20 801 within Section 3.3. All parameters are described within the YANG 802 model in Section 4. 804 2.5.1. Configured Subscription State Model 806 Below is the state machine for a configured subscription on the 807 publisher. This state machine describes the three states (valid, 808 invalid, and concluded), as well as the transitions between these 809 states. Start and end states are depicted to reflect configured 810 subscription creation and deletion events. The creation or 811 modification of a configured subscription initiates an evaluation by 812 the publisher to determine if the subscription is in valid or invalid 813 states. The publisher uses its own criteria in making this 814 determination. If in the valid state, the subscription becomes 815 operational. See (1) in the diagram below. 817 ......... 818 : start :-. 819 :.......: | 820 create .---modify-----.----------------------------------. 821 | | | | 822 V V .-------. ....... .---------. 823 .----[evaluate]--no--->|invalid|-delete->: end :<-delete-|concluded| 824 | '-------' :.....: '---------' 825 |-[evaluate]--no-(2). ^ ^ ^ 826 | ^ | | | | 827 yes | '->unsupportable delete stop-time 828 | modify (subscription- (subscription- (subscription- 829 | | terminated*) terminated*) concluded*) 830 | | | | | 831 (1) | (3) (4) (5) 832 | .---------------------------------------------------------------. 833 '-->| valid | 834 '---------------------------------------------------------------' 836 Legend: 837 dotted boxes: subscription added or removed via configuration 838 dashed boxes: states for a subscription 839 [evaluate]: decision point on whether the subscription is supportable 840 (*): resulting subscription state change notification 842 Figure 8: Publisher state model for a configured subscription 844 A subscription in the valid state may move to the invalid state in 845 one of two ways. First, it may be modified in a way which fails a 846 re-evaluation. See (2) in the diagram. Second, the publisher might 847 determine that the subscription is no longer supportable. This could 848 be for reasons of an unexpected but sustained increase in an event 849 stream's event records, degraded CPU capacity, a more complex 850 referenced filter, or other higher priority subscriptions which have 851 usurped resources. See (3) in the diagram. No matter the case, a 852 "subscription-terminated" notification is sent to any receivers in an 853 active or suspended state. A subscription in the valid state may 854 also transition to the concluded state via (5) if a configured stop 855 time has been reached. In this case, a "subscription-concluded" 856 notification is sent to any receivers in active or suspended states. 857 Finally, a subscription may be deleted by configuration (4). 859 When a subscription is in the valid state, a publisher will attempt 860 to connect with all receivers of a configured subscription and 861 deliver notification messages. Below is the state machine for each 862 receiver of a configured subscription. This receiver state machine 863 is fully contained within the state machine of the configured 864 subscription, and is only relevant when the configured subscription 865 is in the valid state. 867 .-----------------------------------------------------------------. 868 | valid | 869 | .----------. .------------. | 870 | | receiver |---timeout---------------->| receiver | | 871 | |connecting|<----------------reset--(c)|disconnected| | 872 | | |<-transport '------------' | 873 | '----------' loss,reset------------------------------. | 874 | (a) | | | 875 | subscription- (b) (b) | 876 | started* .--------. .---------. | 877 | '----->| |(d)-insufficient CPU,------->| | | 878 | |receiver| buffer overflow |receiver | | 879 | subscription-| active | |suspended| | 880 | modified* | |<----CPU, b/w sufficient,-(e)| | | 881 | '---->'--------' subscription-modified* '---------' | 882 '-----------------------------------------------------------------' 884 Legend: 885 dashed boxes which include the word 'receiver' show the possible 886 states for an individual receiver of a valid configured subscription. 887 * indicates a subscription state change notification 889 Figure 9: Receiver state for a configured subscription on a Publisher 891 When a configured subscription first moves to the valid state, the 892 "state" leaf of each receiver is initialized to the connecting state. 893 If transport connectivity is not available to any receiver and there 894 are any notification messages to deliver, a transport session is 895 established (e.g., through [RFC8071]). Individual receivers are 896 moved to the active state when a "subscription-started" subscription 897 state change notification is successfully passed to that receiver 898 (a). Event records are only sent to active receivers. Receivers of 899 a configured subscription remain active if both transport 900 connectivity can be verified to the receiver, and event records are 901 not being dropped due to a publisher buffer overflow. The result is 902 that a receiver will remain active on the publisher as long as events 903 aren't being lost, or the receiver cannot be reached. In addition, a 904 configured subscription's receiver MUST be moved to the connecting 905 state if the receiver is reset via the "reset" action (b), (c). For 906 more on reset, see Section 2.5.5. If transport connectivity cannot 907 be achieved while in the connecting state, the receiver MAY be moved 908 to the disconnected state. 910 A configured subscription's receiver MUST be moved to the suspended 911 state if there is transport connectivity between the publisher and 912 receiver, but notification messages are failing to be delivered due 913 to publisher buffer overflow, or notification messages are not able 914 to be generated for that receiver due to insufficient CPU (d). This 915 is indicated to the receiver by the "subscription-suspended" 916 subscription state change notification. 918 A configured subscription receiver MUST be returned to the active 919 state from the suspended state when notification messages are able to 920 be generated, bandwidth is sufficient to handle the notification 921 messages, and a receiver has successfully been sent a "subscription- 922 resumed" or "subscription-modified" subscription state change 923 notification (e). The choice as to which of these two subscription 924 state change notifications is sent is determined by whether the 925 subscription was modified during the period of suspension. 927 Modification of a configured subscription is possible at any time. A 928 "subscription-modified" subscription state change notification will 929 be sent to all active receivers, immediately followed by notification 930 messages conforming to the new parameters. Suspended receivers will 931 also be informed of the modification. However this notification will 932 await the end of the suspension for that receiver (e). 934 The mechanisms described above are mirrored in the RPCs and 935 notifications within the document. It should be noted that these 936 RPCs and notifications have been designed to be extensible and allow 937 subscriptions into targets other than event streams. For instance, 938 the YANG module defined in Section 5 of [I-D.ietf-netconf-yang-push] 939 augments "/sn:modify-subscription/sn:input/sn:target". 941 2.5.2. Creating a Configured Subscription 943 Configured subscriptions are established using configuration 944 operations against the top-level "subscriptions" subtree. 946 Because there is no explicit association with an existing transport 947 session, configuration operations MUST include additional parameters 948 beyond those of dynamic subscriptions. These parameters identify 949 each receiver, how to connect with that receiver, and possibly 950 whether the notification messages need to come from a specific egress 951 interface on the publisher. Receiver specific transport connectivity 952 parameters MUST be configured via transport specific augmentations to 953 this specification. See Section 2.5.7 for details. 955 After a subscription is successfully established, the publisher 956 immediately sends a "subscription-started" subscription state change 957 notification to each receiver. It is quite possible that upon 958 configuration, reboot, or even steady-state operations, a transport 959 session may not be currently available to the receiver. In this 960 case, when there is something to transport for an active 961 subscription, transport specific call-home operations will be used to 962 establish the connection. When transport connectivity is available, 963 notification messages may then be pushed. 965 With active configured subscriptions, it is allowable to buffer event 966 records even after a "subscription-started" has been sent. However 967 if events are lost (rather than just delayed) due to replay buffer 968 overflow, a new "subscription-started" must be sent. This new 969 "subscription-started" indicates an event record discontinuity. 971 To see an example of subscription creation using configuration 972 operations over NETCONF, see Appendix A of 973 [I-D.draft-ietf-netconf-netconf-event-notifications]. 975 2.5.3. Modifying a Configured Subscription 977 Configured subscriptions can be modified using configuration 978 operations against the top-level "subscriptions" subtree. 980 If the modification involves adding receivers, added receivers are 981 placed in the connecting state. If a receiver is removed, the 982 subscription state change notification "subscription-terminated" is 983 sent to that receiver if that receiver is active or suspended. 985 If the modification involves changing the policies for the 986 subscription, the publisher sends to currently active receivers a 987 "subscription-modified" notification. For any suspended receivers, a 988 "subscription-modified" notification will be delayed until the 989 receiver is resumed. (Note: in this case, the "subscription- 990 modified" notification informs the receiver that the subscription has 991 been resumed, so no additional "subscription-resumed" need be sent. 992 Also note that if multiple modifications have occurred during the 993 suspension, only the "subscription-modified" notification describing 994 the latest one need be sent to the receiver.) 996 2.5.4. Deleting a Configured Subscription 998 Subscriptions can be deleted through configuration against the top- 999 level "subscriptions" subtree. 1001 Immediately after a subscription is successfully deleted, the 1002 publisher sends to all receivers of that subscription a subscription 1003 state change notification stating the subscription has ended (i.e., 1004 "subscription-terminated"). 1006 2.5.5. Resetting a Configured Subscription Receiver 1008 It is possible that a configured subscription to a receiver needs to 1009 be reset. This is accomplished via the "reset" action within the 1010 YANG model at "/subscriptions/subscription/receivers/receiver/reset". 1011 This action may be useful in cases where a publisher has timed out 1012 trying to reach a receiver. When such a reset occurs, a transport 1013 session will be initiated if necessary, and a new "subscription- 1014 started" notification will be sent. This action does not have any 1015 effect on transport connectivity if the needed connectivity already 1016 exists. 1018 2.5.6. Replay for a Configured Subscription 1020 It is possible to do replay on a configured subscription. This is 1021 supported via the configuration of the "configured-replay" object on 1022 the subscription. The setting of this object enables the streaming 1023 of the buffered event records for the subscribed event stream. All 1024 buffered event records which have been retained since the last 1025 publisher restart will be sent to each configured receiver. 1027 Replay of events records created since restart is useful. It allows 1028 event records generated before transport connectivity establishment 1029 to be passed to a receiver. Setting the restart time as the earliest 1030 configured replay time precludes possibility of resending of event 1031 records logged prior to publisher restart. It also ensures the same 1032 records will be sent to each configured receiver, regardless of the 1033 speed of transport connectivity establishment to each receiver. 1034 Finally, establishing restart as the earliest potential time for 1035 event records to be included within notification messages, a well- 1036 understood timeframe for replay is defined. 1038 As a result, when any configured subscription receivers become 1039 active, buffered event records will be sent immediately after the 1040 "subscription-started" notification. If the publisher knows the last 1041 event record sent to a receiver, and the publisher has not rebooted, 1042 the next event record on the event stream which meets filtering 1043 criteria will be the leading event record sent. Otherwise, the 1044 leading event record will be the first event record meeting filtering 1045 criteria subsequent to the latest of three different times: the 1046 "replay-log-creation-time", "replay-log-aged-time", or the most 1047 recent publisher boot time. The "replay-log-creation-time" and 1048 "replay-log-aged-time" are discussed in Section 2.4.2.1. The most 1049 recent publisher boot time ensures that duplicate event records are 1050 not replayed from a previous time the publisher was booted. 1052 It is quite possible that a receiver might want to retrieve event 1053 records from an event stream prior to the latest boot. If such 1054 records exist where there is a configured replay, the publisher MUST 1055 send the time of the event record immediately preceding the "replay- 1056 start-time" within the "replay-previous-event-time" leaf. Through 1057 the existence of the "replay-previous-event-time", the receiver will 1058 know that earlier events prior to reboot exist. In addition, if the 1059 subscriber was previously receiving event records with the same 1060 subscription "id", the receiver can determine if there was a timegap 1061 where records generated on the publisher were not successully 1062 received. And with this information, the receiver may choose to 1063 dynamically subscribe to retrieve any event records placed into the 1064 event stream before the most recent boot time. 1066 All other replay functionality remains the same as with dynamic 1067 subscriptions as described in Section 2.4.2.1. 1069 2.5.7. Transport Connectivity for a Configured Subscription 1071 This specification is transport independent. However supporting a 1072 configured subscription will often require the establishment of 1073 transport connectivity. And the parameters used for this transport 1074 connectivity establishment are transport specific. As a result, the 1075 YANG model defined within Section 4 is not able to directly define 1076 and expose these transport parameters. 1078 It is necessary for an implementation to support the connection 1079 establishment process. To support this function, the YANG model does 1080 include a node where transport specific parameters for a particular 1081 receiver may be augmented. This node is 1082 "/subscriptions/subscription/receivers/receiver". By augmenting 1083 transport parameters from this node, system developers are able to 1084 incorporate the YANG objects necessary to support the transport 1085 connectivity establishment process. 1087 The result of this is the following requirement. A publisher 1088 supporting the feature "configured" MUST also support least one YANG 1089 model which augments transport connectivity parameters on 1090 "/subscriptions/subscription/receivers/receiver". For an example of 1091 such an augmentation, see Appendix A. 1093 2.6. Event Record Delivery 1095 Whether dynamic or configured, once a subscription has been set up, 1096 the publisher streams event records via notification messages per the 1097 terms of the subscription. For dynamic subscriptions, notification 1098 messages are sent over the session used to establish the 1099 subscription. For configured subscriptions, notification messages 1100 are sent over the connections specified by the transport and each 1101 receiver of a configured subscription. 1103 A notification message is sent to a receiver when an event record is 1104 not blocked by either the specified filter criteria or receiver 1105 permissions. This notification message MUST include an "eventTime" 1106 object as defined per [RFC5277] Section 4. This "eventTime" MUST be 1107 at the top level of YANG structured event record. 1109 The following example within [RFC7950] section 7.16.3 is an example 1110 of a compliant message: 1112 1114 2007-09-01T10:00:00Z 1115 1116 so-1/2/3.0 1117 up 1118 down 1119 1120 1122 Figure 10: subscribed notification message 1124 When a dynamic subscription has been started or modified, with 1125 "establish-subscription" or "modify-subscription" respectively, event 1126 records matching the newly applied filter criteria MUST NOT be sent 1127 until after the RPC reply has been sent. 1129 When a configured subscription has been started or modified, event 1130 records matching the newly applied filter criteria MUST NOT be sent 1131 until after the "subscription-started" or "subscription-modified" 1132 notifications has been sent, respectively. 1134 2.7. subscription state change notifications 1136 In addition to sending event records to receivers, a publisher MUST 1137 also send subscription state change notifications when events related 1138 to subscription management have occurred. 1140 subscription state change notifications are unlike other 1141 notifications in that they are never included in any event stream. 1142 Instead, they are inserted (as defined in this section) within the 1143 sequence of notification messages sent to a particular receiver. 1144 subscription state change notifications cannot be filtered out, they 1145 cannot be stored in replay buffers, and they are delivered only to 1146 impacted receivers of a subscription. The identification of 1147 subscription state change notifications is easy to separate from 1148 other notification messages through the use of the YANG extension 1149 "subscription-state-notif". This extension tags a notification as a 1150 subscription state change notification. 1152 The complete set of subscription state change notifications is 1153 described in the following subsections. 1155 2.7.1. subscription-started 1157 This notification indicates that a configured subscription has 1158 started, and event records may be sent. Included in this 1159 subscription state change notification are all the parameters of the 1160 subscription, except for the receiver(s) transport connection 1161 information and origin information indicating where notification 1162 messages will egress the publisher. Note that if a referenced filter 1163 from the "filters" container has been used within the subscription, 1164 the notification still provides the contents of that referenced 1165 filter under the "within-subscription" subtree. 1167 Note that for dynamic subscriptions, no "subscription-started" 1168 notifications are ever sent. 1170 Below is a tree diagram for "subscription-started". All objects 1171 contained in this tree are described within the included YANG model 1172 within Section 4. 1174 +---n subscription-started {configured}? 1175 +--ro id 1176 | subscription-id 1177 +--ro (target) 1178 | +--:(stream) 1179 | +--ro (stream-filter)? 1180 | | +--:(by-reference) 1181 | | | +--ro stream-filter-name 1182 | | | stream-filter-ref 1183 | | +--:(within-subscription) 1184 | | +--ro (filter-spec)? 1185 | | +--:(stream-subtree-filter) 1186 | | | +--ro stream-subtree-filter? 1187 | | | {subtree}? 1188 | | +--:(stream-xpath-filter) 1189 | | +--ro stream-xpath-filter? yang:xpath1.0 1190 | | {xpath}? 1191 | +--ro stream stream-ref 1192 | +--ro replay-start-time? 1193 | | yang:date-and-time {replay}? 1194 | +--ro replay-previous-event-time? 1195 | yang:date-and-time {replay}? 1196 +--ro stop-time? 1197 | yang:date-and-time 1198 +--ro dscp? inet:dscp 1199 | {dscp}? 1200 +--ro weighting? uint8 {qos}? 1201 +--ro dependency? 1202 | subscription-id {qos}? 1203 +--ro transport? transport 1204 | {configured}? 1205 +--ro encoding? encoding 1206 +--ro purpose? string 1207 {configured}? 1209 Figure 11: subscription-started notification tree diagram 1211 2.7.2. subscription-modified 1213 This notification indicates that a subscription has been modified by 1214 configuration operations. It is delivered directly after the last 1215 event records processed using the previous subscription parameters, 1216 and before any event records processed after the modification. 1218 Below is a tree diagram for "subscription-modified". All objects 1219 contained in this tree are described within the included YANG model 1220 within Section 4. 1222 +---n subscription-modified 1223 +--ro id 1224 | subscription-id 1225 +--ro (target) 1226 | +--:(stream) 1227 | +--ro (stream-filter)? 1228 | | +--:(by-reference) 1229 | | | +--ro stream-filter-name 1230 | | | stream-filter-ref 1231 | | +--:(within-subscription) 1232 | | +--ro (filter-spec)? 1233 | | +--:(stream-subtree-filter) 1234 | | | +--ro stream-subtree-filter? 1235 | | | {subtree}? 1236 | | +--:(stream-xpath-filter) 1237 | | +--ro stream-xpath-filter? yang:xpath1.0 1238 | | {xpath}? 1239 | +--ro stream stream-ref 1240 | +--ro replay-start-time? 1241 | yang:date-and-time {replay}? 1242 +--ro stop-time? 1243 | yang:date-and-time 1244 +--ro dscp? inet:dscp 1245 | {dscp}? 1246 +--ro weighting? uint8 {qos}? 1247 +--ro dependency? 1248 | subscription-id {qos}? 1249 +--ro transport? transport 1250 | {configured}? 1251 +--ro encoding? encoding 1252 +--ro purpose? string 1253 {configured}? 1255 Figure 12: subscription-modified notification tree diagram 1257 A publisher most often sends this notification directly after the 1258 modification of any configuration parameters impacting a configured 1259 subscription. But it may also be sent at two other times: 1261 1. Where a configured subscription has been modified during the 1262 suspension of a receiver, the notification will be delayed until 1263 the receiver's suspension is lifted. In this situation, the 1264 notification indicates that the subscription has been both 1265 modified and resumed. 1267 2. A "subscription-modified" subscription state change notification 1268 MUST be sent if the contents of the filter identified by the 1269 subscription's "stream-filter-ref" leaf has changed. This state 1270 change notification is to be sent for a filter change impacting 1271 any active receiver of a configured or dynamic subscription. 1273 2.7.3. subscription-terminated 1275 This notification indicates that no further event records for this 1276 subscription should be expected from the publisher. A publisher may 1277 terminate the sending event records to a receiver for the following 1278 reasons: 1280 1. Configuration which removes a configured subscription, or a 1281 "kill-subscription" RPC which ends a dynamic subscription. These 1282 are identified via the reason "no-such-subscription". 1284 2. A referenced filter is no longer accessible. This is identified 1285 by "filter-unavailable". 1287 3. The event stream referenced by a subscription is no longer 1288 accessible by the receiver. This is identified by "stream- 1289 unavailable". 1291 4. A suspended subscription has exceeded some timeout. This is 1292 identified by "suspension-timeout". 1294 Each of the reasons above correspond one-to-one with a "reason" 1295 identityref specified within the YANG model. 1297 Below is a tree diagram for "subscription-terminated". All objects 1298 contained in this tree are described within the included YANG model 1299 within Section 4. 1301 +---n subscription-terminated 1302 +--ro id subscription-id 1303 +--ro reason identityref 1305 Figure 13: subscription-terminated notification tree diagram 1307 Note: this subscription state change notification MUST be sent to a 1308 dynamic subscription's receiver when the subscription ends 1309 unexpectedly. The cases when this might happen are when a "kill- 1310 subscription" RPC is successful, or when some other event not 1311 including the reaching the subscription's "stop-time" results in a 1312 publisher choosing to end the subscription. 1314 2.7.4. subscription-suspended 1316 This notification indicates that a publisher has suspended the 1317 sending of event records to a receiver, and also indicates the 1318 possible loss of events. Suspension happens when capacity 1319 constraints stop a publisher from serving a valid subscription. The 1320 two conditions where is this possible are: 1322 1. "insufficient-resources" when a publisher is unable to produce 1323 the requested event stream of notification messages, and 1325 2. "unsupportable-volume" when the bandwidth needed to get generated 1326 notification messages to a receiver exceeds a threshold. 1328 These conditions are encoded within the "reason" object. No further 1329 notification will be sent until the subscription resumes or is 1330 terminated. 1332 Below is a tree diagram for "subscription-suspended". All objects 1333 contained in this tree are described within the included YANG model 1334 within Section 4. 1336 +---n subscription-suspended 1337 +--ro id subscription-id 1338 +--ro reason identityref 1340 Figure 14: subscription-suspended notification tree diagram 1342 2.7.5. subscription-resumed 1344 This notification indicates that a previously suspended subscription 1345 has been resumed under the unmodified terms previously in place. 1346 Subscribed event records generated after the issuance of this 1347 subscription state change notification may now be sent. 1349 Below is the tree diagram for "subscription-resumed". All objects 1350 contained in this tree are described within the included YANG model 1351 within Section 4. 1353 +---n subscription-resumed 1354 +--ro id subscription-id 1356 Figure 15: subscription-resumed notification tree diagram 1358 2.7.6. subscription-completed 1360 This notification indicates that a subscription that includes a 1361 "stop-time" has successfully finished passing event records upon the 1362 reaching of that time. 1364 Below is a tree diagram for "subscription-completed". All objects 1365 contained in this tree are described within the included YANG model 1366 within Section 4. 1368 +---n subscription-completed {configured}? 1369 +--ro id subscription-id 1371 Figure 16: subscription-completed notification tree diagram 1373 2.7.7. replay-completed 1375 This notification indicates that all of the event records prior to 1376 the current time have been passed to a receiver. It is sent before 1377 any notification message containing an event record with a timestamp 1378 later than (1) the "stop-time" or (2) the subscription's start time. 1380 If a subscription contains no "stop-time", or has a "stop-time" that 1381 has not been reached, then after the "replay-completed" notification 1382 has been sent, additional event records will be sent in sequence as 1383 they arise naturally on the publisher. 1385 Below is a tree diagram for "replay-completed". All objects 1386 contained in this tree are described within the included YANG model 1387 within Section 4. 1389 +---n replay-completed {replay}? 1390 +--ro id subscription-id 1392 Figure 17: replay-completed notification tree diagram 1394 2.8. Subscription Monitoring 1396 In the operational state datastore, the container "subscriptions" 1397 maintains the state of all dynamic subscriptions, as well as all 1398 configured subscriptions. Using datastore retrieval operations, or 1399 subscribing to the "subscriptions" container 1400 [I-D.ietf-netconf-yang-push] allows the state of subscriptions and 1401 their connectivity to receivers to be monitored. 1403 Each subscription in the operational state datastore is represented 1404 as a list element. Included in this list are event counters for each 1405 receiver, the state of each receiver, as well as the subscription 1406 parameters currently in effect. The appearance of the leaf 1407 "configured-subscription-state" indicates that a particular 1408 subscription came into being via configuration. This leaf also 1409 indicates if the current state of that subscription is valid, 1410 invalid, and concluded. 1412 To understand the flow of event records within a subscription, there 1413 are two counters available for each receiver. The first counter is 1414 "sent-event-records" which shows the quantity of events actually 1415 identified for sending to a receiver. The second counter is 1416 "excluded-event-records" which shows event records not sent to 1417 receiver. "excluded-event-records" shows the combined results of 1418 both access control and per-subscription filtering. For configured 1419 subscriptions, counters are reset whenever the subscription is 1420 evaluated to valid (see (1) in Figure 8). 1422 Dynamic subscriptions are removed from the operational state 1423 datastore once they expire (reaching stop-time) or when they are 1424 terminated. While many subscription objects are shown as 1425 configurable, dynamic subscriptions are only included within the 1426 operational state datastore and as a result are not configurable. 1428 2.9. Advertisement 1430 Publishers supporting this document MUST indicate support of the YANG 1431 model "ietf-subscribed-notifications" within the YANG library of the 1432 publisher. In addition if supported, the optional features "encode- 1433 xml", "encode-json", "configured" "supports-vrf", "qos", "xpath", 1434 "subtree", "interface-designation", "dscp", and "replay" MUST be 1435 indicated. 1437 3. YANG Data Model Trees 1439 This section contains tree diagrams for nodes defined in Section 4. 1440 For tree diagrams of subscription state change notifications, see 1441 Section 2.7. For the tree diagrams for the RPCs, see Section 2.4. 1443 3.1. Event Streams Container 1445 A publisher maintains a list of available event streams as 1446 operational data. This list contains both standardized and vendor- 1447 specific event streams. This enables subscribers to discover what 1448 streams a publisher supports. 1450 +--ro streams 1451 +--ro stream* [name] 1452 +--ro name string 1453 +--ro description string 1454 +--ro replay-support? empty {replay}? 1455 +--ro replay-log-creation-time yang:date-and-time 1456 | {replay}? 1457 +--ro replay-log-aged-time? yang:date-and-time 1458 {replay}? 1460 Figure 18: Stream Container tree diagram 1462 Above is a tree diagram for the "streams" container. All objects 1463 contained in this tree are described within the included YANG model 1464 within Section 4. 1466 3.2. Filters Container 1468 The "filters" container maintains a list of all subscription filters 1469 that persist outside the life-cycle of a single subscription. This 1470 enables pre-defined filters which may be referenced by more than one 1471 subscription. 1473 +--rw filters 1474 +--rw stream-filter* [name] 1475 +--rw name string 1476 +--rw (filter-spec)? 1477 +--:(stream-subtree-filter) 1478 | +--rw stream-subtree-filter? {subtree}? 1479 +--:(stream-xpath-filter) 1480 +--rw stream-xpath-filter? yang:xpath1.0 {xpath}? 1482 Figure 19: Filter Container tree diagram 1484 Above is a tree diagram for the filters container. All objects 1485 contained in this tree are described within the included YANG model 1486 within Section 4. 1488 3.3. Subscriptions Container 1490 The "subscriptions" container maintains a list of all subscriptions 1491 on a publisher, both configured and dynamic. It can be used to 1492 retrieve information about the subscriptions which a publisher is 1493 serving. 1495 +--rw subscriptions 1496 +--rw subscription* [id] 1497 +--rw id 1498 | subscription-id 1499 +--rw (target) 1500 | +--:(stream) 1501 | +--rw (stream-filter)? 1502 | | +--:(by-reference) 1503 | | | +--rw stream-filter-name 1504 | | | stream-filter-ref 1505 | | +--:(within-subscription) 1506 | | +--rw (filter-spec)? 1507 | | +--:(stream-subtree-filter) 1508 | | | +--rw stream-subtree-filter? 1509 | | | {subtree}? 1510 | | +--:(stream-xpath-filter) 1511 | | +--rw stream-xpath-filter? 1512 | | yang:xpath1.0 {xpath}? 1513 | +--rw stream stream-ref 1514 | +--ro replay-start-time? 1515 | | yang:date-and-time {replay}? 1516 | +--rw configured-replay? empty 1517 | {configured,replay}? 1518 +--rw stop-time? 1519 | yang:date-and-time 1520 +--rw dscp? inet:dscp 1521 | {dscp}? 1522 +--rw weighting? uint8 {qos}? 1523 +--rw dependency? 1524 | subscription-id {qos}? 1525 +--rw transport? transport 1526 | {configured}? 1527 +--rw encoding? encoding 1528 +--rw purpose? string 1529 | {configured}? 1530 +--rw (notification-message-origin)? {configured}? 1531 | +--:(interface-originated) 1532 | | +--rw source-interface? 1533 | | if:interface-ref {interface-designation}? 1534 | +--:(address-originated) 1535 | +--rw source-vrf? 1536 | | -> /ni:network-instances/network-instance/name 1537 | | {supports-vrf}? 1538 | +--rw source-address? 1539 | inet:ip-address-no-zone 1540 +--ro configured-subscription-state? enumeration 1541 | {configured}? 1542 +--rw receivers 1543 +--rw receiver* [name] 1544 +--rw name string 1545 +--ro sent-event-records? 1546 | yang:zero-based-counter64 1547 +--ro excluded-event-records? 1548 | yang:zero-based-counter64 1549 +--ro state enumeration 1550 +---x reset {configured}? 1551 +--ro output 1552 +--ro time yang:date-and-time 1554 Figure 20: Subscriptions tree diagram 1556 Above is a tree diagram for the subscriptions container. All objects 1557 contained in this tree are described within the included YANG model 1558 within Section 4. 1560 4. Data Model 1562 This module imports typedefs from [RFC6991], [RFC8343], and 1563 [RFC8040], and it references [I-D.draft-ietf-rtgwg-ni-model], 1564 [XPATH], [RFC6241], [RFC7540], [RFC7951] and [RFC7950]. 1566 [ note to the RFC Editor - please replace XXXX within this YANG model 1567 with the number of this document, and XXXY with the number of 1568 [I-D.draft-ietf-rtgwg-ni-model] ] 1570 [ note to the RFC Editor - please replace the two dates within the 1571 YANG module with the date of publication ] 1573 file "ietf-subscribed-notifications@2018-10-25.yang" 1574 module ietf-subscribed-notifications { 1575 yang-version 1.1; 1576 namespace 1577 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"; 1579 prefix sn; 1581 import ietf-inet-types { 1582 prefix inet; 1583 reference 1584 "RFC 6991: Common YANG Data Types"; 1585 } 1586 import ietf-interfaces { 1587 prefix if; 1588 reference 1589 "RFC 8343: A YANG Data Model for Interface Management"; 1590 } 1591 import ietf-netconf-acm { 1592 prefix nacm; 1593 reference 1594 "RFC 8341: Network Configuration Access Control Model"; 1595 } 1596 import ietf-network-instance { 1597 prefix ni; 1598 reference 1599 "draft-ietf-rtgwg-ni-model-12: YANG Model for Network Instances"; 1600 } 1601 import ietf-restconf { 1602 prefix rc; 1603 reference 1604 "RFC 8040: RESTCONF Protocol"; 1605 } 1606 import ietf-yang-types { 1607 prefix yang; 1608 reference 1609 "RFC 6991: Common YANG Data Types"; 1610 } 1612 organization "IETF NETCONF (Network Configuration) Working Group"; 1613 contact 1614 "WG Web: 1615 WG List: 1617 Author: Alexander Clemm 1618 1620 Author: Eric Voit 1621 1623 Author: Alberto Gonzalez Prieto 1624 1626 Author: Einar Nilsen-Nygaard 1627 1629 Author: Ambika Prasad Tripathy 1630 "; 1632 description 1633 "Contains a YANG specification for subscribing to event records 1634 and receiving matching content within notification messages. 1636 Copyright (c) 2018 IETF Trust and the persons identified as authors 1637 of the code. All rights reserved. 1639 Redistribution and use in source and binary forms, with or without 1640 modification, is permitted pursuant to, and subject to the license 1641 terms contained in, the Simplified BSD License set forth in Section 1642 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 1643 (https://trustee.ietf.org/license-info). 1645 This version of this YANG module is part of RFC XXXX; see the RFC 1646 itself for full legal notices."; 1648 revision 2018-10-25 { 1649 description 1650 "Initial version"; 1651 reference 1652 "RFC XXXX:Customized Subscriptions to a Publisher's Event Streams"; 1653 } 1655 /* 1656 * FEATURES 1657 */ 1659 feature configured { 1660 description 1661 "This feature indicates that configuration of subscription is 1662 supported."; 1663 } 1665 feature dscp { 1666 description 1667 "This feature indicates a publisher supports the placement of 1668 suggested prioritization levels for network transport within 1669 notification messages."; 1670 } 1672 feature encode-json { 1673 description 1674 "This feature indicates that JSON encoding of notification 1675 messages is supported."; 1676 } 1678 feature encode-xml { 1679 description 1680 "This feature indicates that XML encoding of notification 1681 messages is supported."; 1682 } 1684 feature interface-designation { 1685 description 1686 "This feature indicates a publisher supports sourcing all 1687 receiver interactions for a configured subscription from a single 1688 designated egress interface."; 1689 } 1691 feature qos { 1692 description 1693 "This feature indicates a publisher supports absolute 1694 dependencies of one subscription's traffic over another, as well 1695 as weighted bandwidth sharing between subscriptions. Both of 1696 these are Quality of Service (QoS) features which allow 1697 differentiated treatment of notification messages between a 1698 publisher and a specific receiver."; 1699 } 1701 feature replay { 1702 description 1703 "This feature indicates that historical event record replay is 1704 supported. With replay, it is possible for past event records to 1705 be streamed in chronological order."; 1706 } 1708 feature subtree { 1709 description 1710 "This feature indicates support for YANG subtree filtering."; 1711 reference "RFC 6241, Section 6."; 1712 } 1714 feature supports-vrf { 1715 description 1716 "This feature indicates a publisher supports VRF configuration 1717 for configured subscriptions. VRF support for dynamic 1718 subscriptions does not require this feature."; 1719 reference "RFC XXXY, Section 6."; 1720 } 1722 feature xpath { 1723 description 1724 "This feature indicates support for XPath filtering."; 1725 reference "http://www.w3.org/TR/1999/REC-xpath-19991116"; 1726 } 1728 /* 1729 * EXTENSIONS 1730 */ 1732 extension subscription-state-notification { 1733 description 1734 "This statement applies only to notifications. It indicates that 1735 the notification is a subscription state change notification. 1736 Therefore it does not participate in a regular event stream and 1737 does not need to be specifically subscribed to in order to be 1738 received. This statement can only occur as a substatement to the 1739 YANG 'notification' statement. This statement is not for use 1740 outside of this YANG module."; 1741 } 1743 /* 1744 * IDENTITIES 1745 */ 1747 /* Identities for RPC and Notification errors */ 1749 identity delete-subscription-error { 1750 description 1751 "Problem found while attempting to fulfill either a 1752 'delete-subscription' RPC request or a 'kill-subscription' 1753 RPC request."; 1754 } 1756 identity establish-subscription-error { 1757 description 1758 "Problem found while attempting to fulfill an 1759 'establish-subscription' RPC request."; 1760 } 1762 identity modify-subscription-error { 1763 description 1764 "Problem found while attempting to fulfill a 1765 'modify-subscription' RPC request."; 1766 } 1768 identity subscription-suspended-reason { 1769 description 1770 "Problem condition communicated to a receiver as part of a 1771 'subscription-terminated' notification."; 1772 } 1774 identity subscription-terminated-reason { 1775 description 1776 "Problem condition communicated to a receiver as part of a 1777 'subscription-terminated' notification."; 1778 } 1780 identity dscp-unavailable { 1781 base establish-subscription-error; 1782 if-feature "dscp"; 1783 description 1784 "The publisher is unable mark notification messages with a 1785 prioritization information in a way which will be respected 1786 during network transit."; 1787 } 1789 identity encoding-unsupported { 1790 base establish-subscription-error; 1791 description 1792 "Unable to encode notification messages in the desired format."; 1793 } 1795 identity filter-unavailable { 1796 base subscription-terminated-reason; 1797 description 1798 "Referenced filter does not exist. This means a receiver is 1799 referencing a filter which doesn't exist, or to which they do not 1800 have access permissions."; 1801 } 1803 identity filter-unsupported { 1804 base establish-subscription-error; 1805 base modify-subscription-error; 1806 description 1807 "Cannot parse syntax within the filter. This failure can be from 1808 a syntax error, or a syntax too complex to be processed by the 1809 publisher."; 1810 } 1812 identity insufficient-resources { 1813 base establish-subscription-error; 1814 base modify-subscription-error; 1815 base subscription-suspended-reason; 1816 description 1817 "The publisher has insufficient resources to support the 1818 requested subscription. An example might be that allocated CPU 1819 is too limited to generate the desired set of notification 1820 messages."; 1821 } 1823 identity no-such-subscription { 1824 base modify-subscription-error; 1825 base delete-subscription-error; 1826 base subscription-terminated-reason; 1827 description 1828 "Referenced subscription doesn't exist. This may be as a result of 1829 a non-existent subscription id, an id which belongs to another 1830 subscriber, or an id for configured subscription."; 1832 } 1834 identity replay-unsupported { 1835 base establish-subscription-error; 1836 if-feature "replay"; 1837 description 1838 "Replay cannot be performed for this subscription. This means the 1839 publisher will not provide the requested historic information 1840 from the event stream via replay to this receiver."; 1841 } 1843 identity stream-unavailable { 1844 base subscription-terminated-reason; 1845 description 1846 "Not a subscribable event stream. This means the referenced event 1847 stream is not available for subscription by the receiver."; 1848 } 1850 identity suspension-timeout { 1851 base subscription-terminated-reason; 1852 description 1853 "Termination of previously suspended subscription. The publisher 1854 has eliminated the subscription as it exceeded a time limit for 1855 suspension."; 1856 } 1858 identity unsupportable-volume { 1859 base subscription-suspended-reason; 1860 description 1861 "The publisher does not have the network bandwidth needed to get 1862 the volume of generated information intended for a receiver."; 1863 } 1865 /* Identities for encodings */ 1867 identity configurable-encoding { 1868 description 1869 "If a transport identity derives from this identity, it means 1870 that it supports configurable encodings."; 1871 } 1873 identity encoding { 1874 description 1875 "Base identity to represent data encodings"; 1876 } 1878 identity encode-xml { 1879 base encoding; 1880 if-feature "encode-xml"; 1881 description 1882 "Encode data using XML as described in RFC 7950"; 1883 reference 1884 "RFC 7950 - The YANG 1.1 Data Modeling Language"; 1885 } 1887 identity encode-json { 1888 base encoding; 1889 if-feature "encode-json"; 1890 description 1891 "Encode data using JSON as described in RFC 7951"; 1892 reference 1893 "RFC 7951 - JSON Encoding of Data Modeled with YANG"; 1894 } 1896 /* Identities for transports */ 1897 identity transport { 1898 description 1899 "An identity that represents the underlying mechanism for 1900 passing notification messages."; 1901 } 1903 /* 1904 * TYPEDEFs 1905 */ 1907 typedef encoding { 1908 type identityref { 1909 base encoding; 1910 } 1911 description 1912 "Specifies a data encoding, e.g. for a data subscription."; 1913 } 1915 typedef stream-filter-ref { 1916 type leafref { 1917 path "/sn:filters/sn:stream-filter/sn:name"; 1918 } 1919 description 1920 "This type is used to reference an event stream filter."; 1921 } 1923 typedef stream-ref { 1924 type leafref { 1925 path "/sn:streams/sn:stream/sn:name"; 1926 } 1927 description 1928 "This type is used to reference a system-provided event stream."; 1929 } 1931 typedef subscription-id { 1932 type uint32; 1933 description 1934 "A type for subscription identifiers."; 1935 } 1937 typedef transport { 1938 type identityref { 1939 base transport; 1940 } 1941 description 1942 "Specifies transport used to send notification messages to a 1943 receiver."; 1944 } 1946 /* 1947 * GROUPINGS 1948 */ 1950 grouping stream-filter-elements { 1951 description 1952 "This grouping defines the base for filters applied to event 1953 streams."; 1954 choice filter-spec { 1955 description 1956 "The content filter specification for this request."; 1957 anydata stream-subtree-filter { 1958 if-feature "subtree"; 1959 description 1960 "Event stream evaluation criteria encoded in the syntax of a 1961 subtree filter as defined in RFC 6241, Section 6. 1963 The subtree filter is applied to the representation of 1964 individual, delineated event records as contained within the 1965 event stream. 1967 If the subtree filter returns a non-empty node set, the 1968 filter matches the event record, and the event record is 1969 included in the notification message sent to the receivers."; 1970 reference "RFC 6241, Section 6."; 1971 } 1972 leaf stream-xpath-filter { 1973 if-feature "xpath"; 1974 type yang:xpath1.0; 1975 description 1976 "Event stream evaluation criteria encoded in the syntax of 1977 an XPath 1.0 expression. 1979 The XPath expression is evaluated on the representation of 1980 individual, delineated event records as contained within 1981 the event stream. 1983 The result of the XPath expression is converted to a 1984 boolean value using the standard XPath 1.0 rules. If the 1985 boolean value is 'true', the filter matches the event 1986 record, and the event record is included in the notification 1987 message sent to the receivers. 1989 The expression is evaluated in the following XPath context: 1991 o The set of namespace declarations is the set of prefix 1992 and namespace pairs for all YANG modules implemented 1993 by the server, where the prefix is the YANG module 1994 name and the namespace is as defined by the 1995 "namespace" statement in the YANG module. 1997 If the leaf is encoded in XML, all namespace 1998 declarations in scope on the 'stream-xpath-filter' 1999 leaf element are added to the set of namespace 2000 declarations. If a prefix found in the XML is 2001 already present in the set of namespace declarations, 2002 the namespace in the XML is used. 2004 o The set of variable bindings is empty. 2006 o The function library is the core function library, and 2007 the XPath functions defined in section 10 in RFC 7950. 2009 o The context node is the root node."; 2010 reference 2011 "http://www.w3.org/TR/1999/REC-xpath-19991116 2012 RFC 7950, Section 10."; 2014 } 2015 } 2016 } 2018 grouping update-qos { 2019 description 2020 "This grouping describes Quality of Service information 2021 concerning a subscription. This information is passed to lower 2022 layers for transport prioritization and treatment"; 2023 leaf dscp { 2024 if-feature "dscp"; 2025 type inet:dscp; 2026 default "0"; 2027 description 2028 "The desired network transport priority level. This is the 2029 priority set on notification messages encapsulating the 2030 results of the subscription. This transport priority is 2031 shared for all receivers of a given subscription."; 2032 } 2033 leaf weighting { 2034 if-feature "qos"; 2035 type uint8 { 2036 range "0 .. 255"; 2037 } 2038 description 2039 "Relative weighting for a subscription. Allows an underlying 2040 transport layer perform informed load balance allocations 2041 between various subscriptions"; 2042 reference 2043 "RFC-7540, section 5.3.2"; 2044 } 2045 leaf dependency { 2046 if-feature "qos"; 2047 type subscription-id; 2048 description 2049 "Provides the 'subscription-id' of a parent subscription which 2050 has absolute precedence should that parent have push updates 2051 ready to egress the publisher. In other words, there should be 2052 no streaming of objects from the current subscription if 2053 the parent has something ready to push. 2055 If a dependency is asserted via configuration or via RPC, but 2056 the referenced 'subscription-id' does not exist, the 2057 dependency is silently discarded. If a referenced 2058 subscription is deleted this dependency is removed."; 2059 reference 2060 "RFC-7540, section 5.3.1"; 2061 } 2062 } 2064 grouping subscription-policy-modifiable { 2065 description 2066 "This grouping describes all objects which may be changed 2067 in a subscription."; 2068 choice target { 2069 mandatory true; 2070 description 2071 "Identifies the source of information against which a 2072 subscription is being applied, as well as specifics on the 2073 subset of information desired from that source."; 2074 case stream { 2075 choice stream-filter { 2076 description 2077 "An event stream filter can be applied to a subscription. 2078 That filter will come either referenced from a global list, 2079 or be provided within the subscription itself."; 2080 case by-reference { 2081 description 2082 "Apply a filter that has been configured separately."; 2083 leaf stream-filter-name { 2084 type stream-filter-ref; 2085 mandatory true; 2086 description 2087 "References an existing event stream filter which is to 2088 be applied to an event stream for the subscription."; 2089 } 2090 } 2091 case within-subscription { 2092 description 2093 "Local definition allows a filter to have the same 2094 lifecycle as the subscription."; 2095 uses stream-filter-elements; 2096 } 2097 } 2098 } 2099 } 2100 leaf stop-time { 2101 type yang:date-and-time; 2102 description 2103 "Identifies a time after which notification messages for a 2104 subscription should not be sent. If 'stop-time' is not 2105 present, the notification messages will continue until the 2106 subscription is terminated. If 'replay-start-time' exists, 2107 'stop-time' must be for a subsequent time. If 2108 'replay-start-time' doesn't exist, 'stop-time' when established 2109 must be for a future time."; 2110 } 2111 } 2113 grouping subscription-policy-dynamic { 2114 description 2115 "This grouping describes the only information concerning a 2116 subscription which can be passed over the RPCs defined in this 2117 model."; 2118 uses subscription-policy-modifiable { 2119 augment target/stream { 2120 description 2121 "Adds additional objects which can be modified by RPC."; 2122 leaf stream { 2123 type stream-ref { 2124 require-instance false; 2125 } 2126 mandatory true; 2127 description 2128 "Indicates the event stream to be considered for 2129 this subscription."; 2130 } 2131 leaf replay-start-time { 2132 if-feature "replay"; 2133 type yang:date-and-time; 2134 config false; 2135 description 2136 "Used to trigger the replay feature for a dynamic 2137 subscription, with event records being selected needing to 2138 be at or after the start at the time specified. If 2139 'replay-start-time' is not present, this is not a replay 2140 subscription and event record push should start 2141 immediately. It is never valid to specify start times that 2142 are later than or equal to the current time."; 2143 } 2144 } 2145 } 2146 uses update-qos; 2147 } 2149 grouping subscription-policy { 2150 description 2151 "This grouping describes the full set of policy information 2152 concerning both dynamic and configured subscriptions, with the 2153 exclusion of both receivers and networking information specific 2154 to the publisher such as what interface should be used to 2155 transmit notification messages."; 2156 uses subscription-policy-dynamic; 2157 leaf transport { 2158 if-feature "configured"; 2159 type transport; 2160 description 2161 "For a configured subscription, this leaf specifies the 2162 transport used to deliver messages destined to all receivers 2163 of that subscription."; 2164 } 2165 leaf encoding { 2166 when 'not(../transport) or derived-from(../transport, 2167 "sn:configurable-encoding")'; 2168 type encoding; 2169 description 2170 "The type of encoding for notification messages. For a 2171 dynamic subscription, if not included as part of an establish- 2172 subscription RPC, the encoding will be populated with the 2173 encoding used by that RPC. For a configured subscription, if 2174 not explicitly configured the encoding with be the default 2175 encoding for an underlying transport."; 2176 } 2177 leaf purpose { 2178 if-feature "configured"; 2179 type string; 2180 description 2181 "Open text allowing a configuring entity to embed the 2182 originator or other specifics of this subscription."; 2183 } 2184 } 2186 /* 2187 * RPCs 2188 */ 2190 rpc establish-subscription { 2191 description 2192 "This RPC allows a subscriber to create (and possibly negotiate) 2193 a subscription on its own behalf. If successful, the 2194 subscription remains in effect for the duration of the 2195 subscriber's association with the publisher, or until the 2196 subscription is terminated. In case an error occurs, or the 2197 publisher cannot meet the terms of a subscription, an RPC error 2198 is returned, the subscription is not created. In that case, the 2199 RPC reply's 'error-info' MAY include suggested parameter 2200 settings that would have a higher likelihood of succeeding in a 2201 subsequent 'establish-subscription' request."; 2202 input { 2203 uses subscription-policy-dynamic; 2204 leaf encoding { 2205 type encoding; 2206 description 2207 "The type of encoding for the subscribed data. If not 2208 included as part of the RPC, the encoding MUST be set by the 2209 publisher to be the encoding used by this RPC."; 2210 } 2211 } 2212 output { 2213 leaf id { 2214 type subscription-id; 2215 mandatory true; 2216 description 2217 "Identifier used for this subscription."; 2218 } 2219 leaf replay-start-time-revision { 2220 if-feature "replay"; 2221 type yang:date-and-time; 2222 description 2223 "If a replay has been requested, this represents the 2224 earliest time covered by the event buffer for the requested 2225 event stream. The value of this object is the 2226 'replay-log-aged-time' if it exists. Otherwise it is the 2227 'replay-log-creation-time'. All buffered event records 2228 after this time will be replayed to a receiver. This 2229 object will only be sent if the starting time has been 2230 revised to be later than the time requested by the 2231 subscriber."; 2232 } 2233 } 2234 } 2236 rc:yang-data establish-subscription-stream-error-info { 2237 container establish-subscription-stream-error-info { 2238 description 2239 "If any 'establish-subscription' RPC parameters are 2240 unsupportable against the event stream, a subscription is not 2241 created and the RPC error response MUST indicate the reason 2242 why the subscription failed to be created. This yang-data MAY 2243 be inserted as structured data within a subscription's RPC 2244 error response to indicate the failure reason. This yang-data 2245 MUST be inserted if hints are to be provided back to the 2246 subscriber."; 2247 leaf reason { 2248 type identityref { 2249 base establish-subscription-error; 2250 } 2251 description 2252 "Indicates the reason why the subscription has failed to 2253 be created to a targeted event stream."; 2254 } 2255 leaf filter-failure-hint { 2256 type string; 2257 description 2258 "Information describing where and/or why a provided filter 2259 was unsupportable for a subscription."; 2260 } 2261 } 2262 } 2263 rpc modify-subscription { 2264 description 2265 "This RPC allows a subscriber to modify a dynamic subscription's 2266 parameters. If successful, the changed subscription 2267 parameters remain in effect for the duration of the 2268 subscription, until the subscription is again modified, or until 2269 the subscription is terminated. In case of an error or an 2270 inability to meet the modified parameters, the subscription is 2271 not modified and the original subscription parameters remain in 2272 effect. In that case, the RPC error MAY include 'error-info' 2273 suggested parameter hints that would have a high likelihood of 2274 succeeding in a subsequent 'modify-subscription' request. A 2275 successful 'modify-subscription' will return a suspended 2276 subscription to an 'active' state."; 2277 input { 2278 leaf id { 2279 type subscription-id; 2280 mandatory true; 2281 description 2282 "Identifier to use for this subscription."; 2283 } 2284 uses subscription-policy-modifiable; 2285 } 2286 } 2288 rc:yang-data modify-subscription-stream-error-info { 2289 container modify-subscription-stream-error-info { 2290 description 2291 "This yang-data MAY be provided as part of a subscription's RPC 2292 error response when there is a failure of a 2293 'modify-subscription' RPC which has been made against an event 2294 stream. This yang-data MUST be used if hints are to be 2295 provided back to the subscriber."; 2296 leaf reason { 2297 type identityref { 2298 base modify-subscription-error; 2299 } 2300 description 2301 "Information in a 'modify-subscription' RPC error response 2302 which indicates the reason why the subscription to an event 2303 stream has failed to be modified."; 2304 } 2305 leaf filter-failure-hint { 2306 type string; 2307 description 2308 "Information describing where and/or why a provided filter 2309 was unsupportable for a subscription."; 2310 } 2312 } 2313 } 2315 rpc delete-subscription { 2316 description 2317 "This RPC allows a subscriber to delete a subscription that 2318 was previously created from by that same subscriber using the 2319 'establish-subscription' RPC. 2321 If an error occurs, the server replies with an 'rpc-error' where 2322 the 'error-info' field MAY contain an 2323 'delete-subscription-error-info' structure."; 2324 input { 2325 leaf id { 2326 type subscription-id; 2327 mandatory true; 2328 description 2329 "Identifier of the subscription that is to be deleted. 2330 Only subscriptions that were created using 2331 'establish-subscription' from the same origin as this RPC 2332 can be deleted via this RPC."; 2333 } 2334 } 2335 } 2337 rpc kill-subscription { 2338 nacm:default-deny-all; 2339 description 2340 "This RPC allows an operator to delete a dynamic subscription 2341 without restrictions on the originating subscriber or underlying 2342 transport session. 2344 If an error occurs, the server replies with an 'rpc-error' where 2345 the 'error-info' field MAY contain an 2346 'delete-subscription-error-info' structure."; 2347 input { 2348 leaf id { 2349 type subscription-id; 2350 mandatory true; 2351 description 2352 "Identifier of the subscription that is to be deleted. Only 2353 subscriptions that were created using 2354 'establish-subscription' can be deleted via this RPC."; 2355 } 2356 } 2357 } 2359 rc:yang-data delete-subscription-error-info { 2360 container delete-subscription-error-info { 2361 description 2362 "If a 'delete-subscription' RPC or a 'kill-subscription' RPC 2363 fails, the subscription is not deleted and the RPC error 2364 response MUST indicate the reason for this failure. This 2365 yang-data MAY be inserted as structured data within a 2366 subscription's RPC error response to indicate the failure 2367 reason."; 2368 leaf reason { 2369 type identityref { 2370 base delete-subscription-error; 2371 } 2372 mandatory true; 2373 description 2374 "Indicates the reason why the subscription has failed to be 2375 deleted."; 2376 } 2377 } 2378 } 2380 /* 2381 * NOTIFICATIONS 2382 */ 2384 notification replay-completed { 2385 sn:subscription-state-notification; 2386 if-feature "replay"; 2387 description 2388 "This notification is sent to indicate that all of the replay 2389 notifications have been sent. It must not be sent for any other 2390 reason."; 2391 leaf id { 2392 type subscription-id; 2393 mandatory true; 2394 description 2395 "This references the affected subscription."; 2396 } 2397 } 2399 notification subscription-completed { 2400 sn:subscription-state-notification; 2401 if-feature "configured"; 2402 description 2403 "This notification is sent to indicate that a subscription has 2404 finished passing event records, as the 'stop-time' has been 2405 reached."; 2406 leaf id { 2407 type subscription-id; 2408 mandatory true; 2409 description 2410 "This references the gracefully completed subscription."; 2411 } 2412 } 2414 notification subscription-modified { 2415 sn:subscription-state-notification; 2416 description 2417 "This notification indicates that a subscription has been 2418 modified. Notification messages sent from this point on will 2419 conform to the modified terms of the subscription. For 2420 completeness, this subscription state change notification 2421 includes both modified and non-modified aspects of a 2422 subscription."; 2423 leaf id { 2424 type subscription-id; 2425 mandatory true; 2426 description 2427 "This references the affected subscription."; 2428 } 2429 uses subscription-policy { 2430 refine "target/stream/stream-filter/within-subscription" { 2431 description 2432 "Filter applied to the subscription. If the 2433 'stream-filter-name' is populated, the filter within the 2434 subscription came from the 'filters' container. Otherwise it 2435 is populated in-line as part of the subscription."; 2436 } 2437 } 2438 } 2440 notification subscription-resumed { 2441 sn:subscription-state-notification; 2442 description 2443 "This notification indicates that a subscription that had 2444 previously been suspended has resumed. Notifications will once 2445 again be sent. In addition, a 'subscription-resumed' indicates 2446 that no modification of parameters has occurred since the last 2447 time event records have been sent."; 2448 leaf id { 2449 type subscription-id; 2450 mandatory true; 2451 description 2452 "This references the affected subscription."; 2453 } 2454 } 2455 notification subscription-started { 2456 sn:subscription-state-notification; 2457 if-feature "configured"; 2458 description 2459 "This notification indicates that a subscription has started and 2460 notifications are beginning to be sent. This notification shall 2461 only be sent to receivers of a subscription; it does not 2462 constitute a general-purpose notification."; 2463 leaf id { 2464 type subscription-id; 2465 mandatory true; 2466 description 2467 "This references the affected subscription."; 2468 } 2469 uses subscription-policy { 2470 refine "target/stream/replay-start-time" { 2471 description 2472 "Indicates the time that a replay using for the streaming of 2473 buffered event records. This will be populated with the 2474 most recent of the following: the event time of the previous 2475 event record sent to a receiver, the 2476 'replay-log-creation-time', the 'replay-log-aged-time', 2477 or the most recent publisher boot time."; 2478 } 2479 refine "target/stream/stream-filter/within-subscription" { 2480 description 2481 "Filter applied to the subscription. If the 2482 'stream-filter-name' is populated, the filter within the 2483 subscription came from the 'filters' container. Otherwise it 2484 is populated in-line as part of the subscription."; 2485 } 2486 augment "target/stream" { 2487 description 2488 "This augmentation adds additional parameters specific to a 2489 subscription-started notification."; 2490 leaf replay-previous-event-time { 2491 when "../replay-start-time"; 2492 if-feature "replay"; 2493 type yang:date-and-time; 2494 description 2495 "If there is at least one event in the replay buffer prior 2496 to 'replay-start-time', this gives the time of the event 2497 generated immediately prior to the 'replay-start-time'. 2499 If a receiver previously received event records for this 2500 configured subscription, it can compare this time to the 2501 last event record previously received. If the two are not 2502 the same (perhaps due to a reboot), then a dynamic replay 2503 can be initiated to acquire any missing event records."; 2504 } 2505 } 2506 } 2507 } 2509 notification subscription-suspended { 2510 sn:subscription-state-notification; 2511 description 2512 "This notification indicates that a suspension of the 2513 subscription by the publisher has occurred. No further 2514 notifications will be sent until the subscription resumes. 2515 This notification shall only be sent to receivers of a 2516 subscription; it does not constitute a general-purpose 2517 notification."; 2518 leaf id { 2519 type subscription-id; 2520 mandatory true; 2521 description 2522 "This references the affected subscription."; 2523 } 2524 leaf reason { 2525 type identityref { 2526 base subscription-suspended-reason; 2527 } 2528 mandatory true; 2529 description 2530 "Identifies the condition which resulted in the suspension."; 2531 } 2532 } 2534 notification subscription-terminated { 2535 sn:subscription-state-notification; 2536 description 2537 "This notification indicates that a subscription has been 2538 terminated."; 2539 leaf id { 2540 type subscription-id; 2541 mandatory true; 2542 description 2543 "This references the affected subscription."; 2544 } 2545 leaf reason { 2546 type identityref { 2547 base subscription-terminated-reason; 2548 } 2549 mandatory true; 2550 description 2551 "Identifies the condition which resulted in the termination ."; 2552 } 2553 } 2555 /* 2556 * DATA NODES 2557 */ 2559 container streams { 2560 config false; 2561 description 2562 "This container contains information on the built-in event 2563 streams provided by the publisher."; 2564 list stream { 2565 key "name"; 2566 description 2567 "Identifies the built-in event streams that are supported by 2568 the publisher."; 2569 leaf name { 2570 type string; 2571 description 2572 "A handle for a system-provided event stream made up of a 2573 sequential set of event records, each of which is 2574 characterized by its own domain and semantics."; 2575 } 2576 leaf description { 2577 type string; 2578 mandatory true; 2579 description 2580 "A description of the event stream, including such 2581 information as the type of event records that are available 2582 within this event stream."; 2583 } 2584 leaf replay-support { 2585 if-feature "replay"; 2586 type empty; 2587 description 2588 "Indicates that event record replay is available on this 2589 event stream."; 2590 } 2591 leaf replay-log-creation-time { 2592 when "../replay-support"; 2593 if-feature "replay"; 2594 type yang:date-and-time; 2595 mandatory true; 2596 description 2597 "The timestamp of the creation of the log used to support the 2598 replay function on this event stream. This time might be 2599 earlier than the earliest available information contained in 2600 the log. This object is updated if the log resets for some 2601 reason."; 2602 } 2603 leaf replay-log-aged-time { 2604 when "../replay-support"; 2605 if-feature "replay"; 2606 type yang:date-and-time; 2607 description 2608 "The timestamp associated with last event record which has 2609 been aged out of the log. This timestamp identifies how far 2610 back into history this replay log extends, if it doesn't 2611 extend back to the 'replay-log-creation-time'. This object 2612 MUST be present if replay is supported and any event records 2613 have been aged out of the log."; 2614 } 2615 } 2616 } 2618 container filters { 2619 description 2620 "This container contains a list of configurable filters 2621 that can be applied to subscriptions. This facilitates 2622 the reuse of complex filters once defined."; 2623 list stream-filter { 2624 key "name"; 2625 description 2626 "A list of pre-configured filters that can be applied to 2627 subscriptions."; 2628 leaf name { 2629 type string; 2630 description 2631 "An name to differentiate between filters."; 2632 } 2633 uses stream-filter-elements; 2634 } 2635 } 2637 container subscriptions { 2638 description 2639 "Contains the list of currently active subscriptions, i.e. 2640 subscriptions that are currently in effect, used for 2641 subscription management and monitoring purposes. This includes 2642 subscriptions that have been setup via RPC primitives as well as 2643 subscriptions that have been established via configuration."; 2644 list subscription { 2645 key "id"; 2646 description 2647 "The identity and specific parameters of a subscription. 2648 Subscriptions within this list can be created using a control 2649 channel or RPC, or be established through configuration. 2651 If configuration operations or the 'kill-subscription' RPC are 2652 used to delete a subscription, a 'subscription-terminated' 2653 message is sent to any active or suspended receivers."; 2654 leaf id { 2655 type subscription-id; 2656 description 2657 "Identifier of a subscription; unique within a publisher"; 2658 } 2659 uses subscription-policy { 2660 refine "target/stream/stream" { 2661 description 2662 "Indicates the event stream to be considered for this 2663 subscription. If an event stream has been removed, 2664 and no longer can be referenced by an active subscription, 2665 send a 'subscription-terminated' notification with 2666 'stream-unavailable' as the reason. If a configured 2667 subscription refers to a non-existent event stream, move 2668 that subscription to the 'invalid' state."; 2669 } 2670 refine "transport" { 2671 description 2672 "For a configured subscription, this leaf specifies the 2673 transport used to deliver messages destined to all 2674 receivers of that subscription. This object is mandatory 2675 for subscriptions in the configuration datastore. This 2676 object is not mandatory for dynamic subscriptions within 2677 the operational state datastore. The object should not 2678 be present for dynamic subscriptions."; 2679 } 2680 augment "target/stream" { 2681 description 2682 "Enables objects to added to a configured stream 2683 subscription"; 2684 leaf configured-replay { 2685 if-feature "configured"; 2686 if-feature "replay"; 2687 type empty; 2688 description 2689 "The presence of this leaf indicates that replay for the 2690 configured subscription should start at the earliest time 2691 in the event log, or at the publisher boot time, which 2692 ever is later."; 2693 } 2695 } 2696 } 2697 choice notification-message-origin { 2698 if-feature "configured"; 2699 description 2700 "Identifies the egress interface on the publisher from which 2701 notification messages are to be sent."; 2702 case interface-originated { 2703 description 2704 "When notification messages to egress a specific, 2705 designated interface on the publisher."; 2706 leaf source-interface { 2707 if-feature "interface-designation"; 2708 type if:interface-ref; 2709 description 2710 "References the interface for notification messages."; 2711 } 2712 } 2713 case address-originated { 2714 description 2715 "When notification messages are to depart from a publisher 2716 using specific originating address and/or routing context 2717 information."; 2718 leaf source-vrf { 2719 if-feature "supports-vrf"; 2720 type leafref { 2721 path "/ni:network-instances/ni:network-instance/ni:name"; 2722 } 2723 description 2724 "VRF from which notification messages should egress a 2725 publisher."; 2726 } 2727 leaf source-address { 2728 type inet:ip-address-no-zone; 2729 description 2730 "The source address for the notification messages. If a 2731 source VRF exists, but this object doesn't, a publisher's 2732 default address for that VRF must be used."; 2733 } 2734 } 2735 } 2736 leaf configured-subscription-state { 2737 if-feature "configured"; 2738 type enumeration { 2739 enum valid { 2740 value 1; 2741 description 2742 "Subscription is supportable with current parameters."; 2744 } 2745 enum invalid { 2746 value 2; 2747 description 2748 "The subscription as a whole is unsupportable with its 2749 current parameters."; 2750 } 2751 enum concluded { 2752 value 3; 2753 description 2754 "A subscription is inactive as it has hit a stop time, 2755 but not yet been removed from configuration."; 2756 } 2757 } 2758 config false; 2759 description 2760 "The presence of this leaf indicates that the subscription 2761 originated from configuration, not through a control channel 2762 or RPC. The value indicates the system established state 2763 of the subscription."; 2764 } 2765 container receivers { 2766 description 2767 "Set of receivers in a subscription."; 2768 list receiver { 2769 key "name"; 2770 min-elements 1; 2771 description 2772 "A host intended as a recipient for the notification 2773 messages of a subscription. For configured subscriptions, 2774 transport specific network parameters (or a leafref to 2775 those parameters) may augmentated to a specific receiver 2776 within this list."; 2777 leaf name { 2778 type string; 2779 description 2780 "Identifies a unique receiver for a subscription."; 2781 } 2782 leaf sent-event-records { 2783 type yang:zero-based-counter64; 2784 config false; 2785 description 2786 "The number of event records sent to the receiver. The 2787 count is initialized when a dynamic subscription is 2788 established, or when a configured receiver 2789 transitions to the valid state."; 2790 } 2791 leaf excluded-event-records { 2792 type yang:zero-based-counter64; 2793 config false; 2794 description 2795 "The number of event records explicitly removed either 2796 via an event stream filter or an access control filter so 2797 that they are not passed to a receiver. This count is 2798 set to zero each time 'sent-event-records' is 2799 initialized."; 2800 } 2801 leaf state { 2802 type enumeration { 2803 enum active { 2804 value 1; 2805 description 2806 "Receiver is currently being sent any applicable 2807 notification messages for the subscription."; 2808 } 2809 enum suspended { 2810 value 2; 2811 description 2812 "Receiver state is 'suspended', so the publisher 2813 is currently unable to provide notification messages 2814 for the subscription."; 2815 } 2816 enum connecting { 2817 value 3; 2818 if-feature "configured"; 2819 description 2820 "A subscription has been configured, but a 2821 'subscription-started' subscription state change 2822 notification needs to be successfully received before 2823 notification messages are sent. 2825 If the 'reset' action is invoked for a receiver of an 2826 active configured subscription, the state must be 2827 moved to 'connecting'."; 2828 } 2829 enum disconnected { 2830 value 4; 2831 if-feature "configured"; 2832 description 2833 "A subscription has failed in sending a subscription 2834 started state change to the receiver. 2835 Additional attempts at connection attempts are not 2836 currently being made."; 2837 } 2838 } 2839 config false; 2840 mandatory true; 2841 description 2842 "Specifies the state of a subscription from the 2843 perspective of a particular receiver. With this info it 2844 is possible to determine whether a subscriber is 2845 currently generating notification messages intended for 2846 that receiver."; 2847 } 2848 action reset { 2849 if-feature "configured"; 2850 description 2851 "Allows the reset of this configured subscription 2852 receiver to the 'connecting' state. This enables the 2853 connection process to be re-initiated."; 2854 output { 2855 leaf time { 2856 type yang:date-and-time; 2857 mandatory true; 2858 description 2859 "Time a publisher returned the receiver to a 2860 'connecting' state."; 2861 } 2862 } 2863 } 2864 } 2865 } 2866 } 2867 } 2868 } 2869 2871 5. Considerations 2873 5.1. IANA Considerations 2875 This document registers the following namespace URI in the "IETF XML 2876 Registry" [RFC3688]: 2878 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2879 Registrant Contact: The IESG. 2880 XML: N/A; the requested URI is an XML namespace. 2882 This document registers the following YANG module in the "YANG Module 2883 Names" registry [RFC6020]: 2885 Name: ietf-subscribed-notifications 2886 Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2887 Prefix: sn 2888 Reference: draft-ietf-netconf-ietf-subscribed-notifications-11.txt 2889 (RFC form) 2891 5.2. Implementation Considerations 2893 To support deployments including both configured and dynamic 2894 subscriptions, it is recommended to split the subscription "id" 2895 domain into static and dynamic halves. That way it eliminates the 2896 possibility of collisions if the configured subscriptions attempt to 2897 set a subscription-id which might have already been dynamically 2898 allocated. A best practice is to use lower half the "id" object's 2899 integer space when that "id" is assigned by an external entity (such 2900 as with a configured subscription). This leaves the upper half of 2901 subscription integer space available to be dynamically assigned by 2902 the publisher. 2904 If a subscription is unable to marshal a series of filtered event 2905 records into transmittable notification messages, the receiver should 2906 be suspended with the reason "unsupportable-volume". 2908 For configured subscriptions, operations are against the set of 2909 receivers using the subscription "id" as a handle for that set. But 2910 for streaming updates, subscription state change notifications are 2911 local to a receiver. In this specification it is the case that 2912 receivers get no information from the publisher about the existence 2913 of other receivers. But if a network operator wants to let the 2914 receivers correlate results, it is useful to use the subscription 2915 "id" across the receivers to allow that correlation. 2917 For configured replay subscriptions, the receiver is protected from 2918 duplicated events being pushed after a publisher is rebooted. 2919 However it is possible that a receiver might want to acquire event 2920 records which failed to be delivered just prior to the reboot. 2921 Delivering these event records be accomplished by leveraging the 2922 "eventTime" from the last event record received prior to the receipt 2923 of a "subscription-started" subscription state change notification. 2924 With this "eventTime" and the "replay-start-time" from the 2925 "subscription-started" notification, an independent dynamic 2926 subscription can be established which retrieves any event records 2927 which may have been generated but not sent to the receiver. 2929 5.3. Transport Requirements 2931 This section provides requirements for any subscribed notification 2932 transport supporting the solution presented in this document. 2934 The transport selected by the subscriber to reach the publisher MUST 2935 be able to support multiple "establish-subscription" requests made 2936 within the same transport session. 2938 For both configured and dynamic subscriptions the publisher MUST 2939 authenticate a receiver via some transport level mechanism before 2940 sending any event records for which they are authorized to see. In 2941 addition, the receiver MUST authenticate the publisher at the 2942 transport level. The result is mutual authentication between the 2943 two. 2945 A secure transport is highly recommended and the publisher MUST 2946 ensure that the receiver has sufficient authorization to perform the 2947 function they are requesting against the specific subset of content 2948 involved. 2950 A specific transport specification built upon this document may or 2951 may not choose to require the use of the same logical channel for the 2952 RPCs and the event records. However the event records and the 2953 subscription state change notifications MUST be sent on the same 2954 transport session to ensure the properly ordered delivery. 2956 Additional transport requirements will be dictated by the choice of 2957 transport used with a subscription. For an example of such 2958 requirements with NETCONF transport, see 2959 [I-D.draft-ietf-netconf-netconf-event-notifications]. 2961 5.4. Security Considerations 2963 The YANG module specified in this document defines a schema for data 2964 that is designed to be accessed via network management transports 2965 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 2966 layer is the secure transport layer, and the mandatory-to-implement 2967 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 2968 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 2969 transport is TLS [RFC5246]. 2971 The NETCONF Access Control Model (NACM) [RFC8341] provides the means 2972 to restrict access for particular NETCONF or RESTCONF users to a 2973 preconfigured subset of all available NETCONF or RESTCONF operations 2974 and content. 2976 One subscription "id" can be used for two or more receivers of the 2977 same configured subscription. But due to the possibility of 2978 different access control permissions per receiver, it cannot be 2979 assumed that each receiver is getting identical updates. 2981 With configured subscriptions, one or more publishers could be used 2982 to overwhelm a receiver. Notification messages SHOULD NOT be sent to 2983 any receiver which does not support this specification. Receivers 2984 that do not want notification messages need only terminate or refuse 2985 any transport sessions from the publisher. 2987 When a receiver of a configured subscription gets a new 2988 "subscription-started" message for a known subscription where it is 2989 already consuming events, the receiver SHOULD retrieve any event 2990 records generated since the last event record was received. This can 2991 be accomplish by establishing a separate dynamic replay subscription 2992 with the same filtering criteria with the publisher, assuming the 2993 publisher supports the "replay" feature. 2995 For dynamic subscriptions, implementations need to protect against 2996 malicious or buggy subscribers which may send a large number 2997 "establish-subscription" requests, thereby using up system resources. 2998 To cover this possibility operators SHOULD monitor for such cases 2999 and, if discovered, take remedial action to limit the resources used, 3000 such as suspending or terminating a subset of the subscriptions or, 3001 if the underlying transport is session based, terminate the 3002 underlying transport session. 3004 There are a number of data nodes defined in this YANG module that are 3005 writable/creatable/deletable (i.e., config true, which is the 3006 default). These data nodes may be considered sensitive or vulnerable 3007 in some network environments. Write operations (e.g., edit-config) 3008 to these data nodes without proper protection can have a negative 3009 effect on network operations. These are the subtrees and data nodes 3010 where there is a specific sensitivity/vulnerability: 3012 Container: "/filters" 3014 o "stream-subtree-filter": updating a filter could increase the 3015 computational complexity of all referencing subscriptions. 3017 o "stream-xpath-filter": updating a filter could increase the 3018 computational complexity of all referencing subscriptions. 3020 Container: "/subscriptions" 3022 The following considerations are only relevant for configuration 3023 operations made upon configured subscriptions: 3025 o "configured-replay": can be used to send a large number of event 3026 records to a receiver. 3028 o "dependency": can be used to force important traffic to be queued 3029 behind less important updates. 3031 o "dscp": if unvalidated, can result in the sending of traffic with 3032 a higher priority marking than warranted. 3034 o "id": can overwrite an existing subscription, perhaps one 3035 configured by another entity. 3037 o "name": adding a new key entry can be used to attempt to send 3038 traffic to an unwilling receiver. 3040 o "replay-start-time": can be used to push very large logs, wasting 3041 resources. 3043 o "source-address": the configured address might not be able to 3044 reach a desired receiver. 3046 o "source-interface": the configured interface might not be able to 3047 reach a desired receiver. 3049 o "source-vrf": can place a subscription into a virtual network 3050 where receivers are not entitled to view the subscribed content. 3052 o "stop-time": could be used to terminate content at an inopportune 3053 time. 3055 o "stream": could set a subscription to an event stream containing 3056 no content permitted for the targeted receivers. 3058 o "stream-filter-name": could be set to a filter which is irrelevant 3059 to the event stream. 3061 o "stream-subtree-filter": a complex filter can increase the 3062 computational resources for this subscription. 3064 o "stream-xpath-filter": a complex filter can increase the 3065 computational resources for this subscription. 3067 o "weighting": placing a large weight can overwhelm the dequeuing of 3068 other subscriptions. 3070 Some of the readable data nodes in this YANG module may be considered 3071 sensitive or vulnerable in some network environments. It is thus 3072 important to control read access (e.g., via get, get-config, or 3073 notification) to these data nodes. These are the subtrees and data 3074 nodes and their sensitivity/vulnerability: 3076 Container: "/streams" 3078 o "name": if access control is not properly configured, can expose 3079 system internals to those who should have no access to this 3080 information. 3082 o "replay-support": if access control is not properly configured, 3083 can expose logs to those who should have no access. 3085 Container: "/subscriptions" 3087 o "excluded-event-records": leaf can provide information about 3088 filtered event records. A network operator should have 3089 permissions to know about such filtering. 3091 o "subscription": different operational teams might have a desire to 3092 set varying subsets of subscriptions. Access control should be 3093 designed to permit read access to just the allowed set. 3095 Some of the RPC operations in this YANG module may be considered 3096 sensitive or vulnerable in some network environments. It is thus 3097 important to control access to these operations. These are the 3098 operations and their sensitivity/vulnerability: 3100 RPC: all 3102 o If a malicious or buggy subscriber sends an unexpectedly large 3103 number of RPCs, the result might be an excessive use of system 3104 resources on the publisher just to determine that these 3105 subscriptions should be declined. In such a situation, 3106 subscription interactions MAY be terminated by terminating the 3107 transport session. 3109 RPC: "delete-subscription" 3111 o No special considerations. 3113 RPC: "establish-subscription" 3115 o Subscriptions could overload a publisher's resources. For this 3116 reason, publishers MUST ensure that they have sufficient resources 3117 to fulfill this request or otherwise reject the request. 3119 RPC: "kill-subscription" 3121 o The "kill-subscription" RPC MUST be secured so that only 3122 connections with administrative rights are able to invoke this 3123 RPC. 3125 RPC: "modify-subscription" 3127 o Subscriptions could overload a publisher's resources. For this 3128 reason, publishers MUST ensure that they have sufficient resources 3129 to fulfill this request or otherwise reject the request. 3131 6. Acknowledgments 3133 For their valuable comments, discussions, and feedback, we wish to 3134 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen, 3135 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan 3136 Hares, Michael Scharf, and Guangying Zheng. 3138 7. References 3140 7.1. Normative References 3142 [I-D.draft-ietf-rtgwg-ni-model] 3143 Berger, L., Hopps, C., and A. Lindem, "YANG Network 3144 Instances", draft-ietf-rtgwg-ni-model-12 (work in 3145 progress), March 2018. 3147 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3148 Requirement Levels", BCP 14, RFC 2119, 3149 DOI 10.17487/RFC2119, March 1997, 3150 . 3152 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 3153 "Definition of the Differentiated Services Field (DS 3154 Field) in the IPv4 and IPv6 Headers", RFC 2474, 3155 DOI 10.17487/RFC2474, December 1998, 3156 . 3158 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3159 DOI 10.17487/RFC3688, January 2004, 3160 . 3162 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3163 (TLS) Protocol Version 1.2", RFC 5246, 3164 DOI 10.17487/RFC5246, August 2008, 3165 . 3167 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3168 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 3169 . 3171 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 3172 the Network Configuration Protocol (NETCONF)", RFC 6020, 3173 DOI 10.17487/RFC6020, October 2010, 3174 . 3176 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3177 and A. Bierman, Ed., "Network Configuration Protocol 3178 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 3179 . 3181 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 3182 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 3183 . 3185 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 3186 RFC 6991, DOI 10.17487/RFC6991, July 2013, 3187 . 3189 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3190 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3191 . 3193 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3194 RFC 7951, DOI 10.17487/RFC7951, August 2016, 3195 . 3197 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 3198 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 3199 . 3201 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3202 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3203 May 2017, . 3205 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 3206 Access Control Model", STD 91, RFC 8341, 3207 DOI 10.17487/RFC8341, March 2018, 3208 . 3210 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 3211 and R. Wilton, "Network Management Datastore Architecture 3212 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 3213 . 3215 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 3216 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 3217 . 3219 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 3220 Version 1.0", November 1999, 3221 . 3223 7.2. Informative References 3225 [I-D.draft-ietf-netconf-netconf-event-notifications] 3226 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3227 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 3228 event notifications", May 2018, 3229 . 3232 [I-D.draft-ietf-netconf-restconf-notif] 3233 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen- 3234 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and 3235 HTTP transport for event notifications", May 2018, 3236 . 3239 [I-D.ietf-netconf-yang-push] 3240 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3241 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 3242 Lengyel, "YANG Datastore Subscription", May 2018, 3243 . 3246 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 3247 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 3248 DOI 10.17487/RFC7540, May 2015, 3249 . 3251 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 3252 for Subscription to YANG Datastores", RFC 7923, 3253 DOI 10.17487/RFC7923, June 2016, 3254 . 3256 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 3257 RFC 8071, DOI 10.17487/RFC8071, February 2017, 3258 . 3260 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3261 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3262 . 3264 Appendix A. Example Configured Transport Augmentation 3266 This appendix provides a non-normative example of how the YANG model 3267 defined in Section 4 may be enhanced to incorporate the configuration 3268 parameters needed to support the transport connectivity process. In 3269 this example, connectivity via an imaginary transport type of "foo" 3270 is explored. For more on the overall need, see Section 2.5.7. 3272 The YANG model defined in this section contains two main elements. 3273 First is a transport identity "foo". This transport identity allows 3274 a configuration agent to define "foo" as the selected type of 3275 transport for a subscription. Second is a YANG case augmentation 3276 "foo" which is made to the "/subscriptions/subscription/receivers/ 3277 receiver" node of Section 4. Within this augmentation are the 3278 transport configuration parameters "address" and "port" which are 3279 necessary to make the connect to the receiver. 3281 module example-foo-subscribed-notifications { 3282 yang-version 1.1; 3283 namespace 3284 "urn:example:foo-subscribed-notifications"; 3286 prefix fsn; 3288 import ietf-subscribed-notifications { 3289 prefix sn; 3290 } 3291 import ietf-inet-types { 3292 prefix inet; 3293 } 3295 description 3296 "Defines 'foo' as a supported type of configured transport for 3297 subscribed event notifications."; 3299 identity foo { 3300 base sn:transport; 3301 description 3302 "Transport type 'foo' is available for use as a configured 3303 subscription transport protocol for subscribed notifications."; 3304 } 3306 augment 3307 "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { 3308 when 'derived-from(../../../transport, "fsn:foo")'; 3309 description 3310 "This augmentation makes 'foo' specific transport parameters 3311 available for a receiver."; 3313 leaf address { 3314 type inet:host; 3315 mandatory true; 3316 description 3317 "Specifies the address to use for messages destined to a 3318 receiver."; 3319 } 3320 leaf port { 3321 type inet:port-number; 3322 mandatory true; 3323 description 3324 "Specifies the port number to use for messages destined to a 3325 receiver."; 3326 } 3327 } 3328 } 3330 Figure 21: Example Transport Augmentation for the fictitious protocol 3331 foo 3333 This example YANG model for transport "foo" will not be seen in a 3334 real world deployment. For a real world deployment supporting an 3335 actual transport technology, a similar YANG model must be defined. 3337 Appendix B. Changes between revisions 3339 (To be removed by RFC editor prior to publication) 3341 v18 - v19 3343 o XPath-stream-filter YANG object definition updated based on NETMOD 3344 discussions. 3346 v17 - v18 3348 o Transport optional in YANG model. 3350 o Modify subscription must come from the originator of the 3351 subscription. (Text got dropped somewhere previously.) 3353 o Title change. 3355 v16 - v17 3357 o YANG renaming: Subscription identifier renamed to id. Counters 3358 renamed. Filters id made into name. 3360 o Text tweaks. 3362 v15 - v16 3364 o Mandatory empty case "transport" removed. 3366 o Appendix case turned from "netconf" to "foo". 3368 v14 - v15 3370 o Text tweaks. 3372 o Mandatory empty case "transport" added for transport parameters. 3373 This includes a new section and an appendix explaining it. 3375 v13 - v14 3377 o Removed the 'address' leaf. 3379 o Replay is now of type 'empty' for configured. 3381 v12 - v13 3383 o Tweaks from Kent's comments 3385 o Referenced in YANG model updated per Tom Petch's comments 3387 o Added leaf replay-previous-event-time 3389 o Renamed the event counters, downshifted the subscription states 3391 v11 - v12 3393 o Tweaks from Kent's, Tim's, and Martin's comments 3395 o Clarified dscp text, and made its own feature 3397 o YANG model tweaks alphabetizing, features. 3399 v10 - v11 3401 o access control filtering of events in streams included to match 3402 RFC5277 behavior 3404 o security considerations updated based on YANG template. 3406 o dependency QoS made non-normative on HTTP2 QoS 3408 o tree diagrams referenced for each figure using them 3409 o reference numbers placed into state machine figures 3411 o broke configured replay into its own section 3413 o many tweaks updates based on LC and YANG doctor reviews 3415 o trees and YANG model reconciled were deltas existed 3417 o new feature for interface originated. 3419 o dscp removed from the qos feature 3421 o YANG model updated in a way which collapses groups only used once 3422 so that they are part of the 'subscriptions' container. 3424 o alternative encodings only allowed for transports which support 3425 them. 3427 v09 - v10 3429 o Typos and tweaks 3431 v08 - v09 3433 o NMDA model supported. Non NMDA version at https://github.com/ 3434 netconf-wg/rfc5277bis/ 3436 o Error mechanism revamped to match to embedded implementations. 3438 o Explicitly identified error codes relevant to each RPC/ 3439 Notification 3441 v07 - v08 3443 o Split YANG trees to separate document subsections. 3445 o Clarified configured state machine based on Balazs comments, and 3446 moved it into the configured subscription subsections. 3448 o Normative reference to Network Instance model for VRF 3450 o One transport for all receivers of configured subscriptions. 3452 o QoS section moved in from yang-push 3454 v06 - v07 3456 o Clarification on state machine for configured subscriptions. 3458 v05 - v06 3460 o Made changes proposed by Martin, Kent, and others on the list. 3461 Most significant of these are stream returned to string (with the 3462 SYSLOG identity removed), intro section on 5277 relationship, an 3463 identity set moved to an enumeration, clean up of definitions/ 3464 terminology, state machine proposed for configured subscriptions 3465 with a clean-up of subscription state options. 3467 o JSON and XML become features. Also Xpath and subtree filtering 3468 become features 3470 o Terminology updates with event records, and refinement of filters 3471 to just event stream filters. 3473 o Encoding refined in establish-subscription so it takes the RPC's 3474 encoding as the default. 3476 o Namespaces in examples fixed. 3478 v04 - v05 3480 o Returned to the explicit filter subtyping of v00 3482 o stream object changed to 'name' from 'stream' 3484 o Cleaned up examples 3486 o Clarified that JSON support needs notification-messages draft. 3488 v03 - v04 3490 o Moved back to the use of RFC5277 one-way notifications and 3491 encodings. 3493 v03 - v04 3495 o Replay updated 3497 v02 - v03 3499 o RPCs and Notification support is identified by the Notification 3500 2.0 capability. 3502 o Updates to filtering identities and text 3504 o New error type for unsupportable volume of updates 3505 o Text tweaks. 3507 v01 - v02 3509 o Subscription status moved under receiver. 3511 v00 - v01 3513 o Security considerations updated 3515 o Intro rewrite, as well as scattered text changes 3517 o Added Appendix A, to help match this to related drafts in progress 3519 o Updated filtering definitions, and filter types in yang file, and 3520 moved to identities for filter types 3522 o Added Syslog as an event stream 3524 o HTTP2 moved in from YANG-Push as a transport option 3526 o Replay made an optional feature for events. Won't apply to 3527 datastores 3529 o Enabled notification timestamp to have different formats. 3531 o Two error codes added. 3533 v01 5277bis - v00 subscribed notifications 3535 o Kill subscription RPC added. 3537 o Renamed from 5277bis to Subscribed Notifications. 3539 o Changed the notification capabilities version from 1.1 to 2.0. 3541 o Extracted create-subscription and other elements of RFC5277. 3543 o Error conditions added, and made specific in return codes. 3545 o Simplified yang model structure for removal of 'basic' grouping. 3547 o Added a grouping for items which cannot be statically configured. 3549 o Operational counters per receiver. 3551 o Subscription-id and filter-id renamed to identifier 3552 o Section for replay added. Replay now cannot be configured. 3554 o Control plane notification renamed to subscription state change 3555 notification 3557 o Source address: Source-vrf changed to string, default address 3558 option added 3560 o In yang model: 'info' changed to 'policy' 3562 o Scattered text clarifications 3564 v00 - v01 of 5277bis 3566 o YANG Model changes. New groupings for subscription info to allow 3567 restriction of what is changeable via RPC. Removed notifications 3568 for adding and removing receivers of configured subscriptions. 3570 o Expanded/renamed definitions from event server to publisher, and 3571 client to subscriber as applicable. Updated the definitions to 3572 include and expand on RFC 5277. 3574 o Removal of redundancy with other drafts 3576 o Many other clean-ups of wording and terminology 3578 Authors' Addresses 3580 Eric Voit 3581 Cisco Systems 3583 Email: evoit@cisco.com 3585 Alexander Clemm 3586 Huawei 3588 Email: ludwig@clemm.org 3590 Alberto Gonzalez Prieto 3591 Microsoft 3593 Email: alberto.gonzalez@microsoft.com 3594 Einar Nilsen-Nygaard 3595 Cisco Systems 3597 Email: einarnn@cisco.com 3599 Ambika Prasad Tripathy 3600 Cisco Systems 3602 Email: ambtripa@cisco.com