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