idnits 2.17.00 (12 Aug 2021) /tmp/idnits55118/draft-ietf-netconf-yang-push-15.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 : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 220: '...hat, a dampening period MAY be used to...' RFC 2119 keyword, line 250: '...cription request SHOULD be declined if...' RFC 2119 keyword, line 285: '... publisher MAY accept an on-change s...' RFC 2119 keyword, line 297: '...ely, a publisher MAY decide to simply ...' RFC 2119 keyword, line 300: '...on, the subscription MAY be suspended....' (64 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 873 has weird spacing: '...ro time yan...' == Line 932 has weird spacing: '...ntifier sub...' == Line 972 has weird spacing: '...ntifier sub...' == Line 975 has weird spacing: '...ntifier sub...' == Line 988 has weird spacing: '...ntifier sub...' == (8 more instances...) -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Update records for a single subscription MAY NOT be resequenced prior to transport. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 23, 2018) is 1548 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) == Outdated reference: draft-ietf-netconf-subscribed-notifications has been published as RFC 8639 == Outdated reference: draft-ietf-netmod-revised-datastores has been published as RFC 8342 == Outdated reference: draft-ietf-netconf-rfc6536bis has been published as RFC 8341 -- Possible downref: Normative reference to a draft: ref. 'RFC6536bis' ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) == Outdated reference: draft-ietf-netconf-netconf-event-notifications has been published as RFC 8640 -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 2 errors (**), 0 flaws (~~), 13 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF A. Clemm 3 Internet-Draft Huawei 4 Intended status: Standards Track E. Voit 5 Expires: August 27, 2018 Cisco Systems 6 A. Gonzalez Prieto 7 VMware 8 A. Tripathy 9 E. Nilsen-Nygaard 10 Cisco Systems 11 A. Bierman 12 YumaWorks 13 B. Lengyel 14 Ericsson 15 February 23, 2018 17 YANG Datastore Subscription 18 draft-ietf-netconf-yang-push-15 20 Abstract 22 Via the mechanism described in this document, subscriber applications 23 may request a continuous, customized stream of updates from a YANG 24 datastore. Providing such visibility into changes made upon YANG 25 configuration and operational objects enables new capabilities based 26 on the remote mirroring of configuration and operational state. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on August 27, 2018. 45 Copyright Notice 47 Copyright (c) 2018 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 This document may contain material from IETF Documents or IETF 61 Contributions published or made publicly available before November 62 10, 2008. The person(s) controlling the copyright in some of this 63 material may not have granted the IETF Trust the right to allow 64 modifications of such material outside the IETF Standards Process. 65 Without obtaining an adequate license from the person(s) controlling 66 the copyright in such materials, this document may not be modified 67 outside the IETF Standards Process, and derivative works of it may 68 not be created outside the IETF Standards Process, except to format 69 it for publication as an RFC or to translate it into languages other 70 than English. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 75 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4 76 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 4 77 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 5 78 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6 79 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 6 80 3.4. Promise-Theory Considerations . . . . . . . . . . . . . . 8 81 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 8 82 3.6. Defining the Selection with a Datastore . . . . . . . . . 9 83 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 10 84 3.8. Subscription Management . . . . . . . . . . . . . . . . . 12 85 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 14 86 3.10. On-change Notifiable YANG objects . . . . . . . . . . . . 16 87 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 16 88 4. A YANG data model for management of datastore push 89 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 17 90 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 17 91 4.2. Subscription configuration . . . . . . . . . . . . . . . 25 92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 26 93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 27 94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 32 95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 48 97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49 98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 99 9.1. Normative References . . . . . . . . . . . . . . . . . . 49 100 9.2. Informative References . . . . . . . . . . . . . . . . . 50 101 Appendix A. Appendix A: Subscription Errors . . . . . . . . . . 50 102 A.1. RPC Failures . . . . . . . . . . . . . . . . . . . . . . 50 103 A.2. Notifications of Failure . . . . . . . . . . . . . . . . 52 104 Appendix B. Changes between revisions . . . . . . . . . . . . . 52 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56 107 1. Introduction 109 Traditional approaches to remote visibility have been built on 110 polling. With polling, data is periodically requested and retrieved 111 by a client from a server to stay up-to-date. However, there are 112 issues associated with polling-based management: 114 o Polling incurs significant latency. This latency prohibits many 115 application types. 117 o Polling cycles may be missed, requests may be delayed or get lost, 118 often when the network is under stress and the need for the data 119 is the greatest. 121 o Polling requests may undergo slight fluctuations, resulting in 122 intervals of different lengths. The resulting data is difficult 123 to calibrate and compare. 125 o For applications that monitor for changes, many remote polling 126 cycles place ultimately fruitless load on the network, devices, 127 and applications. 129 A more effective alternative to polling is for an application to 130 receive automatic and continuous updates from a targeted subset of a 131 datastore. Accordingly, there is a need for a service that allows 132 applications to subscribe to updates from a datastore and that 133 enables the publisher to push and in effect stream those updates. 134 The requirements for such a service have been documented in 135 [RFC7923]. 137 This document defines a corresponding solution that is built on top 138 of "Custom Subscription to Event Streams" 139 [I-D.draft-ietf-netconf-subscribed-notifications]. Supplementing 140 that work are YANG data model augmentations, extended RPCs, and new 141 datastore specific update notifications. Transport options for 142 [I-D.draft-ietf-netconf-subscribed-notifications] will work 143 seamlessly with this solution. 145 2. Definitions and Acronyms 147 The terms below supplement those defined in 148 [I-D.draft-ietf-netconf-subscribed-notifications]. In addition, the 149 term "datastore" is defined in 150 [I-D.draft-ietf-netmod-revised-datastores]. 152 Datastore node: An instance of management information in a datastore. 153 Also known as "object". 155 Datastore node update: A data item containing the current value/ 156 property of a datastore node at the time the datastore node update 157 was created. 159 Datastore subtree: An instantiated datastore node and the datastore 160 nodes that are hierarchically contained within it. 162 Update record: A representation datastore node update(s) resulting 163 from the application of a selection filter for a subscription. An 164 update record will include the value/property of one or more 165 datastore nodes at a point in time. It may contain the update type 166 for each datastore node (e.g., add, change, delete). Also included 167 may be metadata/headers such as a subscription identifier. 169 Selection filter: Evaluation and/or selection criteria, which may be 170 applied against a targeted set of objects. 172 Update trigger: A mechanism that determines when an update record 173 needs to be generated. 175 YANG-Push: The subscription and push mechanism for datastore updates 176 that is specified in this document. 178 3. Solution Overview 180 This document specifies a solution for a push update subscription 181 service. This solution supports dynamic as well as configured 182 subscriptions to information updates from datastores. Subscriptions 183 specify when notification messages should be sent and what data to 184 include in update records. YANG objects are subsequently pushed from 185 the publisher to the receiver per the terms of the subscription. 187 3.1. Subscription Model 189 YANG-push subscriptions are defined using a data model that is itself 190 defined in YANG. This model enhances the subscription model defined 191 in [I-D.draft-ietf-netconf-subscribed-notifications] with 192 capabilities that allow subscribers to subscribe to datastore node 193 updates, specifically to specify the triggers defining when to 194 generate update records as well as what to include in an update 195 record. Key enhancements include: 197 o Specification of selection filters which identify targeted YANG 198 datastore nodes and/or subtrees within a datastore for which 199 updates are to be pushed. 201 o Specification of update policies contain conditions which trigger 202 the generation and pushing of new update records. There are two 203 types of triggers for subscriptions: periodic and on-change. 205 * For periodic subscriptions, the trigger is specified by two 206 parameters that define when updates are to be pushed. These 207 parameters are the period interval with which to report 208 updates, and an anchor time which can be used to calculate at 209 which point in time updates need to be assembled and sent. 211 * For on-change subscriptions, a trigger occurs whenever a change 212 in the subscribed information is detected. Included are 213 additional parameters such as: 215 + Dampening period: In an on-change subscription, detected 216 object changes should be sent as quickly as possible. 217 However it may be undesirable to send a rapid series of 218 object changes. Such behavior has the potential to exhaust 219 of resources in the publisher or receiver. In order to 220 protect against that, a dampening period MAY be used to 221 specify the interval which must pass before successive 222 update records for the same subscription are generated for a 223 receiver. The dampening period collectively applies to the 224 set of all datastore nodes selected by a single subscription 225 and sent to a single receiver. This means that when there 226 is a change to one or more subscribed objects, an update 227 record containing those objects is created either 228 immediately when no dampening period is in effect, or at the 229 end of a dampening period. If multiple changes to a single 230 object occur during a dampening period, only the value that 231 is in effect at the time the update record is created is 232 included. The dampening period goes into effect every time 233 an update record completes assembly. 235 + Change type: This parameter can be used to reduce the types 236 of datastore changes for which updates are sent (e.g., you 237 might only send when an object is created or deleted, but 238 not when an object value changes). 240 + No Synch on start: defines whether or not a complete push- 241 update of all subscribed data will be sent at the beginning 242 of a subscription. Such early synchronization establishes 243 the frame of reference for subsequent updates. 245 o An encoding (using anydata) for the contents of periodic and on- 246 change push updates. 248 3.2. Negotiation of Subscription Policies 250 A dynamic subscription request SHOULD be declined if a publisher's 251 assessment is that it may be unable to provide update records meeting 252 the terms of an "establish-subscription" or "modify-subscription" rpc 253 request. In this case, a subscriber may quickly follow up with a new 254 rpc request using different parameters. 256 Random guessing at different parameters by a subscriber is to be 257 discouraged. Therefore, in order to minimize the number of 258 subscription iterations between subscriber and publisher, dynamic 259 subscription supports a simple negotiation between subscribers and 260 publishers for subscription parameters. This negotiation is in the 261 form of supplemental information which may be inserted within error 262 responses to a failed rpc request. This returned error response 263 information, when considered, should increase the likelihood of 264 success for subsequent rpc requests. Such hints include suggested 265 periodic time intervals, acceptable dampening periods, and size 266 estimates for the number or objects which would be returned from a 267 proposed selection filter. However, there are no guarantees that 268 subsequent requests which consider these hints will be accepted. 270 3.3. On-Change Considerations 272 On-change subscriptions allow subscribers to receive updates whenever 273 changes to targeted objects occur. As such, on-change subscriptions 274 are particularly effective for data that changes infrequently, yet 275 for which applications need to be quickly notified whenever a change 276 does occur with minimal delay. 278 On-change subscriptions tend to be more difficult to implement than 279 periodic subscriptions. Accordingly, on-change subscriptions may not 280 be supported by all implementations or for every object. 282 Whether or not to accept or reject on-change subscription requests 283 when the scope of the subscription contains objects for which on- 284 change is not supported is up to the publisher implementation. A 285 publisher MAY accept an on-change subscription even when the scope of 286 the subscription contains objects for which on-change is not 287 supported. In that case, updates are sent only for those objects 288 within the scope that do support on-change updates whereas other 289 objects are excluded from update records, whether or not their values 290 actually change. In order for a subscriber to determine whether 291 objects support on-change subscriptions, objects are marked 292 accordingly on a publisher. Accordingly, when subscribing, it is the 293 responsibility of the subscriber to ensure it is aware of which 294 objects support on-change and which do not. For more on how objects 295 are so marked, see Section 3.10. 297 Alternatively, a publisher MAY decide to simply reject an on-change 298 subscription in case the scope of the subscription contains objects 299 for which on-change is not supported. In case of a configured 300 subscription, the subscription MAY be suspended. 302 To avoid flooding receivers with repeated updates for subscriptions 303 containing fast-changing objects, or objects with oscillating values, 304 an on-change subscription allows for the definition of a dampening 305 period. Once an update record for a given object is generated, no 306 other updates for this particular subscription will be created until 307 the end of the dampening period. Values sent at the end of the 308 dampening period are the current values of all changed objects which 309 are current at the time the dampening period expires. Changed 310 objects include those which were deleted or newly created during that 311 dampening period. If an object has returned to its original value 312 (or even has been created and then deleted) during the dampening- 313 period, the last change will still be sent. This will indicate churn 314 is occurring on that object. 316 On-change subscriptions can be refined to let users subscribe only to 317 certain types of changes. For example, a subscriber might only want 318 object creations and deletions, but not modifications of object 319 values. 321 Putting it all together, following is the conceptual process for 322 creating an push-change-update notification: 324 1. Just before a change, or at the start of a dampening period, 325 evaluate any filtering and any access control rules. The result 326 is a set "A" of datastore nodes and subtrees. 328 2. Just after a change, or at the end of a dampening period, 329 evaluate any filtering and any (possibly new) access control 330 rules. The result is a set "B" of datastore nodes and subtrees. 332 3. Construct a YANG patch record for going from A to B. 334 4. If there were any changes made between A and B which canceled 335 each other out, insert into the YANG patch record the last change 336 made for any object which otherwise wouldn't have appeared. 338 5. If the resulting patch record is non-empty, send it to the 339 receiver. 341 Note: In cases where a subscriber wants to have separate dampening 342 periods for different objects, multiple subscriptions with different 343 objects in a selection filter can be created. 345 3.4. Promise-Theory Considerations 347 A subscription to updates from a datastore is intended to obviate the 348 need for polling. However, in order to do so, it is critical that 349 subscribers can rely on the subscription and have confidence that 350 they will indeed receive the subscribed updates without having to 351 worry about updates being silently dropped. In other words, a 352 subscription constitutes a promise on the side of the publisher to 353 provide the receivers with updates per the terms of the subscription. 355 Now, there are many reasons why a publisher may at some point no 356 longer be able to fulfill the terms of the subscription, even if the 357 subscription had been entered into with good faith. For example, the 358 volume of data objects may be larger than anticipated, the interval 359 may prove too short to send full updates in rapid succession, or an 360 internal problem may prevent objects from being collected. If for 361 some reason the publisher of a subscription is not able to keep its 362 promise, receivers MUST be notified immediately and reliably. The 363 publisher MAY also suspend the subscription. 365 A publisher SHOULD reject a request for a subscription if it is 366 unlikely that the publisher will be able fulfill the terms of that 367 subscription request. In such cases, it is preferable to have a 368 subscriber request a less resource intensive subscription than to 369 deal with frequently degraded behavior. 371 3.5. Data Encodings 372 3.5.1. Periodic Subscriptions 374 In a periodic subscription, the data included as part of an update 375 corresponds to data that could have been read using a retrieval 376 operation. 378 3.5.2. On-Change Subscriptions 380 In an on-change subscription, updates need to indicate not only 381 values of changed datastore nodes but also the types of changes that 382 occurred since the last update. Therefore encoding rules for data in 383 on-change updates will generally follow YANG-patch operation as 384 specified in [RFC8072]. The YANG-patch will describe what needs to 385 be applied to the earlier state reported by the preceding update, to 386 result in the now-current state. Note that contrary to [RFC8072], 387 objects encapsulated are not restricted to configuration objects 388 only. 390 However a patch must be able to do more than just describe the delta 391 from the previous state to the current state. As per Section 3.3, it 392 must also be able to identify if transient changes have occurred on 393 an object during a dampening period. To support this, it is valid to 394 encode a YANG patch operation so that its application would result in 395 no change between the previous and current state. This indicates 396 that some churn has occurred on the object. An example of this would 397 be a patch that does a "create" operation for a datastore node where 398 the receiver believes one already exists, or a "merge" operation 399 which replaces a previous value with the same value. Note that this 400 means that the "create" and "delete" errors described in [RFC8072] 401 section 2.5 are not errors, and are valid operations with YANG push. 403 3.6. Defining the Selection with a Datastore 405 A subscription must specify both the selection filters and the 406 datastore against which these selection filters will be applied. 407 This information is used to choose and subsequently push data from 408 the publisher's datastore to the receivers. 410 Only a single selection filter can be applied to a subscription at a 411 time. An rpc request proposing a new selection filter MUST remove 412 any existing filter. The following selection filter types are 413 included in the yang-push data model, and may be applied against a 414 datastore: 416 o subtree: A subtree selection filter identifies one or more 417 datastore subtrees. When specified, update records will only come 418 from the datastore nodes of selected datastore subtree(s). The 419 syntax and semantics correspond to that specified for [RFC6241] 420 section 6. 422 o xpath: An xpath selection filter is an XPath expression that 423 returns a node set. When specified, updates will only come from 424 the selected data nodes. 426 These filters are intended to be used as selectors that define which 427 objects are within the scope of a subscription. A publisher MUST 428 support at least one type of selection filter. 430 Xpath itself provides powerful filtering constructs and care must be 431 used in filter definition. As an example, consider an xpath filter 432 with a boolean result; such a result will not provide an easily 433 interpretable subset of a datastore. Beyond the boolean example, it 434 is quite possible to define an xpath filter where results are easy 435 for an application to misinterpret. Consider an xpath filter which 436 only passes a datastore object when an interface is up. It is up to 437 the receiver to understand implications of the presence or absence of 438 objects in each update. 440 When the set of selection filtering criteria is applied for a 441 periodic subscription, all selected datastore nodes to which a 442 receiver has access are provided to that receiver. If the same 443 filtering criteria is applied to an on-change subscription, only the 444 subset of those datastore nodes supporting on-change is provided. A 445 datastore node which doesn't support on-change is never sent as part 446 of an on-change subscription's "push-update" or "push-change-update". 448 3.7. Streaming Updates 450 Contrary to traditional data retrieval requests, datastore 451 subscription enables an unbounded series of update records to be 452 streamed over time. Two generic YANG notifications for update 453 records have been defined for this: "push-update" and "push-change- 454 update". 456 A "push-update" notification defines a complete, filtered update of 457 the datastore per the terms of a subscription. This type of YANG 458 notification is used for continuous updates of periodic 459 subscriptions. A "push-update" notification can also be used for the 460 on-change subscriptions in two cases. First it will be used as the 461 initial "push-update" if there is a need to synchronize the receiver 462 at the start of a new subscription. It also MAY be sent if the 463 publisher later chooses to resynch an on-change subscription. The 464 "push-update" update record contains an instantiated datastore 465 subtree with all of the subscribed contents. The content of the 466 update record is equivalent to the contents that would be obtained 467 had the same data been explicitly retrieved using a datastore 468 retrieval operation using the same transport with the same filters 469 applied. 471 A "push-change-update" notification is the most common type of update 472 for on-change subscriptions. The update record in this case contains 473 the set of changes that datastore nodes have undergone since the last 474 notification message. In other words, this indicates which datastore 475 nodes have been created, deleted, or have had changes to their 476 values. In cases where multiple changes have occurred and the object 477 has not been deleted, the object's most current value is reported. 478 (In other words, for each object, only one change is reported, not 479 its entire history. Doing so would defeat the purpose of the 480 dampening period.) 482 These new "push-update" or "push-change-update" are encoded and 483 placed within notification messages, and ultimately queued for egress 484 over the specified transport. 486 The following is an example of a notification message for a 487 subscription tracking the operational status of a single Ethernet 488 port (per [RFC7223]). This notification message is encoded XML over 489 NETCONF as per [I-D.draft-ietf-netconf-netconf-event-notifications]. 491 492 2017-10-25T08:00:11.22Z 493 494 1011 495 496 497 498 eth0 499 up 500 501 502 503 504 506 Figure 1: Push example 508 The following is an example of an on-change notification message for 509 the same subscription. 511 512 2017-10-25T08:22:33.44Z 513 514 89 515 516 517 1 518 519 edit1 520 merge 521 /ietf-interfaces:interfaces-state 522 523 524 525 eth0 526 down 527 528 529 530 531 532 533 534 536 Figure 2: Push example for on change 538 Of note in the above example is the 'patch-id' with a value of '1'. 539 Per [RFC8072], the 'patch-id' is an arbitrary string. With YANG 540 Push, the publisher SHOULD put into the 'patch-id' a counter starting 541 at '1' which increments with every 'push-change-update' generated for 542 a subscription. If used as a counter, this counter MUST be reset to 543 '1' anytime a resynchronization occurs (i.e., with the sending of a 544 'push-update'). Also if used as a counter, the counter MUST be reset 545 to '1' the after passing a maximum value of '99999'. Such a 546 mechanism allows easy identification of lost or out-of-sequence 547 update records. 549 3.8. Subscription Management 551 The RPCs defined within 552 [I-D.draft-ietf-netconf-subscribed-notifications] have been enhanced 553 to support datastore subscription negotiation. Included in these 554 enhancements are error codes which can indicate why a datastore 555 subscription attempt has failed. 557 A datastore subscription can be rejected for multiple reasons. This 558 includes a too large subtree request, or the inability of the 559 publisher to push update records as frequently as requested. In such 560 cases, no subscription is established. Instead, the subscription- 561 result with the failure reason is returned as part of the RPC 562 response. As part of this response, a set of alternative 563 subscription parameters MAY be returned that would likely have 564 resulted in acceptance of the subscription request. The subscriber 565 may consider these as part of future subscription attempts. 567 The specific parameters to be returned in as part of the RPC error 568 response depend on the specific transport that is used to manage the 569 subscription. In the case of NETCONF 570 [I-D.draft-ietf-netconf-netconf-event-notifications], the NETCONF RPC 571 reply MUST include an "rpc-error" element with the following 572 additional elements: 574 o "error-type" of "application". 576 o "error-tag" of "operation-failed". 578 o Optionally, an "error-severity" of "error" (this MAY but does not 579 have to be included). 581 o "error-app-tag" with the value being a string that corresponds to 582 an identity with a base of "establish-subscription-error" (for 583 error responses to an establish-subscription request), "modify- 584 subscription-error" (for error responses to a modify-subscription 585 request), "delete-subscription-error" (for error responses to a 586 delete-subscription request), "resynch-subscription-error" (for 587 error responses to resynch-subscription request), or "kill- 588 subscription-error" (for error responses to a kill-subscription 589 request), respectively. 591 o In case of error responses to an establish-subscription or modify- 592 subscription request: optionally, "error-info" containing XML- 593 encoded data with hints regarding parameter settings that might 594 lead to successful requests in the future, per yang-data 595 definitions "establish-subscription-error-datastore" (for error 596 responses to an establish-subscription request) or "modify- 597 subscription-error-datastore (for error responses to a modify- 598 subscription request), respectively. In case of an rpc error as a 599 result of a delete-subscription, or a kill-subscription, or a 600 resynch-subscription request, no error-info needs to be included, 601 as the subscription-id is the only RPC input parameter and no 602 hints regarding RPC input parameters need to be provided. 604 For instance, for the following request: 606 608 611 612 ds:operational 613 614 616 /ex:foo 617 618 619 500 620 621 622 624 Figure 3: Establish-Subscription example 626 the publisher might return: 628 630 631 application 632 operation-failed 633 period-unsupported 634 635 638 639 2000 640 641 642 643 644 646 Figure 4: Error response example 648 3.9. Receiver Authorization 650 A receiver of subscription data MUST only be sent updates for which 651 they have proper authorization. A publisher MUST ensure that no non- 652 authorized data is included in push updates. To do so, it needs to 653 apply all corresponding checks applicable at the time of a specific 654 pushed update and if necessary silently remove any non-authorized 655 data from datastore subtrees. This enables YANG data pushed based on 656 subscriptions to be authorized equivalently to a regular data 657 retrieval (get) operation. 659 A publisher MUST allow for the possibility that a subscription's 660 selection filter references non-existent or access-protected data. 661 Such support permits a receiver the ability to monitor the entire 662 lifecyle of some datastore tree. In this case, all "push-update" 663 notifications must be sent empty, and no "push-change-update" 664 notifications will be sent until some data becomes visible for a 665 receiver. 667 A publisher MAY choose reject an establish-subscription request which 668 selects non-existent or access-protected data. In addition, a 669 publisher MAY choose to terminate a dynamic subscription or suspend a 670 configured receiver when the authorization privileges of a receiver 671 change, or the access controls for subscribed objects change. Such a 672 capability enables the publisher to avoid having to support a 673 continuous, and total filtering of an entire subscription's content. 675 In these cases above, the error identity "unchanging-selection" 676 SHOULD be returned. This reduces the possibility of leakage of 677 access controlled objects. 679 Each "push-update" and "push-change-update" MUST have access control 680 applied. This includes validating that read access is permitted for 681 any new objects selected since the last notification message was sent 682 to a particular each receiver. To accomplish this, implementations 683 SHOULD support the conceptual authorization model of [RFC6536bis], 684 Section 3.2.4. 686 +-----------------+ +--------------------+ 687 push-update or --> | datastore node | yes | add datastore node | 688 push-change-update | access allowed? | ---> | to update message | 689 +-----------------+ +--------------------+ 691 Figure 5: Updated [rfc6536bis] access control for push updates 693 If read access into previously accessible nodes has been lost due to 694 a receiver permissions change, this SHOULD be reported as a patch 695 "delete" operation for on-change subscriptions. If not capable of 696 handling such receiver permission changes with such a "delete", 697 publisher implementations MUST force dynamic subscription re- 698 establishment or configured subscription re-initialization so that 699 appropriate filtering is installed. 701 3.10. On-change Notifiable YANG objects 703 In some cases, a publisher supporting on-change notifications may not 704 be able to push updates for some object types on-change. Reasons for 705 this might be that the value of the datastore node changes frequently 706 (e.g., [RFC7223]'s in-octets counter), that small object changes are 707 frequent and meaningless (e.g., a temperature gauge changing 0.1 708 degrees), or that the implementation is not capable of on-change 709 notification for a particular object. 711 In those cases, it will be important for client applications to have 712 a way to identify for which objects on-change notifications are 713 supported and for which ones they are not supported. Otherwise 714 client applications will have no way of knowing whether they can 715 indeed rely on their on-change subscription to provide them with the 716 change updates that they are interested in. In other words, if 717 implementations do not provide a solution and do not support 718 comprehensive on-change notifiability, clients of those 719 implementations will have no way of knowing what their on-change 720 subscription actually covers. 722 Implementations are therefore strongly advised to provide a solution 723 to this problem. It is expected that such a solution will be 724 standardized at some point in the future. In the meantime and until 725 this occurs, implementations will be expected to provide their own 726 solution. 728 3.11. Other Considerations 730 3.11.1. Robustness and reliability 732 Particularly in the case of on-change updates, it is important that 733 these updates do not get lost. Or in case the loss of an update is 734 unavoidable, it is critical that the receiver is notified 735 accordingly. 737 Update records for a single subscription MAY NOT be resequenced prior 738 to transport. 740 It is conceivable that under certain circumstances, a publisher will 741 recognize that it is unable to include within an update record the 742 full set of objects desired per the terms of a subscription. In this 743 case, the publisher MUST take one or more of the following actions. 745 o A publisher MUST set the "incomplete-update" flag on any update 746 record which is known to be missing information. 748 o It MAY choose to suspend a subscription as per 749 [I-D.draft-ietf-netconf-subscribed-notifications]. 751 o When resuming an on-change subscription, the publisher SHOULD 752 generate a complete patch from the previous update record. If 753 this is not possible and the "no-synch-on-start" option is not 754 present for the subscription, then the full datastore contents MAY 755 be sent via a "push-update" instead (effectively replacing the 756 previous contents). If neither of these are possible, then an 757 "incomplete-update" flag MUST be included on the next "push- 758 change-update". 760 Note: It is perfectly acceptable to have a series of "push-change- 761 update" notifications (and even "push update" notifications) serially 762 queued at the transport layer awaiting transmission. It is not 763 required to merge pending update messages. I.e., the dampening 764 period applies to update record creation, not transmission. 766 3.11.2. Publisher capacity 768 It is far preferable to decline a subscription request than to accept 769 such a request when it cannot be met. 771 Whether or not a subscription can be supported will be determined by 772 a combination of several factors such as the subscription trigger 773 (on-change or periodic), the period in which to report changes (one 774 second periods will consume more resources than one hour periods), 775 the amount of data in the datastore subtree that is being subscribed 776 to, and the number and combination of other subscriptions that are 777 concurrently being serviced. 779 4. A YANG data model for management of datastore push subscriptions 781 4.1. Overview 783 The YANG data model for datastore push subscriptions is depicted in 784 the following figure. Following YANG tree convention in the 785 depiction, brackets enclose list keys, "rw" means configuration, "ro" 786 operational state data, "?" designates optional nodes, "*" designates 787 nodes that can have multiple instances. Parentheses with a name in 788 the middle enclose choice and case nodes. New schema objects defined 789 here (i.e., beyond those from 790 [I-D.draft-ietf-netconf-subscribed-notifications]) are identified 791 with "yp". 793 module: ietf-subscribed-notifications 794 +--ro streams 795 | +--ro stream* [name] 796 | +--ro name string 797 | +--ro description string 798 | +--ro replay-support? empty {replay}? 799 | +--ro replay-log-creation-time? yang:date-and-time {replay}? 800 | +--ro replay-log-aged-time? yang:date-and-time {replay}? 801 +--rw filters 802 | +--rw stream-filter* [identifier] 803 | | +--rw identifier filter-id 804 | | +--rw (filter-spec)? 805 | | +--:(stream-subtree-filter) 806 | | | +--rw stream-subtree-filter? {subtree}? 807 | | +--:(stream-xpath-filter) 808 | | +--rw stream-xpath-filter? yang:xpath1.0 {xpath}? 809 | +--rw yp:selection-filter* [identifier] 810 | +--rw yp:identifier sn:filter-id 811 | +--rw (yp:filter-spec)? 812 | +--:(yp:datastore-subtree-filter) 813 | | +--rw yp:datastore-subtree-filter? 814 | | {sn:subtree}? 815 | +--:(yp:datastore-xpath-filter) 816 | +--rw yp:datastore-xpath-filter? 817 | yang:xpath1.0 {sn:xpath}? 818 +--rw subscriptions 819 +--rw subscription* [identifier] 820 +--rw identifier subscription-id 821 +--ro configured-subscription-state? enumeration {configured}? 822 +--rw purpose? string {configured}? 823 +--rw protocol transport {configured}? 824 +--rw encoding encoding 825 +--rw (target) 826 | +--:(stream) 827 | | +--rw (stream-filter)? 828 | | | +--:(by-reference) 829 | | | | +--rw stream-filter-ref stream-filter-ref 830 | | | +--:(within-subscription) 831 | | | +--rw (filter-spec)? 832 | | | +--:(stream-subtree-filter) 833 | | | | +--rw stream-subtree-filter? 834 | | | {subtree}? 835 | | | +--:(stream-xpath-filter) 836 | | | +--rw stream-xpath-filter? 837 | | | yang:xpath1.0 {xpath}? 838 | | +--rw stream stream-ref 839 | | +--rw replay-start-time? yang:date-and-time {replay}? 840 | +--:(yp:datastore) 841 | +--rw yp:datastore identityref 842 | +--rw (yp:selection-filter)? 843 | +--:(yp:by-reference) 844 | | +--rw yp:selection-filter-ref selection-filter-ref 845 | +--:(yp:within-subscription) 846 | +--rw (yp:filter-spec)? 847 | +--:(yp:datastore-subtree-filter) 848 | | +--rw yp:datastore-subtree-filter? 849 | {sn:subtree}? 850 | +--:(yp:datastore-xpath-filter) 851 | +--rw yp:datastore-xpath-filter? 852 | yang:xpath1.0 {sn:xpath}? 853 +--rw stop-time? yang:date-and-time 854 +--rw dscp? inet:dscp {qos}? 855 +--rw weighting? uint8 {qos}? 856 +--rw dependency? subscription-id {qos}? 857 +--rw (notification-message-origin)? 858 | +--:(interface-originated) 859 | | +--rw source-interface? if:interface-ref 860 | +--:(address-originated) 861 | +--rw source-vrf? -> 862 | /ni:network-instances/network-instance/name {supports-vrf}? 863 | +--rw source-address? inet:ip-address-no-zone 864 +--rw receivers 865 | +--rw receiver* [address port] 866 | +--rw address inet:host 867 | +--rw port inet:port-number 868 | +--ro pushed-notifications? yang:counter64 869 | +--ro excluded-notifications? yang:counter64 870 | +--ro status enumeration 871 | +---x reset 872 | +--ro output 873 | +--ro time yang:date-and-time 874 +--rw (yp:update-trigger)? 875 +--:(yp:periodic) 876 | +--rw yp:periodic! 877 | +--rw yp:period yang:timeticks 878 | +--rw yp:anchor-time? yang:date-and-time 879 +--:(yp:on-change) {on-change}? 880 +--rw yp:on-change! 881 +--rw yp:dampening-period? yang:timeticks 882 +--rw yp:no-synch-on-start? empty 883 +--rw yp:excluded-change* change-type 885 rpcs: 886 +---x establish-subscription 887 | +---w input 888 | | +---w encoding? encoding 889 | | +---w (target) 890 | | | +--:(stream) 891 | | | | +---w (stream-filter)? 892 | | | | | +--:(by-reference) 893 | | | | | | +---w stream-filter-ref stream-filter-ref 894 | | | | | +--:(within-subscription) 895 | | | | | +---w (filter-spec)? 896 | | | | | +--:(stream-subtree-filter) 897 | | | | | | +---w stream-subtree-filter? 898 | | | | | {subtree}? 899 | | | | | +--:(stream-xpath-filter) 900 | | | | | +---w stream-xpath-filter? 901 | | | | | yang:xpath1.0 {xpath}? 902 | | | | +---w stream stream-ref 903 | | | | +---w replay-start-time? yang:date-and-time {replay}? 904 | | | +--:(yp:datastore) 905 | | | +---w yp:datastore identityref 906 | | | +---w (yp:selection-filter)? 907 | | | +--:(yp:by-reference) 908 | | | | +---w yp:selection-filter-ref selection-filter-ref 909 | | | +--:(yp:within-subscription) 910 | | | +---w (yp:filter-spec)? 911 | | | +--:(yp:datastore-subtree-filter) 912 | | | | +---w yp:datastore-subtree-filter? 913 | | | | {sn:subtree}? 914 | | | +--:(yp:datastore-xpath-filter) 915 | | | +---w yp:datastore-xpath-filter? 916 | | | yang:xpath1.0 {sn:xpath}? 917 | | +---w stop-time? yang:date-and-time 918 | | +---w dscp? inet:dscp {qos}? 919 | | +---w weighting? uint8 {qos}? 920 | | +---w dependency? subscription-id {qos}? 921 | | +---w (yp:update-trigger)? 922 | | +--:(yp:periodic) 923 | | | +---w yp:periodic! 924 | | | +---w yp:period yang:timeticks 925 | | | +---w yp:anchor-time? yang:date-and-time 926 | | +--:(yp:on-change) {on-change}? 927 | | +---w yp:on-change! 928 | | +---w yp:dampening-period? yang:timeticks 929 | | +---w yp:no-synch-on-start? empty 930 | | +---w yp:excluded-change* change-type 931 | +--ro output 932 | +--ro identifier subscription-id 933 +---x modify-subscription 934 | +---w input 935 | +---w identifier? subscription-id 936 | +---w (target) 937 | | +--:(stream) 938 | | | +---w (stream-filter)? 939 | | | +--:(by-reference) 940 | | | | +---w stream-filter-ref stream-filter-ref 941 | | | +--:(within-subscription) 942 | | | +---w (filter-spec)? 943 | | | +--:(stream-subtree-filter) 944 | | | | +---w stream-subtree-filter? 945 | | | {subtree}? 946 | | | +--:(stream-xpath-filter) 947 | | | +---w stream-xpath-filter? 948 | | | yang:xpath1.0 {xpath}? 949 | | +--:(yp:datastore) 950 | | +---w (yp:selection-filter)? 951 | | +--:(yp:by-reference) 952 | | | +---w yp:selection-filter-ref selection-filter-ref 953 | | +--:(yp:within-subscription) 954 | | +---w (yp:filter-spec)? 955 | | +--:(yp:datastore-subtree-filter) 956 | | | +---w yp:datastore-subtree-filter? 957 | | | {sn:subtree}? 958 | | +--:(yp:datastore-xpath-filter) 959 | | +---w yp:datastore-xpath-filter? 960 | | yang:xpath1.0 {sn:xpath}? 961 | +---w stop-time? yang:date-and-time 962 | +---w (yp:update-trigger)? 963 | +--:(yp:periodic) 964 | | +---w yp:periodic! 965 | | +---w yp:period yang:timeticks 966 | | +---w yp:anchor-time? yang:date-and-time 967 | +--:(yp:on-change) {on-change}? 968 | +---w yp:on-change! 969 | +---w yp:dampening-period? yang:timeticks 970 +---x delete-subscription 971 | +---w input 972 | +---w identifier subscription-id 973 +---x kill-subscription 974 +---w input 975 +---w identifier subscription-id 977 yang-data (for placement into rpc error responses) 978 +-- establish-subscription-error-stream 979 | +--ro reason? identityref 980 | +--ro filter-failure-hint? string 981 | +--ro replay-start-time-hint? yang:date-and-time 982 +-- modify-subscription-error-stream 983 +--ro reason? identityref 984 +--ro filter-failure-hint? string 986 notifications: 987 +---n replay-completed {replay}? 988 | +--ro identifier subscription-id 989 +---n subscription-completed 990 | +--ro identifier subscription-id 991 +---n subscription-started {configured}? 992 | +--ro identifier subscription-id 993 | +--ro protocol transport {configured}? 994 | +--ro encoding encoding 995 | +--ro (target) 996 | | +--:(stream) 997 | | | +--ro (stream-filter)? 998 | | | | +--:(by-reference) 999 | | | | | +--ro stream-filter-ref stream-filter-ref 1000 | | | | +--:(within-subscription) 1001 | | | | +--ro (filter-spec)? 1002 | | | | +--:(stream-subtree-filter) 1003 | | | | | +--ro stream-subtree-filter? 1004 | | | | | {subtree}? 1005 | | | | +--:(stream-xpath-filter) 1006 | | | | +--ro stream-xpath-filter? 1007 | | | | yang:xpath1.0 {xpath}? 1008 | | | +--ro stream stream-ref 1009 | | | +--ro replay-start-time? yang:date-and-time {replay}? 1010 | | +--:(yp:datastore) 1011 | | +--ro yp:datastore identityref 1012 | | +--ro (yp:selection-filter)? 1013 | | +--:(yp:by-reference) 1014 | | | +--ro yp:selection-filter-ref selection-filter-ref 1015 | | +--:(yp:within-subscription) 1016 | | +--ro (yp:filter-spec)? 1017 | | +--:(yp:datastore-subtree-filter) 1018 | | | +--ro yp:datastore-subtree-filter? 1019 | | {sn:subtree}? 1020 | | +--:(yp:datastore-xpath-filter) 1021 | | +--ro yp:datastore-xpath-filter? 1022 | | yang:xpath1.0 {sn:xpath}? 1023 | +--ro stop-time? yang:date-and-time 1024 | +--ro dscp? inet:dscp {qos}? 1025 | +--ro weighting? uint8 {qos}? 1026 | +--ro dependency? subscription-id {qos}? 1027 | +--ro (yp:update-trigger)? 1028 | +--:(yp:periodic) 1029 | | +--ro yp:periodic! 1030 | | +--ro yp:period yang:timeticks 1031 | | +--ro yp:anchor-time? yang:date-and-time 1032 | +--:(yp:on-change) {on-change}? 1033 | +--ro yp:on-change! 1034 | +--ro yp:dampening-period? yang:timeticks 1035 | +--ro yp:no-synch-on-start? empty 1036 | +--ro yp:excluded-change* change-type 1037 +---n subscription-resumed 1038 | +--ro identifier subscription-id 1039 +---n subscription-modified 1040 | +--ro identifier subscription-id 1041 | +--ro protocol transport {configured}? 1042 | +--ro encoding encoding 1043 | +--ro (target) 1044 | | +--:(stream) 1045 | | | +--ro (stream-filter)? 1046 | | | | +--:(by-reference) 1047 | | | | | +--ro stream-filter-ref stream-filter-ref 1048 | | | | +--:(within-subscription) 1049 | | | | +--ro (filter-spec)? 1050 | | | | +--:(stream-subtree-filter) 1051 | | | | | +--ro stream-subtree-filter? 1052 | | | | | {subtree}? 1053 | | | | +--:(stream-xpath-filter) 1054 | | | | +--ro stream-xpath-filter? 1055 | | | | yang:xpath1.0 {xpath}? 1056 | | | +--ro stream stream-ref 1057 | | | +--ro replay-start-time? yang:date-and-time {replay}? 1058 | | +--:(yp:datastore) 1059 | | +--ro yp:datastore identityref 1060 | | +--ro (yp:selection-filter)? 1061 | | +--:(yp:by-reference) 1062 | | | +--ro yp:selection-filter-ref selection-filter-ref 1063 | | +--:(yp:within-subscription) 1064 | | +--ro (yp:filter-spec)? 1065 | | +--:(yp:datastore-subtree-filter) 1066 | | | +--ro yp:datastore-subtree-filter? 1067 | | | {sn:subtree}? 1068 | | +--:(yp:datastore-xpath-filter) 1069 | | +--ro yp:datastore-xpath-filter? 1070 | | yang:xpath1.0 {sn:xpath}? 1071 | +--ro stop-time? yang:date-and-time 1072 | +--ro dscp? inet:dscp {qos}? 1073 | +--ro weighting? uint8 {qos}? 1074 | +--ro dependency? subscription-id {qos}? 1075 | +--ro (yp:update-trigger)? 1076 | +--:(yp:periodic) 1077 | | +--ro yp:periodic! 1078 | | +--ro yp:period yang:timeticks 1079 | | +--ro yp:anchor-time? yang:date-and-time 1080 | +--:(yp:on-change) {on-change}? 1081 | +--ro yp:on-change! 1082 | +--ro yp:dampening-period? yang:timeticks 1083 | +--ro yp:no-synch-on-start? empty 1084 | +--ro yp:excluded-change* change-type 1085 +---n subscription-terminated 1086 | +--ro identifier subscription-id 1087 | +--ro reason identityref 1088 +---n subscription-suspended 1089 +--ro identifier subscription-id 1090 +--ro reason identityref 1092 module: ietf-yang-push 1094 rpcs: 1095 +---x resynch-subscription {on-change}? 1096 +---w input 1097 +---w identifier sn:subscription-id 1099 yang-data: (for placement into rpc error responses) 1100 +-- resynch-subscription-error 1101 | +--ro reason? identityref 1102 | +--ro period-hint? timeticks 1103 | +--ro filter-failure-hint? string 1104 | +--ro object-count-estimate? uint32 1105 | +--ro object-count-limit? uint32 1106 | +--ro kilobytes-estimate? uint32 1107 | +--ro kilobytes-limit? uint32 1108 +-- establish-subscription-error-datastore 1109 | +--ro reason? identityref 1110 | +--ro period-hint? timeticks 1111 | +--ro filter-failure-hint? string 1112 | +--ro object-count-estimate? uint32 1113 | +--ro object-count-limit? uint32 1114 | +--ro kilobytes-estimate? uint32 1115 | +--ro kilobytes-limit? uint32 1116 +-- modify-subscription-error-datastore 1117 +--ro reason? identityref 1118 +--ro period-hint? timeticks 1119 +--ro filter-failure-hint? string 1120 +--ro object-count-estimate? uint32 1121 +--ro object-count-limit? uint32 1122 +--ro kilobytes-estimate? uint32 1123 +--ro kilobytes-limit? uint32 1125 notifications: 1126 +---n push-update 1127 | +--ro subscription-id? sn:subscription-id 1128 | +--ro incomplete-update? empty 1129 | +--ro datastore-contents? 1130 +---n push-change-update {on-change}? 1131 +--ro subscription-id? sn:subscription-id 1132 +--ro incomplete-update? empty 1133 +--ro datastore-changes? 1135 Figure 6: Model structure 1137 Selected components of the model are summarized below. 1139 4.2. Subscription configuration 1141 Both configured and dynamic subscriptions are represented within the 1142 list subscription. New and enhanced parameters extending the basic 1143 subscription data model in 1144 [I-D.draft-ietf-netconf-subscribed-notifications] include: 1146 o The targeted datastore from which the selection is being made. 1147 The potential datastores include those from 1148 [I-D.draft-ietf-netmod-revised-datastores]. A platform may also 1149 choose to support a custom datastore. 1151 o A selection filter identifying yang nodes of interest within a 1152 datastore. Filter contents are specified via a reference to an 1153 existing filter, or via an in-line definition for only that 1154 subscription. Referenced filters allows an implementation to 1155 avoid evaluating filter acceptability during a dynamic 1156 subscription request. The case statement differentiates the 1157 options. 1159 o For periodic subscriptions, triggered updates will occur at the 1160 boundaries of a specified time interval. These boundaries many be 1161 calculated from the periodic parameters: 1163 * a "period" which defines duration between period push updates. 1165 * an "anchor-time"; update intervals always fall on the points in 1166 time that are a multiple of a "period" from an "anchor-time". 1167 If "anchor-time" is not provided, then the "anchor-time" MUST 1168 be set with the creation time of the initial update record. 1170 o For on-change subscriptions, assuming any dampening period has 1171 completed, triggering occurs whenever a change in the subscribed 1172 information is detected. On-change subscriptions have more 1173 complex semantics that is guided by its own set of parameters: 1175 * a "dampening-period" specifies the interval that must pass 1176 before a successive update for the subscription is sent. If no 1177 dampening period is in effect, the update is sent immediately. 1179 If a subsequent change is detected, another update is only sent 1180 once the dampening period has passed for this subscription. 1182 * an "excluded-change" flag which allows restriction of the types 1183 of changes for which updates should be sent (e.g., only add to 1184 an update record on object creation). 1186 * a "no-synch-on-start" flag which specifies whether a complete 1187 update with all the subscribed data is to be sent at the 1188 beginning of a subscription. 1190 4.3. YANG Notifications 1192 4.3.1. State Change Notifications 1194 Subscription state notifications and mechanism are reused from 1195 [I-D.draft-ietf-netconf-subscribed-notifications]. Some have been 1196 augmented to include the datastore specific objects. 1198 4.3.2. Notifications for Subscribed Content 1200 Along with the subscribed content, there are other objects which 1201 might be part of a "push-update" or "push-change-update" 1203 A "subscription-id" MUST be transported along with the subscribed 1204 contents. An [RFC5277] Section 4 one-way notification MAY be used 1205 for encoding updates. Where it is, the relevant "subscription-id" 1206 MUST be encoded as the first element within each "push-update" or 1207 "push-change-update". This allows a receiver to differentiate which 1208 subscription resulted in a particular push. 1210 A "time-of-update" which represents the time an update record 1211 snapshot was generated. A receiver MAY assume that a publisher's 1212 objects have these pushed values at this point in time. 1214 An "incomplete-update" object. This object indicates that not all 1215 changes which have occurred since the last update are actually 1216 included with this update. In other words, the publisher has failed 1217 to fulfill its full subscription obligations. (For example a 1218 datastore was unable to providing the full set of datastore nodes to 1219 a publisher process.) To facilitate re-synchronization of on-change 1220 subscriptions, a publisher MAY subsequently send a "push-update" 1221 containing a full selection snapshot of subscribed data. 1223 4.4. YANG RPCs 1225 YANG-Push subscriptions are established, modified, and deleted using 1226 RPCs augmented from 1227 [I-D.draft-ietf-netconf-subscribed-notifications]. 1229 4.4.1. Establish-subscription RPC 1231 The subscriber sends an establish-subscription RPC with the 1232 parameters in section 3.1. An example might look like: 1234 1236 1239 1240 1241 ds:operational 1242 1243 1246 1247 1248 500 1249 1250 1251 1253 Figure 7: Establish-subscription RPC 1255 The publisher MUST respond explicitly positively (i.e., subscription 1256 accepted) or negatively (i.e., subscription rejected) to the request. 1257 Positive responses include the "identifier" of the accepted 1258 subscription. In that case a publisher MAY respond: 1260 1262 1264 ok 1265 1266 1268 52 1269 1270 1272 Figure 8: Establish-subscription positive RPC response 1274 A subscription can be rejected for multiple reasons, including the 1275 lack of authorization to establish a subscription, no capacity to 1276 serve the subscription at the publisher, or the inability of the 1277 publisher to select datastore content at the requested cadence. 1279 If a request is rejected because the publisher is not able to serve 1280 it, the publisher SHOULD include in the returned error hints which 1281 help a subscriber understand subscription parameters might have been 1282 accepted for the request. These hints would be included within the 1283 yang-data structure "establish-subscription-error-datastore". 1284 However even with these hints, there are no guarantee that subsequent 1285 requests will in fact be accepted. 1287 The specific parameters to be returned in as part of the RPC error 1288 response depend on the specific transport that is used to manage the 1289 subscription. In the case of NETCONF 1290 [I-D.draft-ietf-netconf-netconf-event-notifications], when a 1291 subscription request is rejected, the NETCONF RPC reply MUST include 1292 an "rpc-error" element with the following elements: 1294 o "error-type" of "application". 1296 o "error-tag" of "operation-failed". 1298 o Optionally, an "error-severity" of "error" (this MAY but does not 1299 have to be included). 1301 o "error-app-tag" with the value being a string that corresponds to 1302 an identity with a base of "establish-subscription-error". 1304 o Optionally, "error-info" containing XML-encoded data with hints 1305 for parameter settings that might result in future RPC success per 1306 yang-data definition "establish-subscription-error-datastore". 1308 For example, for the following request: 1310 1312 1315 1317 ds:operational 1318 1319 1321 /ex:foo 1322 1323 1324 100 1325 1326 1327 1329 Figure 9: Establish-subscription request example 2 1331 a publisher that cannot serve on-change updates but periodic updates 1332 might return the following: 1334 1336 1337 application 1338 operation-failed 1339 error 1340 1341 on-change-unsupported 1342 1343 1345 /yp:periodic/yp:period 1346 1347 1348 1350 Figure 10: Establish-subscription error response example 2 1352 4.4.2. Modify-subscription RPC 1354 The subscriber MAY invoke the "modify-subscription" RPC for a 1355 subscription it previously established. The subscriber will include 1356 newly desired values in the "modify-subscription" RPC. Parameters 1357 not included MUST remain unmodified. Below is an example where a 1358 subscriber attempts to modify the "period" of a subscription. 1360 1362 1365 1011 1366 1368 ds:operational 1369 1370 1372 /ex:bar 1373 1374 1375 250 1376 1377 1378 1380 Figure 11: Modify subscription request 1382 The publisher MUST respond explicitly positively or negatively to the 1383 request. If the subscription modification is rejected, the 1384 subscription is maintained as it was before the modification request. 1385 In addition, the publisher MUST send an rpc error response. This rpc 1386 error response may contain hints encapsulated within the yang-data 1387 structure "modify-subscription-error-datastore". A subscription MAY 1388 be modified multiple times. 1390 The specific parameters to be returned in as part of the RPC error 1391 response depend on the specific transport that is used to manage the 1392 subscription. In the case of NETCONF 1393 [I-D.draft-ietf-netconf-netconf-event-notifications], when a 1394 subscription request is rejected, the NETCONF RPC reply MUST include 1395 an "rpc-error" element with the following elements: 1397 o "error-type" of "application". 1399 o "error-tag" of "operation-failed". 1401 o Optionally, an "error-severity" of "error" (this MAY but does not 1402 have to be included). 1404 o "error-app-tag" with the value being a string that corresponds to 1405 an identity with a base of "modify-subscription-error". 1407 o "error-path" pointing to the object or parameter that caused the 1408 rejection. 1410 o Optionally, "error-info" containing XML-encoded data with hints 1411 for parameter settings that might result in future RPC success per 1412 yang-data definition "modify-subscription-error-datastore". 1414 A configured subscription cannot be modified using "modify- 1415 subscription" RPC. Instead, the configuration needs to be edited as 1416 needed. 1418 4.4.3. Delete-subscription RPC 1420 To stop receiving updates from a subscription and effectively delete 1421 a subscription that had previously been established using an 1422 "establish-subscription" RPC, a subscriber can send a "delete- 1423 subscription" RPC, which takes as only input the subscription's 1424 "identifier". This RPC is unmodified from 1425 [I-D.draft-ietf-netconf-subscribed-notifications]. 1427 4.4.4. Resynch-subscription RPC 1429 This RPC is only applicable only for on-change subscriptions 1430 previously established using an "establish-subscription" RPC. For 1431 example: 1433 1435 1438 1011 1439 1440 1442 Resynch subscription 1444 On receipt, a publisher must either accept the request and quickly 1445 follow with a "push-update", or send an appropriate error within an 1446 rpc error response. Within an error response, the publisher may 1447 include supplemental information about the reasons within the yang- 1448 data structure "resynch-subscription-error". 1450 4.4.5. YANG Module Synchronization 1452 To make subscription requests, the subscriber needs to know the YANG 1453 module library available on the publisher. The YANG 1.0 module 1454 library information is sent by a NETCONF server in the NETCONF 1455 "hello" message. For YANG 1.1 modules and all modules used with the 1456 RESTCONF [RFC8040] protocol, this information is provided by the YANG 1457 Library module (ietf-yang-library.yang from [RFC7895]. This YANG 1458 library information is important for the receiver to reproduce the 1459 set of object definitions used within the publisher. 1461 The YANG library includes a module list with the name, revision, 1462 enabled features, and applied deviations for each YANG module 1463 implemented by the publisher. The receiver is expected to know the 1464 YANG library information before starting a subscription. The 1465 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module 1466 can be used to cache the YANG library information. 1468 The set of modules, revisions, features, and deviations can change at 1469 run-time (if supported by the publisher implementation). In this 1470 case, the receiver needs to be informed of module changes before 1471 datastore nodes from changed modules can be processed correctly. The 1472 YANG library provides a simple "yang-library-change" notification 1473 that informs the subscriber that the library has changed. The 1474 receiver then needs to re-read the entire YANG library data for the 1475 replicated publisher in order to detect the specific YANG library 1476 changes. The "ietf-netconf-notifications" module defined in 1477 [RFC6470] contains a "netconf-capability-change" notification that 1478 can identify specific module changes. For example, the module URI 1479 capability of a newly loaded module will be listed in the "added- 1480 capability" leaf-list, and the module URI capability of an removed 1481 module will be listed in the "deleted-capability" leaf-list. 1483 5. YANG module 1485 ; file "ietf-yang-push@2018-02-23.yang" 1486 module ietf-yang-push { 1487 yang-version 1.1; 1488 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1489 prefix yp; 1491 import ietf-yang-types { 1492 prefix yang; 1493 } 1494 import ietf-subscribed-notifications { 1495 prefix sn; 1496 } 1497 import ietf-datastores { 1498 prefix ds; 1499 } 1500 import ietf-restconf { 1501 prefix rc; 1502 } 1504 organization "IETF"; 1505 contact 1506 "WG Web: 1507 WG List: 1509 Editor: Alexander Clemm 1510 1512 Editor: Eric Voit 1513 1515 Editor: Alberto Gonzalez Prieto 1516 1518 Editor: Ambika Prasad Tripathy 1519 1521 Editor: Einar Nilsen-Nygaard 1522 1524 Editor: Andy Bierman 1525 1527 Editor: Balazs Lengyel 1528 "; 1530 description 1531 "This module contains YANG specifications for YANG push."; 1533 revision 2018-02-23 { 1534 description 1535 "Initial revision."; 1536 reference 1537 "draft-ietf-netconf-yang-push-15"; 1538 } 1540 /* 1541 * FEATURES 1542 */ 1544 feature on-change { 1545 description 1546 "This feature indicates that on-change triggered subscriptions 1547 are supported."; 1548 } 1550 /* 1551 * IDENTITIES 1552 */ 1554 /* Error type identities for datastore subscription */ 1556 identity resynch-subscription-error { 1557 description 1558 "Problem found while attempting to fulfill an 1559 'resynch-subscription' RPC request. "; 1560 } 1562 identity cant-exclude { 1563 base sn:establish-subscription-error; 1564 description 1565 "Unable to remove the set of 'excluded-changes'. This means the 1566 publisher is unable to restrict 'push-change-update's to just the 1567 change types requested for this subscription."; 1568 } 1570 identity datastore-not-subscribable { 1571 base sn:establish-subscription-error; 1572 base sn:subscription-terminated-reason; 1573 description 1574 "This is not a subscribable datastore."; 1575 } 1577 identity no-such-subscription-resynch { 1578 base resynch-subscription-error; 1579 description 1580 "Referenced subscription doesn't exist. This may be as a result of 1581 a non-existent subscription ID, an ID which belongs to another 1582 subscriber, or an ID for configured subscription."; 1583 } 1585 identity on-change-unsupported { 1586 base sn:establish-subscription-error; 1587 description 1588 "On-change is not supported for any objects which are selectable 1589 by this filter."; 1590 } 1592 identity on-change-synch-unsupported { 1593 base sn:establish-subscription-error; 1594 description 1595 "Neither synch on start nor resynchronization are supported for 1596 this subscription. This error will be used for two reasons. First 1597 if an 'establish-subscription' RPC doesn't include 1598 'no-synch-on-start', yet the publisher can't support sending a 1599 'push-update' for this subscription for reasons other than 1600 'on-change-unsupported' or 'synchronization-size'. And second, if 1601 the 'resynch-subscription' RPC is invoked either for an existing 1602 periodic subscription, or for an on-change subscription which 1603 can't support resynchronization."; 1604 } 1606 identity period-unsupported { 1607 base sn:establish-subscription-error; 1608 base sn:modify-subscription-error; 1609 base sn:subscription-suspended-reason; 1610 description 1611 "Requested time period is too short. This can be for both 1612 periodic and on-change subscriptions (with or without 1613 dampening.) 1615 Hints suggesting alternative periods may be returned as 1616 supplemental information when this expressed."; 1617 } 1619 identity result-too-big { 1620 base sn:establish-subscription-error; 1621 base sn:modify-subscription-error; 1622 base sn:subscription-suspended-reason; 1623 description 1624 "Periodic or on-change push update datatrees exceed a maximum size 1625 limit. Hints on estimated size of what was too big may be 1626 returned as supplemental information when this expressed."; 1627 } 1629 identity synchronization-size { 1630 base sn:establish-subscription-error; 1631 base sn:modify-subscription-error; 1632 base resynch-subscription-error; 1633 base sn:subscription-suspended-reason; 1634 description 1635 "Synch-on-start or resynchronization datatree exceeds a maximum 1636 size limit. 1638 Where this identity is referenced as an 'error-app-tag' within an 1639 RPC response, the response's 'error-info' may contain:"; 1640 } 1641 identity unchanging-selection { 1642 base sn:establish-subscription-error; 1643 base sn:modify-subscription-error; 1644 base sn:subscription-terminated-reason; 1645 description 1646 "Selection filter is unlikely to ever select datatree nodes. This 1647 means that based on the subscriber's current access rights, the 1648 publisher recognizes that the selection filter is unlikely to ever 1649 select datatree nodes which change. Examples for this might be 1650 that node or subtree doesn't exist, read access is not permitted 1651 for a receiver, or static objects that only change at reboot have 1652 been chosen."; 1653 } 1655 /* 1656 * TYPE DEFINITIONS 1657 */ 1659 typedef change-type { 1660 type enumeration { 1661 enum "create" { 1662 description 1663 "Create a new data resource if it does not already exist. If 1664 it already exists, replace it."; 1665 } 1666 enum "delete" { 1667 description 1668 "Delete a data resource if it already exists. If it does not 1669 exist, take no action."; 1670 } 1671 enum "insert" { 1672 description 1673 "Insert a new user-ordered data resource"; 1674 } 1675 enum "merge" { 1676 description 1677 "merge the edit value with the target data resource; create 1678 if it does not already exist"; 1679 } 1680 enum "move" { 1681 description 1682 "Reorder the target data resource"; 1683 } 1684 enum "replace" { 1685 description 1686 "Replace the target data resource with the edit value"; 1687 } 1688 enum "remove" { 1689 description 1690 "Remove a data resource if it already exists "; 1691 } 1692 } 1693 description 1694 "Specifies different types of datastore changes."; 1695 reference 1696 "RFC 8072 section 2.5, with a delta that it is valid for a 1697 receiver to process an update record which performs a create 1698 operation on a datastore node the receiver believes exists, or to 1699 process a delete on a datastore node the receiver believes is 1700 missing."; 1701 } 1703 typedef selection-filter-ref { 1704 type leafref { 1705 path "/sn:filters/yp:selection-filter/yp:identifier"; 1706 } 1707 description 1708 "This type is used to reference a selection filter."; 1709 } 1711 /* 1712 * GROUP DEFINITIONS 1713 */ 1715 grouping datastore-criteria { 1716 description 1717 "A grouping to define criteria for which selected objects from 1718 a targeted datastore should be included in push updates."; 1719 leaf datastore { 1720 type identityref { 1721 base ds:datastore; 1722 } 1723 mandatory true; 1724 description 1725 "Datastore from which to retrieve data."; 1726 } 1727 uses selection-filter-objects; 1728 } 1730 grouping selection-filter-types { 1731 description 1732 "This grouping defines the types of selectors for objects from a 1733 datastore."; 1734 choice filter-spec { 1735 description 1736 "The content filter specification for this request."; 1738 anydata datastore-subtree-filter { 1739 if-feature "sn:subtree"; 1740 description 1741 "This parameter identifies the portions of the 1742 target datastore to retrieve."; 1743 } 1744 leaf datastore-xpath-filter { 1745 if-feature "sn:xpath"; 1746 type yang:xpath1.0; 1747 description 1748 "This parameter contains an XPath expression identifying the 1749 portions of the target datastore to retrieve. 1751 If the expression returns a node-set, all nodes in the 1752 node-set are selected by the filter. Otherwise, if the 1753 expression does not return a node-set, the filter 1754 doesn't select any nodes. 1756 The expression is evaluated in the following XPath context: 1758 o The set of namespace declarations are those in scope on 1759 the 'xpath-filter' leaf element. 1761 o The set of variable bindings is empty. 1763 o The function library is the core function library, and 1764 the XPath functions defined in section 10 in RFC 7950. 1766 o The context node is the root node of the target 1767 datastore."; 1768 } 1769 } 1770 } 1772 grouping selection-filter-objects { 1773 description 1774 "This grouping defines a selector for objects from a 1775 datastore."; 1776 choice selection-filter { 1777 description 1778 "The source of the selection filter applied to the subscription. 1779 This will come either referenced from a global list, or be 1780 provided within the subscription itself."; 1781 case by-reference { 1782 description 1783 "Incorporate a filter that has been configured separately."; 1784 leaf selection-filter-ref { 1785 type selection-filter-ref; 1786 mandatory true; 1787 description 1788 "References an existing selection filter which is to be 1789 applied to the subscription."; 1790 } 1791 } 1792 case within-subscription { 1793 description 1794 "Local definition allows a filter to have the same lifecycle 1795 as the subscription."; 1796 uses selection-filter-types; 1798 } 1799 } 1800 } 1802 grouping update-policy-modifiable { 1803 description 1804 "This grouping describes the datastore specific subscription 1805 conditions that can be changed during the lifetime of the 1806 subscription."; 1807 choice update-trigger { 1808 description 1809 "Defines necessary conditions for sending an event record to 1810 the subscriber."; 1811 case periodic { 1812 container periodic { 1813 presence "indicates an periodic subscription"; 1814 description 1815 "The publisher is requested to notify periodically the 1816 current values of the datastore as defined by the selection 1817 filter."; 1818 leaf period { 1819 type yang:timeticks; 1820 mandatory true; 1821 description 1822 "Duration of time which should occur between periodic 1823 push updates."; 1824 } 1825 leaf anchor-time { 1826 type yang:date-and-time; 1827 description 1828 "Designates a timestamp before or after which a series of 1829 periodic push updates are determined. The next update 1830 will take place at a whole multiple interval from the 1831 anchor time. For example, for an anchor time is set for 1832 the top of a particular minute and a period interval of a 1833 minute, updates will be sent at the top of every minute 1834 this subscription is active."; 1835 } 1836 } 1837 } 1838 case on-change { 1839 if-feature "on-change"; 1840 container on-change { 1841 presence "indicates an on-change subscription"; 1842 description 1843 "The publisher is requested to notify changes in values in 1844 the datastore subset as defined by a selection filter."; 1845 leaf dampening-period { 1846 type yang:timeticks; 1847 default 0; 1848 description 1849 "Specifies the minimum interval between the assembly of 1850 successive update records for a single receiver of a 1851 subscription. Whenever subscribed objects change, and a 1852 dampening period interval (which may be zero) has elapsed 1853 since the previous update record creation for a receiver, 1854 then any subscribed objects and properties which have 1855 changed since the previous update record will have their 1856 current values marshalled and placed into a new update 1857 record."; 1858 } 1859 } 1860 } 1861 } 1862 } 1864 grouping update-policy { 1865 description 1866 "This grouping describes the datastore specific subscription 1867 conditions of a subscription."; 1868 uses update-policy-modifiable { 1869 augment "update-trigger/on-change/on-change" { 1870 description 1871 "Includes objects not modifiable once subscription is 1872 established."; 1873 leaf no-synch-on-start { 1874 type empty; 1875 description 1876 "The presence of this object restricts an on-change 1877 subscription from sending push-update notifications. When 1878 present, pushing a full selection per the terms of the 1879 selection filter MUST NOT be done for this subscription. 1880 Only updates about changes, i.e. only push-change-update 1881 notifications are sent. When absent (default behavior), 1882 in order to facilitate a receiver's synchronization, a full 1883 update is sent when the subscription starts using a 1884 push-update notification. After that, push-change-update 1885 notifications are exclusively sent unless the publisher 1886 chooses to resynch the subscription via a new push-update 1887 notification."; 1888 } 1889 leaf-list excluded-change { 1890 type change-type; 1891 description 1892 "Use to restrict which changes trigger an update. 1893 For example, if modify is excluded, only creation and 1894 deletion of objects is reported."; 1895 } 1896 } 1897 } 1898 } 1900 grouping hints { 1901 description 1902 "Parameters associated with some error for a subscription made 1903 upon a datastore."; 1904 leaf period-hint { 1905 type yang:timeticks; 1906 description 1907 "Returned when the requested time period is too short. This 1908 hint can assert a viable period for either a periodic push 1909 cadence or an on-change dampening interval."; 1910 } 1911 leaf filter-failure-hint { 1912 type string; 1913 description 1914 "Information describing where and/or why a provided filter 1915 was unsupportable for a subscription."; 1916 } 1917 leaf object-count-estimate { 1918 type uint32; 1919 description 1920 "If there are too many objects which could potentially be 1921 returned by the selection filter, this identifies the estimate 1922 of the number of objects which the filter would potentially 1923 pass."; 1924 } 1925 leaf object-count-limit { 1926 type uint32; 1927 description 1928 "If there are too many objects which could be returned by the 1929 selection filter, this identifies the upper limit of the 1930 publisher's ability to service for this subscription."; 1931 } 1932 leaf kilobytes-estimate { 1933 type uint32; 1934 description 1935 "If the returned information could be beyond the capacity of 1936 the publisher, this would identify the data size which could 1937 result from this selection filter."; 1938 } 1939 leaf kilobytes-limit { 1940 type uint32; 1941 description 1942 "If the returned information would be beyond the capacity of 1943 the publisher, this identifies the upper limit of the 1944 publisher's ability to service for this subscription."; 1945 } 1946 } 1948 /* 1949 * RPCs 1950 */ 1952 rpc resynch-subscription { 1953 if-feature "on-change"; 1954 description 1955 "This RPC allows a subscriber of an active on-change 1956 subscription to request a full push of objects in their current 1957 state. A successful result would invoke a push-update of all 1958 datastore objects that the subscriber is permitted to access. 1959 This request may only come from the same subscriber using the 1960 establish-subscription RPC."; 1961 input { 1962 leaf identifier { 1963 type sn:subscription-id; 1964 mandatory true; 1965 description 1966 "Identifier of the subscription that is to be resynched."; 1967 } 1968 } 1969 } 1971 rc:yang-data resynch-subscription-error { 1972 container resynch-subscription-error { 1973 description 1974 "If a 'resynch-subscription' RPC fails, the subscription is not 1975 resynched and the RPC error response MUST indicate the reason 1976 for this failure. This yang-data MAY be inserted as structured 1977 data within a subscription's RPC error response to indicate the 1978 failure reason."; 1979 leaf reason { 1980 type identityref { 1981 base resynch-subscription-error; 1982 } 1983 mandatory true; 1984 description 1985 "Indicates the reason why the publisher has declined a request 1986 for subscription resynchronization."; 1987 } 1988 uses hints; 1989 } 1990 } 1992 augment "/sn:establish-subscription/sn:input" { 1993 description 1994 "This augmentation adds additional subscription parameters that 1995 apply specifically to datastore updates to RPC input."; 1996 uses update-policy; 1997 } 1999 augment "/sn:establish-subscription/sn:input/sn:target" { 2000 description 2001 "This augmentation adds the datastore as a valid target 2002 for the subscription to RPC input."; 2003 case datastore { 2004 description 2005 "Information specifying the parameters of an request for a 2006 datastore subscription."; 2007 uses datastore-criteria; 2008 } 2009 } 2011 rc:yang-data establish-subscription-error-datastore { 2012 container establish-subscription-error-datastore { 2013 description 2014 "If any 'establish-subscription' RPC parameters are 2015 unsupportable against the datastore, a subscription is not 2016 created and the RPC error response MUST indicate the reason why 2017 the subscription failed to be created. This yang-data MAY be 2018 inserted as structured data within a subscription's RPC error 2019 response to indicate the failure reason. This yang-data MUST be 2020 inserted if hints are to be provided back to the subscriber."; 2021 leaf reason { 2022 type identityref { 2023 base sn:establish-subscription-error; 2024 } 2025 description 2026 "Indicates the reason why the subscription has failed to 2027 be created to a targeted datastore."; 2028 } 2029 uses hints; 2030 } 2031 } 2033 augment "/sn:modify-subscription/sn:input" { 2034 description 2035 "This augmentation adds additional subscription parameters 2036 specific to datastore updates."; 2037 uses update-policy-modifiable; 2038 } 2040 augment "/sn:modify-subscription/sn:input/sn:target" { 2041 description 2042 "This augmentation adds the datastore as a valid target 2043 for the subscription to RPC input."; 2044 case datastore { 2045 description 2046 "Information specifying the parameters of an request for a 2047 datastore subscription."; 2048 uses selection-filter-objects; 2049 } 2050 } 2052 rc:yang-data modify-subscription-error-datastore { 2053 container modify-subscription-error-datastore { 2054 description 2055 "This yang-data MAY be provided as part of a subscription's RPC 2056 error response when there is a failure of a 2057 'modify-subscription' RPC which has been made against a 2058 datastore. This yang-data MUST be used if hints are to be 2059 provides back to the subscriber."; 2060 leaf reason { 2061 type identityref { 2062 base sn:modify-subscription-error; 2063 } 2064 description 2065 "Indicates the reason why the subscription has failed to 2066 be modified."; 2067 } 2068 uses hints; 2069 } 2070 } 2072 /* 2073 * NOTIFICATIONS 2074 */ 2076 notification push-update { 2077 description 2078 "This notification contains a push update, containing data 2079 subscribed to via a subscription. This notification is sent for 2080 periodic updates, for a periodic subscription. It can also be 2081 used for synchronization updates of an on-change subscription. 2082 This notification shall only be sent to receivers of a 2083 subscription; it does not constitute a general-purpose 2084 notification."; 2085 leaf subscription-id { 2086 type sn:subscription-id; 2087 description 2088 "This references the subscription which drove the notification 2089 to be sent."; 2090 } 2091 leaf incomplete-update { 2092 type empty; 2093 description 2094 "This is a flag which indicates that not all datastore nodes 2095 subscribed to are included with this update. In other words, 2096 the publisher has failed to fulfill its full subscription 2097 obligations, and despite its best efforts is providing an 2098 incomplete set of objects."; 2099 } 2100 anydata datastore-contents { 2101 description 2102 "This contains the updated data. It constitutes a snapshot 2103 at the time-of-update of the set of data that has been 2104 subscribed to. The format and syntax of the data 2105 corresponds to the format and syntax of data that would be 2106 returned in a corresponding get operation with the same 2107 selection filter parameters applied."; 2108 } 2109 } 2111 notification push-change-update { 2112 if-feature "on-change"; 2113 description 2114 "This notification contains an on-change push update. This 2115 notification shall only be sent to the receivers of a 2116 subscription; it does not constitute a general-purpose 2117 notification."; 2118 leaf subscription-id { 2119 type sn:subscription-id; 2120 description 2121 "This references the subscription which drove the notification 2122 to be sent."; 2123 } 2124 leaf incomplete-update { 2125 type empty; 2126 description 2127 "The presence of this object indicates not all changes which 2128 have occurred since the last update are included with this 2129 update. In other words, the publisher has failed to 2130 fulfill its full subscription obligations, for example in 2131 cases where it was not able to keep up with a change burst."; 2132 } 2133 anydata datastore-changes { 2134 description 2135 "This contains the set of datastore changes needed 2136 to update a remote datastore starting at the time of the 2137 previous update, per the terms of the subscription. Changes 2138 are encoded analogous to the syntax of a corresponding yang- 2139 patch operation, i.e. a yang-patch operation applied to the 2140 datastore implied by the previous update to result in the 2141 current state."; 2142 reference 2143 "RFC 8072 section 2.5, with a delta that it is ok to receive 2144 ability create on an existing node, or receive a delete on a 2145 missing node."; 2146 } 2147 } 2149 augment "/sn:subscription-started" { 2150 description 2151 "This augmentation adds many datastore specific objects to 2152 the notification that a subscription has started."; 2153 uses update-policy; 2154 } 2156 augment "/sn:subscription-started/sn:target" { 2157 description 2158 "This augmentation allows the datastore to be included as part 2159 of the notification that a subscription has started."; 2160 case datastore { 2161 uses datastore-criteria { 2162 refine "selection-filter/within-subscription" { 2163 description 2164 "Specifies where the selection filter, and where it came 2165 from within the subscription and then populated within this 2166 notification. If the 'selection-filter-ref' is populated, 2167 the filter within the subscription came from the 'filters' 2168 container. Otherwise it is populated in-line as part of the 2169 subscription itself."; 2170 } 2171 } 2172 } 2173 } 2175 augment "/sn:subscription-modified" { 2176 description 2177 "This augmentation adds many datastore specific objects to 2178 the notification that a subscription has been modified."; 2179 uses update-policy; 2180 } 2181 augment "/sn:subscription-modified/sn:target" { 2182 description 2183 "This augmentation allows the datastore to be included as part 2184 of the notification that a subscription has been modified."; 2185 case datastore { 2186 uses datastore-criteria { 2187 refine "selection-filter/within-subscription" { 2188 description 2189 "Specifies where the selection filter, and where it came 2190 from within the subscription and then populated within this 2191 notification. If the 'selection-filter-ref' is populated, 2192 the filter within the subscription came from the 'filters' 2193 container. Otherwise it is populated in-line as part of the 2194 subscription itself."; 2195 } 2196 } 2197 } 2198 } 2200 /* 2201 * DATA NODES 2202 */ 2204 augment "/sn:filters" { 2205 description 2206 "This augmentation allows the datastore to be included as part 2207 of the selection filtering criteria for a subscription."; 2208 list selection-filter { 2209 key "identifier"; 2210 description 2211 "A list of pre-positioned filters that can be applied 2212 to datastore subscriptions."; 2213 leaf identifier { 2214 type sn:filter-id; 2215 description 2216 "An identifier to differentiate between selection filters."; 2218 } 2219 uses selection-filter-types; 2220 } 2221 } 2223 augment "/sn:subscriptions/sn:subscription" { 2224 description 2225 "This augmentation adds many datastore specific objects to a 2226 subscription."; 2227 uses update-policy; 2228 } 2229 augment "/sn:subscriptions/sn:subscription/sn:target" { 2230 description 2231 "This augmentation allows the datastore to be included as part 2232 of the selection filtering criteria for a subscription."; 2233 case datastore { 2234 uses datastore-criteria; 2235 } 2236 } 2237 } 2239 2241 6. IANA Considerations 2243 This document registers the following namespace URI in the "IETF XML 2244 Registry" [RFC3688]: 2246 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push 2247 Registrant Contact: The IESG. 2248 XML: N/A; the requested URI is an XML namespace. 2250 This document registers the following YANG module in the "YANG Module 2251 Names" registry [RFC6020]: 2253 Name: ietf-yang-push 2254 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push 2255 Prefix: yp 2256 Reference: draft-ietf-netconf-yang-push-12.txt (RFC form) 2258 7. Security Considerations 2260 All security considerations from 2261 [I-D.draft-ietf-netconf-subscribed-notifications] are relevant for 2262 datastores. In addition there are specific security considerations 2263 for receivers defined in Section 3.9 2264 If the access control permissions on subscribed YANG nodes change 2265 during the lifecycle of a subscription, a publisher MUST either 2266 transparently conform to the new access control permissions, or must 2267 terminate or restart the subscriptions so that new access control 2268 permissions are re-established. 2270 The NETCONF Authorization Control Model SHOULD be used to restrict 2271 the delivery of YANG nodes for which the receiver has no access. 2273 8. Acknowledgments 2275 For their valuable comments, discussions, and feedback, we wish to 2276 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei 2277 Guo, Michael Scharf, Martin Bjorklund, and Guangying Zheng. 2279 9. References 2281 9.1. Normative References 2283 [I-D.draft-ietf-netconf-subscribed-notifications] 2284 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 2285 and E. Nilsen-Nygaard, "Custom Subscription to Event 2286 Streams", draft-ietf-netconf-subscribed-notifications-06 2287 (work in progress), January 2018. 2289 [I-D.draft-ietf-netmod-revised-datastores] 2290 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2291 and R. Wilton, "Network Management Datastore 2292 Architecture", draft-ietf-netmod-revised-datastores-04 2293 (work in progress), August 2017. 2295 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2296 DOI 10.17487/RFC3688, January 2004, 2297 . 2299 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2300 the Network Configuration Protocol (NETCONF)", RFC 6020, 2301 DOI 10.17487/RFC6020, October 2010, 2302 . 2304 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2305 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 2306 February 2012, . 2308 [RFC6536bis] 2309 Bierman, A. and M. Bjorklund, "Network Configuration 2310 Protocol (NETCONF) Access Control Model", draft-ietf- 2311 netconf-rfc6536bis-05 (work in progress), September 2017. 2313 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 2314 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 2315 . 2317 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2318 Media Type", RFC 8072, DOI 10.17487/RFC8072, February 2319 2017, . 2321 9.2. Informative References 2323 [I-D.draft-ietf-netconf-netconf-event-notifications] 2324 Gonzalez Prieto, A., Clemm, A., Voit, E., Nilsen-Nygaard, 2325 E., and A. Tripathy, "NETCONF Support for Event 2326 Notifications", September 2017. 2328 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2329 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 2330 . 2332 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2333 and A. Bierman, Ed., "Network Configuration Protocol 2334 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2335 . 2337 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2338 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 2339 . 2341 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2342 for Subscription to YANG Datastores", RFC 7923, 2343 DOI 10.17487/RFC7923, June 2016, 2344 . 2346 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2347 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2348 . 2350 Appendix A. Appendix A: Subscription Errors 2352 A.1. RPC Failures 2354 Rejection of an RPC for any reason is indicated by via RPC error 2355 response from the publisher. Valid RPC errors returned include both 2356 existing transport layer RPC error codes, such as those seen with 2357 NETCONF in [RFC6241], as well as subscription specific errors such as 2358 those defined within the YANG model. As a result, how subscription 2359 errors are encoded within an RPC error response is transport 2360 dependent. 2362 References to specific identities within the either the subscribed- 2363 notifications YANG model or the yang-push YANG model may be returned 2364 as part of the error responses resulting from failed attempts at 2365 datastore subscription. Following are valid errors per RPC (note: 2366 throughout this section the prefix 'sn' indicates an item imported 2367 from the subscribed-notifications.yang model): 2369 establish-subscription modify-subscription 2370 ---------------------- ------------------- 2371 cant-exclude sn:filter-unsupported 2372 datastore-not-subscribable sn:insufficient-resources 2373 sn:dscp-unavailable sn:no-such-subscription 2374 sn:filter-unsupported period-unsupported 2375 sn:insufficient-resources result-too-big 2376 on-change-unsupported synchronization-size 2377 on-change-synch-unsupported unchanging-selection 2378 period-unsupported 2379 result-too-big resynch-subscription 2380 synchronization-size -------------------- 2381 unchanging-selection no-such-subscription-resynch 2382 synchronization-size 2384 delete-subscription kill-subscription 2385 ---------------------- ----------------- 2386 sn:no-such-subscription sn:no-such-subscription 2388 There is one final set of transport independent RPC error elements 2389 included in the YANG model. These are the following four yang-data 2390 structures for failed datastore subscriptions: 2392 1. yang-data establish-subscription-error-datastore 2393 This MUST be returned if information identifying the reason for an 2394 RPC error has not been placed elsewhere within the transport 2395 portion of a failed "establish-subscription" RPC response. This 2396 MUST be sent if hints are included. 2398 2. yang-data modify-subscription-error-datastore 2399 This MUST be returned if information identifying the reason for an 2400 RPC error has not been placed elsewhere within the transport 2401 portion of a failed "modifiy-subscription" RPC response. This 2402 MUST be sent if hints are included. 2404 3. yang-data sn:delete-subscription-error 2405 This MUST be returned if information identifying the reason for an 2406 RPC error has not been placed elsewhere within the transport 2407 portion of a failed "delete-subscription" or "kill-subscription" 2408 RPC response. 2410 4. yang-data resynch-subscription-error 2411 This MUST be returned if information identifying the reason for an 2412 RPC error has not been placed elsewhere within the transport 2413 portion of a failed "resynch-subscription" RPC response. 2415 A.2. Notifications of Failure 2417 A subscription may be unexpectedly terminated or suspended 2418 independent of any RPC or configuration operation. In such cases, 2419 indications of such a failure MUST be provided. To accomplish this, 2420 the following types of error identities may be returned within the 2421 corresponding subscription state change notification: 2423 subscription-terminated subscription-suspended 2424 ----------------------- ---------------------- 2425 datastore-not-subscribable sn:insufficient-resources 2426 sn:filter-unavailable period-unsupported 2427 sn:no-such-subscription result-too-big 2428 sn:suspension-timeout synchronization-size 2429 unchanging-selection 2431 Appendix B. Changes between revisions 2433 (To be removed by RFC editor prior to publication) 2435 v14 - v15 2436 o Minor text fixes. Includes a fix to on-change update calculation 2437 to cover churn when an object changes to and from a value during a 2438 dampening period. 2440 v13 - v14 2442 o Minor text fixes. 2444 v12 - v13 2446 o Hint negotiation models now show error examples. 2448 o yang-data structures for rpc errors. 2450 v11 - v12 2452 o Included Martin's review clarifications. 2454 o QoS moved to subscribed-notifications 2456 o time-of-update removed as it is redundant with RFC5277's 2457 eventTime, and other times from notification-messages. 2459 o Error model moved to match existing implementations 2461 o On-change notifiable removed, how to do this is implementation 2462 specific. 2464 o NMDA model supported. Non NMDA version at https://github.com/ 2465 netconf-wg/yang-push/ 2467 v10 - v11 2469 o Promise model reference added. 2471 o Error added for no-such-datastore 2473 o Inherited changes from subscribed notifications (such as optional 2474 feature definitions). 2476 o scrubbed the examples for proper encodings 2478 v09 - v10 2480 o Returned to the explicit filter subtyping of v00-v05 2482 o identityref to ds:datastore made explicit 2483 o Returned ability to modify a selection filter via RPC. 2485 v08 - v09 2487 o Minor tweaks cleaning up text, removing appendicies, and making 2488 reference to revised-datastores. 2490 o Subscription-id optional in push updates, except when encoded in 2491 RFC5277, Section 4 one-way notification. 2493 o Finished adding the text descibing the resynch subscription RPC. 2495 o Removed relationships to other drafts and future technology 2496 appendicies as this work is being explored elsewhere. 2498 o Deferred the multi-line card issue to new drafts 2500 o Simplified the NACM interactions. 2502 v07 - v08 2504 o Updated YANG models with minor tweaks to accommodate changes of 2505 ietf-subscribed-notifications. 2507 v06 - v07 2509 o Clarifying text tweaks. 2511 o Clarification that filters act as selectors for subscribed 2512 datastore nodes; support for value filters not included but 2513 possible as a future extension 2515 o Filters don't have to be matched to existing YANG objects 2517 v05 - v06 2519 o Security considerations updated. 2521 o Base YANG model in [subscribe] updated as part of move to 2522 identities, YANG augmentations in this doc matched up 2524 o Terms refined and text updates throughout 2526 o Appendix talking about relationship to other drafts added. 2528 o Datastore replaces stream 2530 o Definitions of filters improved 2531 v04 to v05 2533 o Referenced based subscription document changed to Subscribed 2534 Notifications from 5277bis. 2536 o Getting operational data from filters 2538 o Extension notifiable-on-change added 2540 o New appendix on potential futures. Moved text into there from 2541 several drafts. 2543 o Subscription configuration section now just includes changed 2544 parameters from Subscribed Notifications 2546 o Subscription monitoring moved into Subscribed Notifications 2548 o New error and hint mechanisms included in text and in the yang 2549 model. 2551 o Updated examples based on the error definitions 2553 o Groupings updated for consistency 2555 o Text updates throughout 2557 v03 to v04 2559 o Updates-not-sent flag added 2561 o Not notifiable extension added 2563 o Dampening period is for whole subscription, not single objects 2565 o Moved start/stop into rfc5277bis 2567 o Client and Server changed to subscriber, publisher, and receiver 2569 o Anchor time for periodic 2571 o Message format for synchronization (i.e. synch-on-start) 2573 o Material moved into 5277bis 2575 o QoS parameters supported, by not allowed to be modified by RPC 2577 o Text updates throughout 2579 Authors' Addresses 2581 Alexander Clemm 2582 Huawei 2584 Email: ludwig@clemm.org 2586 Eric Voit 2587 Cisco Systems 2589 Email: evoit@cisco.com 2591 Alberto Gonzalez Prieto 2592 VMware 2594 Email: agonzalezpri@vmware.com 2596 Ambika Prasad Tripathy 2597 Cisco Systems 2599 Email: ambtripa@cisco.com 2601 Einar Nilsen-Nygaard 2602 Cisco Systems 2604 Email: einarnn@cisco.com 2606 Andy Bierman 2607 YumaWorks 2609 Email: andy@yumaworks.com 2611 Balazs Lengyel 2612 Ericsson 2614 Email: balazs.lengyel@ericsson.com