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