idnits 2.17.1 draft-ietf-netconf-yang-push-16.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. ** 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 233: '... period MAY be used to specif...' RFC 2119 keyword, line 263: '...cription request SHOULD be declined if...' RFC 2119 keyword, line 298: '... publisher MAY accept an on-change s...' RFC 2119 keyword, line 310: '...ely, a publisher MAY decide to simply ...' RFC 2119 keyword, line 313: '...on, the subscription MAY be suspended....' (60 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 866 has weird spacing: '...ntifier sub...' == Line 977 has weird spacing: '...ntifier sn:...' == Line 2308 has weird spacing: '...pported unc...' == 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 (May 31, 2018) is 2156 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-12 ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 3 errors (**), 0 flaws (~~), 6 warnings (==), 3 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: December 2, 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 May 31, 2018 17 YANG Datastore Subscription 18 draft-ietf-netconf-yang-push-16 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 datastore nodes enables new 26 capabilities based on the remote mirroring of configuration and 27 operational state. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on December 2, 2018. 46 Copyright Notice 48 Copyright (c) 2018 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 This document may contain material from IETF Documents or IETF 62 Contributions published or made publicly available before November 63 10, 2008. The person(s) controlling the copyright in some of this 64 material may not have granted the IETF Trust the right to allow 65 modifications of such material outside the IETF Standards Process. 66 Without obtaining an adequate license from the person(s) controlling 67 the copyright in such materials, this document may not be modified 68 outside the IETF Standards Process, and derivative works of it may 69 not be created outside the IETF Standards Process, except to format 70 it for publication as an RFC or to translate it into languages other 71 than English. 73 Table of Contents 75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 76 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4 77 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 5 78 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 5 79 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6 80 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 7 81 3.4. Reliability Considerations . . . . . . . . . . . . . . . 8 82 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 9 83 3.6. Defining the Selection with a Datastore . . . . . . . . . 10 84 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 11 85 3.8. Subscription Management . . . . . . . . . . . . . . . . . 13 86 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 14 87 3.10. On-change Notifiable YANG objects . . . . . . . . . . . . 15 88 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 16 89 4. A YANG data model for management of datastore push 90 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 17 91 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 17 92 4.2. Subscription configuration . . . . . . . . . . . . . . . 22 93 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 23 94 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 24 95 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 29 96 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 97 7. Security Considerations . . . . . . . . . . . . . . . . . . . 45 98 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46 99 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 46 100 9.1. Normative References . . . . . . . . . . . . . . . . . . 47 101 9.2. Informative References . . . . . . . . . . . . . . . . . 47 102 Appendix A. Appendix A: Subscription Errors . . . . . . . . . . 48 103 A.1. RPC Failures . . . . . . . . . . . . . . . . . . . . . . 48 104 A.2. Notifications of Failure . . . . . . . . . . . . . . . . 50 105 Appendix B. Changes between revisions . . . . . . . . . . . . . 50 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54 108 1. Introduction 110 Traditional approaches to remote visibility have been built on 111 polling. With polling, data is periodically requested and retrieved 112 by a client from a server to stay up-to-date. However, there are 113 issues associated with polling-based management: 115 o Polling incurs significant latency. This latency prohibits many 116 application types. 118 o Polling cycles may be missed, requests may be delayed or get lost, 119 often when the network is under stress and the need for the data 120 is the greatest. 122 o Polling requests may undergo slight fluctuations, resulting in 123 intervals of different lengths. The resulting data is difficult 124 to calibrate and compare. 126 o For applications that monitor for changes, many remote polling 127 cycles place ultimately fruitless load on the network, devices, 128 and applications. 130 A more effective alternative to polling is for an application to 131 receive automatic and continuous updates from a targeted subset of a 132 datastore. Accordingly, there is a need for a service that allows 133 applications to subscribe to updates from a datastore and that 134 enables the publisher to push and in effect stream those updates. 135 The requirements for such a service have been documented in 136 [RFC7923]. 138 This document defines a corresponding solution that is built on top 139 of "Custom Subscription to Event Streams" 140 [I-D.draft-ietf-netconf-subscribed-notifications]. Supplementing 141 that work are YANG data model augmentations, extended RPCs, and new 142 datastore specific update notifications. Transport options for 143 [I-D.draft-ietf-netconf-subscribed-notifications] will work 144 seamlessly with this solution. 146 2. Definitions and Acronyms 148 This document uses the terminology defined in [RFC7950], [RFC8341], 149 and [RFC8342]. In addition, the following terms are introduced: 151 o Datastore node: An instance of a data node in a datastore. In the 152 context of this document sometimes also referred to as "object". 154 o Datastore node update: A data item containing the current value of 155 a datastore node at the time the datastore node update was 156 created. 158 o Datastore subscription: A subscription to updates regarding 159 contents of a datastore. 161 o Datastore subtree: An instantiated datastore node and the 162 datastore nodes that are hierarchically contained within it. 164 o On-change subscription: A datastore subscription with updates that 165 are triggered when changes in subscribed datastore nodes are 166 detected. 168 o Periodic subscription: A datastore subscription with updates that 169 are triggered periodically according to some time interval. 171 o Selection filter: Evaluation and/or selection criteria, which may 172 be applied against a targeted set of objects. 174 o Update record: A representation of one or more datastore node 175 updates. In addition, an update record may contain which type of 176 update led to the datastore node update (e.g., whether the 177 datastore node was added, changed, deleted). Also included in the 178 update record may be other metadata, such as a subscription 179 identifier of the subscription as part of which the update record 180 was generated. 182 o Update trigger: A mechanism that determines when an update record 183 needs to be generated. 185 o YANG-Push: The subscription and push mechanism for datastore 186 updates that is specified in this document. 188 3. Solution Overview 190 This document specifies a solution that provides subscription service 191 for updates from a datastore. This solution supports dynamic as well 192 as configured subscriptions to updates of datastore nodes. 193 Subscriptions specify when notification messages should be sent and 194 what data to include in update records. YANG objects are 195 subsequently pushed from the publisher to the receiver per the terms 196 of the subscription. 198 3.1. Subscription Model 200 YANG-push subscriptions are defined using a data model that is itself 201 defined in YANG. This model enhances the subscription model defined 202 in [I-D.draft-ietf-netconf-subscribed-notifications] with 203 capabilities that allow subscribers to subscribe to datastore node 204 updates, specifically to specify the update triggers defining when to 205 generate update records as well as what to include in an update 206 record. Key enhancements include: 208 o Specification of selection filters which identify targeted YANG 209 datastore nodes and/or subtrees within a datastore for which 210 updates are to be pushed. 212 o Specification of update policies contain conditions which trigger 213 the generation and pushing of new update records. There are two 214 types of subscriptions, distinguished by how updates are 215 triggered: periodic and on-change. 217 * For periodic subscriptions, the update trigger is specified by 218 two parameters that define when updates are to be pushed. 219 These parameters are the period interval with which to report 220 updates, and an anchor time which can be used to calculate at 221 which point in time updates need to be assembled and sent. 223 * For on-change subscriptions, an update trigger occurs whenever 224 a change in the subscribed information is detected. Included 225 are additional parameters such as: 227 + Dampening period: In an on-change subscription, detected 228 datastore node changes should be sent as quickly as 229 possible. However, it may be undesirable to send a rapid 230 series of datastore node changes. Such behavior has the 231 potential to exhaust of resources in the publisher or 232 receiver. In order to protect against that, a dampening 233 period MAY be used to specify the interval which must pass 234 before successive update records for the same subscription 235 are generated for a receiver. The dampening period 236 collectively applies to the set of all datastore nodes 237 selected by a single subscription and sent to a single 238 receiver. This means that when there is a change to one or 239 more subscribed objects, an update record containing those 240 objects is created either immediately when no dampening 241 period is in effect, or at the end of a dampening period. 242 If multiple changes to a single datastore node occur during 243 a dampening period, only the value that is in effect at the 244 time the update record is created is included. The 245 dampening period goes into effect every time an update 246 record completes assembly. 248 + Change type: This parameter can be used to reduce the types 249 of datastore changes for which updates are sent (e.g., you 250 might only send when a datastore node is created or deleted, 251 but not when a datastore node value changes). 253 + No Synch on start: defines whether or not a complete push- 254 update of all subscribed data will be sent at the beginning 255 of a subscription. Such early synchronization establishes 256 the frame of reference for subsequent updates. 258 o An encoding (using anydata) for the contents of periodic and on- 259 change push updates. 261 3.2. Negotiation of Subscription Policies 263 A dynamic subscription request SHOULD be declined if a publisher's 264 assessment is that it may be unable to provide update records meeting 265 the terms of an "establish-subscription" or "modify-subscription" rpc 266 request. In this case, a subscriber may quickly follow up with a new 267 rpc request using different parameters. 269 Random guessing at different parameters by a subscriber is to be 270 discouraged. Therefore, in order to minimize the number of 271 subscription iterations between subscriber and publisher, dynamic 272 subscription supports a simple negotiation between subscribers and 273 publishers for subscription parameters. This negotiation is in the 274 form of supplemental information which may be inserted within error 275 responses to a failed rpc request. This returned error response 276 information, when considered, should increase the likelihood of 277 success for subsequent rpc requests. Such hints include suggested 278 periodic time intervals, acceptable dampening periods, and size 279 estimates for the number or objects which would be returned from a 280 proposed selection filter. However, there are no guarantees that 281 subsequent requests which consider these hints will be accepted. 283 3.3. On-Change Considerations 285 On-change subscriptions allow subscribers to receive updates whenever 286 changes to targeted objects occur. As such, on-change subscriptions 287 are particularly effective for data that changes infrequently, yet 288 for which applications need to be quickly notified whenever a change 289 does occur with minimal delay. 291 On-change subscriptions tend to be more difficult to implement than 292 periodic subscriptions. Accordingly, on-change subscriptions may not 293 be supported by all implementations or for every datastore node. 295 Whether or not to accept or reject on-change subscription requests 296 when the scope of the subscription contains objects for which on- 297 change is not supported is up to the publisher implementation. A 298 publisher MAY accept an on-change subscription even when the scope of 299 the subscription contains objects for which on-change is not 300 supported. In that case, updates are sent only for those objects 301 within the scope that do support on-change updates whereas other 302 objects are excluded from update records, whether or not their values 303 actually change. In order for a subscriber to determine whether 304 objects support on-change subscriptions, objects are marked 305 accordingly on a publisher. Accordingly, when subscribing, it is the 306 responsibility of the subscriber to ensure it is aware of which 307 objects support on-change and which do not. For more on how objects 308 are so marked, see Section 3.10. 310 Alternatively, a publisher MAY decide to simply reject an on-change 311 subscription in case the scope of the subscription contains objects 312 for which on-change is not supported. In case of a configured 313 subscription, the subscription MAY be suspended. 315 To avoid flooding receivers with repeated updates for subscriptions 316 containing fast-changing objects, or objects with oscillating values, 317 an on-change subscription allows for the definition of a dampening 318 period. Once an update record for a given datastore node is 319 generated, no other updates for this particular subscription will be 320 created until the end of the dampening period. Values sent at the 321 end of the dampening period are the current values of all changed 322 objects which are current at the time the dampening period expires. 323 Changed objects include those which were deleted or newly created 324 during that dampening period. If a datastore node has returned to 325 its original value (or even has been created and then deleted) during 326 the dampening-period, the last change will still be sent. This will 327 indicate churn is occurring on that datastore node. 329 On-change subscriptions can be refined to let users subscribe only to 330 certain types of changes. For example, a subscriber might only want 331 datastore node creations and deletions, but not modifications of 332 datastore node values. 334 Putting it all together, following is the conceptual process for 335 creating an push-change-update notification: 337 1. Just before a change, or at the start of a dampening period, 338 evaluate any filtering and any access control rules. The result 339 is a set "A" of datastore nodes and subtrees. 341 2. Just after a change, or at the end of a dampening period, 342 evaluate any filtering and any (possibly new) access control 343 rules. The result is a set "B" of datastore nodes and subtrees. 345 3. Construct a YANG patch record for going from A to B. 347 4. If there were any changes made between A and B which canceled 348 each other out, insert into the YANG patch record the last change 349 made for any datastore node which otherwise wouldn't have 350 appeared. 352 5. If the resulting patch record is non-empty, send it to the 353 receiver. 355 Note: In cases where a subscriber wants to have separate dampening 356 periods for different objects, multiple subscriptions with different 357 objects in a selection filter can be created. 359 3.4. Reliability Considerations 361 A subscription to updates from a datastore is intended to obviate the 362 need for polling. However, in order to do so, it is critical that 363 subscribers can rely on the subscription and have confidence that 364 they will indeed receive the subscribed updates without having to 365 worry about updates being silently dropped. In other words, a 366 subscription constitutes a promise on the side of the publisher to 367 provide the receivers with updates per the terms of the subscription. 369 Now, there are many reasons why a publisher may at some point no 370 longer be able to fulfill the terms of the subscription, even if the 371 subscription had been entered into with good faith. For example, the 372 volume of data objects may be larger than anticipated, the interval 373 may prove too short to send full updates in rapid succession, or an 374 internal problem may prevent objects from being collected. For this 375 reason, the solution that is defined in this document mandates that a 376 publisher notifies receivers immediately and reliably whenever it 377 encounters a situation in which it is unable to keep the terms of the 378 subscription, and provides the publisher with the option to suspend 379 the subscription in such a case. 381 A publisher SHOULD reject a request for a subscription if it is 382 unlikely that the publisher will be able fulfill the terms of that 383 subscription request. In such cases, it is preferable to have a 384 subscriber request a less resource intensive subscription than to 385 deal with frequently degraded behavior. 387 3.5. Data Encodings 389 3.5.1. Periodic Subscriptions 391 In a periodic subscription, the data included as part of an update 392 corresponds to data that could have been read using a retrieval 393 operation. 395 3.5.2. On-Change Subscriptions 397 In an on-change subscription, updates need to indicate not only 398 values of changed datastore nodes but also the types of changes that 399 occurred since the last update. Therefore encoding rules for data in 400 on-change updates will generally follow YANG-patch operation as 401 specified in [RFC8072]. The YANG-patch will describe what needs to 402 be applied to the earlier state reported by the preceding update, to 403 result in the now-current state. Note that contrary to [RFC8072], 404 objects encapsulated are not restricted to configuration objects 405 only. 407 A publisher will indicate a change to the effect that a value of a 408 datstore node has been updated by indicating a "replace" operation 409 (applied to the datastore node) in the patch. When a new datastore 410 node was created (other than an element in a list), a publisher will 411 indicate a "create" operation in the patch. When a datastore node 412 was deleted (other than an element in a list), the publisher 413 indicates this by a "delete". When a new list element was created or 414 removed, the publisher indicates it by an "insert" or "remove", 415 respectively. 417 However a patch must be able to do more than just describe the delta 418 from the previous state to the current state. As per Section 3.3, it 419 must also be able to identify if transient changes have occurred on a 420 datastore node during a dampening period. To support this, it is 421 valid to encode a YANG patch operation so that its application would 422 result in no change between the previous and current state. This 423 indicates that some churn has occurred on the datastore node. An 424 example of this would be a patch that does a "create" operation for a 425 datastore node where the receiver believes one already exists, or a 426 "merge" operation which replaces a previous value with the same 427 value. Note that this means that the "create" and "delete" errors 428 described in [RFC8072] section 2.5 are not errors, and are valid 429 operations with YANG push. 431 3.6. Defining the Selection with a Datastore 433 A subscription must specify both the selection filters and the 434 datastore against which these selection filters will be applied. 435 This information is used to choose and subsequently push data from 436 the publisher's datastore to the receivers. 438 Only a single selection filter can be applied to a subscription at a 439 time. An rpc request proposing a new selection filter MUST remove 440 any existing filter. The following selection filter types are 441 included in the yang-push data model, and may be applied against a 442 datastore: 444 o subtree: A subtree selection filter identifies one or more 445 datastore subtrees. When specified, update records will only come 446 from the datastore nodes of selected datastore subtree(s). The 447 syntax and semantics correspond to that specified for [RFC6241] 448 section 6. 450 o xpath: An "xpath" selection filter is an XPath expression that 451 returns a node set. When specified, updates will only come from 452 the selected datastore nodes. 454 These filters are intended to be used as selectors that define which 455 objects are within the scope of a subscription. A publisher MUST 456 support at least one type of selection filter. 458 Xpath itself provides powerful filtering constructs and care must be 459 used in filter definition. As an example, consider an XPath filter 460 with a boolean result; such a result will not provide an easily 461 interpretable subset of a datastore. Beyond the boolean example, it 462 is quite possible to define an XPath filter where results are easy 463 for an application to misinterpret. Consider an XPath filter which 464 only passes a datastore node when an interface is up. It is up to 465 the receiver to understand implications of the presence or absence of 466 objects in each update. 468 When the set of selection filtering criteria is applied for a 469 periodic subscription, all selected datastore nodes to which a 470 receiver has access are provided to that receiver. If the same 471 filtering criteria is applied to an on-change subscription, only the 472 subset of those datastore nodes supporting on-change is provided. A 473 datastore node which doesn't support on-change is never sent as part 474 of an on-change subscription's "push-update" or "push-change-update". 476 3.7. Streaming Updates 478 Contrary to traditional data retrieval requests, datastore 479 subscription enables an unbounded series of update records to be 480 streamed over time. Two generic YANG notifications for update 481 records have been defined for this: "push-update" and "push-change- 482 update". 484 A "push-update" notification defines a complete, filtered update of 485 the datastore per the terms of a subscription. This type of YANG 486 notification is used for continuous updates of periodic 487 subscriptions. A "push-update" notification can also be used for the 488 on-change subscriptions in two cases. First it will be used as the 489 initial "push-update" if there is a need to synchronize the receiver 490 at the start of a new subscription. It also MAY be sent if the 491 publisher later chooses to resynch an on-change subscription. The 492 "push-update" update record contains an instantiated datastore 493 subtree with all of the subscribed contents. The content of the 494 update record is equivalent to the contents that would be obtained 495 had the same data been explicitly retrieved using a datastore 496 retrieval operation using the same transport with the same filters 497 applied. 499 A "push-change-update" notification is the most common type of update 500 for on-change subscriptions. The update record in this case contains 501 the set of changes that datastore nodes have undergone since the last 502 notification message. In other words, this indicates which datastore 503 nodes have been created, deleted, or have had changes to their 504 values. In cases where multiple changes have occurred and the 505 datastore node has not been deleted, the datastore node's most 506 current value is reported. (In other words, for each datastore node, 507 only one change is reported, not its entire history. Doing so would 508 defeat the purpose of the dampening period.) 510 These new "push-update" or "push-change-update" are encoded and 511 placed within notification messages, and ultimately queued for egress 512 over the specified transport. 514 The following is an example of a notification message for a 515 subscription tracking the operational status of a single Ethernet 516 port (per [RFC7223]). This notification message is encoded XML over 517 NETCONF as per [I-D.draft-ietf-netconf-netconf-event-notifications]. 519 520 2017-10-25T08:00:11.22Z 521 522 1011 523 524 525 526 eth0 527 up 528 529 530 531 532 534 Figure 1: Push example 536 The following is an example of an on-change notification message for 537 the same subscription. 539 540 2017-10-25T08:22:33.44Z 541 542 89 543 544 545 1 546 547 edit1 548 merge 549 /ietf-interfaces:interfaces-state 550 551 552 553 eth0 554 down 555 556 557 558 559 560 561 562 564 Figure 2: Push example for on change 566 Of note in the above example is the 'patch-id' with a value of '1'. 567 Per [RFC8072], the 'patch-id' is an arbitrary string. With YANG 568 Push, the publisher SHOULD put into the 'patch-id' a counter starting 569 at '1' which increments with every 'push-change-update' generated for 570 a subscription. If used as a counter, this counter MUST be reset to 571 '1' anytime a resynchronization occurs (i.e., with the sending of a 572 'push-update'). Also if used as a counter, the counter MUST be reset 573 to '1' the after passing a maximum value of '4294967295' (i.e. 574 maximum value that can be represented using uint32 data type). Such 575 a mechanism allows easy identification of lost or out-of-sequence 576 update records. 578 3.8. Subscription Management 580 The RPCs defined within 581 [I-D.draft-ietf-netconf-subscribed-notifications] have been enhanced 582 to support datastore subscription negotiation. Also, new error codes 583 have been added that are able to indicate why a datastore 584 subscription attempt has failed, along with new yang-data that MAY be 585 used to include details on input parameters that might result in a 586 successful subsequent RPC invocation. 588 The establishment or modification of a datastore subscription can be 589 rejected for multiple reasons. This includes a too large subtree 590 request, or the inability of the publisher to push update records as 591 frequently as requested. In such cases, no subscription is 592 established. Instead, the subscription-result with the failure 593 reason is returned as part of the RPC response. As part of this 594 response, a set of alternative subscription parameters MAY be 595 returned that would likely have resulted in acceptance of the 596 subscription request. The subscriber may consider these as part of 597 future subscription attempts. 599 In the case of a rejected request for an establishment of a datastore 600 subscription, the hints MUST be transported within a yang-data 601 "establish-subscription-datastore-error-info" container inserted into 602 the RPC error response, in lieu of the "establish-subscription- 603 stream-error-info" that is inserted in case of a stream subscription. 605 Below is a tree diagram for "establish-subscription-datastore-error- 606 info". All tree diagrams used in this document follow the notation 607 defined in [RFC8340] 608 yang-data establish-subscription-datastore-error-info 609 +--ro establish-subscription-datasore-error-info 610 +--ro reason? identityref 611 +--ro period-hint? yang:timeticks 612 +--ro filter-failure-hint? string 613 +--ro object-count-estimate? uint32 614 +--ro object-count-limit? uint32 615 +--ro kilobytes-estimate? uint32 616 +--ro kilobytes-limit? uint32 618 Figure 3: Tree diagram for establish-subscription-datastore-error- 619 info 621 Similarly, in the case of a rejected request for modification of a 622 datastore subscription, the hints MUST be transported within a yang- 623 data "modify-subscription-datastore-error-info" container inserted 624 into the RPC error response, in lieu of the "modify-subscription- 625 stream-error-info" that is inserted in case of a stream subscription. 627 Below is a tree diagram for "modify-subscription-datastore-error- 628 info". 630 yang-data modify-subscription-datastore-error-info 631 +--ro modify-subscription-datasore-error-info 632 +--ro reason? identityref 633 +--ro period-hint? yang:timeticks 634 +--ro filter-failure-hint? string 635 +--ro object-count-estimate? uint32 636 +--ro object-count-limit? uint32 637 +--ro kilobytes-estimate? uint32 638 +--ro kilobytes-limit? uint32 640 Figure 4: Tree diagram for modify-subscription-datastore-error-info 642 3.9. Receiver Authorization 644 A receiver of subscription data MUST only be sent updates for which 645 they have proper authorization. A publisher MUST ensure that no non- 646 authorized data is included in push updates. To do so, it needs to 647 apply all corresponding checks applicable at the time of a specific 648 pushed update and if necessary silently remove any non-authorized 649 data from datastore subtrees. This enables YANG data pushed based on 650 subscriptions to be authorized equivalently to a regular data 651 retrieval (get) operation. 653 A publisher MUST allow for the possibility that a subscription's 654 selection filter references non-existent or access-protected data. 655 Such support permits a receiver the ability to monitor the entire 656 lifecyle of some datastore tree. In this case, all "push-update" 657 notifications must be sent empty, and no "push-change-update" 658 notifications will be sent until some data becomes visible for a 659 receiver. 661 A publisher MAY choose reject an establish-subscription request which 662 selects non-existent or access-protected data. In addition, a 663 publisher MAY choose to terminate a dynamic subscription or suspend a 664 configured receiver when the authorization privileges of a receiver 665 change, or the access controls for subscribed objects change. Such a 666 capability enables the publisher to avoid having to support a 667 continuous, and total filtering of an entire subscription's content. 669 In these cases above, the error identity "unchanging-selection" 670 SHOULD be returned. This reduces the possibility of leakage of 671 access controlled objects. 673 Each "push-update" and "push-change-update" MUST have access control 674 applied. This includes validating that read access is permitted for 675 any new objects selected since the last notification message was sent 676 to a particular each receiver. To accomplish this, implementations 677 SHOULD support the conceptual authorization model of [RFC8342], 678 specifically section 3.2.4. 680 +-----------------+ +--------------------+ 681 push-update or --> | datastore node | yes | add datastore node | 682 push-change-update | access allowed? | ---> | to update message | 683 +-----------------+ +--------------------+ 685 Figure 5: Updated [rfc6536bis] access control for push updates 687 If read access into previously accessible nodes has been lost due to 688 a receiver permissions change, this SHOULD be reported as a patch 689 "delete" operation for on-change subscriptions. If not capable of 690 handling such receiver permission changes with such a "delete", 691 publisher implementations MUST force dynamic subscription re- 692 establishment or configured subscription re-initialization so that 693 appropriate filtering is installed. 695 3.10. On-change Notifiable YANG objects 697 In some cases, a publisher supporting on-change notifications may not 698 be able to push updates for some datastore nodes on-change. Reasons 699 for this might be that the value of the datastore node changes 700 frequently (e.g., [RFC7223]'s in-octets counter), that small 701 datastore node changes are frequent and meaningless (e.g., a 702 temperature gauge changing 0.1 degrees), or that the implementation 703 is not capable of on-change notification for a particular datastore 704 node. 706 In those cases, it will be important for client applications to have 707 a way to identify for which objects on-change notifications are 708 supported and for which ones they are not supported. Otherwise 709 client applications will have no way of knowing whether they can 710 indeed rely on their on-change subscription to provide them with the 711 change updates that they are interested in. In other words, if 712 implementations do not provide a solution and do not support 713 comprehensive on-change notifiability, clients of those 714 implementations will have no way of knowing what their on-change 715 subscription actually covers. 717 Implementations are therefore strongly advised to provide a solution 718 to this problem. It is expected that such a solution will be 719 standardized at some point in the future. In the meantime and until 720 this occurs, implementations will be expected to provide their own 721 solution. 723 3.11. Other Considerations 725 3.11.1. Robustness and reliability 727 Particularly in the case of on-change updates, it is important that 728 these updates do not get lost. Or in case the loss of an update is 729 unavoidable, it is critical that the receiver is notified 730 accordingly. 732 Update records for a single subscription MUST NOT be resequenced 733 prior to transport. 735 It is conceivable that under certain circumstances, a publisher will 736 recognize that it is unable to include within an update record the 737 full set of objects desired per the terms of a subscription. In this 738 case, the publisher MUST take one or more of the following actions. 740 o A publisher MUST set the "incomplete-update" flag on any update 741 record which is known to be missing information. 743 o It MAY choose to suspend a subscription as per 744 [I-D.draft-ietf-netconf-subscribed-notifications]. 746 o When resuming an on-change subscription, the publisher SHOULD 747 generate a complete patch from the previous update record. If 748 this is not possible and the "no-synch-on-start" option is not 749 present for the subscription, then the full datastore contents MAY 750 be sent via a "push-update" instead (effectively replacing the 751 previous contents). If neither of these are possible, then an 752 "incomplete-update" flag MUST be included on the next "push- 753 change-update". 755 Note: It is perfectly acceptable to have a series of "push-change- 756 update" notifications (and even "push update" notifications) serially 757 queued at the transport layer awaiting transmission. It is not 758 required to merge pending update messages. I.e., the dampening 759 period applies to update record creation, not transmission. 761 3.11.2. Publisher capacity 763 It is far preferable to decline a subscription request than to accept 764 such a request when it cannot be met. 766 Whether or not a subscription can be supported will be determined by 767 a combination of several factors such as the subscription update 768 trigger (on-change or periodic), the period in which to report 769 changes (one second periods will consume more resources than one hour 770 periods), the amount of data in the datastore subtree that is being 771 subscribed to, and the number and combination of other subscriptions 772 that are concurrently being serviced. 774 4. A YANG data model for management of datastore push subscriptions 776 4.1. Overview 778 The YANG data model for datastore push subscriptions is depicted in 779 the following figure. The tree diagram follows the notiation defined 780 in [RFC8340]. New schema objects defined here (i.e., beyond those 781 from [I-D.draft-ietf-netconf-subscribed-notifications]) are 782 identified with "yp". For the reader's convenience, in order to 783 compact the tree representation, some nodes that are defined in ietf- 784 subscribed-notifications and that are not essential to the 785 understanding of the data model defined here have been removed. This 786 is indicated by "..." in the diagram where applicable. 788 module: ietf-subscribed-notifications 789 ... 790 +--rw filters 791 | ... 792 | +--rw yp:selection-filter* [identifier] 793 | +--rw yp:identifier sn:filter-id 794 | +--rw (yp:filter-spec)? 795 | +--:(yp:datastore-subtree-filter) 796 | | +--rw yp:datastore-subtree-filter? 797 | | {sn:subtree}? 798 | +--:(yp:datastore-xpath-filter) 799 | +--rw yp:datastore-xpath-filter? yang:xpath1.0 800 | {sn:xpath}? 801 +--rw subscriptions 802 +--rw subscription* [identifier] 803 | ... 804 +--rw (target) 805 | +--:(stream) 806 | | ... 807 | +--:(yp:datastore) 808 | +--rw yp:datastore identityref 809 | +--rw (yp:selection-filter)? 810 | +--:(yp:by-reference) 811 | | +--rw yp:selection-filter-ref 812 | | selection-filter-ref 813 | +--:(yp:within-subscription) 814 | +--rw (yp:filter-spec)? 815 | +--:(yp:datastore-subtree-filter) 816 | | +--rw yp:datastore-subtree-filter? 817 | | {sn:subtree}? 818 | +--:(yp:datastore-xpath-filter) 819 | +--rw yp:datastore-xpath-filter? 820 | yang:xpath1.0 {sn:xpath}? 821 | ... 822 +--rw (yp:update-trigger)? 823 +--:(yp:periodic) 824 | +--rw yp:periodic! 825 | +--rw yp:period yang:timeticks 826 | +--rw yp:anchor-time? yang:date-and-time 827 +--:(yp:on-change) {on-change}? 828 +--rw yp:on-change! 829 +--rw yp:dampening-period? yang:timeticks 830 +--rw yp:no-synch-on-start? empty 831 +--rw yp:excluded-change* change-type 833 rpcs: 834 +---x establish-subscription 835 | +---w input 836 | | ... 837 | | +---w (target) 838 | | | +--:(stream) 839 | | | | ... 840 | | | +--:(yp:datastore) 841 | | | +---w yp:datastore identityref 842 | | | +---w (yp:selection-filter)? 843 | | | +--:(yp:by-reference) 844 | | | | +---w yp:selection-filter-ref 845 | | | | selection-filter-ref 846 | | | +--:(yp:within-subscription) 847 | | | +---w (yp:filter-spec)? 848 | | | +--:(yp:datastore-subtree-filter) 849 | | | | +---w yp:datastore-subtree-filter? 850 | | | | {sn:subtree}? 851 | | | +--:(yp:datastore-xpath-filter) 852 | | | +---w yp:datastore-xpath-filter? 853 | | | yang:xpath1.0 {sn:xpath}? 854 | | | ... 855 | | +---w (yp:update-trigger)? 856 | | +--:(yp:periodic) 857 | | | +---w yp:periodic! 858 | | | +---w yp:period yang:timeticks 859 | | | +---w yp:anchor-time? yang:date-and-time 860 | | +--:(yp:on-change) {on-change}? 861 | | +---w yp:on-change! 862 | | +---w yp:dampening-period? yang:timeticks 863 | | +---w yp:no-synch-on-start? empty 864 | | +---w yp:excluded-change* change-type 865 | +--ro output 866 | +--ro identifier subscription-id 867 +---x modify-subscription 868 | +---w input 869 | ... 870 | +---w (target) 871 | | ... 872 | | +--:(yp:datastore) 873 | | +---w (yp:selection-filter)? 874 | | +--:(yp:by-reference) 875 | | | +---w yp:selection-filter-ref 876 | | | selection-filter-ref 877 | | +--:(yp:within-subscription) 878 | | +---w (yp:filter-spec)? 879 | | +--:(yp:datastore-subtree-filter) 880 | | | +---w yp:datastore-subtree-filter? 881 | | | {sn:subtree}? 882 | | +--:(yp:datastore-xpath-filter) 883 | | +---w yp:datastore-xpath-filter? 884 | | yang:xpath1.0 {sn:xpath}? 885 | | ... 886 | +---w (yp:update-trigger)? 887 | +--:(yp:periodic) 888 | | +---w yp:periodic! 889 | | +---w yp:period yang:timeticks 890 | | +---w yp:anchor-time? yang:date-and-time 891 | +--:(yp:on-change) {on-change}? 892 | +---w yp:on-change! 893 | +---w yp:dampening-period? yang:timeticks 894 +---x delete-subscription 895 | ... 896 +---x kill-subscription 897 ... 899 yang-data (for placement into rpc error responses) 900 ... 902 notifications: 903 +---n replay-completed {replay}? 904 | ... 905 +---n subscription-completed 906 | ... 907 +---n subscription-started {configured}? 908 | | ... 909 | +--ro (target) 910 | | ... 911 | | +--:(yp:datastore) 912 | | +--ro yp:datastore identityref 913 | | +--ro (yp:selection-filter)? 914 | | +--:(yp:by-reference) 915 | | | +--ro yp:selection-filter-ref 916 | | | selection-filter-ref 917 | | +--:(yp:within-subscription) 918 | | +--ro (yp:filter-spec)? 919 | | +--:(yp:datastore-subtree-filter) 920 | | | +--ro yp:datastore-subtree-filter? 921 | | {sn:subtree}? 922 | | +--:(yp:datastore-xpath-filter) 923 | | +--ro yp:datastore-xpath-filter? 924 | | yang:xpath1.0 {sn:xpath}? 925 | ... 926 | +--ro (yp:update-trigger)? 927 | +--:(yp:periodic) 928 | | +--ro yp:periodic! 929 | | +--ro yp:period yang:timeticks 930 | | +--ro yp:anchor-time? yang:date-and-time 931 | +--:(yp:on-change) {on-change}? 932 | +--ro yp:on-change! 933 | +--ro yp:dampening-period? yang:timeticks 934 | +--ro yp:no-synch-on-start? empty 935 | +--ro yp:excluded-change* change-type 936 +---n subscription-resumed 937 | ... 938 +---n subscription-modified 939 | ... 940 | +--ro (target) 941 | | | ... 942 | | +--:(yp:datastore) 943 | | +--ro yp:datastore identityref 944 | | +--ro (yp:selection-filter)? 945 | | +--:(yp:by-reference) 946 | | | +--ro yp:selection-filter-ref 947 | | | selection-filter-ref 948 | | +--:(yp:within-subscription) 949 | | +--ro (yp:filter-spec)? 950 | | +--:(yp:datastore-subtree-filter) 951 | | | +--ro yp:datastore-subtree-filter? 952 | | | {sn:subtree}? 953 | | +--:(yp:datastore-xpath-filter) 954 | | +--ro yp:datastore-xpath-filter? 955 | | yang:xpath1.0 {sn:xpath}? 956 | ... 957 | +--ro (yp:update-trigger)? 958 | +--:(yp:periodic) 959 | | +--ro yp:periodic! 960 | | +--ro yp:period yang:timeticks 961 | | +--ro yp:anchor-time? yang:date-and-time 962 | +--:(yp:on-change) {on-change}? 963 | +--ro yp:on-change! 964 | +--ro yp:dampening-period? yang:timeticks 965 | +--ro yp:no-synch-on-start? empty 966 | +--ro yp:excluded-change* change-type 967 +---n subscription-terminated 968 | ... 969 +---n subscription-suspended 970 ... 972 module: ietf-yang-push 974 rpcs: 975 +---x resynch-subscription {on-change}? 976 +---w input 977 +---w identifier sn:subscription-id 979 yang-data: (for placement into rpc error responses) 980 +-- resynch-subscription-error 981 | +--ro reason? identityref 982 | +--ro period-hint? timeticks 983 | +--ro filter-failure-hint? string 984 | +--ro object-count-estimate? uint32 985 | +--ro object-count-limit? uint32 986 | +--ro kilobytes-estimate? uint32 987 | +--ro kilobytes-limit? uint32 988 +-- establish-subscription-error-datastore 989 | +--ro reason? identityref 990 | +--ro period-hint? timeticks 991 | +--ro filter-failure-hint? string 992 | +--ro object-count-estimate? uint32 993 | +--ro object-count-limit? uint32 994 | +--ro kilobytes-estimate? uint32 995 | +--ro kilobytes-limit? uint32 996 +-- modify-subscription-error-datastore 997 +--ro reason? identityref 998 +--ro period-hint? timeticks 999 +--ro filter-failure-hint? string 1000 +--ro object-count-estimate? uint32 1001 +--ro object-count-limit? uint32 1002 +--ro kilobytes-estimate? uint32 1003 +--ro kilobytes-limit? uint32 1005 notifications: 1006 +---n push-update 1007 | +--ro subscription-id? sn:subscription-id 1008 | +--ro incomplete-update? empty 1009 | +--ro datastore-contents? 1010 +---n push-change-update {on-change}? 1011 +--ro subscription-id? sn:subscription-id 1012 +--ro incomplete-update? empty 1013 +--ro datastore-changes? 1015 Figure 6: Model structure 1017 Selected components of the model are summarized below. 1019 4.2. Subscription configuration 1021 Both configured and dynamic subscriptions are represented within the 1022 list "subscription". New parameters extending the basic subscription 1023 data model in [I-D.draft-ietf-netconf-subscribed-notifications] 1024 include: 1026 o The targeted datastore from which the selection is being made. 1027 The potential datastores include those from [RFC8341]. A platform 1028 may also choose to support a custom datastore. 1030 o A selection filter identifying yang nodes of interest within a 1031 datastore. Filter contents are specified via a reference to an 1032 existing filter, or via an in-line definition for only that 1033 subscription. Referenced filters allows an implementation to 1034 avoid evaluating filter acceptability during a dynamic 1035 subscription request. The case statement differentiates the 1036 options. 1038 o For periodic subscriptions, triggered updates will occur at the 1039 boundaries of a specified time interval. These boundaries can be 1040 calculated from the periodic parameters: 1042 * a "period" which defines the duration between push updates. 1044 * an "anchor-time"; update intervals always fall on the points in 1045 time that are a multiple of a "period" from an "anchor-time". 1046 If "anchor-time" is not provided, then the "anchor-time" MUST 1047 be set with the creation time of the initial update record. 1049 o For on-change subscriptions, assuming any dampening period has 1050 completed, triggering occurs whenever a change in the subscribed 1051 information is detected. On-change subscriptions have more 1052 complex semantics that is guided by its own set of parameters: 1054 * a "dampening-period" specifies the interval that must pass 1055 before a successive update for the subscription is sent. If no 1056 dampening period is in effect, the update is sent immediately. 1057 If a subsequent change is detected, another update is only sent 1058 once the dampening period has passed for this subscription. 1060 * an "excluded-change" flag which allows restriction of the types 1061 of changes for which updates should be sent (e.g., only add to 1062 an update record on datastore node creation). 1064 * a "no-synch-on-start" flag which specifies whether a complete 1065 update with all the subscribed data is to be sent at the 1066 beginning of a subscription. 1068 4.3. YANG Notifications 1070 4.3.1. State Change Notifications 1072 Subscription state notifications and mechanism are reused from 1073 [I-D.draft-ietf-netconf-subscribed-notifications]. Notifications 1074 "subscription-started" and "subscription-modified" have been 1075 augmented to include the datastore specific objects. 1077 4.3.2. Notifications for Subscribed Content 1079 Along with the subscribed content, there are other objects which 1080 might be part of a "push-update" or "push-change-update" 1081 notification. 1083 A "subscription-id" MUST be transported along with the subscribed 1084 contents. An [RFC5277] Section 4 one-way notification MAY be used 1085 for encoding updates. Where it is, the relevant "subscription-id" 1086 MUST be encoded as the first element within each "push-update" or 1087 "push-change-update". This allows a receiver to differentiate which 1088 subscription resulted in a particular push. 1090 A "time-of-update" which represents the time an update record 1091 snapshot was generated. A receiver MAY assume that a publisher's 1092 objects have these pushed values at this point in time. 1094 An "incomplete-update" leaf. This leaf indicates that not all 1095 changes which have occurred since the last update are actually 1096 included with this update. In other words, the publisher has failed 1097 to fulfill its full subscription obligations. (For example a 1098 datastore was unable to providing the full set of datastore nodes to 1099 a publisher process.) To facilitate re-synchronization of on-change 1100 subscriptions, a publisher MAY subsequently send a "push-update" 1101 containing a full selection snapshot of subscribed data. 1103 4.4. YANG RPCs 1105 YANG-Push subscriptions are established, modified, and deleted using 1106 RPCs augmented from 1107 [I-D.draft-ietf-netconf-subscribed-notifications]. 1109 4.4.1. Establish-subscription RPC 1111 The subscriber sends an establish-subscription RPC with the 1112 parameters in section 3.1. An example might look like: 1114 1116 1119 1120 1121 ds:operational 1122 1123 1126 1127 1128 500 1129 1130 1131 1133 Figure 7: Establish-subscription RPC 1135 A positive response includes the "identifier" of the accepted 1136 subscription. In that case a publisher MAY respond: 1138 1140 1142 ok 1143 1144 1146 52 1147 1148 1150 Figure 8: Establish-subscription positive RPC response 1152 A subscription can be rejected for multiple reasons, including the 1153 lack of authorization to establish a subscription, no capacity to 1154 serve the subscription at the publisher, or the inability of the 1155 publisher to select datastore content at the requested cadence. 1157 If a request is rejected because the publisher is not able to serve 1158 it, the publisher SHOULD include in the returned error hints which 1159 help a subscriber understand subscription parameters might have been 1160 accepted for the request. These hints would be included within the 1161 yang-data structure "establish-subscription-error-datastore". 1162 However even with these hints, there are no guarantee that subsequent 1163 requests will in fact be accepted. 1165 The specific parameters to be returned in as part of the RPC error 1166 response depend on the specific transport that is used to manage the 1167 subscription. In the case of NETCONF 1168 [I-D.draft-ietf-netconf-netconf-event-notifications], when a 1169 subscription request is rejected, the NETCONF RPC reply MUST include 1170 an "rpc-error" element with the following elements: 1172 o "error-type" of "application". 1174 o "error-tag" of "operation-failed". 1176 o Optionally, an "error-severity" of "error" (this MAY but does not 1177 have to be included). 1179 o "error-app-tag" with the value being a string that corresponds to 1180 an identity with a base of "establish-subscription-error". 1182 o Optionally, "error-info" containing XML-encoded data with hints 1183 for parameter settings that might result in future RPC success per 1184 yang-data definition "establish-subscription-error-datastore". 1186 For example, for the following request: 1188 1190 1193 1195 ds:operational 1196 1197 1199 /ex:foo 1200 1201 1202 100 1203 1204 1205 1207 Figure 9: Establish-subscription request example 2 1209 a publisher that cannot serve on-change updates but periodic updates 1210 might return the following: 1212 1214 1215 application 1216 operation-failed 1217 error 1218 1219 on-change-unsupported 1220 1221 1223 /yp:periodic/yp:period 1224 1225 1226 1228 Figure 10: Establish-subscription error response example 2 1230 4.4.2. Modify-subscription RPC 1232 The subscriber MAY invoke the "modify-subscription" RPC for a 1233 subscription it previously established. The subscriber will include 1234 newly desired values in the "modify-subscription" RPC. Parameters 1235 not included MUST remain unmodified. Below is an example where a 1236 subscriber attempts to modify the "period" of a subscription. 1238 1240 1243 1011 1244 1246 ds:operational 1247 1248 1250 /ex:bar 1251 1252 1253 250 1254 1255 1256 1258 Figure 11: Modify subscription request 1260 The publisher MUST respond explicitly positively or negatively to the 1261 request. If the subscription modification is rejected, the 1262 subscription is maintained as it was before the modification request. 1263 In addition, the publisher MUST send an rpc error response. This rpc 1264 error response may contain hints encapsulated within the yang-data 1265 structure "modify-subscription-error-datastore". A subscription MAY 1266 be modified multiple times. 1268 The specific parameters to be returned in as part of the RPC error 1269 response depend on the specific transport that is used to manage the 1270 subscription. In the case of NETCONF 1271 [I-D.draft-ietf-netconf-netconf-event-notifications], when a 1272 subscription request is rejected, the NETCONF RPC reply MUST include 1273 an "rpc-error" element with the following elements: 1275 o "error-type" of "application". 1277 o "error-tag" of "operation-failed". 1279 o Optionally, an "error-severity" of "error" (this MAY but does not 1280 have to be included). 1282 o "error-app-tag" with the value being a string that corresponds to 1283 an identity with a base of "modify-subscription-error". 1285 o "error-path" pointing to the data node or parameter that caused 1286 the rejection. 1288 o Optionally, "error-info" containing XML-encoded data with hints 1289 for parameter settings that might result in future RPC success per 1290 yang-data definition "modify-subscription-error-datastore". 1292 A configured subscription cannot be modified using "modify- 1293 subscription" RPC. Instead, the configuration needs to be edited as 1294 needed. 1296 4.4.3. Delete-subscription RPC 1298 To stop receiving updates from a subscription and effectively delete 1299 a subscription that had previously been established using an 1300 "establish-subscription" RPC, a subscriber can send a "delete- 1301 subscription" RPC, which takes as only input the subscription's 1302 "identifier". This RPC is unmodified from 1303 [I-D.draft-ietf-netconf-subscribed-notifications]. 1305 4.4.4. Resynch-subscription RPC 1307 This RPC is only applicable only for on-change subscriptions 1308 previously established using an "establish-subscription" RPC. For 1309 example: 1311 1313 1316 1011 1317 1318 1320 Resynch subscription 1322 On receipt, a publisher must either accept the request and quickly 1323 follow with a "push-update", or send an appropriate error within an 1324 rpc error response. Within an error response, the publisher may 1325 include supplemental information about the reasons within the yang- 1326 data structure "resynch-subscription-error". 1328 4.4.5. YANG Module Synchronization 1330 To make subscription requests, the subscriber needs to know the YANG 1331 module library available on the publisher. The YANG 1.0 module 1332 library information is sent by a NETCONF server in the NETCONF 1333 "hello" message. For YANG 1.1 modules and all modules used with the 1334 RESTCONF [RFC8040] protocol, this information is provided by the YANG 1335 Library module (ietf-yang-library.yang from [RFC7895]. This YANG 1336 library information is important for the receiver to reproduce the 1337 set of data node definitions used within the publisher. 1339 The YANG library includes a module list with the name, revision, 1340 enabled features, and applied deviations for each YANG module 1341 implemented by the publisher. The receiver is expected to know the 1342 YANG library information before starting a subscription. The 1343 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module 1344 can be used to cache the YANG library information. 1346 The set of modules, revisions, features, and deviations can change at 1347 run-time (if supported by the publisher implementation). In this 1348 case, the receiver needs to be informed of module changes before 1349 datastore nodes from changed modules can be processed correctly. The 1350 YANG library provides a simple "yang-library-change" notification 1351 that informs the subscriber that the library has changed. The 1352 receiver then needs to re-read the entire YANG library data for the 1353 replicated publisher in order to detect the specific YANG library 1354 changes. The "ietf-netconf-notifications" module defined in 1355 [RFC6470] contains a "netconf-capability-change" notification that 1356 can identify specific module changes. For example, the module URI 1357 capability of a newly loaded module will be listed in the "added- 1358 capability" leaf-list, and the module URI capability of an removed 1359 module will be listed in the "deleted-capability" leaf-list. 1361 5. YANG module 1363 file "ietf-yang-push@2018-05-31.yang" 1364 module ietf-yang-push { 1365 yang-version 1.1; 1366 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1367 prefix yp; 1369 import ietf-yang-types { 1370 prefix yang; 1371 } 1372 import ietf-subscribed-notifications { 1373 prefix sn; 1374 } 1375 import ietf-datastores { 1376 prefix ds; 1377 } 1378 import ietf-restconf { 1379 prefix rc; 1380 } 1382 organization 1383 "IETF"; 1384 contact 1385 "WG Web: 1386 WG List: 1388 Editor: Alexander Clemm 1389 1391 Editor: Eric Voit 1392 1394 Editor: Alberto Gonzalez Prieto 1395 1397 Editor: Ambika Prasad Tripathy 1398 1400 Editor: Einar Nilsen-Nygaard 1401 1403 Editor: Andy Bierman 1404 1406 Editor: Balazs Lengyel 1407 "; 1408 description 1409 "This module contains YANG specifications for YANG push."; 1411 revision 2018-05-31 { 1412 description 1413 "Initial revision."; 1414 reference "draft-ietf-netconf-yang-push-16"; 1415 } 1417 /* 1418 * FEATURES 1419 */ 1421 feature on-change { 1422 description 1423 "This feature indicates that on-change triggered subscriptions 1424 are supported."; 1425 } 1427 /* 1428 * IDENTITIES 1429 */ 1430 /* Error type identities for datastore subscription */ 1432 identity resynch-subscription-error { 1433 description 1434 "Problem found while attempting to fulfill an 1435 'resynch-subscription' RPC request. "; 1436 } 1438 identity cant-exclude { 1439 base sn:establish-subscription-error; 1440 description 1441 "Unable to remove the set of 'excluded-changes'. This means the 1442 publisher is unable to restrict 'push-change-update's to just 1443 the change types requested for this subscription."; 1444 } 1446 identity datastore-not-subscribable { 1447 base sn:establish-subscription-error; 1448 base sn:subscription-terminated-reason; 1449 description 1450 "This is not a subscribable datastore."; 1451 } 1453 identity no-such-subscription-resynch { 1454 base resynch-subscription-error; 1455 description 1456 "Referenced subscription doesn't exist. This may be as a result 1457 of a non-existent subscription ID, an ID which belongs to 1458 another subscriber, or an ID for configured subscription."; 1459 } 1461 identity on-change-unsupported { 1462 base sn:establish-subscription-error; 1463 description 1464 "On-change is not supported for any objects which are selectable 1465 by this filter."; 1466 } 1468 identity on-change-synch-unsupported { 1469 base sn:establish-subscription-error; 1470 description 1471 "Neither synch on start nor resynchronization are supported for 1472 this subscription. This error will be used for two reasons. 1473 First if an 'establish-subscription' RPC doesn't include 1474 'no-synch-on-start', yet the publisher can't support sending a 1475 'push-update' for this subscription for reasons other than 1476 'on-change-unsupported' or 'synchronization-size'. And second, 1477 if the 'resynch-subscription' RPC is invoked either for an 1478 existing periodic subscription, or for an on-change subscription 1479 which can't support resynchronization."; 1480 } 1482 identity period-unsupported { 1483 base sn:establish-subscription-error; 1484 base sn:modify-subscription-error; 1485 base sn:subscription-suspended-reason; 1486 description 1487 "Requested time period is too short. This can be for both 1488 periodic and on-change subscriptions (with or without 1489 dampening.) Hints suggesting alternative periods may be 1490 returned as supplemental information."; 1491 } 1493 identity result-too-big { 1494 base sn:establish-subscription-error; 1495 base sn:modify-subscription-error; 1496 base sn:subscription-suspended-reason; 1497 description 1498 "Periodic or on-change push update datatrees exceed a maximum 1499 size limit. Hints on estimated size of what was too big may 1500 be returned as supplemental information."; 1501 } 1503 identity synchronization-size { 1504 base sn:establish-subscription-error; 1505 base sn:modify-subscription-error; 1506 base resynch-subscription-error; 1507 base sn:subscription-suspended-reason; 1508 description 1509 "Synch-on-start or resynchronization datatree exceeds a maximum 1510 size limit. Hints on estimated size of what was too big may be 1511 returned as supplemental information."; 1512 } 1514 identity unchanging-selection { 1515 base sn:establish-subscription-error; 1516 base sn:modify-subscription-error; 1517 base sn:subscription-terminated-reason; 1518 description 1519 "Selection filter is unlikely to ever select datatree nodes. 1521 This means that based on the subscriber's current access 1522 rights, the publisher recognizes that the selection filter is 1523 unlikely to ever select datatree nodes which change. Examples 1524 for this might be that node or subtree doesn't exist, read 1525 access is not permitted for a receiver, or static objects that 1526 only change at reboot have been chosen."; 1527 } 1529 /* 1530 * TYPE DEFINITIONS 1531 */ 1533 typedef change-type { 1534 type enumeration { 1535 enum create { 1536 description 1537 "A change that refers to the creation of a new data node."; 1538 } 1539 enum delete { 1540 description 1541 "A change that refers to the deletion of a data node."; 1542 } 1543 enum insert { 1544 description 1545 "A change that refers to the insertion of a new 1546 user-ordered data node."; 1547 } 1548 enum merge { 1549 description 1550 "A change that refers to a merging of a new value with a 1551 target data node."; 1552 } 1553 enum move { 1554 description 1555 "A change that refers to a reordering of the target data 1556 node"; 1557 } 1558 enum replace { 1559 description 1560 "A change that refers to a replacement of the target data 1561 node's value."; 1562 } 1563 enum remove { 1564 description 1565 "A change that refers to the removal of a data node."; 1566 } 1567 } 1568 description 1569 "Specifies different types of datastore changes."; 1570 reference 1571 "RFC 8072 section 2.5, with a delta that it is valid for a 1572 receiver to process an update record which performs a create 1573 operation on a datastore node the receiver believes exists, or 1574 to process a delete on a datastore node the receiver believes 1575 is missing."; 1576 } 1578 typedef selection-filter-ref { 1579 type leafref { 1580 path "/sn:filters/yp:selection-filter/yp:filter-id"; 1581 } 1582 description 1583 "This type is used to reference a selection filter."; 1584 } 1586 /* 1587 * GROUP DEFINITIONS 1588 */ 1590 grouping datastore-criteria { 1591 description 1592 "A grouping to define criteria for which selected objects from 1593 a targeted datastore should be included in push updates."; 1594 leaf datastore { 1595 type identityref { 1596 base ds:datastore; 1597 } 1598 mandatory true; 1599 description 1600 "Datastore from which to retrieve data."; 1601 } 1602 uses selection-filter-objects; 1603 } 1605 grouping selection-filter-types { 1606 description 1607 "This grouping defines the types of selectors for objects from a 1608 datastore."; 1609 choice filter-spec { 1610 description 1611 "The content filter specification for this request."; 1612 anydata datastore-subtree-filter { 1613 if-feature "sn:subtree"; 1614 description 1615 "This parameter identifies the portions of the 1616 target datastore to retrieve."; 1618 } 1619 leaf datastore-xpath-filter { 1620 if-feature "sn:xpath"; 1621 type yang:xpath1.0; 1622 description 1623 "This parameter contains an XPath expression identifying the 1624 portions of the target datastore to retrieve. 1626 If the expression returns a node-set, all nodes in the 1627 node-set are selected by the filter. Otherwise, if the 1628 expression does not return a node-set, the filter 1629 doesn't select any nodes. 1631 The expression is evaluated in the following XPath context: 1633 o The set of namespace declarations are those in scope on 1634 the 'datastore-xpath-filter' leaf element. 1636 o The set of variable bindings is empty. 1638 o The function library is the core function library, and 1639 the XPath functions defined in section 10 in RFC 7950. 1641 o The context node is the root node of the target 1642 datastore."; 1643 } 1644 } 1645 } 1647 grouping selection-filter-objects { 1648 description 1649 "This grouping defines a selector for objects from a 1650 datastore."; 1651 choice selection-filter { 1652 description 1653 "The source of the selection filter applied to the 1654 subscription. This will come either referenced from a 1655 global list, or be provided within the subscription 1656 itself."; 1657 case by-reference { 1658 description 1659 "Incorporate a filter that has been configured separately."; 1660 leaf selection-filter-ref { 1661 type selection-filter-ref; 1662 mandatory true; 1663 description 1664 "References an existing selection filter which is to be 1665 applied to the subscription."; 1667 } 1668 } 1669 case within-subscription { 1670 description 1671 "Local definition allows a filter to have the same lifecycle 1672 as the subscription."; 1673 uses selection-filter-types; 1674 } 1675 } 1676 } 1678 grouping update-policy-modifiable { 1679 description 1680 "This grouping describes the datastore specific subscription 1681 conditions that can be changed during the lifetime of the 1682 subscription."; 1683 choice update-trigger { 1684 description 1685 "Defines necessary conditions for sending an event record to 1686 the subscriber."; 1687 case periodic { 1688 container periodic { 1689 presence "indicates an periodic subscription"; 1690 description 1691 "The publisher is requested to notify periodically the 1692 current values of the datastore as defined by the 1693 selection filter."; 1694 leaf period { 1695 type yang:timeticks; 1696 mandatory true; 1697 description 1698 "Duration of time which should occur between periodic 1699 push updates."; 1700 } 1701 leaf anchor-time { 1702 type yang:date-and-time; 1703 description 1704 "Designates a timestamp before or after which a series 1705 of periodic push updates are determined. The next 1706 update will take place at a whole multiple interval 1707 from the anchor time. For example, for an anchor time 1708 is set for the top of a particular minute and a period 1709 interval of a minute, updates will be sent at the top 1710 of every minute this subscription is active."; 1711 } 1712 } 1713 } 1714 case on-change { 1715 if-feature "on-change"; 1716 container on-change { 1717 presence "indicates an on-change subscription"; 1718 description 1719 "The publisher is requested to notify changes in values in 1720 the datastore subset as defined by a selection filter."; 1721 leaf dampening-period { 1722 type yang:timeticks; 1723 default "0"; 1724 description 1725 "Specifies the minimum interval between the assembly of 1726 successive update records for a single receiver of a 1727 subscription. Whenever subscribed objects change, and a 1728 dampening period interval (which may be zero) has 1729 elapsed since the previous update record creation for a 1730 receiver, then any subscribed objects and properties 1731 which have changed since the previous update record 1732 will have their current values marshalled and placed 1733 into a new update record."; 1734 } 1735 } 1736 } 1737 } 1738 } 1740 grouping update-policy { 1741 description 1742 "This grouping describes the datastore specific subscription 1743 conditions of a subscription."; 1744 uses update-policy-modifiable { 1745 augment "update-trigger/on-change/on-change" { 1746 description 1747 "Includes objects not modifiable once subscription is 1748 established."; 1749 leaf no-synch-on-start { 1750 type empty; 1751 description 1752 "The presence of this object restricts an on-change 1753 subscription from sending push-update notifications. 1754 When present, pushing a full selection per the terms of 1755 the selection filter MUST NOT be done for this 1756 subscription. Only updates about changes, i.e. only 1757 push-change-update notifications are sent. When absent 1758 (default behavior), in order to facilitate a receiver's 1759 synchronization, a full update is sent when the 1760 subscription starts using a push-update notification. 1761 After that, push-change-update notifications are 1762 exclusively sent unless the publisher chooses to resynch 1763 the subscription via a new push-update notification."; 1764 } 1765 leaf-list excluded-change { 1766 type change-type; 1767 description 1768 "Use to restrict which changes trigger an update. 1769 For example, if modify is excluded, only creation and 1770 deletion of objects is reported."; 1771 } 1772 } 1773 } 1774 } 1776 grouping hints { 1777 description 1778 "Parameters associated with some error for a subscription made 1779 upon a datastore."; 1780 leaf period-hint { 1781 type yang:timeticks; 1782 description 1783 "Returned when the requested time period is too short. This 1784 hint can assert a viable period for either a periodic push 1785 cadence or an on-change dampening interval."; 1786 } 1787 leaf filter-failure-hint { 1788 type string; 1789 description 1790 "Information describing where and/or why a provided filter 1791 was unsupportable for a subscription."; 1792 } 1793 leaf object-count-estimate { 1794 type uint32; 1795 description 1796 "If there are too many objects which could potentially be 1797 returned by the selection filter, this identifies the 1798 estimate of the number of objects which the filter would 1799 potentially pass."; 1800 } 1801 leaf object-count-limit { 1802 type uint32; 1803 description 1804 "If there are too many objects which could be returned by the 1805 selection filter, this identifies the upper limit of the 1806 publisher's ability to service for this subscription."; 1807 } 1808 leaf kilobytes-estimate { 1809 type uint32; 1810 description 1811 "If the returned information could be beyond the capacity of 1812 the publisher, this would identify the data size which could 1813 result from this selection filter."; 1814 } 1815 leaf kilobytes-limit { 1816 type uint32; 1817 description 1818 "If the returned information would be beyond the capacity of 1819 the publisher, this identifies the upper limit of the 1820 publisher's ability to service for this subscription."; 1821 } 1822 } 1824 /* 1825 * RPCs 1826 */ 1828 rpc resynch-subscription { 1829 if-feature "on-change"; 1830 description 1831 "This RPC allows a subscriber of an active on-change 1832 subscription to request a full push of objects. 1833 A successful invocation results in a push-update of all 1834 datastore objects that the subscriber is permitted to access. 1835 This RPC can only be invoked on the same session on which the 1836 subscription was established (using an establish-subscription 1837 RPC). In case of an error, a resynch-subscription-error is 1838 sent as part of an error response."; 1839 input { 1840 leaf identifier { 1841 type sn:subscription-id; 1842 mandatory true; 1843 description 1844 "Identifier of the subscription that is to be resynched."; 1845 } 1846 } 1847 } 1848 rc:yang-data resynch-subscription-error { 1849 container resynch-subscription-error { 1850 description 1851 "If a 'resynch-subscription' RPC fails, the subscription is 1852 not resynched and the RPC error response MUST indicate the 1853 reason for this failure. This yang-data MAY be inserted as 1854 structured data within a subscription's RPC error response 1855 to indicate the failure reason."; 1856 leaf reason { 1857 type identityref { 1858 base resynch-subscription-error; 1860 } 1861 mandatory true; 1862 description 1863 "Indicates the reason why the publisher has declined a 1864 request for subscription resynchronization."; 1865 } 1866 uses hints; 1867 } 1868 } 1870 augment "/sn:establish-subscription/sn:input" { 1871 description 1872 "This augmentation adds additional subscription parameters that 1873 apply specifically to datastore updates to RPC input."; 1874 uses update-policy; 1875 } 1876 augment "/sn:establish-subscription/sn:input/sn:target" { 1877 description 1878 "This augmentation adds the datastore as a valid target 1879 for the subscription to RPC input."; 1880 case datastore { 1881 description 1882 "Information specifying the parameters of an request for a 1883 datastore subscription."; 1884 uses datastore-criteria; 1885 } 1886 } 1887 rc:yang-data establish-subscription-datastore-error-info { 1888 container establish-subscription-datastore-error-info { 1889 description 1890 "If any 'establish-subscription' RPC parameters are 1891 unsupportable against the datastore, a subscription is not 1892 created and the RPC error response MUST indicate the reason 1893 why the subscription failed to be created. This yang-data MAY 1894 be inserted as structured data within a subscription's RPC 1895 error response to indicate the failure reason. This 1896 yang-data MUST be inserted if hints are to be provided back 1897 to the subscriber."; 1898 leaf reason { 1899 type identityref { 1900 base sn:establish-subscription-error; 1901 } 1902 description 1903 "Indicates the reason why the subscription has failed to 1904 be created to a targeted datastore."; 1905 } 1906 uses hints; 1907 } 1909 } 1911 augment "/sn:modify-subscription/sn:input" { 1912 description 1913 "This augmentation adds additional subscription parameters 1914 specific to datastore updates."; 1915 uses update-policy-modifiable; 1916 } 1917 augment "/sn:modify-subscription/sn:input/sn:target" { 1918 description 1919 "This augmentation adds the datastore as a valid target 1920 for the subscription to RPC input."; 1921 case datastore { 1922 description 1923 "Information specifying the parameters of an request for a 1924 datastore subscription."; 1925 uses selection-filter-objects; 1926 } 1927 } 1928 rc:yang-data modify-subscription-datastore-error-info { 1929 container modify-subscription-datastore-error-info { 1930 description 1931 "This yang-data MAY be provided as part of a subscription's RPC 1932 error response when there is a failure of a 1933 'modify-subscription' RPC which has been made against a 1934 datastore. This yang-data MUST be used if hints are to be 1935 provides back to the subscriber."; 1936 leaf reason { 1937 type identityref { 1938 base sn:modify-subscription-error; 1939 } 1940 description 1941 "Indicates the reason why the subscription has failed to 1942 be modified."; 1943 } 1944 uses hints; 1945 } 1946 } 1948 /* 1949 * NOTIFICATIONS 1950 */ 1952 notification push-update { 1953 description 1954 "This notification contains a push update, containing data 1955 subscribed to via a subscription. This notification is sent for 1956 periodic updates, for a periodic subscription. It can also be 1957 used for synchronization updates of an on-change subscription. 1958 This notification shall only be sent to receivers of a 1959 subscription. It does not constitute a general-purpose 1960 notification that would be subscribable as part of the NETCONF 1961 event stream by any receiver."; 1962 leaf subscription-id { 1963 type sn:subscription-id; 1964 description 1965 "This references the subscription which drove the notification 1966 to be sent."; 1967 } 1968 leaf incomplete-update { 1969 type empty; 1970 description 1971 "This is a flag which indicates that not all datastore nodes 1972 subscribed to are included with this update. In other words, 1973 the publisher has failed to fulfill its full subscription 1974 obligations, and despite its best efforts is providing an 1975 incomplete set of objects."; 1976 } 1977 anydata datastore-contents { 1978 description 1979 "This contains the updated data. It constitutes a snapshot 1980 at the time-of-update of the set of data that has been 1981 subscribed to. The snapshot corresponds to the same 1982 snapshot that would be returned in a corresponding get 1983 operation with the same selection filter parameters 1984 applied."; 1985 } 1986 } 1987 notification push-change-update { 1988 if-feature "on-change"; 1989 description 1990 "This notification contains an on-change push update. This 1991 notification shall only be sent to the receivers of a 1992 subscription; it does not constitute a general-purpose 1993 notification."; 1994 leaf subscription-id { 1995 type sn:subscription-id; 1996 description 1997 "This references the subscription which drove the notification 1998 to be sent."; 1999 } 2000 leaf incomplete-update { 2001 type empty; 2002 description 2003 "The presence of this object indicates not all changes which 2004 have occurred since the last update are included with this 2005 update. In other words, the publisher has failed to 2006 fulfill its full subscription obligations, for example in 2007 cases where it was not able to keep up with a change burst."; 2008 } 2009 anydata datastore-changes { 2010 description 2011 "This contains the set of datastore changes of the 2012 target datastore starting at the time of the 2013 previous update, per the terms of the subscription. 2014 The datastore changes are encoded per RFC 8027 2015 (YANG Patch)."; 2016 } 2017 } 2018 augment "/sn:subscription-started" { 2019 description 2020 "This augmentation adds datastore-specific objects to 2021 the notification that a subscription has started."; 2022 uses update-policy; 2023 } 2024 augment "/sn:subscription-started/sn:target" { 2025 description 2026 "This augmentation allows the datastore to be included as part 2027 of the notification that a subscription has started."; 2028 case datastore { 2029 uses datastore-criteria { 2030 refine "selection-filter/within-subscription" { 2031 description 2032 "Specifies the selection filter and where it originated 2033 from. If the 'selection-filter-ref' is populated, 2034 the filter within the subscription came from the 'filters' 2035 container. Otherwise it is populated in-line as part of 2036 the subscription itself."; 2037 } 2038 } 2039 } 2040 } 2041 augment "/sn:subscription-modified" { 2042 description 2043 "This augmentation adds datastore-specific objects to 2044 the notification that a subscription has been modified."; 2045 uses update-policy; 2046 } 2047 augment "/sn:subscription-modified/sn:target" { 2048 description 2049 "This augmentation allows the datastore to be included as part 2050 of the notification that a subscription has been modified."; 2051 case datastore { 2052 uses datastore-criteria { 2053 refine "selection-filter/within-subscription" { 2054 description 2055 "Specifies where the selection filter, and where it came 2056 from within the subscription and then populated within 2057 this notification. If the 'selection-filter-ref' is 2058 populated, the filter within the subscription came from 2059 the 'filters' container. Otherwise it is populated 2060 in-line as part of the subscription itself."; 2061 } 2062 } 2063 } 2064 } 2066 /* 2067 * DATA NODES 2068 */ 2070 augment "/sn:filters" { 2071 description 2072 "This augmentation allows the datastore to be included as part 2073 of the selection filtering criteria for a subscription."; 2074 list selection-filter { 2075 key "filter-id"; 2076 description 2077 "A list of pre-configured filters that can be applied 2078 to datastore subscriptions."; 2079 leaf filter-id { 2080 type string; 2081 description 2082 "An identifier to differentiate between selection filters."; 2083 } 2084 uses selection-filter-types; 2085 } 2086 } 2087 augment "/sn:subscriptions/sn:subscription" { 2088 description 2089 "This augmentation adds many datastore specific objects to a 2090 subscription."; 2091 uses update-policy; 2092 } 2093 augment "/sn:subscriptions/sn:subscription/sn:target" { 2094 description 2095 "This augmentation allows the datastore to be included as part 2096 of the selection filtering criteria for a subscription."; 2097 case datastore { 2098 uses datastore-criteria; 2099 } 2100 } 2102 } 2104 2106 6. IANA Considerations 2108 This document registers the following namespace URI in the "IETF XML 2109 Registry" [RFC3688]: 2111 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push 2112 Registrant Contact: The IESG. 2113 XML: N/A; the requested URI is an XML namespace. 2115 This document registers the following YANG module in the "YANG Module 2116 Names" registry [RFC6020]: 2118 Name: ietf-yang-push 2119 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push 2120 Prefix: yp 2121 Reference: draft-ietf-netconf-yang-push-16.txt (RFC form) 2123 7. Security Considerations 2125 The YANG module specified in this document defines a schema for data 2126 that is designed to be accessed via network management protocols such 2127 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 2128 is the secure transport layer, and the mandatory-to-implement secure 2129 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 2130 is HTTPS, and the mandatory-to-implement secure transport is TLS 2131 [RFC5246]. 2133 The NETCONF access control model [RFC8341] provides the means to 2134 restrict access for particular NETCONF or RESTCONF users to a 2135 preconfigured subset of all available NETCONF or RESTCONF protocol 2136 operations and content. 2138 There are a number of data nodes defined in this YANG module that are 2139 writable/creatable/deletable (i.e., config true, which is the 2140 default). These data nodes may be considered sensitive or vulnerable 2141 in some network environments. Write operations (e.g., edit-config) 2142 to these data nodes without proper protection can have a negative 2143 effect on network operations. These are the subtrees and data nodes 2144 and their sensitivity/vulnerability: 2146 First, it should be noted that the YANG module augments the YANG 2147 module from [I-D.draft-ietf-netconf-subscribed-notifications]. 2148 All security considerations that are listed there are relevant 2149 also for datastore subscriptions. In the following, we focus on 2150 the data nodes that are newly introduced here. 2152 Subtree "selection-filter" under container "filters": This subtree 2153 allows to specify which objects or subtrees to include in a 2154 datastore subscription. An attacker could attempt to modify the 2155 filter. For example, the filter might be modified to result in 2156 very few objects being filtered in order to attempt to overwhelm 2157 the receiver. Alternatively, the filter might be modified to 2158 result in certain objects to be excluded from updates, in order to 2159 have certain changes go unnoticed. 2161 Subtree "datastore" in choice "target" in list "subscription": 2162 Analogous to "selection filter", an attacker might attempt to 2163 modify the objects being filtered in order to overwhelm a receiver 2164 with a larger volume of datastore node updates than expected, or 2165 to have certain changes go unnoticed. 2167 Choice "update-trigger" in list "subscription": By modifying the 2168 update trigger, an attacker might alter the updates that are being 2169 sent in order to confuse a receiver, to withhold certain updates 2170 to be sent to the receiver, and/or to overwhelm a receiver. For 2171 example, an attacker might modify the period with which updates 2172 are reported for a periodic subscription, or it might modify the 2173 dampening period for an on-change subscription, resulting in 2174 greater delay of successive updates (potentially affecting 2175 responsiveness of applications that depend on the updates) or in a 2176 high volume of updates (to exhaust receiver resources). 2178 RPC "resynch-subscription": This RPC allows a subscriber of an on- 2179 change subscription to request a full push of objects in the 2180 subscription's scope. This can result in a large volume of data. 2181 An attacker could attempt to use this RPC to exhaust resources on 2182 the server to generate the data, and attempt to overwhelm a 2183 receiver with the resulting data volume. 2185 8. Acknowledgments 2187 For their valuable comments, discussions, and feedback, we wish to 2188 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei 2189 Guo, Michael Scharf, Martin Bjorklund, and Guangying Zheng. 2191 9. References 2192 9.1. Normative References 2194 [I-D.draft-ietf-netconf-subscribed-notifications] 2195 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 2196 and E. Nilsen-Nygaard, "Custom Subscription to Event 2197 Streams", draft-ietf-netconf-subscribed-notifications-12 2198 (work in progress), April 2018. 2200 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2201 DOI 10.17487/RFC3688, January 2004, 2202 . 2204 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2205 the Network Configuration Protocol (NETCONF)", RFC 6020, 2206 DOI 10.17487/RFC6020, October 2010, 2207 . 2209 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2210 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 2211 February 2012, . 2213 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 2214 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 2215 . 2217 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2218 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2219 . 2221 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2222 Media Type", RFC 8072, DOI 10.17487/RFC8072, February 2223 2017, . 2225 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2226 Access Control Model", STD 91, RFC 8341, 2227 DOI 10.17487/RFC8341, March 2018, 2228 . 2230 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2231 and R. Wilton, "Network Management Datastore Architecture 2232 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2233 . 2235 9.2. Informative References 2237 [bergstra2014] 2238 Bergstra, J. and M. Burgess, "Promise Theory, Createspace 2239 Independent Publishers, ISBN-13 9781495437779", 2014. 2241 [I-D.draft-ietf-netconf-netconf-event-notifications] 2242 Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 2243 E., and A. Tripathy, "NETCONF Support for Event 2244 Notifications", May 2018. 2246 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2247 (TLS) Protocol Version 1.2", RFC 5246, 2248 DOI 10.17487/RFC5246, August 2008, 2249 . 2251 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2252 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 2253 . 2255 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2256 and A. Bierman, Ed., "Network Configuration Protocol 2257 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2258 . 2260 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2261 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2262 . 2264 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2265 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 2266 . 2268 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2269 for Subscription to YANG Datastores", RFC 7923, 2270 DOI 10.17487/RFC7923, June 2016, 2271 . 2273 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2274 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2275 . 2277 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2278 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2279 . 2281 Appendix A. Appendix A: Subscription Errors 2283 A.1. RPC Failures 2285 Rejection of an RPC for any reason is indicated by via RPC error 2286 response from the publisher. Valid RPC errors returned include both 2287 existing transport layer RPC error codes, such as those seen with 2288 NETCONF in [RFC6241], as well as subscription specific errors such as 2289 those defined within the YANG model. As a result, how subscription 2290 errors are encoded within an RPC error response is transport 2291 dependent. 2293 References to specific identities within the either the subscribed- 2294 notifications YANG model or the yang-push YANG model may be returned 2295 as part of the error responses resulting from failed attempts at 2296 datastore subscription. Following are valid errors per RPC (note: 2297 throughout this section the prefix 'sn' indicates an item imported 2298 from the subscribed-notifications.yang model): 2300 establish-subscription modify-subscription 2301 ---------------------- ------------------- 2302 cant-exclude sn:filter-unsupported 2303 datastore-not-subscribable sn:insufficient-resources 2304 sn:dscp-unavailable sn:no-such-subscription 2305 sn:filter-unsupported period-unsupported 2306 sn:insufficient-resources result-too-big 2307 on-change-unsupported synchronization-size 2308 on-change-synch-unsupported unchanging-selection 2309 period-unsupported 2310 result-too-big resynch-subscription 2311 synchronization-size -------------------- 2312 unchanging-selection no-such-subscription-resynch 2313 synchronization-size 2315 delete-subscription kill-subscription 2316 ---------------------- ----------------- 2317 sn:no-such-subscription sn:no-such-subscription 2319 There is one final set of transport independent RPC error elements 2320 included in the YANG model. These are the following four yang-data 2321 structures for failed datastore subscriptions: 2323 1. yang-data establish-subscription-error-datastore 2324 This MUST be returned if information identifying the reason for an 2325 RPC error has not been placed elsewhere within the transport 2326 portion of a failed "establish-subscription" RPC response. This 2327 MUST be sent if hints are included. 2329 2. yang-data modify-subscription-error-datastore 2330 This MUST be returned if information identifying the reason for an 2331 RPC error has not been placed elsewhere within the transport 2332 portion of a failed "modifiy-subscription" RPC response. This 2333 MUST be sent if hints are included. 2335 3. yang-data sn:delete-subscription-error 2336 This MUST be returned if information identifying the reason for an 2337 RPC error has not been placed elsewhere within the transport 2338 portion of a failed "delete-subscription" or "kill-subscription" 2339 RPC response. 2341 4. yang-data resynch-subscription-error 2342 This MUST be returned if information identifying the reason for an 2343 RPC error has not been placed elsewhere within the transport 2344 portion of a failed "resynch-subscription" RPC response. 2346 A.2. Notifications of Failure 2348 A subscription may be unexpectedly terminated or suspended 2349 independent of any RPC or configuration operation. In such cases, 2350 indications of such a failure MUST be provided. To accomplish this, 2351 the following types of error identities may be returned within the 2352 corresponding subscription state change notification: 2354 subscription-terminated subscription-suspended 2355 ----------------------- ---------------------- 2356 datastore-not-subscribable sn:insufficient-resources 2357 sn:filter-unavailable period-unsupported 2358 sn:no-such-subscription result-too-big 2359 sn:suspension-timeout synchronization-size 2360 unchanging-selection 2362 Appendix B. Changes between revisions 2364 (To be removed by RFC editor prior to publication) 2366 v15 - v16 2368 o Updated security considerations. 2370 o Updated references. 2372 o Addressed comments from last call review, specifically comments 2373 received from Martin Bjorklund. 2375 v14 - v15 2377 o Minor text fixes. Includes a fix to on-change update calculation 2378 to cover churn when a object changes to and from a value during a 2379 dampening period. 2381 v13 - v14 2383 o Minor text fixes. 2385 v12 - v13 2387 o Hint negotiation models now show error examples. 2389 o yang-data structures for rpc errors. 2391 v11 - v12 2393 o Included Martin's review clarifications. 2395 o QoS moved to subscribed-notifications 2397 o time-of-update removed as it is redundant with RFC5277's 2398 eventTime, and other times from notification-messages. 2400 o Error model moved to match existing implementations 2402 o On-change notifiable removed, how to do this is implementation 2403 specific. 2405 o NMDA model supported. Non NMDA version at https://github.com/ 2406 netconf-wg/yang-push/ 2408 v10 - v11 2410 o Promise model reference added. 2412 o Error added for no-such-datastore 2414 o Inherited changes from subscribed notifications (such as optional 2415 feature definitions). 2417 o scrubbed the examples for proper encodings 2418 v09 - v10 2420 o Returned to the explicit filter subtyping of v00-v05 2422 o identityref to ds:datastore made explicit 2424 o Returned ability to modify a selection filter via RPC. 2426 v08 - v09 2428 o Minor tweaks cleaning up text, removing appendicies, and making 2429 reference to revised-datastores. 2431 o Subscription-id optional in push updates, except when encoded in 2432 RFC5277, Section 4 one-way notification. 2434 o Finished adding the text descibing the resynch subscription RPC. 2436 o Removed relationships to other drafts and future technology 2437 appendicies as this work is being explored elsewhere. 2439 o Deferred the multi-line card issue to new drafts 2441 o Simplified the NACM interactions. 2443 v07 - v08 2445 o Updated YANG models with minor tweaks to accommodate changes of 2446 ietf-subscribed-notifications. 2448 v06 - v07 2450 o Clarifying text tweaks. 2452 o Clarification that filters act as selectors for subscribed 2453 datastore nodes; support for value filters not included but 2454 possible as a future extension 2456 o Filters don't have to be matched to existing YANG objects 2458 v05 - v06 2460 o Security considerations updated. 2462 o Base YANG model in [subscribe] updated as part of move to 2463 identities, YANG augmentations in this doc matched up 2465 o Terms refined and text updates throughout 2466 o Appendix talking about relationship to other drafts added. 2468 o Datastore replaces stream 2470 o Definitions of filters improved 2472 v04 to v05 2474 o Referenced based subscription document changed to Subscribed 2475 Notifications from 5277bis. 2477 o Getting operational data from filters 2479 o Extension notifiable-on-change added 2481 o New appendix on potential futures. Moved text into there from 2482 several drafts. 2484 o Subscription configuration section now just includes changed 2485 parameters from Subscribed Notifications 2487 o Subscription monitoring moved into Subscribed Notifications 2489 o New error and hint mechanisms included in text and in the yang 2490 model. 2492 o Updated examples based on the error definitions 2494 o Groupings updated for consistency 2496 o Text updates throughout 2498 v03 to v04 2500 o Updates-not-sent flag added 2502 o Not notifiable extension added 2504 o Dampening period is for whole subscription, not single objects 2506 o Moved start/stop into rfc5277bis 2508 o Client and Server changed to subscriber, publisher, and receiver 2510 o Anchor time for periodic 2512 o Message format for synchronization (i.e. synch-on-start) 2513 o Material moved into 5277bis 2515 o QoS parameters supported, by not allowed to be modified by RPC 2517 o Text updates throughout 2519 Authors' Addresses 2521 Alexander Clemm 2522 Huawei 2524 Email: ludwig@clemm.org 2526 Eric Voit 2527 Cisco Systems 2529 Email: evoit@cisco.com 2531 Alberto Gonzalez Prieto 2532 VMware 2534 Email: agonzalezpri@vmware.com 2536 Ambika Prasad Tripathy 2537 Cisco Systems 2539 Email: ambtripa@cisco.com 2541 Einar Nilsen-Nygaard 2542 Cisco Systems 2544 Email: einarnn@cisco.com 2546 Andy Bierman 2547 YumaWorks 2549 Email: andy@yumaworks.com 2551 Balazs Lengyel 2552 Ericsson 2554 Email: balazs.lengyel@ericsson.com