idnits 2.17.1 draft-ietf-netconf-yang-push-13.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 223: '...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 867 has weird spacing: '...ro time yan...' == Line 926 has weird spacing: '...ntifier sub...' == Line 966 has weird spacing: '...ntifier sub...' == Line 969 has weird spacing: '...ntifier sub...' == Line 982 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 02, 2018) is 2246 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: A later version (-26) exists of draft-ietf-netconf-subscribed-notifications-06 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-revised-datastores-04 == Outdated reference: A later version (-09) exists of draft-ietf-netconf-rfc6536bis-05 -- Possible downref: Normative reference to a draft: ref. 'RFC6536bis' ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 2 errors (**), 0 flaws (~~), 12 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 6, 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 02, 2018 17 YANG Datastore Subscription 18 draft-ietf-netconf-yang-push-13 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 6, 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. Datastore Selection . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . 26 94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 32 95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 49 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 . . . . . . . . . . 51 102 A.1. RPC Failures . . . . . . . . . . . . . . . . . . . . . . 51 103 A.2. Notifications of Failure . . . . . . . . . . . . . . . . 52 104 Appendix B. Changes between revisions . . . . . . . . . . . . . 52 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 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 An encoding (using anydata) for the contents of periodic and on- 202 change push updates. 204 o Specification of update policies contain conditions which trigger 205 the generation and pushing of new update records. There are two 206 types of triggers for subscriptions: periodic and on-change. 208 * For periodic subscriptions, the trigger is specified by two 209 parameters that define when updates are to be pushed. These 210 parameters are the period interval with which to report 211 updates, and an anchor time which can be used to calculate at 212 which point in time updates need to be assembled and sent. 214 * For on-change subscriptions, a trigger occurs whenever a change 215 in the subscribed information is detected. Included are 216 additional parameters such as: 218 + Dampening period: In an on-change subscription, detected 219 object changes should be sent as quickly as possible. 220 However it may be undesirable to send a rapid series of 221 object changes. Such behavior has the potential to exhaust 222 of resources in the publisher or receiver. In order to 223 protect against that, a dampening period MAY be used to 224 specify the interval which must pass before successive 225 update records for the same subscription are generated for a 226 receiver. The dampening period collectively applies to the 227 set of all datastore nodes selected by a single subscription 228 and sent to a single receiver. This means that when there 229 is a change to one or more subscribed objects, an update 230 record containing those objects is created either 231 immediately when no dampening period is in effect, or at the 232 end of a dampening period. If multiple changes to a single 233 object occur during a dampening period, only the value that 234 is in effect at the time the update record is created is 235 included. The dampening period goes into effect every time 236 an update record completes assembly. 238 + Change type: This parameter can be used to reduce the types 239 of datastore changes for which updates are sent (e.g., you 240 might only send when an object is created or deleted, but 241 not when an object value changes). 243 + No Synch on start: defines whether or not a complete push- 244 update of all subscribed data will be sent at the beginning 245 of a subscription. Such early synchronization establishes 246 the frame of reference for subsequent 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. If the 333 record is non-empty, send it to the receiver. 335 Note: In cases where a subscriber wants to have separate dampening 336 periods for different objects, multiple subscriptions with different 337 objects in a selection filter can be created. 339 3.4. Promise-Theory Considerations 341 A subscription to updates from a datastore is intended to obviate the 342 need for polling. However, in order to do so, it is critical that 343 subscribers can rely on the subscription and have confidence that 344 they will indeed receive the subscribed updates without having to 345 worry updates being silently dropped. In other words, a subscription 346 constitutes a promise on the side of the publisher to provide the 347 receivers with updates per the terms of the subscription. 349 Now, there are many reasons why a publisher may at some point no 350 longer be able to fulfill the terms of the subscription, even if the 351 subscription had been entered into with good faith. For example, the 352 volume of data objects may be larger than anticipated, the interval 353 may prove too short to send full updates in rapid succession, or an 354 internal problem may prevent objects from being collected. If for 355 some reason the publisher of a subscription is not able to keep its 356 promise, receivers MUST be notified immediately and reliably. The 357 publisher MAY also suspend the subscription. 359 A publisher SHOULD reject a request for a subscription if it is 360 unlikely that the publisher will be able fulfill the terms of that 361 subscription request. In such cases, it is preferable to have a 362 subscriber request a less resource intensive subscription than to 363 deal with frequently degraded behavior. 365 3.5. Data Encodings 367 3.5.1. Periodic Subscriptions 369 In a periodic subscription, the data included as part of an update 370 corresponds to data that could have been read using a retrieval 371 operation. 373 3.5.2. On-Change Subscriptions 375 In an on-change subscription, updates need to indicate not only 376 values of changed datastore nodes but also the types of changes that 377 occurred since the last update. Therefore encoding rules for data in 378 on-change updates will generally follow YANG-patch operation as 379 specified in [RFC8072]. The YANG-patch will describe what needs to 380 be applied to the earlier state reported by the preceding update, to 381 result in the now-current state. Note that contrary to [RFC8072], 382 objects encapsulated are not restricted to configuration objects 383 only. 385 However a patch must be able to do more than just describe the delta 386 from the previous state to the current state. As per Section 3.3, it 387 must also be able to identify if transient changes have occurred on 388 an object during a dampening period. To support this, it is valid to 389 encode a YANG patch operation so that its application would result in 390 a no change between the previous and current state. This indicates 391 that some churn has occurred on the object. An example of this would 392 be a patch that does a "create" operation for a datastore node where 393 the receiver believes one already exists, or a "merge" operation 394 which replaces a previous value with the same value. Note that this 395 means that the "create" and "delete" errors described in [RFC8072] 396 section 2.5 are not errors, and are valid operations with YANG push. 398 3.6. Datastore Selection 400 A subscription must specify both the selection filters and the 401 datastore against which these selection filters will be applied. 402 This information is used to choose and subsequently push data from 403 the publisher's datastore to the receivers. 405 Only a single selection filter can be applied to a subscription at a 406 time. An rpc request proposing a new selection filter MUST remove 407 any existing filter. The following selection filter types are 408 included in the yang-push data model, and may be applied against a 409 datastore: 411 o subtree: A subtree selection filter identifies one or more 412 datastore subtrees. When specified, update records will only come 413 from the datastore nodes of selected datastore subtree(s). The 414 syntax and semantics correspond to that specified for [RFC6241] 415 section 6. 417 o xpath: An xpath selection filter is an XPath expression that 418 returns a node set. When specified, updates will only come from 419 the selected data nodes. 421 These filters are intended to be used as selectors that define which 422 objects are within the scope of a subscription. A publisher MUST 423 support at least one type of selection filter. 425 Selection filters are not intended to be used for property value 426 filtering for non-key objects. Supporting non-key property value 427 filtering would have a number of implications that would result in 428 significant complexity, specifically in the case of on-change 429 subscriptions. While it is possible to define extensions in the 430 future that will support selection filtering based on values, this is 431 not supported in this version of yang-push and a publisher MAY reject 432 a subscription request that contains a filter for object values. 434 Xpath itself provides powerful filtering constructs and care must be 435 used in filter definition. As an example, consider an xpath filter 436 with a boolean result; such a result will not provide an easily 437 interpretable subset of a datastore. Beyond the boolean example, it 438 is quite possible to define an xpath filter where results are easy 439 for an application to mis-interpret. Consider an xpath filter which 440 only passes a datastore object when an interface is up. It is up to 441 the receiver to understand implications of the presence or absence of 442 objects in each update. 444 When the set of selection filtering criteria is applied for periodic 445 subscription, all selected datastore nodes to which a receiver has 446 access are provided to a receiver. If the same filtering criteria is 447 applied to an on-change subscription, only the subset of those 448 datastore nodes supporting on-change is provided. A datastore node 449 which doesn't support on-change is never sent as part of an on-change 450 subscription's "push-update" or "push-change-update". 452 3.7. Streaming Updates 454 Contrary to traditional data retrieval requests, datastore 455 subscription enables an unbounded series of update records to be 456 streamed over time. Two generic YANG notifications for update 457 records have been defined for this: "push-update" and "push-change- 458 update". 460 A "push-update" notification defines a complete, filtered update of 461 the datastore per the terms of a subscription. This type of YANG 462 notification is used for continuous updates of periodic 463 subscriptions. A "push-update" notification can also be used for the 464 on-change subscriptions in two cases. First it will be used as the 465 initial "push-update" if there is a need to synchronize the receiver 466 at the start of a new subscription. It also MAY be sent if the 467 publisher later chooses to resynch an on-change subscription. The 468 "push-update" update record contains a data snippet that contains an 469 instantiated datastore subtree with all of the subscribed contents. 470 The content of the update record is equivalent to the contents that 471 would be obtained had the same data been explicitly retrieved using 472 e.g., a NETCONF "get" operation, with the same filters applied. 474 A "push-change-update" notification is the most common type of update 475 for on-change subscriptions. The update record in this case contains 476 a data snippet that indicates the set of changes that datastore nodes 477 have undergone since the last notification message. In other words, 478 this indicates which datastore nodes have been created, deleted, or 479 have had changes to their values. In cases where multiple changes 480 have occurred and the object has not been deleted, the object's most 481 current value is reported. (In other words, for each object, only 482 one change is reported, not its entire history. Doing so would 483 defeat the purpose of the dampening period.) 485 These new "push-update" or "push-change-update" are encoded and 486 placed within notification messages, and ultimately queued for egress 487 over the specified transport. 489 The following is an example of a notification message for a 490 subscription tracking the operational status of a single Ethernet 491 port (per [RFC7223]). This notification message is encoded XML over 492 NETCONF as per [I-D.draft-ietf-netconf-netconf-event-notifications]. 494 495 2017-10-25T08:00:11.22Z 496 497 1011 498 499 500 501 eth0 502 up 503 504 505 506 507 509 Figure 1: Push example 511 The following is an example of an on-change notification message for 512 the same subscription. 514 515 2017-10-25T08:22:33.44Z 516 517 89 518 519 520 1 521 522 edit1 523 merge 524 /ietf-interfaces:interfaces-state 525 526 527 528 eth0 529 down 530 531 532 533 534 535 536 537 539 Figure 2: Push example for on change 541 Of note in the above example is the 'patch-id' with a value of '1'. 542 Per [RFC8072], the 'patch-id' is an arbitrary string. With YANG 543 Push, the publisher SHOULD put into the 'patch-id' a counter starting 544 at '1' which increments with every 'push-change-update' generated for 545 a subscription. If used as a counter, this counter MUST be reset to 546 '1' anytime a resynchronization occurs (i.e., with the sending of a 547 'push-update'). Also if used as a counter, the counter MUST be reset 548 to '1' the after passing a maximum value of '99999'. Such a 549 mechanism allows easy identification of lost or out-of-sequence 550 update records. 552 3.8. Subscription Management 554 The RPCs defined within 555 [I-D.draft-ietf-netconf-subscribed-notifications] have been enhanced 556 to support datastore subscription negotiation. Included in these 557 enhancements are error codes which can indicate why a datastore 558 subscription attempt has failed. 560 A datastore subscription can be rejected for multiple reasons. This 561 includes a too large subtree request, or the inability of the 562 publisher to push update records as frequently as requested. In such 563 cases, no subscription is established. Instead, the subscription- 564 result with the failure reason is returned as part of the RPC 565 response. As part of this response, a set of alternative 566 subscription parameters MAY be returned that would likely have 567 resulted in acceptance of the subscription request. The subscriber 568 may consider these as part of future subscription attempts. 570 The specific parameters to be returned in as part of the RPC error 571 response depend on the specific transport that is used to manage the 572 subscription. In the case of NETCONF 573 [I-D.draft-ietf-netconf-netconf-event-notifications], the NETCONF RPC 574 reply MUST include an "rpc-error" element with the following 575 additional elements: 577 o "error-type" of "rpc". 579 o "error-tag" of "operation-failed". 581 o Optionally, an "error-severity" of "error" (this MAY but does not 582 have to be included). 584 o "error-app-tag" with the value being a string that corresponds to 585 an identity with a base of "establish-subscription-error" (for 586 error responses to an establish-subscription request), "modify- 587 subscription-error" (for error responses to a modify-subscription 588 request), "delete-subscription-error" (for error responses to a 589 delete-subscription request), "resynch-subscription-error" (for 590 error responses to resynch-subscription request), or "kill- 591 subscription-error" (for error responses to a kill-subscription 592 request), respectively. 594 o In case of error responses to an establish-subscription or modify- 595 subscription request: optionally, "error-info" containing XML- 596 encoded data with hints regarding parameter settings that might 597 lead to successful requests in the future, per yang-data 598 definitions "establish-subscription-error-datastore" (for error 599 responses to an establish-subscription request) or "modify- 600 subscription-error-datastore (for error responses to a modify- 601 subscription request), respectively. In case of an rpc error as a 602 result of a delete-subscription, or a kill-subscription, or a 603 resynch-subscription request, no error-info needs to be included, 604 as the subscription-id is the only RPC input parameter and no 605 hints regarding RPC input parameters need to be provided. 607 For instance, for the following request: 609 611 614 615 ds:operational 616 617 619 /ex:foo 620 621 622 500 623 624 625 627 Figure 3: Establish-Subscription example 629 the publisher might return: 631 633 634 application 635 operation-failed 636 period-unsupported 637 638 641 642 2000 643 644 645 646 647 649 Figure 4: Error response example 651 3.9. Receiver Authorization 653 A receiver of subscription data MUST only be sent updates for which 654 they have proper authorization. A publisher MUST ensure that no non- 655 authorized data is included in push updates. To do so, it needs to 656 apply all corresponding checks applicable at the time of a specific 657 pushed update and if necessary silently remove any non-authorized 658 data from datastore subtrees. This enables YANG data pushed based on 659 subscriptions to be authorized equivalently to a regular data 660 retrieval (get) operation. 662 A publisher MUST allow for the possibility that a subscription's 663 selection filter references non-existent or access-protected data. 664 Such support permits a receiver the ability to monitor the entire 665 lifecyle of some datastore tree. In this case, all "push-update" 666 notifications must be sent empty, and no "push-change-update" 667 notifications will be sent until some data becomes visible for a 668 receiver. 670 A publisher MAY choose reject an establish-subscription request which 671 selects non-existent or access-protected data. In addition, a 672 publisher MAY choose to terminate a dynamic subscription or suspend a 673 configured receiver when the authorization privileges of a receiver 674 change, or the access controls for subscribed objects change. Such a 675 capability enables the publisher to avoid having to support a 676 continuous, and total filtering of an entire subscription's content. 678 In these cases above, the error identity "data-unavailable" SHOULD be 679 returned. This reduces the possibility of leakage of access 680 controlled objects. 682 The conceptual authorization model for datastores is the NETCONF 683 Access Control Model [RFC6536bis], Section 3.2.4. A clarification to 684 this is that each of the individual nodes in a resulting update 685 record MUST also have applied access control to resulting pushed 686 messages. This includes validating that read access is ok for any 687 nodes newly selected since the last update record for each receiver. 689 +-----------------+ +--------------------+ 690 push-update or --> | datastore node | yes | add datastore node | 691 push-change-update | access allowed? | ---> | to update message | 692 +-----------------+ +--------------------+ 694 Figure 5: Access control for push updates 696 If read access into previously accessible nodes has been lost due to 697 a receiver permissions change, this SHOULD be reported as a patch 698 "delete" operation for on-change subscriptions. If not capable of 699 handling such receiver permission changes with such a "delete", 700 publisher implementations MUST force dynamic subscription re- 701 establishment or configured subscription re-initialization so that 702 appropriate filtering is installed. 704 3.10. On-change Notifiable YANG objects 706 In some cases, a publisher supporting on-change notifications may not 707 be able to push updates for some object types on-change. Reasons for 708 this might be that the value of the datastore node changes frequently 709 (e.g., [RFC7223]'s in-octets counter), that small object changes are 710 frequent and meaningless (e.g., a temperature gauge changing 0.1 711 degrees), or that the implementation is not capable of on-change 712 notification for a particular object. 714 Support for on-change notification is specific to the individual YANG 715 model and/or implementation, and is useful to define in design time. 716 System integrators need this information (without reading any data 717 from a live node). 719 Mechanisms for identifying which data nodes support on-change 720 notification are left to individual implementations. 722 3.11. Other Considerations 724 3.11.1. Robustness and reliability 726 Particularly in the case of on-change updates, it is important that 727 these updates do not get lost. Or in case the loss of an update is 728 unavoidable, it is critical that the receiver is notified 729 accordingly. 731 Update records for a single subscription MAY NOT be resequenced prior 732 to transport. 734 It is conceivable that under certain circumstances, a publisher will 735 recognize that it is unable to include within an update record the 736 full set of objects desired per the terms of a subscription. In this 737 case, the publisher MUST take one or more of the following actions. 739 o A publisher MUST set the "updates-not-sent" flag on any update 740 record which is known to be missing information. 742 o It MAY choose to suspend a subscription as per 743 [I-D.draft-ietf-netconf-subscribed-notifications]. 745 o When resuming an on-change subscription, the publisher SHOULD 746 generate a complete patch from the previous update record. If 747 this is not possible and the "no-synch-on-start" option is not 748 present for the subscription, then the full datastore contents MAY 749 be sent via a "push-update" instead (effectively replacing the 750 previous contents). If neither of these are possible, then an 751 "updates-not-sent" flag MUST be included on the next "push-change- 752 update". 754 Note: It is perfectly acceptable to have a series of "push-change- 755 update" notifications (and even "push update" notifications) serially 756 queued at the transport layer awaiting transmission. It is not 757 required to merge pending update messages. I.e., the dampening 758 period applies to update record creation, not transmission. 760 3.11.2. Publisher capacity 762 It is far preferable to decline a subscription request than to accept 763 such a request when it cannot be met. 765 Whether or not a subscription can be supported will be determined by 766 a combination of several factors such as the subscription trigger 767 (on-change or periodic), the period in which to report changes (one 768 second periods will consume more resources than one hour periods), 769 the amount of data in the datastore subtree that is being subscribed 770 to, and the number and combination of other subscriptions that are 771 concurrently being serviced. 773 4. A YANG data model for management of datastore push subscriptions 775 4.1. Overview 777 The YANG data model for datastore push subscriptions is depicted in 778 the following figure. Following YANG tree convention in the 779 depiction, brackets enclose list keys, "rw" means configuration, "ro" 780 operational state data, "?" designates optional nodes, "*" designates 781 nodes that can have multiple instances. Parentheses with a name in 782 the middle enclose choice and case nodes. New schema objects defined 783 here (i.e., beyond those from 784 [I-D.draft-ietf-netconf-subscribed-notifications]) are identified 785 with "yp". 787 module: ietf-subscribed-notifications 788 +--ro streams 789 | +--ro stream* [name] 790 | +--ro name string 791 | +--ro description string 792 | +--ro replay-support? empty {replay}? 793 | +--ro replay-log-creation-time? yang:date-and-time {replay}? 794 | +--ro replay-log-aged-time? yang:date-and-time {replay}? 795 +--rw filters 796 | +--rw stream-filter* [identifier] 797 | | +--rw identifier filter-id 798 | | +--rw (filter-spec)? 799 | | +--:(stream-subtree-filter) 800 | | | +--rw stream-subtree-filter? {subtree}? 801 | | +--:(stream-xpath-filter) 802 | | +--rw stream-xpath-filter? yang:xpath1.0 {xpath}? 803 | +--rw yp:selection-filter* [identifier] 804 | +--rw yp:identifier sn:filter-id 805 | +--rw (yp:filter-spec)? 806 | +--:(yp:datastore-subtree-filter) 807 | | +--rw yp:datastore-subtree-filter? 808 | | {sn:subtree}? 809 | +--:(yp:datastore-xpath-filter) 810 | +--rw yp:datastore-xpath-filter? 811 | yang:xpath1.0 {sn:xpath}? 812 +--rw subscriptions 813 +--rw subscription* [identifier] 814 +--rw identifier subscription-id 815 +--ro configured-subscription-state? enumeration {configured}? 816 +--rw purpose? string {configured}? 817 +--rw protocol transport {configured}? 818 +--rw encoding encoding 819 +--rw (target) 820 | +--:(stream) 821 | | +--rw (stream-filter)? 822 | | | +--:(by-reference) 823 | | | | +--rw stream-filter-ref stream-filter-ref 824 | | | +--:(within-subscription) 825 | | | +--rw (filter-spec)? 826 | | | +--:(stream-subtree-filter) 827 | | | | +--rw stream-subtree-filter? 828 | | | {subtree}? 829 | | | +--:(stream-xpath-filter) 830 | | | +--rw stream-xpath-filter? 831 | | | yang:xpath1.0 {xpath}? 832 | | +--rw stream stream-ref 833 | | +--rw replay-start-time? yang:date-and-time {replay}? 834 | +--:(yp:datastore) 835 | +--rw yp:datastore identityref 836 | +--rw (yp:selected-content)? 837 | +--:(yp:by-reference) 838 | | +--rw yp:selection-filter-ref selection-filter-ref 839 | +--:(yp:within-subscription) 840 | +--rw (yp:filter-spec)? 841 | +--:(yp:datastore-subtree-filter) 842 | | +--rw yp:datastore-subtree-filter? 843 | {sn:subtree}? 844 | +--:(yp:datastore-xpath-filter) 845 | +--rw yp:datastore-xpath-filter? 846 | yang:xpath1.0 {sn:xpath}? 847 +--rw stop-time? yang:date-and-time 848 +--rw dscp? inet:dscp {qos}? 849 +--rw weighting? uint8 {qos}? 850 +--rw dependency? subscription-id {qos}? 851 +--rw (notification-message-origin)? 852 | +--:(interface-originated) 853 | | +--rw source-interface? if:interface-ref 854 | +--:(address-originated) 855 | +--rw source-vrf? -> 856 | /ni:network-instances/network-instance/name {supports-vrf}? 857 | +--rw source-address? inet:ip-address-no-zone 858 +--rw receivers 859 | +--rw receiver* [address port] 860 | +--rw address inet:host 861 | +--rw port inet:port-number 862 | +--ro pushed-notifications? yang:counter64 863 | +--ro excluded-notifications? yang:counter64 864 | +--ro status enumeration 865 | +---x reset 866 | +--ro output 867 | +--ro time yang:date-and-time 868 +--rw (yp:update-trigger)? 869 +--:(yp:periodic) 870 | +--rw yp:periodic! 871 | +--rw yp:period yang:timeticks 872 | +--rw yp:anchor-time? yang:date-and-time 873 +--:(yp:on-change) {on-change}? 874 +--rw yp:on-change! 875 +--rw yp:dampening-period? yang:timeticks 876 +--rw yp:no-synch-on-start? empty 877 +--rw yp:excluded-change* change-type 879 rpcs: 880 +---x establish-subscription 881 | +---w input 882 | | +---w encoding? encoding 883 | | +---w (target) 884 | | | +--:(stream) 885 | | | | +---w (stream-filter)? 886 | | | | | +--:(by-reference) 887 | | | | | | +---w stream-filter-ref stream-filter-ref 888 | | | | | +--:(within-subscription) 889 | | | | | +---w (filter-spec)? 890 | | | | | +--:(stream-subtree-filter) 891 | | | | | | +---w stream-subtree-filter? 892 | | | | | {subtree}? 893 | | | | | +--:(stream-xpath-filter) 894 | | | | | +---w stream-xpath-filter? 895 | | | | | yang:xpath1.0 {xpath}? 896 | | | | +---w stream stream-ref 897 | | | | +---w replay-start-time? yang:date-and-time {replay}? 898 | | | +--:(yp:datastore) 899 | | | +---w yp:datastore identityref 900 | | | +---w (yp:selected-content)? 901 | | | +--:(yp:by-reference) 902 | | | | +---w yp:selection-filter-ref selection-filter-ref 903 | | | +--:(yp:within-subscription) 904 | | | +---w (yp:filter-spec)? 905 | | | +--:(yp:datastore-subtree-filter) 906 | | | | +---w yp:datastore-subtree-filter? 907 | | | | {sn:subtree}? 908 | | | +--:(yp:datastore-xpath-filter) 909 | | | +---w yp:datastore-xpath-filter? 910 | | | yang:xpath1.0 {sn:xpath}? 911 | | +---w stop-time? yang:date-and-time 912 | | +---w dscp? inet:dscp {qos}? 913 | | +---w weighting? uint8 {qos}? 914 | | +---w dependency? subscription-id {qos}? 915 | | +---w (yp:update-trigger)? 916 | | +--:(yp:periodic) 917 | | | +---w yp:periodic! 918 | | | +---w yp:period yang:timeticks 919 | | | +---w yp:anchor-time? yang:date-and-time 920 | | +--:(yp:on-change) {on-change}? 921 | | +---w yp:on-change! 922 | | +---w yp:dampening-period? yang:timeticks 923 | | +---w yp:no-synch-on-start? empty 924 | | +---w yp:excluded-change* change-type 925 | +--ro output 926 | +--ro identifier subscription-id 927 +---x modify-subscription 928 | +---w input 929 | +---w identifier? subscription-id 930 | +---w (target) 931 | | +--:(stream) 932 | | | +---w (stream-filter)? 933 | | | +--:(by-reference) 934 | | | | +---w stream-filter-ref stream-filter-ref 935 | | | +--:(within-subscription) 936 | | | +---w (filter-spec)? 937 | | | +--:(stream-subtree-filter) 938 | | | | +---w stream-subtree-filter? 939 | | | {subtree}? 940 | | | +--:(stream-xpath-filter) 941 | | | +---w stream-xpath-filter? 942 | | | yang:xpath1.0 {xpath}? 943 | | +--:(yp:datastore) 944 | | +---w (yp:selected-content)? 945 | | +--:(yp:by-reference) 946 | | | +---w yp:selection-filter-ref selection-filter-ref 947 | | +--:(yp:within-subscription) 948 | | +---w (yp:filter-spec)? 949 | | +--:(yp:datastore-subtree-filter) 950 | | | +---w yp:datastore-subtree-filter? 951 | | | {sn:subtree}? 952 | | +--:(yp:datastore-xpath-filter) 953 | | +---w yp:datastore-xpath-filter? 954 | | yang:xpath1.0 {sn:xpath}? 955 | +---w stop-time? yang:date-and-time 956 | +---w (yp:update-trigger)? 957 | +--:(yp:periodic) 958 | | +---w yp:periodic! 959 | | +---w yp:period yang:timeticks 960 | | +---w yp:anchor-time? yang:date-and-time 961 | +--:(yp:on-change) {on-change}? 962 | +---w yp:on-change! 963 | +---w yp:dampening-period? yang:timeticks 964 +---x delete-subscription 965 | +---w input 966 | +---w identifier subscription-id 967 +---x kill-subscription 968 +---w input 969 +---w identifier subscription-id 971 yang-data (for placement into rpc error responses) 972 +-- establish-subscription-error-stream 973 | +--ro reason? identityref 974 | +--ro filter-failure-hint? string 975 | +--ro replay-start-time-hint? yang:date-and-time 976 +-- modify-subscription-error-stream 977 +--ro reason? identityref 978 +--ro filter-failure-hint? string 980 notifications: 981 +---n replay-completed {replay}? 982 | +--ro identifier subscription-id 983 +---n subscription-completed 984 | +--ro identifier subscription-id 985 +---n subscription-started {configured}? 986 | +--ro identifier subscription-id 987 | +--ro protocol transport {configured}? 988 | +--ro encoding encoding 989 | +--ro (target) 990 | | +--:(stream) 991 | | | +--ro (stream-filter)? 992 | | | | +--:(by-reference) 993 | | | | | +--ro stream-filter-ref stream-filter-ref 994 | | | | +--:(within-subscription) 995 | | | | +--ro (filter-spec)? 996 | | | | +--:(stream-subtree-filter) 997 | | | | | +--ro stream-subtree-filter? 998 | | | | | {subtree}? 999 | | | | +--:(stream-xpath-filter) 1000 | | | | +--ro stream-xpath-filter? 1001 | | | | yang:xpath1.0 {xpath}? 1002 | | | +--ro stream stream-ref 1003 | | | +--ro replay-start-time? yang:date-and-time {replay}? 1004 | | +--:(yp:datastore) 1005 | | +--ro yp:datastore identityref 1006 | | +--ro (yp:selected-content)? 1007 | | +--:(yp:by-reference) 1008 | | | +--ro yp:selection-filter-ref selection-filter-ref 1009 | | +--:(yp:within-subscription) 1010 | | +--ro (yp:filter-spec)? 1011 | | +--:(yp:datastore-subtree-filter) 1012 | | | +--ro yp:datastore-subtree-filter? 1013 | | {sn:subtree}? 1014 | | +--:(yp:datastore-xpath-filter) 1015 | | +--ro yp:datastore-xpath-filter? 1016 | | yang:xpath1.0 {sn:xpath}? 1017 | +--ro stop-time? yang:date-and-time 1018 | +--ro dscp? inet:dscp {qos}? 1019 | +--ro weighting? uint8 {qos}? 1020 | +--ro dependency? subscription-id {qos}? 1021 | +--ro (yp:update-trigger)? 1022 | +--:(yp:periodic) 1023 | | +--ro yp:periodic! 1024 | | +--ro yp:period yang:timeticks 1025 | | +--ro yp:anchor-time? yang:date-and-time 1026 | +--:(yp:on-change) {on-change}? 1027 | +--ro yp:on-change! 1028 | +--ro yp:dampening-period? yang:timeticks 1029 | +--ro yp:no-synch-on-start? empty 1030 | +--ro yp:excluded-change* change-type 1031 +---n subscription-resumed 1032 | +--ro identifier subscription-id 1033 +---n subscription-modified 1034 | +--ro identifier subscription-id 1035 | +--ro protocol transport {configured}? 1036 | +--ro encoding encoding 1037 | +--ro (target) 1038 | | +--:(stream) 1039 | | | +--ro (stream-filter)? 1040 | | | | +--:(by-reference) 1041 | | | | | +--ro stream-filter-ref stream-filter-ref 1042 | | | | +--:(within-subscription) 1043 | | | | +--ro (filter-spec)? 1044 | | | | +--:(stream-subtree-filter) 1045 | | | | | +--ro stream-subtree-filter? 1046 | | | | | {subtree}? 1047 | | | | +--:(stream-xpath-filter) 1048 | | | | +--ro stream-xpath-filter? 1049 | | | | yang:xpath1.0 {xpath}? 1050 | | | +--ro stream stream-ref 1051 | | | +--ro replay-start-time? yang:date-and-time {replay}? 1052 | | +--:(yp:datastore) 1053 | | +--ro yp:datastore identityref 1054 | | +--ro (yp:selected-content)? 1055 | | +--:(yp:by-reference) 1056 | | | +--ro yp:selection-filter-ref selection-filter-ref 1057 | | +--:(yp:within-subscription) 1058 | | +--ro (yp:filter-spec)? 1059 | | +--:(yp:datastore-subtree-filter) 1060 | | | +--ro yp:datastore-subtree-filter? 1061 | | | {sn:subtree}? 1062 | | +--:(yp:datastore-xpath-filter) 1063 | | +--ro yp:datastore-xpath-filter? 1064 | | yang:xpath1.0 {sn:xpath}? 1065 | +--ro stop-time? yang:date-and-time 1066 | +--ro dscp? inet:dscp {qos}? 1067 | +--ro weighting? uint8 {qos}? 1068 | +--ro dependency? subscription-id {qos}? 1069 | +--ro (yp:update-trigger)? 1070 | +--:(yp:periodic) 1071 | | +--ro yp:periodic! 1072 | | +--ro yp:period yang:timeticks 1073 | | +--ro yp:anchor-time? yang:date-and-time 1074 | +--:(yp:on-change) {on-change}? 1075 | +--ro yp:on-change! 1076 | +--ro yp:dampening-period? yang:timeticks 1077 | +--ro yp:no-synch-on-start? empty 1078 | +--ro yp:excluded-change* change-type 1079 +---n subscription-terminated 1080 | +--ro identifier subscription-id 1081 | +--ro reason identityref 1082 +---n subscription-suspended 1083 +--ro identifier subscription-id 1084 +--ro reason identityref 1086 module: ietf-yang-push 1087 rpcs: 1088 +---x resynch-subscription {on-change}? 1089 +---w input 1090 +---w identifier sn:subscription-id 1092 yang-data: (for placement into rpc error responses) 1093 +-- resynch-subscription-error 1094 | +--ro reason? identityref 1095 | +--ro period-hint? timeticks 1096 | +--ro filter-failure-hint? string 1097 | +--ro object-count-estimate? uint32 1098 | +--ro object-count-limit? uint32 1099 | +--ro kilobytes-estimate? uint32 1100 | +--ro kilobytes-limit? uint32 1101 +-- establish-subscription-error-datastore 1102 | +--ro reason? identityref 1103 | +--ro period-hint? timeticks 1104 | +--ro filter-failure-hint? string 1105 | +--ro object-count-estimate? uint32 1106 | +--ro object-count-limit? uint32 1107 | +--ro kilobytes-estimate? uint32 1108 | +--ro kilobytes-limit? uint32 1109 +-- modify-subscription-error-datastore 1110 +--ro reason? identityref 1111 +--ro period-hint? timeticks 1112 +--ro filter-failure-hint? string 1113 +--ro object-count-estimate? uint32 1114 +--ro object-count-limit? uint32 1115 +--ro kilobytes-estimate? uint32 1116 +--ro kilobytes-limit? uint32 1118 notifications: 1119 +---n push-update 1120 | +--ro subscription-id? sn:subscription-id 1121 | +--ro updates-not-sent? empty 1122 | +--ro datastore-contents? 1123 +---n push-change-update {on-change}? 1124 +--ro subscription-id? sn:subscription-id 1125 +--ro updates-not-sent? empty 1126 +--ro datastore-changes? 1128 Figure 6: Model structure 1130 Selected components of the model are summarized below. 1132 4.2. Subscription configuration 1134 Both configured and dynamic subscriptions are represented within the 1135 list subscription. But only configured subscriptions are listed 1136 within list subscription-config. In both lists, each subscription 1137 has own list elements. New and enhanced parameters extending the 1138 basic subscription data model in 1139 [I-D.draft-ietf-netconf-subscribed-notifications] include: 1141 o The targeted datastore from which the selection is being made. 1142 The potential datastores include those from 1143 [I-D.draft-ietf-netmod-revised-datastores]. A platform may also 1144 choose to support a custom datastore. 1146 o A selection filter identifying yang nodes of interest within a 1147 datastore. Filter contents are specified via a reference to an 1148 existing filter, or via an in-line definition for only that 1149 subscription. Referenced filters allows an implementation to 1150 avoid evaluating filter acceptability during a dynamic 1151 subscription request. The case statement differentiates the 1152 options. 1154 o For periodic subscriptions, triggered updates will occur at the 1155 boundaries of a specified time interval. These boundaries many be 1156 calculated from the periodic parameters: 1158 * a "period" which defines duration between period push updates. 1160 * an "anchor-time"; update intervals always fall on the points in 1161 time that are a multiple of a "period" from an "anchor-time". 1162 If "anchor-time" is not provided, then the "anchor-time" MUST 1163 be set with the creation time of the initial update record. 1165 o For on-change subscriptions, assuming any dampening period has 1166 completed, triggering occurs whenever a change in the subscribed 1167 information is detected. On-change subscriptions have more 1168 complex semantics that is guided by its own set of parameters: 1170 * a "dampening-period" specifies the interval that must pass 1171 before a successive update for the subscription is sent. If no 1172 dampening period is in effect, the update is sent immediately. 1173 If a subsequent change is detected, another update is only sent 1174 once the dampening period has passed for this subscription. 1176 * an "excluded-change" flag which allows restriction of the types 1177 of changes for which updates should be sent (e.g., only add to 1178 an update record on object creation). 1180 * a "no-synch-on-start" flag which specifies whether a complete 1181 update with all the subscribed data is to be sent at the 1182 beginning of a subscription. 1184 4.3. YANG Notifications 1186 4.3.1. State Change Notifications 1188 Subscription state notifications and mechanism are reused from 1189 [I-D.draft-ietf-netconf-subscribed-notifications]. Some have been 1190 augmented to include the datastore specific objects. 1192 4.3.2. Notifications for Subscribed Content 1194 Along with the subscribed content, there are other objects which 1195 might be part of a "push-update" or "push-change-update" 1197 A "subscription-id" MUST be transported along with the subscribed 1198 contents. An [RFC5277] Section 4 one-way notification MAY be used 1199 for encoding updates. Where it is, the relevant "subscription-id" 1200 MUST be encoded as the first element within each "push-update" or 1201 "push-change-update". This allows a receiver to differentiate which 1202 subscription resulted in a particular push. 1204 A "time-of-update" which represents the time an update record 1205 snapshot was generated. A receiver MAY assume that a publisher's 1206 objects have these pushed values at this point in time. 1208 An "updates-not-sent" object. This object indicates that not all 1209 changes which have occurred since the last update are actually 1210 included with this update. In other words, the publisher has failed 1211 to fulfill its full subscription obligations. (For example a 1212 datastore was unable to providing the full set of datastore nodes to 1213 a publisher process.) To facilitate re-synchronization of on-change 1214 subscriptions, a publisher MAY subsequently send a "push-update" 1215 containing a full selection snapshot of subscribed data. 1217 4.4. YANG RPCs 1219 YANG-Push subscriptions are established, modified, and deleted using 1220 RPCs augmented from 1221 [I-D.draft-ietf-netconf-subscribed-notifications]. 1223 4.4.1. Establish-subscription RPC 1225 The subscriber sends an establish-subscription RPC with the 1226 parameters in section 3.1. An example might look like: 1228 1230 1233 1234 1235 ds:operational 1236 1237 1240 1241 1242 500 1243 1244 1245 1247 Figure 7: Establish-subscription RPC 1249 The publisher MUST respond explicitly positively (i.e., subscription 1250 accepted) or negatively (i.e., subscription rejected) to the request. 1251 Positive responses include the "identifier" of the accepted 1252 subscription. In that case a publisher MAY respond: 1254 1256 1258 ok 1259 1260 1262 52 1263 1264 1266 Figure 8: Establish-subscription positive RPC response 1268 A subscription can be rejected for multiple reasons, including the 1269 lack of authorization to establish a subscription, no capacity to 1270 serve the subscription at the publisher, or the inability of the 1271 publisher to select datastore content at the requested cadence. 1273 If a request is rejected because the publisher is not able to serve 1274 it, the publisher SHOULD include in the returned error hints which 1275 help a subscriber understand subscription parameters might have been 1276 accepted for the request. These hints would be included within the 1277 yang-data structure "establish-subscription-error-datastore". 1278 However even with these hints, there are no guarantee that subsequent 1279 requests will in fact be accepted. 1281 The specific parameters to be returned in as part of the RPC error 1282 response depend on the specific transport that is used to manage the 1283 subscription. In the case of NETCONF 1284 [I-D.draft-ietf-netconf-netconf-event-notifications], when a 1285 subscription request is rejected, the NETCONF RPC reply MUST include 1286 an "rpc-error" element with the following elements: 1288 o "error-type" of "rpc". 1290 o "error-tag" of "operation-failed". 1292 o Optionally, an "error-severity" of "error" (this MAY but does not 1293 have to be included). 1295 o "error-app-tag" with the value being a string that corresponds to 1296 an identity with a base of "establish-subscription-error". 1298 o Optionally, "error-info" containing XML-encoded data with hints 1299 for parameter settings that might result in future RPC success per 1300 yang-data definition "establish-subscription-error-datastore". 1302 For example, for the following request: 1304 1306 1309 1311 ds:operational 1312 1313 1315 /ex:foo 1316 1317 1318 100 1319 1320 1321 1323 Figure 9: Establish-subscription request example 2 1325 a publisher that cannot serve on-change updates but periodic updates 1326 might return the following: 1328 1330 1331 application 1332 operation-failed 1333 error 1334 1335 on-change-unsupported 1336 1337 1339 /yp:periodic/yp:period 1340 1341 1342 1344 Figure 10: Establish-subscription error response example 2 1346 4.4.2. Modify-subscription RPC 1348 The subscriber MAY invoke the "modify-subscription" RPC for a 1349 subscription it previously established. The subscriber will include 1350 newly desired values in the "modify-subscription" RPC. Parameters 1351 not included MUST remain unmodified. Below is an example where a 1352 subscriber attempts to modify the "period" of a subscription. 1354 1356 1359 1011 1360 1362 ds:operational 1363 1364 1366 /ex:bar 1367 1368 1369 250 1370 1371 1372 1374 Figure 11: Modify subscription request 1376 The publisher MUST respond explicitly positively or negatively to the 1377 request. If the subscription modification is rejected, the 1378 subscription is maintained as it was before the modification request. 1379 In addition, the publisher MUST send an rpc error response. This rpc 1380 error response may contain hints encapsulated within the yang-data 1381 structure "modify-subscription-error-datastore". A subscription MAY 1382 be modified multiple times. 1384 The specific parameters to be returned in as part of the RPC error 1385 response depend on the specific transport that is used to manage the 1386 subscription. In the case of NETCONF 1387 [I-D.draft-ietf-netconf-netconf-event-notifications], when a 1388 subscription request is rejected, the NETCONF RPC reply MUST include 1389 an "rpc-error" element with the following elements: 1391 o "error-type" of "rpc". 1393 o "error-tag" of "operation-failed". 1395 o Optionally, an "error-severity" of "error" (this MAY but does not 1396 have to be included). 1398 o "error-app-tag" with the value being a string that corresponds to 1399 an identity with a base of "modify-subscription-error". 1401 o "error-path" pointing to the object or parameter that caused the 1402 rejection. 1404 o Optionally, "error-info" containing XML-encoded data with hints 1405 for parameter settings that might result in future RPC success per 1406 yang-data definition "modify-subscription-error-datastore". 1408 A configured subscription cannot be modified using "modify- 1409 subscription" RPC. Instead, the configuration needs to be edited as 1410 needed. 1412 4.4.3. Delete-subscription RPC 1414 To stop receiving updates from a subscription and effectively delete 1415 a subscription that had previously been established using an 1416 "establish-subscription" RPC, a subscriber can send a "delete- 1417 subscription" RPC, which takes as only input the subscription's 1418 "identifier". 1420 Configured subscriptions cannot be deleted via RPC, but have to be 1421 removed from the configuration. This RPC is identical to the RPC 1422 from [I-D.draft-ietf-netconf-subscribed-notifications]. 1424 4.4.4. Resynch-subscription RPC 1426 This RPC is only applicable only for on-change subscriptions 1427 previously been established using an "establish-subscription" RPC. 1428 For example: 1430 1432 1435 1011 1436 1437 1439 Resynch subscription 1441 On receipt, a publisher must either accept the request and quickly 1442 follow with a "push-update", or send an appropriate error within an 1443 rpc error response. Within an error response, the publisher may 1444 include supplemental information about the reasons within the yang- 1445 data structure "resynch-subscription-error". 1447 4.4.5. YANG Module Synchronization 1449 To make subscription requests, the subscriber needs to know the YANG 1450 module library available on the publisher. The YANG 1.0 module 1451 library information is sent by a NETCONF server in the NETCONF 1452 "hello" message. For YANG 1.1 modules and all modules used with the 1453 RESTCONF [RFC8040] protocol, this information is provided by the YANG 1454 Library module (ietf-yang-library.yang from [RFC7895]. This YANG 1455 library information is important for the receiver to reproduce the 1456 set of object definitions used within the publisher. 1458 The YANG library includes a module list with the name, revision, 1459 enabled features, and applied deviations for each YANG module 1460 implemented by the publisher. The receiver is expected to know the 1461 YANG library information before starting a subscription. The 1462 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module 1463 can be used to cache the YANG library information. 1465 The set of modules, revisions, features, and deviations can change at 1466 run-time (if supported by the publisher implementation). In this 1467 case, the receiver needs to be informed of module changes before 1468 datastore nodes from changed modules can be processed correctly. The 1469 YANG library provides a simple "yang-library-change" notification 1470 that informs the subscriber that the library has changed. The 1471 receiver then needs to re-read the entire YANG library data for the 1472 replicated publisher in order to detect the specific YANG library 1473 changes. The "ietf-netconf-notifications" module defined in 1474 [RFC6470] contains a "netconf-capability-change" notification that 1475 can identify specific module changes. For example, the module URI 1476 capability of a newly loaded module will be listed in the "added- 1477 capability" leaf-list, and the module URI capability of an removed 1478 module will be listed in the "deleted-capability" leaf-list. 1480 5. YANG module 1482 ; file "ietf-yang-push@2018-02-05.yang" 1483 module ietf-yang-push { 1484 yang-version 1.1; 1485 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1486 prefix yp; 1488 import ietf-yang-types { 1489 prefix yang; 1490 } 1491 import ietf-subscribed-notifications { 1492 prefix sn; 1493 } 1494 import ietf-datastores { 1495 prefix ds; 1496 } 1497 import ietf-restconf { 1498 prefix rc; 1499 } 1501 organization "IETF"; 1502 contact 1503 "WG Web: 1504 WG List: 1506 Editor: Alexander Clemm 1507 1509 Editor: Eric Voit 1510 1512 Editor: Alberto Gonzalez Prieto 1513 1515 Editor: Ambika Prasad Tripathy 1516 1518 Editor: Einar Nilsen-Nygaard 1519 1521 Editor: Andy Bierman 1522 1524 Editor: Balazs Lengyel 1525 "; 1527 description 1528 "This module contains YANG specifications for YANG push."; 1530 revision 2018-02-05 { 1531 description 1532 "Initial revision."; 1533 reference 1534 "draft-ietf-netconf-yang-push-13"; 1535 } 1537 /* 1538 * FEATURES 1539 */ 1541 feature on-change { 1542 description 1543 "This feature indicates that on-change triggered subscriptions 1544 are supported."; 1545 } 1547 /* 1548 * IDENTITIES 1549 */ 1551 /* Error type identities for datastore subscription */ 1553 identity resynch-subscription-error { 1554 description 1555 "Problem found while attempting to fulfill an 1556 'resynch-subscription' rpc request. "; 1557 } 1559 identity cant-exclude { 1560 base sn:establish-subscription-error; 1561 description 1562 "Unable to remove the set of 'excluded-changes'. This means the 1563 publisher is unable to restrict 'push-change-update's to just the 1564 change types requested for this subscription."; 1565 } 1567 identity datastore-not-subscribable { 1568 base sn:establish-subscription-error; 1569 base sn:subscription-terminated-reason; 1570 description 1571 "This is not a subscribable datastore."; 1572 } 1574 identity no-such-subscription-resynch { 1575 base resynch-subscription-error; 1576 description 1577 "Referenced subscription doesn't exist. This may be as a result of 1578 a non-existent subscription ID, an ID which belongs to another 1579 subscriber, or an ID for configured subscription."; 1580 } 1582 identity on-change-unsupported { 1583 base sn:establish-subscription-error; 1584 description 1585 "On-change is not supported for any objects which are selectable 1586 by this filter."; 1587 } 1589 identity on-change-synch-unsupported { 1590 base sn:establish-subscription-error; 1591 description 1592 "Neither synch on start nor resynchronization are supported for 1593 this subscription. This error will be used for two reasons. First 1594 if an 'establish-subscription' RPC doesn't include 1595 'no-synch-on-start', yet the publisher can't support sending a 1596 'push-update' for this subscription for reasons other than 1597 'on-change-unsupported' or 'synchronization-size'. And second, if 1598 the 'resynch-subscription' RPC is invoked either for an existing 1599 periodic subscription, or for an on-change subscription which 1600 can't support resynchronization."; 1601 } 1603 identity period-unsupported { 1604 base sn:establish-subscription-error; 1605 base sn:modify-subscription-error; 1606 base sn:subscription-suspended-reason; 1607 description 1608 "Requested time period is too short. This can be for both 1609 periodic and on-change subscriptions (with or without 1610 dampening.) 1612 Hints suggesting an acceptable period setting may be returned 1613 as supplemental information in a corresponding RPC error 1614 response, as applicable."; 1615 } 1617 identity result-too-big { 1618 base sn:establish-subscription-error; 1619 base sn:modify-subscription-error; 1620 base sn:subscription-suspended-reason; 1621 description 1622 "Periodic or on-change push update datatrees exceed a maximum 1623 size limit. 1625 Hints on a parameter setting that would result in a reasonable 1626 size may be returned as supplemental information in a 1627 corresponding RPC error response, as applicable."; 1628 } 1630 identity synchronization-size { 1631 base sn:establish-subscription-error; 1632 base sn:modify-subscription-error; 1633 base resynch-subscription-error; 1634 base sn:subscription-suspended-reason; 1635 description 1636 "Synch-on-start or resynchronization datatree exceeds a maximum 1637 size limit. 1639 Hints on a parameter setting that would result in a reasonable 1640 size may be returned as supplemental information in a 1641 corresponding RPC error response, as applicable."; 1642 } 1644 identity unchanging-selection { 1645 base sn:establish-subscription-error; 1646 base sn:modify-subscription-error; 1647 base sn:subscription-terminated-reason; 1648 description 1649 "Selection filter is unlikely to ever select datatree nodes. This 1650 means that based on the subscriber's current access rights, the 1651 publisher recognizes that the selection filter is unlikely to ever 1652 select datatree nodes which change. Examples for this might be 1653 that node or subtree doesn't exist, read access is not permitted 1654 for a receiver, or static objects that only change at reboot have 1655 been chosen."; 1656 } 1658 /* 1659 * TYPE DEFINITIONS 1660 */ 1662 typedef change-type { 1663 type enumeration { 1664 enum "create" { 1665 description 1666 "Create a new data resource if it does not already exist. If 1667 it already exists, replace."; 1668 } 1669 enum "delete" { 1670 description 1671 "Delete a data resource if it already exists. If it does not 1672 exists, take no action."; 1673 } 1674 enum "insert" { 1675 description 1676 "Insert a new user-ordered data resource"; 1677 } 1678 enum "merge" { 1679 description 1680 "merge the edit value with the target data resource; create 1681 if it does not already exist"; 1682 } 1683 enum "move" { 1684 description 1685 "Reorder the target data resource"; 1686 } 1687 enum "replace" { 1688 description 1689 "Replace the target data resource with the edit value"; 1690 } 1691 enum "remove" { 1692 description 1693 "Remove a data resource if it already exists "; 1694 } 1695 } 1696 description 1697 "Specifies different types of datastore changes."; 1698 reference 1699 "RFC 8072 section 2.5, with a delta that it is valid for a 1700 receiver to process an update record which performs a create 1701 operation on a datastore node the receiver believes exists, or to 1702 process a delete on a datastore node the receiver believes is 1703 missing."; 1704 } 1706 typedef selection-filter-ref { 1707 type leafref { 1708 path "/sn:filters/yp:selection-filter/yp:identifier"; 1709 } 1710 description 1711 "This type is used to reference a selection filter."; 1712 } 1714 /* 1715 * GROUP DEFINITIONS 1716 */ 1718 grouping datastore-criteria { 1719 description 1720 "A grouping to define criteria for which selected objects from 1721 a targeted datastore should be included in push updates."; 1722 leaf datastore { 1723 type identityref { 1724 base ds:datastore; 1725 } 1726 mandatory true; 1727 description 1728 "Datastore from which to retrieve data."; 1729 } 1730 uses selection-filter-objects; 1731 } 1733 grouping selection-filter-types { 1734 description 1735 "This grouping defines a selector for objects from a 1736 datastore."; 1737 choice filter-spec { 1738 description 1739 "The content filter specification for this request."; 1740 anydata datastore-subtree-filter { 1741 if-feature "sn:subtree"; 1742 description 1743 "This parameter identifies the portions of the 1744 target datastore to retrieve."; 1745 } 1746 leaf datastore-xpath-filter { 1747 if-feature "sn:xpath"; 1748 type yang:xpath1.0; 1749 description 1750 "This parameter contains an XPath expression identifying the 1751 portions of the target datastore to retrieve. 1753 If the expression returns a node-set, all nodes in the 1754 node-set are selected by the filter. Otherwise, if the 1755 expression does not return a node-set, the filter 1756 doesn't select any nodes. 1758 The expression is evaluated in the following XPath context: 1760 o The set of namespace declarations are those in scope on 1761 the 'xpath-filter' leaf element. 1763 o The set of variable bindings is empty. 1765 o The function library is the core function library, and 1766 the XPath functions defined in section 10 in RFC 7950. 1768 o The context node is the root node of the target 1769 datastore."; 1770 } 1771 } 1772 } 1774 grouping selection-filter-objects { 1775 description 1776 "This grouping defines a selector for objects from a 1777 datastore."; 1778 choice selected-content { 1779 description 1780 "The source of the selection filter applied to the subscription. 1781 This will come either referenced from a global list, or be 1782 provided within the subscription itself."; 1784 case by-reference { 1785 description 1786 "Incorporate a filter that has been configured separately."; 1787 leaf selection-filter-ref { 1788 type selection-filter-ref; 1789 mandatory true; 1790 description 1791 "References an existing selection filter which is to be 1792 applied to the subscription."; 1793 } 1794 } 1795 case within-subscription { 1796 description 1797 "Local definition allows a filter to have the same lifecycle 1798 as the subscription."; 1799 uses selection-filter-types; 1801 } 1802 } 1803 } 1805 grouping update-policy-modifiable { 1806 description 1807 "This grouping describes the datastore specific subscription 1808 conditions that can be changed during the lifetime of the 1809 subscription."; 1810 choice update-trigger { 1811 description 1812 "Defines necessary conditions for sending an event record to 1813 the subscriber."; 1814 case periodic { 1815 container periodic { 1816 presence "indicates an periodic subscription"; 1817 description 1818 "The publisher is requested to notify periodically the 1819 current values of the datastore as defined by the selection 1820 filter."; 1821 leaf period { 1822 type yang:timeticks; 1823 mandatory true; 1824 description 1825 "Duration of time which should occur between periodic 1826 push updates. Where the anchor-time is 1827 available, the push will include the objects and their 1828 values which exist at an exact multiple of timeticks 1829 aligning to this start-time anchor."; 1830 } 1831 leaf anchor-time { 1832 type yang:date-and-time; 1833 description 1834 "Designates a timestamp before or after which a series of 1835 periodic push updates are determined. The next update 1836 will take place at a whole multiple interval from the 1837 anchor time. For example, for an anchor time is set for 1838 the top of a particular minute and a period interval of a 1839 minute, updates will be sent at the top of every minute 1840 this subscription is active."; 1841 } 1842 } 1843 } 1844 case on-change { 1845 if-feature "on-change"; 1846 container on-change { 1847 presence "indicates an on-change subscription"; 1848 description 1849 "The publisher is requested to notify changes in values in 1850 the datastore subset as defined by a selection filter."; 1851 leaf dampening-period { 1852 type yang:timeticks; 1853 default 0; 1854 description 1855 "Specifies the minimum interval between the assembly of 1856 successive update records for a single receiver of a 1857 subscription. Whenever subscribed objects change, and a 1858 dampening period interval (which may be zero) has elapsed 1859 since the previous update record creation for a receiver, 1860 then any subscribed objects and properties which have 1861 changed since the previous update record will have their 1862 current values marshalled and placed into a new update 1863 record."; 1864 } 1865 } 1866 } 1867 } 1868 } 1870 grouping update-policy { 1871 description 1872 "This grouping describes the datastore specific subscription 1873 conditions of a subscription."; 1874 uses update-policy-modifiable { 1875 augment "update-trigger/on-change/on-change" { 1876 description 1877 "Includes objects not modifiable once subscription is 1878 established."; 1879 leaf no-synch-on-start { 1880 type empty; 1881 description 1882 "The presence of this object restricts an on-change 1883 subscription from sending push-update notifications. When 1884 present, pushing a full selection per the terms of the 1885 selection filter MUST NOT be done for this subscription. 1886 Only updates about changes, i.e. only push-change-update 1887 notifications are sent. When absent (default behavior), 1888 in order to facilitate a receiver's synchronization, a full 1889 update is sent when the subscription starts using a 1890 push-update notification, just like in the case of a 1891 periodic subscription. After that, push-change-update 1892 notifications are exclusively sent unless the publisher 1893 chooses to resynch the subscription via a new push-update 1894 notification."; 1895 } 1896 leaf-list excluded-change { 1897 type change-type; 1898 description 1899 "Use to restrict which changes trigger an update. 1900 For example, if modify is excluded, only creation and 1901 deletion of objects is reported."; 1902 } 1903 } 1904 } 1905 } 1907 grouping hints { 1908 description 1909 "Parameters associated with some error on for a subscription made 1910 upon a datastore."; 1911 leaf period-hint { 1912 type yang:timeticks; 1913 description 1914 "Returned when the requested time period is too short. This 1915 hint can assert a viable period for either a periodic push 1916 cadence or an on-change dampening interval."; 1917 } 1918 leaf filter-failure-hint { 1919 type string; 1920 description 1921 "Information describing where and/or why a provided filter 1922 was unsupportable for a subscription."; 1923 } 1924 leaf object-count-estimate { 1925 type uint32; 1926 description 1927 "If there are too many objects which could potentially be 1928 returned by the selection filter, this identifies the estimate 1929 of the number of objects which the filter would potentially 1930 pass."; 1931 } 1932 leaf object-count-limit { 1933 type uint32; 1934 description 1935 "If there are too many objects which could be returned by the 1936 selection filter, this identifies the upper limit of the 1937 publisher's ability to service for this subscription."; 1938 } 1939 leaf kilobytes-estimate { 1940 type uint32; 1941 description 1942 "If the returned information could be beyond the capacity of 1943 the publisher, this would identify the data size which could 1944 result from this selection filter."; 1945 } 1946 leaf kilobytes-limit { 1947 type uint32; 1948 description 1949 "If the returned information would be beyond the capacity of 1950 the publisher, this identifies the upper limit of the 1951 publisher's ability to service for this subscription."; 1952 } 1953 } 1955 /* 1956 * RPCs 1957 */ 1959 rpc resynch-subscription { 1960 if-feature "on-change"; 1961 description 1962 "This RPC allows a subscriber of an active on-change 1963 subscription to request a full push of objects in there current 1964 state. A successful result would be the set of YANG objects 1965 equivalent to a Get using the existing selection criteria. This 1966 request may only come from the same subscriber using the 1967 establish-subscription RPC."; 1968 input { 1969 leaf identifier { 1970 type sn:subscription-id; 1971 mandatory true; 1972 description 1973 "Identifier of the subscription that is to be resynched."; 1974 } 1976 } 1977 } 1979 rc:yang-data resynch-subscription-error { 1980 container resynch-subscription-error { 1981 description 1982 "If a 'resynch-subscription' RPC fails, the subscription is not 1983 resynched and the RPC error response MUST indicate the reason 1984 for this failure. This yang-data MAY be inserted as structured 1985 data within a subscription's RPC error response to indicate the 1986 failure reason."; 1987 leaf reason { 1988 type identityref { 1989 base resynch-subscription-error; 1990 } 1991 mandatory true; 1992 description 1993 "Indicates the reason why the publisher has declined a request 1994 for subscription resynchronization."; 1995 } 1996 uses hints; 1997 } 1998 } 2000 augment "/sn:establish-subscription/sn:input" { 2001 description 2002 "This augmentation adds additional subscription parameters that 2003 apply specifically to datastore updates to RPC input."; 2004 uses update-policy; 2005 } 2007 augment "/sn:establish-subscription/sn:input/sn:target" { 2008 description 2009 "This augmentation adds the datastore as a valid parameter object 2010 for the subscription to RPC input. This provides a target for 2011 the filter."; 2012 case datastore { 2013 description 2014 "Information specifying the parameters of an request for a 2015 datastore subscription."; 2016 uses datastore-criteria; 2017 } 2018 } 2020 rc:yang-data establish-subscription-error-datastore { 2021 container establish-subscription-error-datastore { 2022 description 2023 "If any 'establish-subscription' RPC parameters are 2024 unsupportable against the datastore, a subscription is not 2025 created and the RPC error response MUST indicate the reason why 2026 the subscription failed to be created. This yang-data MAY be 2027 inserted as structured data within a subscription's RPC error 2028 response to indicate the failure reason. This yang-data MUST be 2029 inserted if hints are to be provided back to the subscriber."; 2030 leaf reason { 2031 type identityref { 2032 base sn:establish-subscription-error; 2033 } 2034 description 2035 "Indicates the reason why the subscription has failed to 2036 be created to a targeted datastore."; 2037 } 2038 uses hints; 2039 } 2040 } 2042 augment "/sn:modify-subscription/sn:input" { 2043 description 2044 "This augmentation adds additional subscription parameters 2045 specific to datastore updates."; 2046 uses update-policy-modifiable; 2047 } 2049 augment "/sn:modify-subscription/sn:input/sn:target" { 2050 description 2051 "This augmentation adds the datastore as a valid parameter object 2052 for the subscription to RPC input. This provides a target for 2053 the filter."; 2054 case datastore { 2055 description 2056 "Information specifying the parameters of an request for a 2057 datastore subscription."; 2058 uses selection-filter-objects; 2059 } 2060 } 2062 rc:yang-data modify-subscription-error-datastore { 2063 container modify-subscription-error-datastore { 2064 description 2065 "This yang-data MAY be provided as part of a subscription's RPC 2066 error response when there is a failure of a 2067 'modify-subscription' RPC which has been made against a 2068 datastore. This yang-data MUST be used if hints are to be 2069 provides back to the subscriber."; 2070 leaf reason { 2071 type identityref { 2072 base sn:modify-subscription-error; 2073 } 2074 description 2075 "Indicates the reason why the subscription has failed to 2076 be modified."; 2077 } 2078 uses hints; 2079 } 2080 } 2082 /* 2083 * NOTIFICATIONS 2084 */ 2086 notification push-update { 2087 description 2088 "This notification contains a push update, containing data 2089 subscribed to via a subscription. This notification is sent for 2090 periodic updates, for a periodic subscription. It can also be 2091 used for synchronization updates of an on-change subscription. 2092 This notification shall only be sent to receivers of a 2093 subscription; it does not constitute a general-purpose 2094 notification."; 2095 leaf subscription-id { 2096 type sn:subscription-id; 2097 description 2098 "This references the subscription which drove the notification 2099 to be sent."; 2100 } 2101 leaf updates-not-sent { 2102 type empty; 2103 description 2104 "This is a flag which indicates that not all datastore nodes 2105 subscribed to are included with this update. In other words, 2106 the publisher has failed to fulfill its full subscription 2107 obligations, and despite its best efforts is providing an 2108 incomplete set of objects."; 2109 } 2110 anydata datastore-contents { 2111 description 2112 "This contains the updated data. It constitutes a snapshot 2113 at the time-of-update of the set of data that has been 2114 subscribed to. The format and syntax of the data 2115 corresponds to the format and syntax of data that would be 2116 returned in a corresponding get operation with the same 2117 selection filter parameters applied."; 2118 } 2119 } 2120 notification push-change-update { 2121 if-feature "on-change"; 2122 description 2123 "This notification contains an on-change push update. This 2124 notification shall only be sent to the receivers of a 2125 subscription; it does not constitute a general-purpose 2126 notification."; 2127 leaf subscription-id { 2128 type sn:subscription-id; 2129 description 2130 "This references the subscription which drove the notification 2131 to be sent."; 2132 } 2133 leaf updates-not-sent { 2134 type empty; 2135 description 2136 "The presence of this object indicates not all changes which 2137 have occurred since the last update are included with this 2138 update. In other words, the publisher has failed to 2139 fulfill its full subscription obligations, for example in 2140 cases where it was not able to keep up with a change burst."; 2141 } 2142 anydata datastore-changes { 2143 description 2144 "This contains the set of datastore changes needed 2145 to update a remote datastore starting at the time of the 2146 previous update, per the terms of the subscription. Changes 2147 are encoded analogous to the syntax of a corresponding yang- 2148 patch operation, i.e. a yang-patch operation applied to the 2149 datastore implied by the previous update to result in the 2150 current state."; 2151 reference 2152 "RFC 8072 section 2.5, with a delta that it is ok to receive 2153 ability create on an existing node, or receive a delete on a 2154 missing node."; 2155 } 2156 } 2158 augment "/sn:subscription-started" { 2159 description 2160 "This augmentation adds many datastore specific objects to 2161 the notification that a subscription has started."; 2162 uses update-policy; 2163 } 2165 augment "/sn:subscription-started/sn:target" { 2166 description 2167 "This augmentation allows the datastore to be included as part 2168 of the notification that a subscription has started."; 2169 case datastore { 2170 uses datastore-criteria { 2171 refine "selected-content/within-subscription" { 2172 description 2173 "Specifies where the selection filter, and where came from 2174 within the subscription and then populated within this 2175 notification. If the 'selection-filter-ref' is populated, 2176 the filter within the subscription came from the 'filters' 2177 container. Otherwise it is populated in-line as part of the 2178 subscription itself."; 2179 } 2180 } 2181 } 2182 } 2184 augment "/sn:subscription-modified" { 2185 description 2186 "This augmentation adds many datastore specific objects to 2187 the notification that a subscription has been modified."; 2188 uses update-policy; 2189 } 2190 augment "/sn:subscription-modified/sn:target" { 2191 description 2192 "This augmentation allows the datastore to be included as part 2193 of the notification that a subscription has been modified."; 2194 case datastore { 2195 uses datastore-criteria { 2196 refine "selected-content/within-subscription" { 2197 description 2198 "Specifies where the selection filter, and where came from 2199 within the subscription and then populated within this 2200 notification. If the 'selection-filter-ref' is populated, 2201 the filter within the subscription came from the 'filters' 2202 container. Otherwise it is populated in-line as part of the 2203 subscription itself."; 2204 } 2205 } 2206 } 2207 } 2209 /* 2210 * DATA NODES 2211 */ 2213 augment "/sn:filters" { 2214 description 2215 "This augmentation allows the datastore to be included as part 2216 of the selection filtering criteria for a subscription."; 2217 list selection-filter { 2218 key "identifier"; 2219 description 2220 "A list of pre-positioned filters that can be applied 2221 to datastore subscriptions."; 2222 leaf identifier { 2223 type sn:filter-id; 2224 description 2225 "An identifier to differentiate between selection filters."; 2226 } 2227 uses selection-filter-types; 2228 } 2229 } 2231 augment "/sn:subscriptions/sn:subscription" { 2232 description 2233 "This augmentation adds many datastore specific objects to a 2234 subscription."; 2235 uses update-policy; 2236 } 2237 augment "/sn:subscriptions/sn:subscription/sn:target" { 2238 description 2239 "This augmentation allows the datastore to be included as part 2240 of the selection filtering criteria for a subscription."; 2241 case datastore { 2242 uses datastore-criteria; 2243 } 2244 } 2245 } 2247 2249 6. IANA Considerations 2251 This document registers the following namespace URI in the "IETF XML 2252 Registry" [RFC3688]: 2254 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push 2255 Registrant Contact: The IESG. 2256 XML: N/A; the requested URI is an XML namespace. 2258 This document registers the following YANG module in the "YANG Module 2259 Names" registry [RFC6020]: 2261 Name: ietf-yang-push 2262 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push 2263 Prefix: yp 2264 Reference: draft-ietf-netconf-yang-push-12.txt (RFC form) 2266 7. Security Considerations 2268 All security considerations from 2269 [I-D.draft-ietf-netconf-subscribed-notifications] are relevant for 2270 datastores. In addition there are specific security considerations 2271 for receivers defined in Section 3.9 2273 If the access control permissions on subscribed YANG nodes change 2274 during the lifecycle of a subscription, a publisher MUST either 2275 transparently conform to the new access control permissions, or must 2276 terminate or restart the subscriptions so that new access control 2277 permissions are re-established. 2279 The NETCONF Authorization Control Model SHOULD be used to restrict 2280 the delivery of YANG nodes for which the receiver has no access. 2282 8. Acknowledgments 2284 For their valuable comments, discussions, and feedback, we wish to 2285 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei 2286 Guo, Michael Scharf, Martin Bjorklund, and Guangying Zheng. 2288 9. References 2290 9.1. Normative References 2292 [I-D.draft-ietf-netconf-subscribed-notifications] 2293 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 2294 and E. Nilsen-Nygaard, "Custom Subscription to Event 2295 Streams", draft-ietf-netconf-subscribed-notifications-06 2296 (work in progress), January 2018. 2298 [I-D.draft-ietf-netmod-revised-datastores] 2299 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2300 and R. Wilton, "Network Management Datastore 2301 Architecture", draft-ietf-netmod-revised-datastores-04 2302 (work in progress), August 2017. 2304 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2305 DOI 10.17487/RFC3688, January 2004, 2306 . 2308 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2309 the Network Configuration Protocol (NETCONF)", RFC 6020, 2310 DOI 10.17487/RFC6020, October 2010, 2311 . 2313 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2314 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 2315 February 2012, . 2317 [RFC6536bis] 2318 Bierman, A. and M. Bjorklund, "Network Configuration 2319 Protocol (NETCONF) Access Control Model", draft-ietf- 2320 netconf-rfc6536bis-05 (work in progress), September 2017. 2322 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 2323 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 2324 . 2326 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2327 Media Type", RFC 8072, DOI 10.17487/RFC8072, February 2328 2017, . 2330 9.2. Informative References 2332 [I-D.draft-ietf-netconf-netconf-event-notifications] 2333 Gonzalez Prieto, A., Clemm, A., Voit, E., Nilsen-Nygaard, 2334 E., and A. Tripathy, "NETCONF Support for Event 2335 Notifications", September 2017. 2337 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2338 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 2339 . 2341 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2342 and A. Bierman, Ed., "Network Configuration Protocol 2343 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2344 . 2346 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2347 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 2348 . 2350 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2351 for Subscription to YANG Datastores", RFC 7923, 2352 DOI 10.17487/RFC7923, June 2016, 2353 . 2355 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2356 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2357 . 2359 Appendix A. Appendix A: Subscription Errors 2361 A.1. RPC Failures 2363 Rejection of an RPC for any reason is indicated by via RPC error 2364 response from the publisher. Valid RPC errors returned include both 2365 existing transport layer RPC error codes, such as those seen with 2366 NETCONF in [RFC6241], as well as subscription specific errors such as 2367 those defined within the YANG model. As a result, how subscription 2368 errors are encoded within an RPC error response is transport 2369 dependent. 2371 References to specific identities within the either the subscribed- 2372 notifications YANG model or the yang-push YANG model may be returned 2373 as part of the error responses resulting from failed attempts at 2374 datastore subscription. Following are valid errors per RPC (note: 2375 throughout this section the prefix 'sn' indicates an item imported 2376 from the subscribed-notifications.yang model): 2378 establish-subscription modify-subscription 2379 ---------------------- ------------------- 2380 cant-exclude sn:filter-unsupported 2381 datastore-not-subscribable sn:insufficient-resources 2382 sn:dscp-unavailable sn:no-such-subscription 2383 sn:filter-unsupported period-unsupported 2384 sn:insufficient-resources result-too-big 2385 on-change-unsupported synchronization-size 2386 on-change-synch-unsupported unchanging-selection 2387 period-unsupported 2388 result-too-big resynch-subscription 2389 synchronization-size -------------------- 2390 unchanging-selection no-such-subscription-resynch 2391 synchronization-size 2393 delete-subscription kill-subscription 2394 ---------------------- ----------------- 2395 sn:no-such-subscription sn:no-such-subscription 2397 There is one final set of transport independent RPC error elements 2398 included in the YANG model. These are the following four yang-data 2399 structures for failed datastore subscriptions: 2401 1. yang-data establish-subscription-error-datastore 2402 This MUST be returned if an RPC error reason has not been placed 2403 elsewhere within the transport portion of a failed "establish- 2404 subscription" RPC response. This MUST be sent if hints on how to 2405 overcome the RPC error are included. 2407 2. yang-data modify-subscription-error-datastore 2408 This MUST be returned if an RPC error reason has not been placed 2409 elsewhere within the transport portion of a failed "modify-subscription" 2410 RPC response. This MUST be sent if hints on how to overcome the RPC 2411 error are included. 2413 3. yang-data sn:delete-subscription-error 2414 This MUST be returned if an RPC error reason has not been placed 2415 elsewhere within the transport portion of a failed "delete-subscription" 2416 or "kill-subscription" RPC response. 2418 4. yang-data resynch-subscription-error 2419 This MUST be returned if an RPC error reason has not been placed 2420 elsewhere within the transport portion of a failed "resynch- 2421 subscription" RPC response. 2423 A.2. Notifications of Failure 2425 A subscription may be unexpectedly terminated or suspended 2426 independent of any RPC or configuration operation. In such cases, 2427 indications of such a failure MUST be provided. To accomplish this, 2428 the following types of error identities may be returned within the 2429 corresponding subscription state change notification: 2431 subscription-terminated subscription-suspended 2432 ----------------------- ---------------------- 2433 datastore-not-subscribable sn:insufficient-resources 2434 sn:filter-unavailable period-unsupported 2435 sn:no-such-subscription result-too-big 2436 sn:suspension-timeout synchronization-size 2437 unchanging-selection 2439 Appendix B. Changes between revisions 2441 (To be removed by RFC editor prior to publication) 2443 v12 - v13 2445 o Hint negotiation models now show error examples. 2447 o yang-data structures for rpc errors. 2449 v11 - v12 2451 o Included Martin's review clarifications. 2453 o QoS moved to subscribed-notifications 2455 o time-of-update removed as it is redundant with RFC5277's 2456 eventTime, and other times from notification-messages. 2458 o Error model moved to match existing implementations 2460 o On-change notifiable removed, how to do this is implementation 2461 specific. 2463 o NMDA model supported. Non NMDA version at https://github.com/ 2464 netconf-wg/yang-push/ 2466 v10 - v11 2468 o Promise model reference added. 2470 o Error added for no-such-datastore 2472 o Inherited changes from subscribed notifications (such as optional 2473 feature definitions). 2475 o scrubbed the examples for proper encodings 2477 v09 - v10 2479 o Returned to the explicit filter subtyping of v00-v05 2481 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 2532 v04 to v05 2534 o Referenced based subscription document changed to Subscribed 2535 Notifications from 5277bis. 2537 o Getting operational data from filters 2539 o Extension notifiable-on-change added 2541 o New appendix on potential futures. Moved text into there from 2542 several drafts. 2544 o Subscription configuration section now just includes changed 2545 parameters from Subscribed Notifications 2547 o Subscription monitoring moved into Subscribed Notifications 2549 o New error and hint mechanisms included in text and in the yang 2550 model. 2552 o Updated examples based on the error definitions 2554 o Groupings updated for consistency 2556 o Text updates throughout 2558 v03 to v04 2560 o Updates-not-sent flag added 2562 o Not notifiable extension added 2564 o Dampening period is for whole subscription, not single objects 2566 o Moved start/stop into rfc5277bis 2568 o Client and Server changed to subscriber, publisher, and receiver 2570 o Anchor time for periodic 2572 o Message format for synchronization (i.e. synch-on-start) 2574 o Material moved into 5277bis 2576 o QoS parameters supported, by not allowed to be modified by RPC 2578 o Text updates throughout 2580 Authors' Addresses 2582 Alexander Clemm 2583 Huawei 2585 Email: ludwig@clemm.org 2587 Eric Voit 2588 Cisco Systems 2590 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