idnits 2.17.1 draft-ietf-netconf-subscribed-notifications-17.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 1304 has weird spacing: '... reason ide...' == Line 1339 has weird spacing: '... reason ide...' == Line 1355 has weird spacing: '...--ro id sub...' == Line 1370 has weird spacing: '...--ro id sub...' == Line 1391 has weird spacing: '...--ro id sub...' == (3 more instances...) -- The document date (September 28, 2018) is 2027 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF E. Voit 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track A. Clemm 5 Expires: April 1, 2019 Huawei 6 A. Gonzalez Prieto 7 Microsoft 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 September 28, 2018 13 Customized Subscriptions to a Publisher's Event Streams 14 draft-ietf-netconf-subscribed-notifications-17 16 Abstract 18 This document defines a YANG data model and associated mechanisms 19 enabling subscriber-specific subscriptions to a publisher's event 20 streams. Applying these elements allows a subscriber to request for 21 and receive a continuous, custom feed of publisher generated 22 information. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on April 1, 2019. 41 Copyright Notice 43 Copyright (c) 2018 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.3. Solution Overview . . . . . . . . . . . . . . . . . . . . 5 62 1.4. Relationship to RFC 5277 . . . . . . . . . . . . . . . . 6 63 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 7 65 2.2. Event Stream Filters . . . . . . . . . . . . . . . . . . 7 66 2.3. QoS . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 2.4. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 9 68 2.5. Configured Subscriptions . . . . . . . . . . . . . . . . 17 69 2.6. Event Record Delivery . . . . . . . . . . . . . . . . . . 24 70 2.7. subscription state change notifications . . . . . . . . . 25 71 2.8. Subscription Monitoring . . . . . . . . . . . . . . . . . 31 72 2.9. Advertisement . . . . . . . . . . . . . . . . . . . . . . 32 73 3. YANG Data Model Trees . . . . . . . . . . . . . . . . . . . . 32 74 3.1. Event Streams Container . . . . . . . . . . . . . . . . . 32 75 3.2. Filters Container . . . . . . . . . . . . . . . . . . . . 33 76 3.3. Subscriptions Container . . . . . . . . . . . . . . . . . 33 77 4. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 35 78 5. Considerations . . . . . . . . . . . . . . . . . . . . . . . 62 79 5.1. IANA Considerations . . . . . . . . . . . . . . . . . . . 62 80 5.2. Implementation Considerations . . . . . . . . . . . . . . 62 81 5.3. Transport Requirements . . . . . . . . . . . . . . . . . 63 82 5.4. Security Considerations . . . . . . . . . . . . . . . . . 64 83 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 67 84 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 67 85 7.1. Normative References . . . . . . . . . . . . . . . . . . 67 86 7.2. Informative References . . . . . . . . . . . . . . . . . 69 87 Appendix A. Example Configured Transport Augmentation . . . . . 70 88 Appendix B. Changes between revisions . . . . . . . . . . . . . 72 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 76 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. If the publisher accepts the requested 585 modifications, it acknowledges success to the subscriber, then 586 immediately starts sending event records based on the new terms. 588 Subscriptions created by configuration cannot be modified via this 589 RPC. However configuration may be used to modify objects referenced 590 by the subscription (such as a referenced filter). 592 Below is a tree diagram for "modify-subscription". All objects 593 contained in this tree are described within the included YANG model 594 within Section 4. 596 +---x modify-subscription 597 +---w input 598 +---w id 599 | subscription-id 600 +---w (target) 601 | +--:(stream) 602 | +---w (stream-filter)? 603 | +--:(by-reference) 604 | | +---w stream-filter-name 605 | | stream-filter-ref 606 | +--:(within-subscription) 607 | +---w (filter-spec)? 608 | +--:(stream-subtree-filter) 609 | | +---w stream-subtree-filter? 610 | | {subtree}? 611 | +--:(stream-xpath-filter) 612 | +---w stream-xpath-filter? 613 | yang:xpath1.0 {xpath}? 614 +---w stop-time? 615 yang:date-and-time 617 Figure 4: modify-subscription RPC tree diagram 619 If the publisher accepts the requested modifications on a currently 620 suspended subscription, the subscription will immediately be resumed 621 (i.e., the modified subscription is returned to the active state.) 622 The publisher MAY immediately suspend this newly modified 623 subscription through the "subscription-suspended" notification before 624 any event records are sent. 626 If the publisher rejects the RPC request, the subscription remains as 627 prior to the request. That is, the request has no impact whatsoever. 628 Rejection of the RPC for any reason is indicated by via RPC error as 629 described in Section 2.4.6. The contents of such a rejected RPC MAY 630 include hints on inputs which (if considered) may result in a 631 successfully modified subscription. These hints MUST be transported 632 within a yang-data "modify-subscription-stream-error-info" container 633 inserted into the RPC error response. 635 Below is a tree diagram for "modify-subscription-RPC-yang-data". All 636 objects contained in this tree are described within the included YANG 637 model within Section 4. 639 yang-data modify-subscription-stream-error-info 640 +--ro modify-subscription-stream-error-info 641 +--ro reason? identityref 642 +--ro filter-failure-hint? string 644 Figure 5: modify-subscription RPC yang-data tree diagram 646 2.4.4. Deleting a Dynamic Subscription 648 The "delete-subscription" operation permits canceling an existing 649 subscription. If the publisher accepts the request, and the 650 publisher has indicated success, the publisher MUST NOT send any more 651 notification messages for this subscription. If the delete request 652 matches a known subscription established on the same transport 653 session, then it MUST be deleted; otherwise it MUST be rejected with 654 no changes to the publisher. 656 Below is a tree diagram for "delete-subscription". All objects 657 contained in this tree are described within the included YANG model 658 within Section 4. 660 +---x delete-subscription 661 +---w input 662 +---w id subscription-id 664 Figure 6: delete-subscription RPC tree diagram 666 Dynamic subscriptions can only be deleted via this RPC using a 667 transport session connecting to the subscriber. Configured 668 subscriptions cannot be deleted using RPCs. 670 2.4.5. Killing a Dynamic Subscription 672 The "kill-subscription" operation permits an operator to end a 673 dynamic subscription which is not associated with the transport 674 session used for the RPC. A publisher MUST terminate any dynamic 675 subscription identified by the "id" parameter in the RPC request, if 676 such a subscription exists. 678 Configured subscriptions cannot be killed using this RPC. Instead, 679 configured subscriptions are deleted as part of regular configuration 680 operations. Publishers MUST reject any RPC attempt to kill a 681 configured subscription. 683 Below is a tree diagram for "kill-subscription". All objects 684 contained in this tree are described within the included YANG model 685 within Section 4. 687 +---x kill-subscription 688 +---w input 689 +---w id subscription-id 691 Figure 7: kill-subscription RPC tree diagram 693 2.4.6. RPC Failures 695 Whenever an RPC is unsuccessful, the publisher returns relevant 696 information as part of the RPC error response. Transport level error 697 processing MUST be done before RPC error processing described in this 698 section. In all cases, RPC error information returned will use 699 existing transport layer RPC structures, such as those seen with 700 NETCONF in [RFC6241] Appendix A, or with RESTCONF in [RFC8040] 701 Section 7.1. These structures MUST be able to encode subscription 702 specific errors identified below and defined within this document's 703 YANG model. 705 As a result of this mixture, how subscription errors are encoded 706 within an RPC error response is transport dependent. Following are 707 valid errors which can occur for each RPC: 709 establish-subscription modify-subscription 710 ---------------------- ------------------- 711 dscp-unavailable filter-unsupported 712 encoding-unsupported insufficient-resources 713 filter-unsupported no-such-subscription 714 insufficient-resources 715 replay-unsupported 717 delete-subscription kill-subscription 718 ---------------------- ---------------------- 719 no-such-subscription no-such-subscription 721 To see a NETCONF based example of an error response from above, see 722 [I-D.draft-ietf-netconf-netconf-event-notifications], Figure 10. 724 There is one final set of transport independent RPC error elements 725 included in the YANG model. These are three yang-data structures 726 which enable the publisher to provide to the receiver that error 727 information which does not fit into existing transport layer RPC 728 structures. These three yang-data structures are: 730 1. "establish-subscription-stream-error-info": This MUST be returned 731 with the leaf "reason" populated if an RPC error reason has not 732 been placed elsewhere within the transport portion of a failed 733 "establish-subscription" RPC response. This MUST be sent if 734 hints on how to overcome the RPC error are included. 736 2. "modify-subscription-stream-error-info": This MUST be returned 737 with the leaf "reason" populated if an RPC error reason has not 738 been placed elsewhere within the transport portion of a failed 739 "modify-subscription" RPC response. This MUST be sent if hints 740 on how to overcome the RPC error are included. 742 3. "delete-subscription-error-info": This MUST be returned with the 743 leaf "reason" populated if an RPC error reason has not been 744 placed elsewhere within the transport portion of a failed 745 "delete-subscription" or "kill-subscription" RPC response. 747 2.5. Configured Subscriptions 749 A configured subscription is a subscription installed via 750 configuration. Configured subscriptions may be modified by any 751 configuration client with the proper permissions. Subscriptions can 752 be modified or terminated via configuration at any point of their 753 lifetime. Multiple configured subscriptions MUST be supportable over 754 a single transport session. 756 Configured subscriptions have several characteristics distinguishing 757 them from dynamic subscriptions: 759 o persistence across publisher reboots, 761 o persistence even when transport is unavailable, and 763 o an ability to send notification messages to more than one receiver 764 (note that receivers are unaware of the existence of any other 765 receivers.) 767 On the publisher, supporting configured subscriptions is optional and 768 advertised using the "configured" feature. On a receiver of a 769 configured subscription, support for dynamic subscriptions is 770 optional except where replaying missed event records is required. 772 In addition to the subscription parameters available to dynamic 773 subscriptions described in Section 2.4.2, the following additional 774 parameters are also available to configured subscriptions: 776 o A "transport" which identifies the transport protocol to use to 777 connect with all subscription receivers. 779 o One or more receivers, each intended as the destination for event 780 records. Note that each individual receiver is identifiable by 781 its "name". 783 o Optional parameters to identify where traffic should egress a 784 publisher: 786 * A "source-interface" which identifies the egress interface to 787 use from the publisher. Publisher support for this is optional 788 and advertised using the "interface-designation" feature. 790 * A "source-address" address, which identifies the IP address to 791 stamp on notification messages destined for the receiver. 793 * A "source-vrf" which identifies the VRF on which to reach 794 receivers. This VRF is a network instance as defined within 795 [I-D.draft-ietf-rtgwg-ni-model]. Publisher support for VRFs is 796 optional and advertised using the "supports-vrf" feature. 798 If none of the above parameters are set, notification messages 799 MUST egress the publisher's default interface. 801 A tree diagram describing these parameters is shown in Figure 20 802 within Section 3.3. All parameters are described within the YANG 803 model in Section 4. 805 2.5.1. Configured Subscription State Model 807 Below is the state machine for a configured subscription on the 808 publisher. This state machine describes the three states (valid, 809 invalid, and concluded), as well as the transitions between these 810 states. Start and end states are depicted to reflect configured 811 subscription creation and deletion events. The creation or 812 modification of a configured subscription initiates an evaluation by 813 the publisher to determine if the subscription is in valid or invalid 814 states. The publisher uses its own criteria in making this 815 determination. If in the valid state, the subscription becomes 816 operational. See (1) in the diagram below. 818 ......... 819 : start :-. 820 :.......: | 821 create .---modify-----.----------------------------------. 822 | | | | 823 V V .-------. ....... .---------. 824 .----[evaluate]--no--->|invalid|-delete->: end :<-delete-|concluded| 825 | '-------' :.....: '---------' 826 |-[evaluate]--no-(2). ^ ^ ^ 827 | ^ | | | | 828 yes | '->unsupportable delete stop-time 829 | modify (subscription- (subscription- (subscription- 830 | | terminated*) terminated*) concluded*) 831 | | | | | 832 (1) | (3) (4) (5) 833 | .---------------------------------------------------------------. 834 '-->| valid | 835 '---------------------------------------------------------------' 837 Legend: 838 dotted boxes: subscription added or removed via configuration 839 dashed boxes: states for a subscription 840 [evaluate]: decision point on whether the subscription is supportable 841 (*): resulting subscription state change notification 843 Figure 8: Publisher state model for a configured subscription 845 A subscription in the valid state may move to the invalid state in 846 one of two ways. First, it may be modified in a way which fails a 847 re-evaluation. See (2) in the diagram. Second, the publisher might 848 determine that the subscription is no longer supportable. This could 849 be for reasons of an unexpected but sustained increase in an event 850 stream's event records, degraded CPU capacity, a more complex 851 referenced filter, or other higher priority subscriptions which have 852 usurped resources. See (3) in the diagram. No matter the case, a 853 "subscription-terminated" notification is sent to any receivers in an 854 active or suspended state. A subscription in the valid state may 855 also transition to the concluded state via (5) if a configured stop 856 time has been reached. In this case, a "subscription-concluded" 857 notification is sent to any receivers in active or suspended states. 858 Finally, a subscription may be deleted by configuration (4). 860 When a subscription is in the valid state, a publisher will attempt 861 to connect with all receivers of a configured subscription and 862 deliver notification messages. Below is the state machine for each 863 receiver of a configured subscription. This receiver state machine 864 is fully contained within the state machine of the configured 865 subscription, and is only relevant when the configured subscription 866 is in the valid state. 868 .-----------------------------------------------------------------. 869 | valid | 870 | .----------. .------------. | 871 | | receiver |---timeout---------------->| receiver | | 872 | |connecting|<----------------reset--(c)|disconnected| | 873 | | |<-transport '------------' | 874 | '----------' loss,reset------------------------------. | 875 | (a) | | | 876 | subscription- (b) (b) | 877 | started* .--------. .---------. | 878 | '----->| |(d)-insufficient CPU,------->| | | 879 | |receiver| buffer overflow |receiver | | 880 | subscription-| active | |suspended| | 881 | modified* | |<----CPU, b/w sufficient,-(e)| | | 882 | '---->'--------' subscription-modified* '---------' | 883 '-----------------------------------------------------------------' 885 Legend: 886 dashed boxes which include the word 'receiver' show the possible 887 states for an individual receiver of a valid configured subscription. 888 * indicates a subscription state change notification 890 Figure 9: Receiver state for a configured subscription on a Publisher 892 When a configured subscription first moves to the valid state, the 893 "state" leaf of each receiver is initialized to the connecting state. 894 If transport connectivity is not available to any receiver and there 895 are any notification messages to deliver, a transport session is 896 established (e.g., through [RFC8071]). Individual receivers are 897 moved to the active state when a "subscription-started" subscription 898 state change notification is successfully passed to that receiver 899 (a). Event records are only sent to active receivers. Receivers of 900 a configured subscription remain active if both transport 901 connectivity can be verified to the receiver, and event records are 902 not being dropped due to a publisher buffer overflow. The result is 903 that a receiver will remain active on the publisher as long as events 904 aren't being lost, or the receiver cannot be reached. In addition, a 905 configured subscription's receiver MUST be moved to the connecting 906 state if the receiver is reset via the "reset" action (b), (c). For 907 more on reset, see Section 2.5.5. If transport connectivity cannot 908 be achieved while in the connecting state, the receiver MAY be moved 909 to the disconnected state. 911 A configured subscription's receiver MUST be moved to the suspended 912 state if there is transport connectivity between the publisher and 913 receiver, but notification messages are failing to be delivered due 914 to publisher buffer overflow, or notification messages are not able 915 to be generated for that receiver due to insufficient CPU (d). This 916 is indicated to the receiver by the "subscription-suspended" 917 subscription state change notification. 919 A configured subscription receiver MUST be returned to the active 920 state from the suspended state when notification messages are able to 921 be generated, bandwidth is sufficient to handle the notification 922 messages, and a receiver has successfully been sent a "subscription- 923 resumed" or "subscription-modified" subscription state change 924 notification (e). The choice as to which of these two subscription 925 state change notifications is sent is determined by whether the 926 subscription was modified during the period of suspension. 928 Modification of a configured subscription is possible at any time. A 929 "subscription-modified" subscription state change notification will 930 be sent to all active receivers, immediately followed by notification 931 messages conforming to the new parameters. Suspended receivers will 932 also be informed of the modification. However this notification will 933 await the end of the suspension for that receiver (e). 935 The mechanisms described above are mirrored in the RPCs and 936 notifications within the document. It should be noted that these 937 RPCs and notifications have been designed to be extensible and allow 938 subscriptions into targets other than event streams. For instance, 939 the YANG module defined in Section 5 of [I-D.ietf-netconf-yang-push] 940 augments "/sn:modify-subscription/sn:input/sn:target". 942 2.5.2. Creating a Configured Subscription 944 Configured subscriptions are established using configuration 945 operations against the top-level "subscriptions" subtree. 947 Because there is no explicit association with an existing transport 948 session, configuration operations MUST include additional parameters 949 beyond those of dynamic subscriptions. These parameters identify 950 each receiver, how to connect with that receiver, and possibly 951 whether the notification messages need to come from a specific egress 952 interface on the publisher. Receiver specific transport connectivity 953 parameters MUST be configured via transport specific augmentations to 954 this specification. See Section 2.5.7 for details. 956 After a subscription is successfully established, the publisher 957 immediately sends a "subscription-started" subscription state change 958 notification to each receiver. It is quite possible that upon 959 configuration, reboot, or even steady-state operations, a transport 960 session may not be currently available to the receiver. In this 961 case, when there is something to transport for an active 962 subscription, transport specific call-home operations will be used to 963 establish the connection. When transport connectivity is available, 964 notification messages may then be pushed. 966 With active configured subscriptions, it is allowable to buffer event 967 records even after a "subscription-started" has been sent. However 968 if events are lost (rather than just delayed) due to replay buffer 969 overflow, a new "subscription-started" must be sent. This new 970 "subscription-started" indicates an event record discontinuity. 972 To see an example of subscription creation using configuration 973 operations over NETCONF, see Appendix A of 974 [I-D.draft-ietf-netconf-netconf-event-notifications]. 976 2.5.3. Modifying a Configured Subscription 978 Configured subscriptions can be modified using configuration 979 operations against the top-level "subscriptions" subtree. 981 If the modification involves adding receivers, added receivers are 982 placed in the connecting state. If a receiver is removed, the 983 subscription state change notification "subscription-terminated" is 984 sent to that receiver if that receiver is active or suspended. 986 If the modification involves changing the policies for the 987 subscription, the publisher sends to currently active receivers a 988 "subscription-modified" notification. For any suspended receivers, a 989 "subscription-modified" notification will be delayed until the 990 receiver is resumed. (Note: in this case, the "subscription- 991 modified" notification informs the receiver that the subscription has 992 been resumed, so no additional "subscription-resumed" need be sent. 993 Also note that if multiple modifications have occurred during the 994 suspension, only the "subscription-modified" notification describing 995 the latest one need be sent to the receiver.) 997 2.5.4. Deleting a Configured Subscription 999 Subscriptions can be deleted through configuration against the top- 1000 level "subscriptions" subtree. 1002 Immediately after a subscription is successfully deleted, the 1003 publisher sends to all receivers of that subscription a subscription 1004 state change notification stating the subscription has ended (i.e., 1005 "subscription-terminated"). 1007 2.5.5. Resetting a Configured Subscription Receiver 1009 It is possible that a configured subscription to a receiver needs to 1010 be reset. This is accomplished via the "reset" action within the 1011 YANG model at "/subscriptions/subscription/receivers/receiver/reset". 1012 This action may be useful in cases where a publisher has timed out 1013 trying to reach a receiver. When such a reset occurs, a transport 1014 session will be initiated if necessary, and a new "subscription- 1015 started" notification will be sent. This action does not have any 1016 effect on transport connectivity if the needed connectivity already 1017 exists. 1019 2.5.6. Replay for a Configured Subscription 1021 It is possible to do replay on a configured subscription. This is 1022 supported via the configuration of the "configured-replay" object on 1023 the subscription. The setting of this object enables the streaming 1024 of the buffered event records for the subscribed event stream. All 1025 buffered event records which have been retained since the last 1026 publisher restart will be sent to each configured receiver. 1028 Replay of events records created since restart is useful. It allows 1029 event records generated before transport connectivity establishment 1030 to be passed to a receiver. Setting the restart time as the earliest 1031 configured replay time precludes possibility of resending of event 1032 records logged prior to publisher restart. It also ensures the same 1033 records will be sent to each configured receiver, regardless of the 1034 speed of transport connectivity establishment to each receiver. 1035 Finally, establishing restart as the earliest potential time for 1036 event records to be included within notification messages, a well- 1037 understood timeframe for replay is defined. 1039 As a result, when any configured subscription receivers become 1040 active, buffered event records will be sent immediately after the 1041 "subscription-started" notification. If the publisher knows the last 1042 event record sent to a receiver, and the publisher has not rebooted, 1043 the next event record on the event stream which meets filtering 1044 criteria will be the leading event record sent. Otherwise, the 1045 leading event record will be the first event record meeting filtering 1046 criteria subsequent to the latest of three different times: the 1047 "replay-log-creation-time", "replay-log-aged-time", or the most 1048 recent publisher boot time. The "replay-log-creation-time" and 1049 "replay-log-aged-time" are discussed in Section 2.4.2.1. The most 1050 recent publisher boot time ensures that duplicate event records are 1051 not replayed from a previous time the publisher was booted. 1053 It is quite possible that a receiver might want to retrieve event 1054 records from an event stream prior to the latest boot. If such 1055 records exist where there is a configured replay, the publisher MUST 1056 send the time of the event record immediately preceding the "replay- 1057 start-time" within the "replay-previous-event-time" leaf. Through 1058 the existence of the "replay-previous-event-time", the receiver will 1059 know that earlier events prior to reboot exist. In addition, if the 1060 subscriber was previously receiving event records with the same 1061 subscription "id", the receiver can determine if there was a timegap 1062 where records generated on the publisher were not successully 1063 received. And with this information, the receiver may choose to 1064 dynamically subscribe to retrieve any event records placed into the 1065 event stream before the most recent boot time. 1067 All other replay functionality remains the same as with dynamic 1068 subscriptions as described in Section 2.4.2.1. 1070 2.5.7. Transport Connectivity for a Configured Subscription 1072 This specification is transport independent. However supporting a 1073 configured subscription will often require the establishment of 1074 transport connectivity. And the parameters used for this transport 1075 connectivity establishment are transport specific. As a result, the 1076 YANG model defined within Section 4 is not able to directly define 1077 and expose these transport parameters. 1079 It is necessary for an implementation to support the connection 1080 establishment process. To support this function, the YANG model does 1081 include a node where transport specific parameters for a particular 1082 receiver may be augmented. This node is 1083 "/subscriptions/subscription/receivers/receiver". By augmenting 1084 transport parameters from this node, system developers are able to 1085 incorporate the YANG objects necessary to support the transport 1086 connectivity establishment process. 1088 The result of this is the following requirement. A publisher 1089 supporting the feature "configured" MUST also support least one YANG 1090 model which augments transport connectivity parameters on 1091 "/subscriptions/subscription/receivers/receiver". For an example of 1092 such an augmentation, see Appendix A. 1094 2.6. Event Record Delivery 1096 Whether dynamic or configured, once a subscription has been set up, 1097 the publisher streams event records via notification messages per the 1098 terms of the subscription. For dynamic subscriptions, notification 1099 messages are sent over the session used to establish the 1100 subscription. For configured subscriptions, notification messages 1101 are sent over the connections specified by the transport and each 1102 receiver of a configured subscription. 1104 A notification message is sent to a receiver when an event record is 1105 not blocked by either the specified filter criteria or receiver 1106 permissions. This notification message MUST include an "eventTime" 1107 object as defined per [RFC5277] Section 4. This "eventTime" MUST be 1108 at the top level of YANG structured event record. 1110 The following example within [RFC7950] section 7.16.3 is an example 1111 of a compliant message: 1113 1115 2007-09-01T10:00:00Z 1116 1117 so-1/2/3.0 1118 up 1119 down 1120 1121 1123 Figure 10: subscribed notification message 1125 When a dynamic subscription has been started or modified, with 1126 "establish-subscription" or "modify-subscription" respectively, event 1127 records matching the newly applied filter criteria MUST NOT be sent 1128 until after the RPC reply has been sent. 1130 When a configured subscription has been started or modified, event 1131 records matching the newly applied filter criteria MUST NOT be sent 1132 until after the "subscription-started" or "subscription-modified" 1133 notifications has been sent, respectively. 1135 2.7. subscription state change notifications 1137 In addition to sending event records to receivers, a publisher MUST 1138 also send subscription state change notifications when events related 1139 to subscription management have occurred. 1141 subscription state change notifications are unlike other 1142 notifications in that they are never included in any event stream. 1143 Instead, they are inserted (as defined in this section) within the 1144 sequence of notification messages sent to a particular receiver. 1145 subscription state change notifications cannot be filtered out, they 1146 cannot be stored in replay buffers, and they are delivered only to 1147 impacted receivers of a subscription. The identification of 1148 subscription state change notifications is easy to separate from 1149 other notification messages through the use of the YANG extension 1150 "subscription-state-notif". This extension tags a notification as a 1151 subscription state change notification. 1153 The complete set of subscription state change notifications is 1154 described in the following subsections. 1156 2.7.1. subscription-started 1158 This notification indicates that a configured subscription has 1159 started, and event records may be sent. Included in this 1160 subscription state change notification are all the parameters of the 1161 subscription, except for the receiver(s) transport connection 1162 information and origin information indicating where notification 1163 messages will egress the publisher. Note that if a referenced filter 1164 from the "filters" container has been used within the subscription, 1165 the notification still provides the contents of that referenced 1166 filter under the "within-subscription" subtree. 1168 Note that for dynamic subscriptions, no "subscription-started" 1169 notifications are ever sent. 1171 Below is a tree diagram for "subscription-started". All objects 1172 contained in this tree are described within the included YANG model 1173 within Section 4. 1175 +---n subscription-started {configured}? 1176 +--ro id 1177 | subscription-id 1178 +--ro (target) 1179 | +--:(stream) 1180 | +--ro (stream-filter)? 1181 | | +--:(by-reference) 1182 | | | +--ro stream-filter-name 1183 | | | stream-filter-ref 1184 | | +--:(within-subscription) 1185 | | +--ro (filter-spec)? 1186 | | +--:(stream-subtree-filter) 1187 | | | +--ro stream-subtree-filter? 1188 | | | {subtree}? 1189 | | +--:(stream-xpath-filter) 1190 | | +--ro stream-xpath-filter? yang:xpath1.0 1191 | | {xpath}? 1192 | +--ro stream stream-ref 1193 | +--ro replay-start-time? 1194 | | yang:date-and-time {replay}? 1195 | +--ro replay-previous-event-time? 1196 | yang:date-and-time {replay}? 1197 +--ro stop-time? 1198 | yang:date-and-time 1199 +--ro dscp? inet:dscp 1200 | {dscp}? 1201 +--ro weighting? uint8 {qos}? 1202 +--ro dependency? 1203 | subscription-id {qos}? 1204 +--ro transport transport 1205 | {configured}? 1206 +--ro encoding? encoding 1207 +--ro purpose? string 1208 {configured}? 1210 Figure 11: subscription-started notification tree diagram 1212 2.7.2. subscription-modified 1214 This notification indicates that a subscription has been modified by 1215 configuration operations. It is delivered directly after the last 1216 event records processed using the previous subscription parameters, 1217 and before any event records processed after the modification. 1219 Below is a tree diagram for "subscription-modified". All objects 1220 contained in this tree are described within the included YANG model 1221 within Section 4. 1223 +---n subscription-modified 1224 +--ro id 1225 | subscription-id 1226 +--ro (target) 1227 | +--:(stream) 1228 | +--ro (stream-filter)? 1229 | | +--:(by-reference) 1230 | | | +--ro stream-filter-name 1231 | | | stream-filter-ref 1232 | | +--:(within-subscription) 1233 | | +--ro (filter-spec)? 1234 | | +--:(stream-subtree-filter) 1235 | | | +--ro stream-subtree-filter? 1236 | | | {subtree}? 1237 | | +--:(stream-xpath-filter) 1238 | | +--ro stream-xpath-filter? yang:xpath1.0 1239 | | {xpath}? 1240 | +--ro stream stream-ref 1241 | +--ro replay-start-time? 1242 | yang:date-and-time {replay}? 1243 +--ro stop-time? 1244 | yang:date-and-time 1245 +--ro dscp? inet:dscp 1246 | {dscp}? 1247 +--ro weighting? uint8 {qos}? 1248 +--ro dependency? 1249 | subscription-id {qos}? 1250 +--ro transport transport 1251 | {configured}? 1252 +--ro encoding? encoding 1253 +--ro purpose? string 1254 {configured}? 1256 Figure 12: subscription-modified notification tree diagram 1258 A publisher most often sends this notification directly after the 1259 modification of any configuration parameters impacting a configured 1260 subscription. But it may also be sent at two other times: 1262 1. Where a configured subscription has been modified during the 1263 suspension of a receiver, the notification will be delayed until 1264 the receiver's suspension is lifted. In this situation, the 1265 notification indicates that the subscription has been both 1266 modified and resumed. 1268 2. A "subscription-modified" subscription state change notification 1269 MUST be sent if the contents of the filter identified by the 1270 subscription's "stream-filter-ref" leaf has changed. This state 1271 change notification is to be sent for a filter change impacting 1272 any active receiver of a configured or dynamic subscription. 1274 2.7.3. subscription-terminated 1276 This notification indicates that no further event records for this 1277 subscription should be expected from the publisher. A publisher may 1278 terminate the sending event records to a receiver for the following 1279 reasons: 1281 1. Configuration which removes a configured subscription, or a 1282 "kill-subscription" RPC which ends a dynamic subscription. These 1283 are identified via the reason "no-such-subscription". 1285 2. A referenced filter is no longer accessible. This is identified 1286 by "filter-unavailable". 1288 3. The event stream referenced by a subscription is no longer 1289 accessible by the receiver. This is identified by "stream- 1290 unavailable". 1292 4. A suspended subscription has exceeded some timeout. This is 1293 identified by "suspension-timeout". 1295 Each of the reasons above correspond one-to-one with a "reason" 1296 identityref specified within the YANG model. 1298 Below is a tree diagram for "subscription-terminated". All objects 1299 contained in this tree are described within the included YANG model 1300 within Section 4. 1302 +---n subscription-terminated 1303 +--ro id subscription-id 1304 +--ro reason identityref 1306 Figure 13: subscription-terminated notification tree diagram 1308 Note: this subscription state change notification MUST be sent to a 1309 dynamic subscription's receiver when the subscription ends 1310 unexpectedly. The cases when this might happen are when a "kill- 1311 subscription" RPC is successful, or when some other event not 1312 including the reaching the subscription's "stop-time" results in a 1313 publisher choosing to end the subscription. 1315 2.7.4. subscription-suspended 1317 This notification indicates that a publisher has suspended the 1318 sending of event records to a receiver, and also indicates the 1319 possible loss of events. Suspension happens when capacity 1320 constraints stop a publisher from serving a valid subscription. The 1321 two conditions where is this possible are: 1323 1. "insufficient-resources" when a publisher is unable to produce 1324 the requested event stream of notification messages, and 1326 2. "unsupportable-volume" when the bandwidth needed to get generated 1327 notification messages to a receiver exceeds a threshold. 1329 These conditions are encoded within the "reason" object. No further 1330 notification will be sent until the subscription resumes or is 1331 terminated. 1333 Below is a tree diagram for "subscription-suspended". All objects 1334 contained in this tree are described within the included YANG model 1335 within Section 4. 1337 +---n subscription-suspended 1338 +--ro id subscription-id 1339 +--ro reason identityref 1341 Figure 14: subscription-suspended notification tree diagram 1343 2.7.5. subscription-resumed 1345 This notification indicates that a previously suspended subscription 1346 has been resumed under the unmodified terms previously in place. 1347 Subscribed event records generated after the issuance of this 1348 subscription state change notification may now be sent. 1350 Below is the tree diagram for "subscription-resumed". All objects 1351 contained in this tree are described within the included YANG model 1352 within Section 4. 1354 +---n subscription-resumed 1355 +--ro id subscription-id 1357 Figure 15: subscription-resumed notification tree diagram 1359 2.7.6. subscription-completed 1361 This notification indicates that a subscription that includes a 1362 "stop-time" has successfully finished passing event records upon the 1363 reaching of that time. 1365 Below is a tree diagram for "subscription-completed". All objects 1366 contained in this tree are described within the included YANG model 1367 within Section 4. 1369 +---n subscription-completed {configured}? 1370 +--ro id subscription-id 1372 Figure 16: subscription-completed notification tree diagram 1374 2.7.7. replay-completed 1376 This notification indicates that all of the event records prior to 1377 the current time have been passed to a receiver. It is sent before 1378 any notification message containing an event record with a timestamp 1379 later than (1) the "stop-time" or (2) the subscription's start time. 1381 If a subscription contains no "stop-time", or has a "stop-time" that 1382 has not been reached, then after the "replay-completed" notification 1383 has been sent, additional event records will be sent in sequence as 1384 they arise naturally on the publisher. 1386 Below is a tree diagram for "replay-completed". All objects 1387 contained in this tree are described within the included YANG model 1388 within Section 4. 1390 +---n replay-completed {replay}? 1391 +--ro id subscription-id 1393 Figure 17: replay-completed notification tree diagram 1395 2.8. Subscription Monitoring 1397 In the operational state datastore, the container "subscriptions" 1398 maintains the state of all dynamic subscriptions, as well as all 1399 configured subscriptions. Using datastore retrieval operations, or 1400 subscribing to the "subscriptions" container 1401 [I-D.ietf-netconf-yang-push] allows the state of subscriptions and 1402 their connectivity to receivers to be monitored. 1404 Each subscription in the operational state datastore is represented 1405 as a list element. Included in this list are event counters for each 1406 receiver, the state of each receiver, as well as the subscription 1407 parameters currently in effect. The appearance of the leaf 1408 "configured-subscription-state" indicates that a particular 1409 subscription came into being via configuration. This leaf also 1410 indicates if the current state of that subscription is valid, 1411 invalid, and concluded. 1413 To understand the flow of event records within a subscription, there 1414 are two counters available for each receiver. The first counter is 1415 "sent-event-records" which shows the quantity of events actually 1416 identified for sending to a receiver. The second counter is 1417 "excluded-event-records" which shows event records not sent to 1418 receiver. "excluded-event-records" shows the combined results of 1419 both access control and per-subscription filtering. For configured 1420 subscriptions, counters are reset whenever the subscription is 1421 evaluated to valid (see (1) in Figure 8). 1423 Dynamic subscriptions are removed from the operational state 1424 datastore once they expire (reaching stop-time) or when they are 1425 terminated. While many subscription objects are shown as 1426 configurable, dynamic subscriptions are only included within the 1427 operational state datastore and as a result are not configurable. 1429 2.9. Advertisement 1431 Publishers supporting this document MUST indicate support of the YANG 1432 model "ietf-subscribed-notifications" within the YANG library of the 1433 publisher. In addition if supported, the optional features "encode- 1434 xml", "encode-json", "configured" "supports-vrf", "qos", "xpath", 1435 "subtree", "interface-designation", "dscp", and "replay" MUST be 1436 indicated. 1438 3. YANG Data Model Trees 1440 This section contains tree diagrams for nodes defined in Section 4. 1441 For tree diagrams of subscription state change notifications, see 1442 Section 2.7. For the tree diagrams for the RPCs, see Section 2.4. 1444 3.1. Event Streams Container 1446 A publisher maintains a list of available event streams as 1447 operational data. This list contains both standardized and vendor- 1448 specific event streams. This enables subscribers to discover what 1449 streams a publisher supports. 1451 +--ro streams 1452 +--ro stream* [name] 1453 +--ro name string 1454 +--ro description string 1455 +--ro replay-support? empty {replay}? 1456 +--ro replay-log-creation-time yang:date-and-time 1457 | {replay}? 1458 +--ro replay-log-aged-time? yang:date-and-time 1459 {replay}? 1461 Figure 18: Stream Container tree diagram 1463 Above is a tree diagram for the "streams" container. All objects 1464 contained in this tree are described within the included YANG model 1465 within Section 4. 1467 3.2. Filters Container 1469 The "filters" container maintains a list of all subscription filters 1470 that persist outside the life-cycle of a single subscription. This 1471 enables pre-defined filters which may be referenced by more than one 1472 subscription. 1474 +--rw filters 1475 +--rw stream-filter* [name] 1476 +--rw name string 1477 +--rw (filter-spec)? 1478 +--:(stream-subtree-filter) 1479 | +--rw stream-subtree-filter? {subtree}? 1480 +--:(stream-xpath-filter) 1481 +--rw stream-xpath-filter? yang:xpath1.0 {xpath}? 1483 Figure 19: Filter Container tree diagram 1485 Above is a tree diagram for the filters container. All objects 1486 contained in this tree are described within the included YANG model 1487 within Section 4. 1489 3.3. Subscriptions Container 1491 The "subscriptions" container maintains a list of all subscriptions 1492 on a publisher, both configured and dynamic. It can be used to 1493 retrieve information about the subscriptions which a publisher is 1494 serving. 1496 +--rw subscriptions 1497 +--rw subscription* [id] 1498 +--rw id 1499 | subscription-id 1500 +--rw (target) 1501 | +--:(stream) 1502 | +--rw (stream-filter)? 1503 | | +--:(by-reference) 1504 | | | +--rw stream-filter-name 1505 | | | stream-filter-ref 1506 | | +--:(within-subscription) 1507 | | +--rw (filter-spec)? 1508 | | +--:(stream-subtree-filter) 1509 | | | +--rw stream-subtree-filter? 1510 | | | {subtree}? 1511 | | +--:(stream-xpath-filter) 1512 | | +--rw stream-xpath-filter? 1513 | | yang:xpath1.0 {xpath}? 1514 | +--rw stream stream-ref 1515 | +--ro replay-start-time? 1516 | | yang:date-and-time {replay}? 1517 | +--rw configured-replay? empty 1518 | {configured,replay}? 1519 +--rw stop-time? 1520 | yang:date-and-time 1521 +--rw dscp? inet:dscp 1522 | {dscp}? 1523 +--rw weighting? uint8 {qos}? 1524 +--rw dependency? 1525 | subscription-id {qos}? 1526 +--rw transport transport 1527 | {configured}? 1528 +--rw encoding? encoding 1529 +--rw purpose? string 1530 | {configured}? 1531 +--rw (notification-message-origin)? {configured}? 1532 | +--:(interface-originated) 1533 | | +--rw source-interface? 1534 | | if:interface-ref {interface-designation}? 1535 | +--:(address-originated) 1536 | +--rw source-vrf? 1537 | | -> /ni:network-instances/network-instance/name 1538 | | {supports-vrf}? 1539 | +--rw source-address? 1540 | inet:ip-address-no-zone 1541 +--ro configured-subscription-state? enumeration 1542 | {configured}? 1543 +--rw receivers 1544 +--rw receiver* [name] 1545 +--rw name string 1546 +--ro sent-event-records? 1547 | yang:zero-based-counter64 1548 +--ro excluded-event-records? 1549 | yang:zero-based-counter64 1550 +--ro state enumeration 1551 +---x reset {configured}? 1552 +--ro output 1553 +--ro time yang:date-and-time 1555 Figure 20: Subscriptions tree diagram 1557 Above is a tree diagram for the subscriptions container. All objects 1558 contained in this tree are described within the included YANG model 1559 within Section 4. 1561 4. Data Model 1563 This module imports typedefs from [RFC6991], [RFC8343], and 1564 [RFC8040], and it references [I-D.draft-ietf-rtgwg-ni-model], 1565 [XPATH], [RFC6241], [RFC7540], [RFC7951] and [RFC7950]. 1567 [ note to the RFC Editor - please replace XXXX within this YANG model 1568 with the number of this document, and XXXY with the number of 1569 [I-D.draft-ietf-rtgwg-ni-model] ] 1571 [ note to the RFC Editor - please replace the two dates within the 1572 YANG module with the date of publication ] 1574 file "ietf-subscribed-notifications@2018-09-13.yang" 1575 module ietf-subscribed-notifications { 1576 yang-version 1.1; 1577 namespace 1578 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"; 1580 prefix sn; 1582 import ietf-inet-types { 1583 prefix inet; 1584 reference 1585 "RFC 6991: Common YANG Data Types"; 1586 } 1587 import ietf-interfaces { 1588 prefix if; 1589 reference 1590 "RFC 8343: A YANG Data Model for Interface Management"; 1591 } 1592 import ietf-netconf-acm { 1593 prefix nacm; 1594 reference 1595 "RFC 8341: Network Configuration Access Control Model"; 1596 } 1597 import ietf-network-instance { 1598 prefix ni; 1599 reference 1600 "draft-ietf-rtgwg-ni-model-12: YANG Model for Network Instances"; 1601 } 1602 import ietf-restconf { 1603 prefix rc; 1604 reference 1605 "RFC 8040: RESTCONF Protocol"; 1606 } 1607 import ietf-yang-types { 1608 prefix yang; 1609 reference 1610 "RFC 6991: Common YANG Data Types"; 1611 } 1613 organization "IETF NETCONF (Network Configuration) Working Group"; 1614 contact 1615 "WG Web: 1616 WG List: 1618 Author: Alexander Clemm 1619 1621 Author: Eric Voit 1622 1624 Author: Alberto Gonzalez Prieto 1625 1627 Author: Einar Nilsen-Nygaard 1628 1630 Author: Ambika Prasad Tripathy 1631 "; 1633 description 1634 "Contains a YANG specification for subscribing to event records 1635 and receiving matching content within notification messages. 1637 Copyright (c) 2018 IETF Trust and the persons identified as authors 1638 of the code. All rights reserved. 1640 Redistribution and use in source and binary forms, with or without 1641 modification, is permitted pursuant to, and subject to the license 1642 terms contained in, the Simplified BSD License set forth in Section 1643 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 1644 (https://trustee.ietf.org/license-info). 1646 This version of this YANG module is part of RFC XXXX; see the RFC 1647 itself for full legal notices."; 1649 revision 2018-09-13 { 1650 description 1651 "Initial version"; 1652 reference 1653 "RFC XXXX:Customized Subscriptions to a Publisher's Event Streams"; 1654 } 1656 /* 1657 * FEATURES 1658 */ 1660 feature configured { 1661 description 1662 "This feature indicates that configuration of subscription is 1663 supported."; 1664 } 1666 feature dscp { 1667 description 1668 "This feature indicates a publisher supports the placement of 1669 suggested prioritization levels for network transport within 1670 notification messages."; 1671 } 1673 feature encode-json { 1674 description 1675 "This feature indicates that JSON encoding of notification 1676 messages is supported."; 1677 } 1679 feature encode-xml { 1680 description 1681 "This feature indicates that XML encoding of notification 1682 messages is supported."; 1683 } 1685 feature interface-designation { 1686 description 1687 "This feature indicates a publisher supports sourcing all 1688 receiver interactions for a configured subscription from a single 1689 designated egress interface."; 1690 } 1692 feature qos { 1693 description 1694 "This feature indicates a publisher supports absolute 1695 dependencies of one subscription's traffic over another, as well 1696 as weighted bandwidth sharing between subscriptions. Both of 1697 these are Quality of Service (QoS) features which allow 1698 differentiated treatment of notification messages between a 1699 publisher and a specific receiver."; 1700 } 1702 feature replay { 1703 description 1704 "This feature indicates that historical event record replay is 1705 supported. With replay, it is possible for past event records to 1706 be streamed in chronological order."; 1707 } 1709 feature subtree { 1710 description 1711 "This feature indicates support for YANG subtree filtering."; 1712 reference "RFC 6241, Section 6."; 1713 } 1715 feature supports-vrf { 1716 description 1717 "This feature indicates a publisher supports VRF configuration 1718 for configured subscriptions. VRF support for dynamic 1719 subscriptions does not require this feature."; 1720 reference "RFC XXXY, Section 6."; 1721 } 1723 feature xpath { 1724 description 1725 "This feature indicates support for XPath filtering."; 1726 reference "http://www.w3.org/TR/1999/REC-xpath-19991116"; 1727 } 1729 /* 1730 * EXTENSIONS 1731 */ 1733 extension subscription-state-notification { 1734 description 1735 "This statement applies only to notifications. It indicates that 1736 the notification is a subscription state change notification. 1737 Therefore it does not participate in a regular event stream and 1738 does not need to be specifically subscribed to in order to be 1739 received. This statement can only occur as a substatement to the 1740 YANG 'notification' statement. This statement is not for use 1741 outside of this YANG module."; 1742 } 1744 /* 1745 * IDENTITIES 1746 */ 1748 /* Identities for RPC and Notification errors */ 1750 identity delete-subscription-error { 1751 description 1752 "Problem found while attempting to fulfill either a 1753 'delete-subscription' RPC request or a 'kill-subscription' 1754 RPC request."; 1755 } 1757 identity establish-subscription-error { 1758 description 1759 "Problem found while attempting to fulfill an 1760 'establish-subscription' RPC request."; 1761 } 1763 identity modify-subscription-error { 1764 description 1765 "Problem found while attempting to fulfill a 1766 'modify-subscription' RPC request."; 1767 } 1769 identity subscription-suspended-reason { 1770 description 1771 "Problem condition communicated to a receiver as part of a 1772 'subscription-terminated' notification."; 1773 } 1775 identity subscription-terminated-reason { 1776 description 1777 "Problem condition communicated to a receiver as part of a 1778 'subscription-terminated' notification."; 1779 } 1781 identity dscp-unavailable { 1782 base establish-subscription-error; 1783 if-feature "dscp"; 1784 description 1785 "The publisher is unable mark notification messages with a 1786 prioritization information in a way which will be respected 1787 during network transit."; 1788 } 1790 identity encoding-unsupported { 1791 base establish-subscription-error; 1792 description 1793 "Unable to encode notification messages in the desired format."; 1794 } 1796 identity filter-unavailable { 1797 base subscription-terminated-reason; 1798 description 1799 "Referenced filter does not exist. This means a receiver is 1800 referencing a filter which doesn't exist, or to which they do not 1801 have access permissions."; 1802 } 1804 identity filter-unsupported { 1805 base establish-subscription-error; 1806 base modify-subscription-error; 1807 description 1808 "Cannot parse syntax within the filter. This failure can be from 1809 a syntax error, or a syntax too complex to be processed by the 1810 publisher."; 1811 } 1813 identity insufficient-resources { 1814 base establish-subscription-error; 1815 base modify-subscription-error; 1816 base subscription-suspended-reason; 1817 description 1818 "The publisher has insufficient resources to support the 1819 requested subscription. An example might be that allocated CPU 1820 is too limited to generate the desired set of notification 1821 messages."; 1822 } 1824 identity no-such-subscription { 1825 base modify-subscription-error; 1826 base delete-subscription-error; 1827 base subscription-terminated-reason; 1828 description 1829 "Referenced subscription doesn't exist. This may be as a result of 1830 a non-existent subscription id, an id which belongs to another 1831 subscriber, or an id for configured subscription."; 1833 } 1835 identity replay-unsupported { 1836 base establish-subscription-error; 1837 if-feature "replay"; 1838 description 1839 "Replay cannot be performed for this subscription. This means the 1840 publisher will not provide the requested historic information 1841 from the event stream via replay to this receiver."; 1842 } 1844 identity stream-unavailable { 1845 base subscription-terminated-reason; 1846 description 1847 "Not a subscribable stream. This means the referenced event 1848 stream is not available for subscription by the receiver."; 1849 } 1851 identity suspension-timeout { 1852 base subscription-terminated-reason; 1853 description 1854 "Termination of previously suspended subscription. The publisher 1855 has eliminated the subscription as it exceeded a time limit for 1856 suspension."; 1857 } 1859 identity unsupportable-volume { 1860 base subscription-suspended-reason; 1861 description 1862 "The publisher does not have the network bandwidth needed to get 1863 the volume of generated information intended for a receiver."; 1864 } 1866 /* Identities for encodings */ 1868 identity configurable-encoding { 1869 description 1870 "If a transport identity derives from this identity, it means 1871 that it supports configurable encodings."; 1872 } 1874 identity encoding { 1875 description 1876 "Base identity to represent data encodings"; 1877 } 1879 identity encode-xml { 1880 base encoding; 1881 if-feature "encode-xml"; 1882 description 1883 "Encode data using XML as described in RFC 7950"; 1884 reference 1885 "RFC 7950 - The YANG 1.1 Data Modeling Language"; 1886 } 1888 identity encode-json { 1889 base encoding; 1890 if-feature "encode-json"; 1891 description 1892 "Encode data using JSON as described in RFC 7951"; 1893 reference 1894 "RFC 7951 - JSON Encoding of Data Modeled with YANG"; 1895 } 1897 /* Identities for transports */ 1898 identity transport { 1899 description 1900 "An identity that represents the underlying mechanism for 1901 passing notification messages."; 1902 } 1904 /* 1905 * TYPEDEFs 1906 */ 1908 typedef encoding { 1909 type identityref { 1910 base encoding; 1911 } 1912 description 1913 "Specifies a data encoding, e.g. for a data subscription."; 1914 } 1916 typedef stream-filter-ref { 1917 type leafref { 1918 path "/sn:filters/sn:stream-filter/sn:name"; 1919 } 1920 description 1921 "This type is used to reference an event stream filter."; 1922 } 1924 typedef stream-ref { 1925 type leafref { 1926 path "/sn:streams/sn:stream/sn:name"; 1927 } 1928 description 1929 "This type is used to reference a system-provided stream."; 1930 } 1932 typedef subscription-id { 1933 type uint32; 1934 description 1935 "A type for subscription identifiers."; 1936 } 1938 typedef transport { 1939 type identityref { 1940 base transport; 1941 } 1942 description 1943 "Specifies transport used to send notification messages to a 1944 receiver."; 1945 } 1947 /* 1948 * GROUPINGS 1949 */ 1951 grouping stream-filter-elements { 1952 description 1953 "This grouping defines the base for filters applied to event 1954 streams."; 1955 choice filter-spec { 1956 description 1957 "The content filter specification for this request."; 1958 anydata stream-subtree-filter { 1959 if-feature "subtree"; 1960 description 1961 "Event stream evaluation criteria encoded in the syntax of a 1962 subtree filter as defined in RFC 6241, Section 6. 1964 The subtree filter is applied to the representation of 1965 individual, delineated event records as contained within the 1966 event stream. 1968 If the subtree filter returns a non-empty node set, the 1969 filter matches the event record, and the event record is 1970 included in the notification message sent to the receivers."; 1971 reference "RFC 6241, Section 6."; 1972 } 1973 leaf stream-xpath-filter { 1974 if-feature "xpath"; 1975 type yang:xpath1.0; 1976 description 1977 "Event stream evaluation criteria encoded in the syntax of 1978 an XPath 1.0 expression. 1980 The XPath expression is evaluated on the representation of 1981 individual, delineated event records as contained within 1982 the event stream. 1984 The result of the XPath expression is converted to a 1985 boolean value using the standard XPath 1.0 rules. If the 1986 boolean value is 'true', the filter matches the event 1987 record, and the event record is included in the notification 1988 message sent to the receivers. 1990 The expression is evaluated in the following XPath context: 1992 o The set of namespace declarations are those in scope on 1993 the 'stream-xpath-filter' leaf element. 1995 o The set of variable bindings is empty. 1997 o The function library is the core function library, and 1998 the XPath functions defined in section 10 in RFC 7950. 2000 o The context node is the root node."; 2001 reference 2002 "http://www.w3.org/TR/1999/REC-xpath-19991116 2003 RFC 7950, Section 10."; 2005 } 2006 } 2007 } 2009 grouping update-qos { 2010 description 2011 "This grouping describes Quality of Service information 2012 concerning a subscription. This information is passed to lower 2013 layers for transport prioritization and treatment"; 2014 leaf dscp { 2015 if-feature "dscp"; 2016 type inet:dscp; 2017 default "0"; 2018 description 2019 "The desired network transport priority level. This is the 2020 priority set on notification messages encapsulating the 2021 results of the subscription. This transport priority is 2022 shared for all receivers of a given subscription."; 2023 } 2024 leaf weighting { 2025 if-feature "qos"; 2026 type uint8 { 2027 range "0 .. 255"; 2028 } 2029 description 2030 "Relative weighting for a subscription. Allows an underlying 2031 transport layer perform informed load balance allocations 2032 between various subscriptions"; 2033 reference 2034 "RFC-7540, section 5.3.2"; 2035 } 2036 leaf dependency { 2037 if-feature "qos"; 2038 type subscription-id; 2039 description 2040 "Provides the 'subscription-id' of a parent subscription which 2041 has absolute precedence should that parent have push updates 2042 ready to egress the publisher. In other words, there should be 2043 no streaming of objects from the current subscription if 2044 the parent has something ready to push. 2046 If a dependency is asserted via configuration or via RPC, but 2047 the referenced 'subscription-id' does not exist, the 2048 dependency is silently discarded. If a referenced 2049 subscription is deleted this dependency is removed."; 2050 reference 2051 "RFC-7540, section 5.3.1"; 2052 } 2053 } 2055 grouping subscription-policy-modifiable { 2056 description 2057 "This grouping describes all objects which may be changed 2058 in a subscription."; 2059 choice target { 2060 mandatory true; 2061 description 2062 "Identifies the source of information against which a 2063 subscription is being applied, as well as specifics on the 2064 subset of information desired from that source."; 2065 case stream { 2066 choice stream-filter { 2067 description 2068 "An event stream filter can be applied to a subscription. 2069 That filter will come either referenced from a global list, 2070 or be provided within the subscription itself."; 2071 case by-reference { 2072 description 2073 "Apply a filter that has been configured separately."; 2074 leaf stream-filter-name { 2075 type stream-filter-ref; 2076 mandatory true; 2077 description 2078 "References an existing stream filter which is to 2079 be applied to an event stream for the subscription."; 2080 } 2081 } 2082 case within-subscription { 2083 description 2084 "Local definition allows a filter to have the same 2085 lifecycle as the subscription."; 2086 uses stream-filter-elements; 2087 } 2088 } 2089 } 2090 } 2091 leaf stop-time { 2092 type yang:date-and-time; 2093 description 2094 "Identifies a time after which notification messages for a 2095 subscription should not be sent. If 'stop-time' is not 2096 present, the notification messages will continue until the 2097 subscription is terminated. If 'replay-start-time' exists, 2098 'stop-time' must be for a subsequent time. If 2099 'replay-start-time' doesn't exist, 'stop-time' when established 2100 must be for a future time."; 2101 } 2102 } 2104 grouping subscription-policy-dynamic { 2105 description 2106 "This grouping describes the only information concerning a 2107 subscription which can be passed over the RPCs defined in this 2108 model."; 2109 uses subscription-policy-modifiable { 2110 augment target/stream { 2111 description 2112 "Adds additional objects which can be modified by RPC."; 2113 leaf stream { 2114 type stream-ref { 2115 require-instance false; 2116 } 2117 mandatory true; 2118 description 2119 "Indicates the event stream to be considered for 2120 this subscription."; 2122 } 2123 leaf replay-start-time { 2124 if-feature "replay"; 2125 type yang:date-and-time; 2126 config false; 2127 description 2128 "Used to trigger the replay feature for a dynamic 2129 subscription, with event records being selected needing to 2130 be at or after the start at the time specified. If 2131 'replay-start-time' is not present, this is not a replay 2132 subscription and event record push should start 2133 immediately. It is never valid to specify start times that 2134 are later than or equal to the current time."; 2135 } 2136 } 2137 } 2138 uses update-qos; 2139 } 2141 grouping subscription-policy { 2142 description 2143 "This grouping describes the full set of policy information 2144 concerning both dynamic and configured subscriptions, with the 2145 exclusion of both receivers and networking information specific 2146 to the publisher such as what interface should be used to 2147 transmit notification messages."; 2148 uses subscription-policy-dynamic; 2149 leaf transport { 2150 if-feature "configured"; 2151 type transport; 2152 mandatory true; 2153 description 2154 "This leaf specifies the transport used to deliver 2155 messages destined to all receivers of a subscription."; 2156 } 2157 leaf encoding { 2158 when 'not(../transport) or derived-from(../transport, 2159 "sn:configurable-encoding")'; 2160 type encoding; 2161 description 2162 "The type of encoding for notification messages. For a 2163 dynamic subscription, if not included as part of an establish- 2164 subscription RPC, the encoding will be populated with the 2165 encoding used by that RPC. For a configured subscription, if 2166 not explicitly configured the encoding with be the default 2167 encoding for an underlying transport."; 2168 } 2169 leaf purpose { 2170 if-feature "configured"; 2171 type string; 2172 description 2173 "Open text allowing a configuring entity to embed the 2174 originator or other specifics of this subscription."; 2175 } 2176 } 2178 /* 2179 * RPCs 2180 */ 2182 rpc establish-subscription { 2183 description 2184 "This RPC allows a subscriber to create (and possibly negotiate) 2185 a subscription on its own behalf. If successful, the 2186 subscription remains in effect for the duration of the 2187 subscriber's association with the publisher, or until the 2188 subscription is terminated. In case an error occurs, or the 2189 publisher cannot meet the terms of a subscription, an RPC error 2190 is returned, the subscription is not created. In that case, the 2191 RPC reply's 'error-info' MAY include suggested parameter 2192 settings that would have a higher likelihood of succeeding in a 2193 subsequent 'establish-subscription' request."; 2194 input { 2195 uses subscription-policy-dynamic; 2196 leaf encoding { 2197 type encoding; 2198 description 2199 "The type of encoding for the subscribed data. If not 2200 included as part of the RPC, the encoding MUST be set by the 2201 publisher to be the encoding used by this RPC."; 2202 } 2203 } 2204 output { 2205 leaf id { 2206 type subscription-id; 2207 mandatory true; 2208 description 2209 "Identifier used for this subscription."; 2210 } 2211 leaf replay-start-time-revision { 2212 if-feature "replay"; 2213 type yang:date-and-time; 2214 description 2215 "If a replay has been requested, this represents the 2216 earliest time covered by the event buffer for the requested 2217 stream. The value of this object is the 2218 'replay-log-aged-time' if it exists. Otherwise it is the 2219 'replay-log-creation-time'. All buffered event records 2220 after this time will be replayed to a receiver. This 2221 object will only be sent if the starting time has been 2222 revised to be later than the time requested by the 2223 subscriber."; 2224 } 2225 } 2226 } 2228 rc:yang-data establish-subscription-stream-error-info { 2229 container establish-subscription-stream-error-info { 2230 description 2231 "If any 'establish-subscription' RPC parameters are 2232 unsupportable against the event stream, a subscription is not 2233 created and the RPC error response MUST indicate the reason 2234 why the subscription failed to be created. This yang-data MAY 2235 be inserted as structured data within a subscription's RPC 2236 error response to indicate the failure reason. This yang-data 2237 MUST be inserted if hints are to be provided back to the 2238 subscriber."; 2239 leaf reason { 2240 type identityref { 2241 base establish-subscription-error; 2242 } 2243 description 2244 "Indicates the reason why the subscription has failed to 2245 be created to a targeted stream."; 2246 } 2247 leaf filter-failure-hint { 2248 type string; 2249 description 2250 "Information describing where and/or why a provided filter 2251 was unsupportable for a subscription."; 2252 } 2253 } 2254 } 2256 rpc modify-subscription { 2257 description 2258 "This RPC allows a subscriber to modify a dynamic subscription's 2259 parameters. If successful, the changed subscription 2260 parameters remain in effect for the duration of the 2261 subscription, until the subscription is again modified, or until 2262 the subscription is terminated. In case of an error or an 2263 inability to meet the modified parameters, the subscription is 2264 not modified and the original subscription parameters remain in 2265 effect. In that case, the RPC error MAY include 'error-info' 2266 suggested parameter hints that would have a high likelihood of 2267 succeeding in a subsequent 'modify-subscription' request. A 2268 successful 'modify-subscription' will return a suspended 2269 subscription to an 'active' state."; 2270 input { 2271 leaf id { 2272 type subscription-id; 2273 mandatory true; 2274 description 2275 "Identifier to use for this subscription."; 2276 } 2277 uses subscription-policy-modifiable; 2278 } 2279 } 2281 rc:yang-data modify-subscription-stream-error-info { 2282 container modify-subscription-stream-error-info { 2283 description 2284 "This yang-data MAY be provided as part of a subscription's RPC 2285 error response when there is a failure of a 2286 'modify-subscription' RPC which has been made against a 2287 stream. This yang-data MUST be used if hints are to be 2288 provided back to the subscriber."; 2289 leaf reason { 2290 type identityref { 2291 base modify-subscription-error; 2292 } 2293 description 2294 "Information in a 'modify-subscription' RPC error response 2295 which indicates the reason why the subscription to an event 2296 stream has failed to be modified."; 2297 } 2298 leaf filter-failure-hint { 2299 type string; 2300 description 2301 "Information describing where and/or why a provided filter 2302 was unsupportable for a subscription."; 2303 } 2304 } 2305 } 2307 rpc delete-subscription { 2308 description 2309 "This RPC allows a subscriber to delete a subscription that 2310 was previously created from by that same subscriber using the 2311 'establish-subscription' RPC. 2313 If an error occurs, the server replies with an 'rpc-error' where 2314 the 'error-info' field MAY contain an 2315 'delete-subscription-error-info' structure."; 2316 input { 2317 leaf id { 2318 type subscription-id; 2319 mandatory true; 2320 description 2321 "Identifier of the subscription that is to be deleted. 2322 Only subscriptions that were created using 2323 'establish-subscription' from the same origin as this RPC 2324 can be deleted via this RPC."; 2325 } 2326 } 2327 } 2329 rpc kill-subscription { 2330 nacm:default-deny-all; 2331 description 2332 "This RPC allows an operator to delete a dynamic subscription 2333 without restrictions on the originating subscriber or underlying 2334 transport session. 2336 If an error occurs, the server replies with an 'rpc-error' where 2337 the 'error-info' field MAY contain an 2338 'delete-subscription-error-info' structure."; 2339 input { 2340 leaf id { 2341 type subscription-id; 2342 mandatory true; 2343 description 2344 "Identifier of the subscription that is to be deleted. Only 2345 subscriptions that were created using 2346 'establish-subscription' can be deleted via this RPC."; 2347 } 2348 } 2349 } 2351 rc:yang-data delete-subscription-error-info { 2352 container delete-subscription-error-info { 2353 description 2354 "If a 'delete-subscription' RPC or a 'kill-subscription' RPC 2355 fails, the subscription is not deleted and the RPC error 2356 response MUST indicate the reason for this failure. This 2357 yang-data MAY be inserted as structured data within a 2358 subscription's RPC error response to indicate the failure 2359 reason."; 2360 leaf reason { 2361 type identityref { 2362 base delete-subscription-error; 2363 } 2364 mandatory true; 2365 description 2366 "Indicates the reason why the subscription has failed to be 2367 deleted."; 2368 } 2369 } 2370 } 2372 /* 2373 * NOTIFICATIONS 2374 */ 2376 notification replay-completed { 2377 sn:subscription-state-notification; 2378 if-feature "replay"; 2379 description 2380 "This notification is sent to indicate that all of the replay 2381 notifications have been sent. It must not be sent for any other 2382 reason."; 2383 leaf id { 2384 type subscription-id; 2385 mandatory true; 2386 description 2387 "This references the affected subscription."; 2388 } 2389 } 2391 notification subscription-completed { 2392 sn:subscription-state-notification; 2393 if-feature "configured"; 2394 description 2395 "This notification is sent to indicate that a subscription has 2396 finished passing event records, as the 'stop-time' has been 2397 reached."; 2398 leaf id { 2399 type subscription-id; 2400 mandatory true; 2401 description 2402 "This references the gracefully completed subscription."; 2403 } 2404 } 2406 notification subscription-modified { 2407 sn:subscription-state-notification; 2408 description 2409 "This notification indicates that a subscription has been 2410 modified. Notification messages sent from this point on will 2411 conform to the modified terms of the subscription. For 2412 completeness, this subscription state change notification 2413 includes both modified and non-modified aspects of a 2414 subscription."; 2415 leaf id { 2416 type subscription-id; 2417 mandatory true; 2418 description 2419 "This references the affected subscription."; 2420 } 2421 uses subscription-policy { 2422 refine "target/stream/stream-filter/within-subscription" { 2423 description 2424 "Filter applied to the subscription. If the 2425 'stream-filter-name' is populated, the filter within the 2426 subscription came from the 'filters' container. Otherwise it 2427 is populated in-line as part of the subscription."; 2428 } 2429 } 2430 } 2432 notification subscription-resumed { 2433 sn:subscription-state-notification; 2434 description 2435 "This notification indicates that a subscription that had 2436 previously been suspended has resumed. Notifications will once 2437 again be sent. In addition, a 'subscription-resumed' indicates 2438 that no modification of parameters has occurred since the last 2439 time event records have been sent."; 2440 leaf id { 2441 type subscription-id; 2442 mandatory true; 2443 description 2444 "This references the affected subscription."; 2445 } 2446 } 2448 notification subscription-started { 2449 sn:subscription-state-notification; 2450 if-feature "configured"; 2451 description 2452 "This notification indicates that a subscription has started and 2453 notifications are beginning to be sent. This notification shall 2454 only be sent to receivers of a subscription; it does not 2455 constitute a general-purpose notification."; 2456 leaf id { 2457 type subscription-id; 2458 mandatory true; 2459 description 2460 "This references the affected subscription."; 2461 } 2462 uses subscription-policy { 2463 refine "target/stream/replay-start-time" { 2464 description 2465 "Indicates the time that a replay using for the streaming of 2466 buffered event records. This will be populated with the 2467 most recent of the following: the event time of the previous 2468 event record sent to a receiver, the 2469 'replay-log-creation-time', the 'replay-log-aged-time', 2470 or the most recent publisher boot time."; 2471 } 2472 refine "target/stream/stream-filter/within-subscription" { 2473 description 2474 "Filter applied to the subscription. If the 2475 'stream-filter-name' is populated, the filter within the 2476 subscription came from the 'filters' container. Otherwise it 2477 is populated in-line as part of the subscription."; 2478 } 2479 augment "target/stream" { 2480 description 2481 "This augmentation adds additional parameters specific to a 2482 subscription-started notification."; 2483 leaf replay-previous-event-time { 2484 when "../replay-start-time"; 2485 if-feature "replay"; 2486 type yang:date-and-time; 2487 description 2488 "If there is at least one event in the replay buffer prior 2489 to 'replay-start-time', this gives the time of the event 2490 generated immediately prior to the 'replay-start-time'. 2492 If a receiver previously received event records for this 2493 configured subscription, it can compare this time to the 2494 last event record previously received. If the two are not 2495 the same (perhaps due to a reboot), then a dynamic replay 2496 can be initiated to acquire any missing event records."; 2497 } 2498 } 2499 } 2500 } 2502 notification subscription-suspended { 2503 sn:subscription-state-notification; 2504 description 2505 "This notification indicates that a suspension of the 2506 subscription by the publisher has occurred. No further 2507 notifications will be sent until the subscription resumes. 2508 This notification shall only be sent to receivers of a 2509 subscription; it does not constitute a general-purpose 2510 notification."; 2511 leaf id { 2512 type subscription-id; 2513 mandatory true; 2514 description 2515 "This references the affected subscription."; 2516 } 2517 leaf reason { 2518 type identityref { 2519 base subscription-suspended-reason; 2520 } 2521 mandatory true; 2522 description 2523 "Identifies the condition which resulted in the suspension."; 2524 } 2525 } 2527 notification subscription-terminated { 2528 sn:subscription-state-notification; 2529 description 2530 "This notification indicates that a subscription has been 2531 terminated."; 2532 leaf id { 2533 type subscription-id; 2534 mandatory true; 2535 description 2536 "This references the affected subscription."; 2537 } 2538 leaf reason { 2539 type identityref { 2540 base subscription-terminated-reason; 2541 } 2542 mandatory true; 2543 description 2544 "Identifies the condition which resulted in the termination ."; 2545 } 2546 } 2548 /* 2549 * DATA NODES 2550 */ 2552 container streams { 2553 config false; 2554 description 2555 "This container contains information on the built-in streams 2556 provided by the publisher."; 2557 list stream { 2558 key "name"; 2559 description 2560 "Identifies the built-in event streams that are supported by 2561 the publisher."; 2562 leaf name { 2563 type string; 2564 description 2565 "A handle for a system-provided event stream made up of a 2566 sequential set of event records, each of which is 2567 characterized by its own domain and semantics."; 2568 } 2569 leaf description { 2570 type string; 2571 mandatory true; 2572 description 2573 "A description of the event stream, including such 2574 information as the type of event records that are available 2575 within this event stream."; 2576 } 2577 leaf replay-support { 2578 if-feature "replay"; 2579 type empty; 2580 description 2581 "Indicates that event record replay is available on this 2582 stream."; 2583 } 2584 leaf replay-log-creation-time { 2585 when "../replay-support"; 2586 if-feature "replay"; 2587 type yang:date-and-time; 2588 mandatory true; 2589 description 2590 "The timestamp of the creation of the log used to support the 2591 replay function on this stream. This time might be earlier 2592 than the earliest available information contained in the log. 2593 This object is updated if the log resets for some reason."; 2594 } 2595 leaf replay-log-aged-time { 2596 if-feature "replay"; 2597 type yang:date-and-time; 2598 description 2599 "The timestamp associated with last event record which has 2600 been aged out of the log. This timestamp identifies how far 2601 back into history this replay log extends, if it doesn't 2602 extend back to the 'replay-log-creation-time'. This object 2603 MUST be present if replay is supported and any event records 2604 have been aged out of the log."; 2605 } 2606 } 2607 } 2609 container filters { 2610 description 2611 "This container contains a list of configurable filters 2612 that can be applied to subscriptions. This facilitates 2613 the reuse of complex filters once defined."; 2614 list stream-filter { 2615 key "name"; 2616 description 2617 "A list of pre-configured filters that can be applied to 2618 subscriptions."; 2619 leaf name { 2620 type string; 2621 description 2622 "An name to differentiate between filters."; 2623 } 2624 uses stream-filter-elements; 2625 } 2626 } 2628 container subscriptions { 2629 description 2630 "Contains the list of currently active subscriptions, i.e. 2631 subscriptions that are currently in effect, used for 2632 subscription management and monitoring purposes. This includes 2633 subscriptions that have been setup via RPC primitives as well as 2634 subscriptions that have been established via configuration."; 2635 list subscription { 2636 key "id"; 2637 description 2638 "The identity and specific parameters of a subscription. 2639 Subscriptions within this list can be created using a control 2640 channel or RPC, or be established through configuration. 2642 If configuration operations or the 'kill-subscription' RPC are 2643 used to delete a subscription, a 'subscription-terminated' 2644 message is sent to any active or suspended receivers."; 2645 leaf id { 2646 type subscription-id; 2647 description 2648 "Identifier of a subscription; unique within a publisher"; 2650 } 2651 uses subscription-policy { 2652 refine "target/stream/stream" { 2653 description 2654 "Indicates the event stream to be considered for this 2655 subscription. If an event stream has been removed, 2656 and no longer can be referenced by an active subscription, 2657 send a 'subscription-terminated' notification with 2658 'stream-unavailable' as the reason. If a configured 2659 subscription refers to a non-existent stream, move that 2660 subscription to the 'invalid' state."; 2661 } 2662 augment "target/stream" { 2663 description 2664 "Enables objects to added to a configured stream 2665 subscription"; 2666 leaf configured-replay { 2667 if-feature "configured"; 2668 if-feature "replay"; 2669 type empty; 2670 description 2671 "The presence of this leaf indicates that replay for the 2672 configured subscription should start at the earliest time 2673 in the event log, or at the publisher boot time, which 2674 ever is later."; 2675 } 2676 } 2677 } 2678 choice notification-message-origin { 2679 if-feature "configured"; 2680 description 2681 "Identifies the egress interface on the publisher from which 2682 notification messages are to be sent."; 2683 case interface-originated { 2684 description 2685 "When notification messages to egress a specific, 2686 designated interface on the publisher."; 2687 leaf source-interface { 2688 if-feature "interface-designation"; 2689 type if:interface-ref; 2690 description 2691 "References the interface for notification messages."; 2692 } 2693 } 2694 case address-originated { 2695 description 2696 "When notification messages are to depart from a publisher 2697 using specific originating address and/or routing context 2698 information."; 2699 leaf source-vrf { 2700 if-feature "supports-vrf"; 2701 type leafref { 2702 path "/ni:network-instances/ni:network-instance/ni:name"; 2703 } 2704 description 2705 "VRF from which notification messages should egress a 2706 publisher."; 2707 } 2708 leaf source-address { 2709 type inet:ip-address-no-zone; 2710 description 2711 "The source address for the notification messages. If a 2712 source VRF exists, but this object doesn't, a publisher's 2713 default address for that VRF must be used."; 2714 } 2715 } 2716 } 2717 leaf configured-subscription-state { 2718 if-feature "configured"; 2719 type enumeration { 2720 enum valid { 2721 value 1; 2722 description 2723 "Connection is active and healthy."; 2724 } 2725 enum invalid { 2726 value 2; 2727 description 2728 "The subscription as a whole is unsupportable with its 2729 current parameters."; 2730 } 2731 enum concluded { 2732 value 3; 2733 description 2734 "A subscription is inactive as it has hit a stop time, 2735 but not yet been removed from configuration."; 2736 } 2737 } 2738 config false; 2739 description 2740 "The presence of this leaf indicates that the subscription 2741 originated from configuration, not through a control channel 2742 or RPC. The value indicates the system established state 2743 of the subscription."; 2744 } 2745 container receivers { 2746 description 2747 "Set of receivers in a subscription."; 2748 list receiver { 2749 key "name"; 2750 min-elements 1; 2751 description 2752 "A host intended as a recipient for the notification 2753 messages of a subscription. For configured subscriptions, 2754 transport specific network parameters (or a leafref to 2755 those parameters) may augmentated to a specific receiver 2756 within this list."; 2757 leaf name { 2758 type string; 2759 description 2760 "Identifies a unique receiver for a subscription."; 2761 } 2762 leaf sent-event-records { 2763 type yang:zero-based-counter64; 2764 config false; 2765 description 2766 "The number of event records sent to the receiver. The 2767 count is initialized when a dynamic subscription is 2768 established, or when a configured subscription 2769 transitions to the valid state."; 2770 } 2771 leaf excluded-event-records { 2772 type yang:zero-based-counter64; 2773 config false; 2774 description 2775 "The number of event records explicitly removed either 2776 via an event stream filter or an access control filter so 2777 that they are not passed to a receiver. This count is 2778 set to zero each time 'sent-event-records' is 2779 initialized."; 2780 } 2781 leaf state { 2782 type enumeration { 2783 enum active { 2784 value 1; 2785 description 2786 "Receiver is currently being sent any applicable 2787 notification messages for the subscription."; 2788 } 2789 enum suspended { 2790 value 2; 2791 description 2792 "Receiver state is 'suspended', so the publisher 2793 is currently unable to provide notification messages 2794 for the subscription."; 2795 } 2796 enum connecting { 2797 value 3; 2798 if-feature "configured"; 2799 description 2800 "A subscription has been configured, but a 2801 'subscription-started' subscription state change 2802 notification needs to be successfully received before 2803 notification messages are sent. 2805 If the 'reset' action is invoked for a receiver of an 2806 active configured subscription, the state must be 2807 moved to 'connecting'."; 2808 } 2809 enum disconnected { 2810 value 4; 2811 if-feature "configured"; 2812 description 2813 "A subscription has failed in sending a subscription 2814 started state change to the receiver. 2815 Additional attempts at connection attempts are not 2816 currently being made."; 2817 } 2818 } 2819 config false; 2820 mandatory true; 2821 description 2822 "Specifies the state of a subscription from the 2823 perspective of a particular receiver. With this info it 2824 is possible to determine whether a subscriber is 2825 currently generating notification messages intended for 2826 that receiver."; 2827 } 2828 action reset { 2829 if-feature "configured"; 2830 description 2831 "Allows the reset of this configured subscription 2832 receiver to the 'connecting' state. This enables the 2833 connection process to be re-initiated."; 2834 output { 2835 leaf time { 2836 type yang:date-and-time; 2837 mandatory true; 2838 description 2839 "Time a publisher returned the receiver to a 2840 'connecting' state."; 2841 } 2843 } 2844 } 2845 } 2846 } 2847 } 2848 } 2849 } 2850 2852 5. Considerations 2854 5.1. IANA Considerations 2856 This document registers the following namespace URI in the "IETF XML 2857 Registry" [RFC3688]: 2859 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2860 Registrant Contact: The IESG. 2861 XML: N/A; the requested URI is an XML namespace. 2863 This document registers the following YANG module in the "YANG Module 2864 Names" registry [RFC6020]: 2866 Name: ietf-subscribed-notifications 2867 Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications 2868 Prefix: sn 2869 Reference: draft-ietf-netconf-ietf-subscribed-notifications-11.txt 2870 (RFC form) 2872 5.2. Implementation Considerations 2874 To support deployments including both configured and dynamic 2875 subscriptions, it is recommended to split the subscription "id" 2876 domain into static and dynamic halves. That way it eliminates the 2877 possibility of collisions if the configured subscriptions attempt to 2878 set a subscription-id which might have already been dynamically 2879 allocated. A best practice is to use lower half the "id" object's 2880 integer space when that "id" is assigned by an external entity (such 2881 as with a configured subscription). This leaves the upper half of 2882 subscription integer space available to be dynamically assigned by 2883 the publisher. 2885 If a subscription is unable to marshal a series of filtered event 2886 records into transmittable notification messages, the receiver should 2887 be suspended with the reason "unsupportable-volume". 2889 For configured subscriptions, operations are against the set of 2890 receivers using the subscription "id" as a handle for that set. But 2891 for streaming updates, subscription state change notifications are 2892 local to a receiver. In this specification it is the case that 2893 receivers get no information from the publisher about the existence 2894 of other receivers. But if a network operator wants to let the 2895 receivers correlate results, it is useful to use the subscription 2896 "id" across the receivers to allow that correlation. 2898 For configured replay subscriptions, the receiver is protected from 2899 duplicated events being pushed after a publisher is rebooted. 2900 However it is possible that a receiver might want to acquire event 2901 records which failed to be delivered just prior to the reboot. 2902 Delivering these event records be accomplished by leveraging the 2903 "eventTime" from the last event record received prior to the receipt 2904 of a "subscription-started" subscription state change notification. 2905 With this "eventTime" and the "replay-start-time" from the 2906 "subscription-started" notification, an independent dynamic 2907 subscription can be established which retrieves any event records 2908 which may have been generated but not sent to the receiver. 2910 5.3. Transport Requirements 2912 This section provides requirements for any subscribed notification 2913 transport supporting the solution presented in this document. 2915 The transport selected by the subscriber to reach the publisher MUST 2916 be able to support multiple "establish-subscription" requests made 2917 within the same transport session. 2919 For both configured and dynamic subscriptions the publisher MUST 2920 authenticate a receiver via some transport level mechanism before 2921 sending any event records for which they are authorized to see. In 2922 addition, the receiver MUST authenticate the publisher at the 2923 transport level. The result is mutual authentication between the 2924 two. 2926 A secure transport is highly recommended and the publisher MUST 2927 ensure that the receiver has sufficient authorization to perform the 2928 function they are requesting against the specific subset of content 2929 involved. 2931 A specific transport specification built upon this document may or 2932 may not choose to require the use of the same logical channel for the 2933 RPCs and the event records. However the event records and the 2934 subscription state change notifications MUST be sent on the same 2935 transport session to ensure the properly ordered delivery. 2937 Additional transport requirements will be dictated by the choice of 2938 transport used with a subscription. For an example of such 2939 requirements with NETCONF transport, see 2940 [I-D.draft-ietf-netconf-netconf-event-notifications]. 2942 5.4. Security Considerations 2944 The YANG module specified in this document defines a schema for data 2945 that is designed to be accessed via network management transports 2946 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 2947 layer is the secure transport layer, and the mandatory-to-implement 2948 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 2949 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 2950 transport is TLS [RFC5246]. 2952 The NETCONF Access Control Model (NACM) [RFC8341] provides the means 2953 to restrict access for particular NETCONF or RESTCONF users to a 2954 preconfigured subset of all available NETCONF or RESTCONF operations 2955 and content. 2957 One subscription "id" can be used for two or more receivers of the 2958 same configured subscription. But due to the possibility of 2959 different access control permissions per receiver, it cannot be 2960 assumed that each receiver is getting identical updates. 2962 With configured subscriptions, one or more publishers could be used 2963 to overwhelm a receiver. Notification messages SHOULD NOT be sent to 2964 any receiver which does not support this specification. Receivers 2965 that do not want notification messages need only terminate or refuse 2966 any transport sessions from the publisher. 2968 When a receiver of a configured subscription gets a new 2969 "subscription-started" message for a known subscription where it is 2970 already consuming events, the receiver SHOULD retrieve any event 2971 records generated since the last event record was received. This can 2972 be accomplish by establishing a separate dynamic replay subscription 2973 with the same filtering criteria with the publisher, assuming the 2974 publisher supports the "replay" feature. 2976 For dynamic subscriptions, implementations need to protect against 2977 malicious or buggy subscribers which may send a large number 2978 "establish-subscription" requests, thereby using up system resources. 2979 To cover this possibility operators SHOULD monitor for such cases 2980 and, if discovered, take remedial action to limit the resources used, 2981 such as suspending or terminating a subset of the subscriptions or, 2982 if the underlying transport is session based, terminate the 2983 underlying transport session. 2985 There are a number of data nodes defined in this YANG module that are 2986 writable/creatable/deletable (i.e., config true, which is the 2987 default). These data nodes may be considered sensitive or vulnerable 2988 in some network environments. Write operations (e.g., edit-config) 2989 to these data nodes without proper protection can have a negative 2990 effect on network operations. These are the subtrees and data nodes 2991 where there is a specific sensitivity/vulnerability: 2993 Container: "/filters" 2995 o "stream-subtree-filter": updating a filter could increase the 2996 computational complexity of all referencing subscriptions. 2998 o "stream-xpath-filter": updating a filter could increase the 2999 computational complexity of all referencing subscriptions. 3001 Container: "/subscriptions" 3003 The following considerations are only relevant for configuration 3004 operations made upon configured subscriptions: 3006 o "configured-replay": can be used to send a large number of event 3007 records to a receiver. 3009 o "dependency": can be used to force important traffic to be queued 3010 behind less important updates. 3012 o "dscp": if unvalidated, can result in the sending of traffic with 3013 a higher priority marking than warranted. 3015 o "id": can overwrite an existing subscription, perhaps one 3016 configured by another entity. 3018 o "name": adding a new key entry can be used to attempt to send 3019 traffic to an unwilling receiver. 3021 o "replay-start-time": can be used to push very large logs, wasting 3022 resources. 3024 o "source-address": the configured address might not be able to 3025 reach a desired receiver. 3027 o "source-interface": the configured interface might not be able to 3028 reach a desired receiver. 3030 o "source-vrf": can place a subscription into a virtual network 3031 where receivers are not entitled to view the subscribed content. 3033 o "stop-time": could be used to terminate content at an inopportune 3034 time. 3036 o "stream": could set a subscription to an event stream containing 3037 no content permitted for the targeted receivers. 3039 o "stream-filter-name": could be set to a filter which is irrelevant 3040 to the event stream. 3042 o "stream-subtree-filter": a complex filter can increase the 3043 computational resources for this subscription. 3045 o "stream-xpath-filter": a complex filter can increase the 3046 computational resources for this subscription. 3048 o "weighting": placing a large weight can overwhelm the dequeuing of 3049 other subscriptions. 3051 Some of the readable data nodes in this YANG module may be considered 3052 sensitive or vulnerable in some network environments. It is thus 3053 important to control read access (e.g., via get, get-config, or 3054 notification) to these data nodes. These are the subtrees and data 3055 nodes and their sensitivity/vulnerability: 3057 Container: "/streams" 3059 o "name": if access control is not properly configured, can expose 3060 system internals to those who should have no access to this 3061 information. 3063 o "replay-support": if access control is not properly configured, 3064 can expose logs to those who should have no access. 3066 Container: "/subscriptions" 3068 o "excluded-event-records": leaf can provide information about 3069 filtered event records. A network operator should have 3070 permissions to know about such filtering. 3072 o "subscription": different operational teams might have a desire to 3073 set varying subsets of subscriptions. Access control should be 3074 designed to permit read access to just the allowed set. 3076 Some of the RPC operations in this YANG module may be considered 3077 sensitive or vulnerable in some network environments. It is thus 3078 important to control access to these operations. These are the 3079 operations and their sensitivity/vulnerability: 3081 RPC: all 3082 o If a malicious or buggy subscriber sends an unexpectedly large 3083 number of RPCs, the result might be an excessive use of system 3084 resources on the publisher just to determine that these 3085 subscriptions should be declined. In such a situation, 3086 subscription interactions MAY be terminated by terminating the 3087 transport session. 3089 RPC: "delete-subscription" 3091 o No special considerations. 3093 RPC: "establish-subscription" 3095 o Subscriptions could overload a publisher's resources. For this 3096 reason, publishers MUST ensure that they have sufficient resources 3097 to fulfill this request or otherwise reject the request. 3099 RPC: "kill-subscription" 3101 o The "kill-subscription" RPC MUST be secured so that only 3102 connections with administrative rights are able to invoke this 3103 RPC. 3105 RPC: "modify-subscription" 3107 o Subscriptions could overload a publisher's resources. For this 3108 reason, publishers MUST ensure that they have sufficient resources 3109 to fulfill this request or otherwise reject the request. 3111 6. Acknowledgments 3113 For their valuable comments, discussions, and feedback, we wish to 3114 acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen, 3115 Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan 3116 Hares, Michael Scharf, and Guangying Zheng. 3118 7. References 3120 7.1. Normative References 3122 [I-D.draft-ietf-rtgwg-ni-model] 3123 Berger, L., Hopps, C., and A. Lindem, "YANG Network 3124 Instances", draft-ietf-rtgwg-ni-model-12 (work in 3125 progress), March 2018. 3127 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3128 Requirement Levels", BCP 14, RFC 2119, 3129 DOI 10.17487/RFC2119, March 1997, 3130 . 3132 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 3133 "Definition of the Differentiated Services Field (DS 3134 Field) in the IPv4 and IPv6 Headers", RFC 2474, 3135 DOI 10.17487/RFC2474, December 1998, 3136 . 3138 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3139 DOI 10.17487/RFC3688, January 2004, 3140 . 3142 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3143 (TLS) Protocol Version 1.2", RFC 5246, 3144 DOI 10.17487/RFC5246, August 2008, 3145 . 3147 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 3148 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 3149 . 3151 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 3152 the Network Configuration Protocol (NETCONF)", RFC 6020, 3153 DOI 10.17487/RFC6020, October 2010, 3154 . 3156 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 3157 and A. Bierman, Ed., "Network Configuration Protocol 3158 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 3159 . 3161 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 3162 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 3163 . 3165 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 3166 RFC 6991, DOI 10.17487/RFC6991, July 2013, 3167 . 3169 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3170 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3171 . 3173 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3174 RFC 7951, DOI 10.17487/RFC7951, August 2016, 3175 . 3177 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 3178 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 3179 . 3181 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3182 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3183 May 2017, . 3185 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 3186 Access Control Model", STD 91, RFC 8341, 3187 DOI 10.17487/RFC8341, March 2018, 3188 . 3190 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 3191 and R. Wilton, "Network Management Datastore Architecture 3192 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 3193 . 3195 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 3196 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 3197 . 3199 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 3200 Version 1.0", November 1999, 3201 . 3203 7.2. Informative References 3205 [I-D.draft-ietf-netconf-netconf-event-notifications] 3206 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3207 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 3208 event notifications", May 2018, 3209 . 3212 [I-D.draft-ietf-netconf-restconf-notif] 3213 Voit, Eric., Clemm, Alexander., Tripathy, A., Nilsen- 3214 Nygaard, E., and Alberto. Gonzalez Prieto, "Restconf and 3215 HTTP transport for event notifications", May 2018, 3216 . 3219 [I-D.ietf-netconf-yang-push] 3220 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 3221 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 3222 Lengyel, "YANG Datastore Subscription", May 2018, 3223 . 3226 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 3227 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 3228 DOI 10.17487/RFC7540, May 2015, 3229 . 3231 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 3232 for Subscription to YANG Datastores", RFC 7923, 3233 DOI 10.17487/RFC7923, June 2016, 3234 . 3236 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 3237 RFC 8071, DOI 10.17487/RFC8071, February 2017, 3238 . 3240 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3241 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3242 . 3244 Appendix A. Example Configured Transport Augmentation 3246 This appendix provides a non-normative example of how the YANG model 3247 defined in Section 4 may be enhanced to incorporate the configuration 3248 parameters needed to support the transport connectivity process. In 3249 this example, connectivity via an imaginary transport type of "foo" 3250 is explored. For more on the overall need, see Section 2.5.7. 3252 The YANG model defined in this section contains two main elements. 3253 First is a transport identity "foo". This transport identity allows 3254 a configuration agent to define "foo" as the selected type of 3255 transport for a subscription. Second is a YANG case augmentation 3256 "foo" which is made to the "/subscriptions/subscription/receivers/ 3257 receiver" node of Section 4. Within this augmentation are the 3258 transport configuration parameters "address" and "port" which are 3259 necessary to make the connect to the receiver. 3261 module example-foo-subscribed-notifications { 3262 yang-version 1.1; 3263 namespace 3264 "urn:example:foo-subscribed-notifications"; 3266 prefix fsn; 3267 import ietf-subscribed-notifications { 3268 prefix sn; 3269 } 3270 import ietf-inet-types { 3271 prefix inet; 3272 } 3274 description 3275 "Defines 'foo' as a supported type of configured transport for 3276 subscribed event notifications."; 3278 identity foo { 3279 base sn:transport; 3280 description 3281 "Transport type 'foo' is available for use as a configured 3282 subscription transport protocol for subscribed notifications."; 3283 } 3285 augment 3286 "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { 3287 when 'derived-from(../../../transport, "fsn:foo")'; 3288 description 3289 "This augmentation makes 'foo' specific transport parameters 3290 available for a receiver."; 3291 leaf address { 3292 type inet:host; 3293 mandatory true; 3294 description 3295 "Specifies the address to use for messages destined to a 3296 receiver."; 3297 } 3298 leaf port { 3299 type inet:port-number; 3300 mandatory true; 3301 description 3302 "Specifies the port number to use for messages destined to a 3303 receiver."; 3304 } 3305 } 3306 } 3308 Figure 21: Example Transport Augmentation for the fictitious protocol 3309 foo 3311 This example YANG model for transport "foo" will not be seen in a 3312 real world deployment. For a real world deployment supporting an 3313 actual transport technology, a similar YANG model must be defined. 3315 Appendix B. Changes between revisions 3317 (To be removed by RFC editor prior to publication) 3319 v16 - v17 3321 o YANG renaming: Subscription identifier renamed to id. Counters 3322 renamed. Filters id made into name. 3324 o Text tweaks. 3326 v15 - v16 3328 o Mandatory empty case "transport" removed. 3330 o Appendix case turned from "netconf" to "foo". 3332 v14 - v15 3334 o Text tweaks. 3336 o Mandatory empty case "transport" added for transport parameters. 3337 This includes a new section and an appendix explaining it. 3339 v13 - v14 3341 o Removed the 'address' leaf. 3343 o Replay is now of type 'empty' for configured. 3345 v12 - v13 3347 o Tweaks from Kent's comments 3349 o Referenced in YANG model updated per Tom Petch's comments 3351 o Added leaf replay-previous-event-time 3353 o Renamed the event counters, downshifted the subscription states 3355 v11 - v12 3357 o Tweaks from Kent's, Tim's, and Martin's comments 3359 o Clarified dscp text, and made its own feature 3361 o YANG model tweaks alphabetizing, features. 3363 v10 - v11 3365 o access control filtering of events in streams included to match 3366 RFC5277 behavior 3368 o security considerations updated based on YANG template. 3370 o dependency QoS made non-normative on HTTP2 QoS 3372 o tree diagrams referenced for each figure using them 3374 o reference numbers placed into state machine figures 3376 o broke configured replay into its own section 3378 o many tweaks updates based on LC and YANG doctor reviews 3380 o trees and YANG model reconciled were deltas existed 3382 o new feature for interface originated. 3384 o dscp removed from the qos feature 3386 o YANG model updated in a way which collapses groups only used once 3387 so that they are part of the 'subscriptions' container. 3389 o alternative encodings only allowed for transports which support 3390 them. 3392 v09 - v10 3394 o Typos and tweaks 3396 v08 - v09 3398 o NMDA model supported. Non NMDA version at https://github.com/ 3399 netconf-wg/rfc5277bis/ 3401 o Error mechanism revamped to match to embedded implementations. 3403 o Explicitly identified error codes relevant to each RPC/ 3404 Notification 3406 v07 - v08 3408 o Split YANG trees to separate document subsections. 3410 o Clarified configured state machine based on Balazs comments, and 3411 moved it into the configured subscription subsections. 3413 o Normative reference to Network Instance model for VRF 3415 o One transport for all receivers of configured subscriptions. 3417 o QoS section moved in from yang-push 3419 v06 - v07 3421 o Clarification on state machine for configured subscriptions. 3423 v05 - v06 3425 o Made changes proposed by Martin, Kent, and others on the list. 3426 Most significant of these are stream returned to string (with the 3427 SYSLOG identity removed), intro section on 5277 relationship, an 3428 identity set moved to an enumeration, clean up of definitions/ 3429 terminology, state machine proposed for configured subscriptions 3430 with a clean-up of subscription state options. 3432 o JSON and XML become features. Also Xpath and subtree filtering 3433 become features 3435 o Terminology updates with event records, and refinement of filters 3436 to just event stream filters. 3438 o Encoding refined in establish-subscription so it takes the RPC's 3439 encoding as the default. 3441 o Namespaces in examples fixed. 3443 v04 - v05 3445 o Returned to the explicit filter subtyping of v00 3447 o stream object changed to 'name' from 'stream' 3449 o Cleaned up examples 3451 o Clarified that JSON support needs notification-messages draft. 3453 v03 - v04 3455 o Moved back to the use of RFC5277 one-way notifications and 3456 encodings. 3458 v03 - v04 3460 o Replay updated 3462 v02 - v03 3464 o RPCs and Notification support is identified by the Notification 3465 2.0 capability. 3467 o Updates to filtering identities and text 3469 o New error type for unsupportable volume of updates 3471 o Text tweaks. 3473 v01 - v02 3475 o Subscription status moved under receiver. 3477 v00 - v01 3479 o Security considerations updated 3481 o Intro rewrite, as well as scattered text changes 3483 o Added Appendix A, to help match this to related drafts in progress 3485 o Updated filtering definitions, and filter types in yang file, and 3486 moved to identities for filter types 3488 o Added Syslog as an event stream 3490 o HTTP2 moved in from YANG-Push as a transport option 3492 o Replay made an optional feature for events. Won't apply to 3493 datastores 3495 o Enabled notification timestamp to have different formats. 3497 o Two error codes added. 3499 v01 5277bis - v00 subscribed notifications 3501 o Kill subscription RPC added. 3503 o Renamed from 5277bis to Subscribed Notifications. 3505 o Changed the notification capabilities version from 1.1 to 2.0. 3507 o Extracted create-subscription and other elements of RFC5277. 3509 o Error conditions added, and made specific in return codes. 3511 o Simplified yang model structure for removal of 'basic' grouping. 3513 o Added a grouping for items which cannot be statically configured. 3515 o Operational counters per receiver. 3517 o Subscription-id and filter-id renamed to identifier 3519 o Section for replay added. Replay now cannot be configured. 3521 o Control plane notification renamed to subscription state change 3522 notification 3524 o Source address: Source-vrf changed to string, default address 3525 option added 3527 o In yang model: 'info' changed to 'policy' 3529 o Scattered text clarifications 3531 v00 - v01 of 5277bis 3533 o YANG Model changes. New groupings for subscription info to allow 3534 restriction of what is changeable via RPC. Removed notifications 3535 for adding and removing receivers of configured subscriptions. 3537 o Expanded/renamed definitions from event server to publisher, and 3538 client to subscriber as applicable. Updated the definitions to 3539 include and expand on RFC 5277. 3541 o Removal of redundancy with other drafts 3543 o Many other clean-ups of wording and terminology 3545 Authors' Addresses 3547 Eric Voit 3548 Cisco Systems 3550 Email: evoit@cisco.com 3551 Alexander Clemm 3552 Huawei 3554 Email: ludwig@clemm.org 3556 Alberto Gonzalez Prieto 3557 Microsoft 3559 Email: alberto.gonzalez@microsoft.com 3561 Einar Nilsen-Nygaard 3562 Cisco Systems 3564 Email: einarnn@cisco.com 3566 Ambika Prasad Tripathy 3567 Cisco Systems 3569 Email: ambtripa@cisco.com