idnits 2.17.1 draft-ietf-netconf-yang-push-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 220: '...hat, a dampening period MAY be used to...' RFC 2119 keyword, line 247: '...cription request SHOULD be declined if...' RFC 2119 keyword, line 258: '...-success message SHOULD include in the...' RFC 2119 keyword, line 286: '... publisher MAY accept an on-change s...' RFC 2119 keyword, line 298: '...ely, a publisher MAY decide to simply ...' (47 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 846 has weird spacing: '...address ine...' == Line 912 has weird spacing: '...ro time yan...' == Line 1032 has weird spacing: '...ntifier sub...' == Line 1034 has weird spacing: '...-result sub...' == Line 1037 has weird spacing: '...ntifier sub...' == (9 more instances...) -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Update records for a single subscription MAY NOT be resequenced prior to transport. == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 22, 2017) is 2317 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-netconf-subscribed-notifications-06 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-revised-datastores-04 == Outdated reference: A later version (-09) exists of draft-ietf-netconf-rfc6536bis-05 -- Possible downref: Normative reference to a draft: ref. 'RFC6536bis' ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 2 errors (**), 0 flaws (~~), 12 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF A. Clemm 3 Internet-Draft Huawei 4 Intended status: Standards Track E. Voit 5 Expires: June 25, 2018 Cisco Systems 6 A. Gonzalez Prieto 7 VMware 8 A. Tripathy 9 E. Nilsen-Nygaard 10 Cisco Systems 11 A. Bierman 12 YumaWorks 13 B. Lengyel 14 Ericsson 15 December 22, 2017 17 YANG Datastore Subscription 18 draft-ietf-netconf-yang-push-12 20 Abstract 22 Via the mechanism described in this document, subscriber applications 23 may request a continuous, customized stream of updates from a YANG 24 datastore. Providing such visibility into changes made upon YANG 25 configuration and operational objects enables new capabilities based 26 on the remote mirroring of configuration and operational state. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on June 25, 2018. 45 Copyright Notice 47 Copyright (c) 2017 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 This document may contain material from IETF Documents or IETF 61 Contributions published or made publicly available before November 62 10, 2008. The person(s) controlling the copyright in some of this 63 material may not have granted the IETF Trust the right to allow 64 modifications of such material outside the IETF Standards Process. 65 Without obtaining an adequate license from the person(s) controlling 66 the copyright in such materials, this document may not be modified 67 outside the IETF Standards Process, and derivative works of it may 68 not be created outside the IETF Standards Process, except to format 69 it for publication as an RFC or to translate it into languages other 70 than English. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 75 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4 76 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 4 77 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 4 78 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6 79 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 6 80 3.4. Promise-Theory Considerations . . . . . . . . . . . . . . 8 81 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 8 82 3.6. Datastore Selection . . . . . . . . . . . . . . . . . . . 9 83 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 10 84 3.8. Subscription Management . . . . . . . . . . . . . . . . . 12 85 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 14 86 3.10. On-change Notifiable YANG objects . . . . . . . . . . . . 15 87 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 16 88 4. A YANG data model for management of datastore push 89 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 17 90 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 17 91 4.2. Subscription configuration . . . . . . . . . . . . . . . 25 92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 26 93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 27 94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 32 95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 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. Changes between revisions . . . . . . . . . . . . . 49 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 52 104 1. Introduction 106 Traditional approaches to remote visibility have been built on 107 polling. With polling, data is periodically requested and retrieved 108 by a client from a server to stay up-to-date. However, there are 109 issues associated with polling-based management: 111 o Polling incurs significant latency. This latency prohibits many 112 application types. 114 o Polling cycles may be missed, requests may be delayed or get lost, 115 often when the network is under stress and the need for the data 116 is the greatest. 118 o Polling requests may undergo slight fluctuations, resulting in 119 intervals of different lengths. The resulting data is difficult 120 to calibrate and compare. 122 o For applications that monitor for changes, many remote polling 123 cycles place ultimately fruitless load on the network, devices, 124 and applications. 126 A more effective alternative to polling is for an application to 127 receive automatic and continuous updates from a targeted subset of a 128 datastore. Accordingly, there is a need for a service that allows 129 applications to subscribe to updates from a datastore and that 130 enables the publisher to push and in effect stream those updates. 131 The requirements for such a service have been documented in 132 [RFC7923]. 134 This document defines a corresponding solution that is built on top 135 of "Custom Subscription to Event Streams" 136 [I-D.draft-ietf-netconf-subscribed-notifications]. Supplementing 137 that work are YANG data model augmentations, extended RPCs, and new 138 datastore specific update notifications. Transport options for 139 [I-D.draft-ietf-netconf-subscribed-notifications] will work 140 seamlessly with this solution. 142 2. Definitions and Acronyms 144 The terms below supplement those defined in 145 [I-D.draft-ietf-netconf-subscribed-notifications]. In addition, the 146 term "datastore" is defined in 147 [I-D.draft-ietf-netmod-revised-datastores]. 149 Datastore node: An instance of management information in a datastore. 150 Also known as "object". 152 Datastore node update: A data item containing the current value/ 153 property of a datastore node at the time the datastore node update 154 was created. 156 Datastore subtree: An instantiated datastore node and the datastore 157 nodes that are hierarchically contained within it. 159 Update record: A representation datastore node update(s) resulting 160 from the application of a selection filter for a subscription. An 161 update record will include the value/property of one or more 162 datastore nodes at a point in time. It may contain the update type 163 for each datastore node (e.g., add, change, delete). Also included 164 may be metadata/headers such as a subscription identifier. 166 Selection filter: Evaluation and/or selection criteria, which may be 167 applied against a targeted set of objects. 169 Update trigger: A mechanism that determines when an update record 170 needs to be generated. 172 YANG-Push: The subscription and push mechanism for datastores that is 173 specified in this document. 175 3. Solution Overview 177 This document specifies a solution for a push update subscription 178 service. This solution supports the dynamic as well as configured 179 subscriptions to information updates from datastores. Subscriptions 180 specify when notification messages should be sent and what data to 181 include in update records. YANG objects are subsequently pushed from 182 the publisher to the receiver per the terms of the subscription. 184 3.1. Subscription Model 186 YANG-push subscriptions are defined using a data model that is itself 187 defined in YANG. This model enhances the subscription model defined 188 in [I-D.draft-ietf-netconf-subscribed-notifications] with 189 capabilities that allow subscribers to subscribe to datastore node 190 updates, specifically to specify the triggers defining when to 191 generate update records as well as what to include in an update 192 record. Key enhancements include: 194 o Specification of selection filters which identify targeted YANG 195 datastore nodes and/or subtrees within a datastore for which 196 updates are to be pushed. 198 o An encoding (using anydata) for the contents of periodic and on- 199 change push updates. 201 o Specification of update policies contain conditions which trigger 202 the generation and pushing of new update records. There are two 203 types of triggers for subscriptions: periodic and on-change. 205 * For periodic subscriptions, the trigger is specified by two 206 parameters that define when updates are to be pushed. These 207 parameters are the period interval with which to report 208 updates, and an anchor time which can be used to calculate at 209 which point in time updates need to be assembled and sent. 211 * For on-change subscriptions, a trigger occurs whenever a change 212 in the subscribed information is detected. Included are 213 additional parameters such as: 215 + Dampening period: In an on-change subscription, detected 216 object changes should be sent as quickly as possible. 217 However it may be undesirable to send a rapid series of 218 object changes. Such behavior has the potential to exhaust 219 of resources in the publisher or receiver. In order to 220 protect against that, a dampening period MAY be used to 221 specify the interval which must pass before successive 222 update records for the same subscription are generated for a 223 receiver. The dampening period collectively applies to the 224 set of all datastore nodes selected by a single subscription 225 and sent to a single receiver. This means that when there 226 is a change to one or more subscribed objects, an update 227 record containing those objects is created either 228 immediately when no dampening period is in effect, or at the 229 end of a dampening period. If multiple changes to a single 230 object occur during a dampening period, only the value that 231 is in effect is included as part of the update record. The 232 dampening period goes into effect every time an update 233 record completes assembly. 235 + Change type: This parameter can be used to reduce the types 236 of datastore changes for which updates are sent (e.g., you 237 might only send when an object is created or deleted, but 238 not when an object value changes). 240 + No Synch on start: defines whether or not a complete push- 241 update of all subscribed data will be sent at the beginning 242 of a subscription. Such early synchronization establishes 243 the frame of reference for subsequent updates. 245 3.2. Negotiation of Subscription Policies 247 A dynamic subscription request SHOULD be declined if a publisher's 248 assessment is that it may be unable to provide update records meeting 249 the terms of the request. In this case, a subscriber may quickly 250 follow up with a new subscription request using different parameters. 252 Random guessing at different parameters by a subscriber is to be 253 discouraged. Therefore, in order to minimize the number of 254 subscription iterations between subscriber and publisher, dynamic 255 subscriptions supports a simple negotiation between subscribers and 256 publishers for subscription parameters. This negotiation is in the 257 form of a no-success response to a failed establish or modify 258 subscription request. The no-success message SHOULD include in the 259 returned error response information that, when considered, increases 260 the likelihood of success for subsequent requests. However, there 261 are no guarantees that subsequent requests for this subscriber will 262 be accepted. 264 [I-D.draft-ietf-netconf-subscribed-notifications] contains several 265 negotiable subscription parameters. Additional yang-push negotiation 266 information defined in this specification includes hints at 267 acceptable time intervals, size estimates for the number or objects 268 which would be returned from a filter, and the location of an error 269 in a provided filter. 271 3.3. On-Change Considerations 273 On-change subscriptions allow subscribers to receive updates whenever 274 changes to targeted objects occur. As such, on-change subscriptions 275 are particularly effective for data that changes infrequently, yet 276 for which applications need to be quickly notified whenever a change 277 does occur with minimal delay. 279 On-change subscriptions tend to be more difficult to implement than 280 periodic subscriptions. Accordingly, on-change subscriptions may not 281 be supported by all implementations or for every object. 283 Whether or not to accept or reject on-change subscription requests 284 when the scope of the subscription contains objects for which on- 285 change is not supported is up to the publisher implementation. A 286 publisher MAY accept an on-change subscription even when the scope of 287 the subscription contains objects for which on-change is not 288 supported. In that case, updates are sent only for those objects 289 within the scope that do support on-change updates whereas other 290 objects are excluded from update records, whether or not their values 291 actually change. In order for a subscriber to determine whether 292 objects support on-change subscriptions, objects are marked 293 accordingly on a publisher. Accordingly, when subscribing, it is the 294 responsibility of the subscriber to ensure it is aware of which 295 objects support on-change and which do not. For more on how objects 296 are so marked, see Section 3.10. 298 Alternatively, a publisher MAY decide to simply reject an on-change 299 subscription in case the scope of the subscription contains objects 300 for which on-change is not supported. In case of a configured 301 subscription, the subscription MAY be suspended. 303 To avoid flooding receivers with repeated updates for subscriptions 304 containing fast-changing objects, or objects with oscillating values, 305 an on-change subscription allows for the definition of a dampening 306 period. Once an update record for a given object is generated, no 307 other updates for this particular subscription will be created until 308 the end of the dampening period. Values sent at the end of the 309 dampening period are the current values of all changed objects which 310 are current at the time the dampening period expires. Changed 311 objects include those which were deleted or newly created during that 312 dampening period. If an object has returned to its original value 313 (or even has been created and then deleted) during the dampening- 314 period, the last change will still be sent. This will indicate churn 315 is occurring on that object. 317 On-change subscriptions can be refined to let users subscribe only to 318 certain types of changes. For example, a subscriber might only want 319 object creations and deletions, but not modifications of object 320 values. 322 Putting it all together, following is the conceptual process for 323 creating an push-change-update notification: 325 1. Just before a change, or at the start of a dampening period, 326 evaluate any filtering and any access control rules. The result 327 is a set "A" of datastore nodes and subtrees. 329 2. Just after a change, or at the end of a dampening period, 330 evaluate any filtering and any (possibly new) access control 331 rules. The result is a set "B" of datastore nodes and subtrees. 333 3. Construct a YANG patch record for going from A to B. If the 334 record is non-empty, send it to the receiver. 336 Note: In cases where a subscriber wants to have separate dampening 337 periods for different objects, multiple subscriptions with different 338 objects in a selection filter can be created. 340 3.4. Promise-Theory Considerations 342 A subscription to updates from a datastore is intended to obviate the 343 need for polling. However, in order to do so, it is critical that 344 subscribers can rely on the subscription and have confidence that 345 they will indeed receive the subscribed updates without having to 346 worry updates being silently dropped. In other words, a subscription 347 constitutes a promise on the side of the publisher to provide the 348 receivers with updates per the terms of the subscription. 350 Now, there are many reasons why a publisher may at some point no 351 longer be able to fulfill the terms of the subscription, even if the 352 subscription had been entered into with good faith. For example, the 353 volume of data objects may be larger than anticipated, the interval 354 may prove too short to send full updates in rapid succession, or an 355 internal problem may prevent objects from being collected. If for 356 some reason the publisher of a subscription is not able to keep its 357 promise, receivers MUST be notified immediately and reliably. The 358 publisher MAY also suspend the subscription. 360 A publisher SHOULD reject a request for a subscription if it is 361 unlikely that the publisher will be able fulfill the terms of that 362 subscription request. In such cases, it is preferable to have a 363 subscriber request a less resource intensive subscription than to 364 deal with frequently degraded behavior. 366 3.5. Data Encodings 368 3.5.1. Periodic Subscriptions 370 In a periodic subscription, the data included as part of an update 371 corresponds to data that could have been read using a retrieval 372 operation over that subscription's transport. 374 3.5.2. On-Change Subscriptions 376 In an on-change subscription, updates need to indicate not only 377 values of changed datastore nodes but also the types of changes that 378 occurred since the last update. Therefore encoding rules for data in 379 on-change updates will generally follow YANG-patch operation as 380 specified in [RFC8072]. The YANG-patch will describe what needs to 381 be applied to the earlier state reported by the preceding update, to 382 result in the now-current state. Note that contrary to [RFC8072], 383 objects encapsulated are not restricted to configuration objects 384 only. 386 However a patch must be able to do more than just describe the delta 387 from the previous state to the current state. As per Section 3.3, it 388 must also be able to identify if transient changes have occurred on 389 an object during a dampening period. To support this, it is valid to 390 encode a YANG patch operation so that its application would result in 391 a no change between the previous and current state. This indicates 392 that some churn has occurred on the object. An example of this would 393 be a patch that does a "create" operation for a datastore node where 394 the receiver believes one already exists, or a "merge" operation 395 which replaces a previous value with the same value. Note that this 396 means that the "create" and "delete" errors described in [RFC8072] 397 section 2.5 are not errors, and are valid operations with YANG push. 399 3.6. Datastore Selection 401 A subscription must specify both the selection filters and the 402 datastore against which these selection filters will be applied. 403 This information is used to choose and subsequently push data from 404 the publisher's datastore to the receivers. 406 Only a single selection filter can be applied to a subscription at a 407 time. The following selection filter types are included in the yang- 408 push data model, and may be applied against a datastore: 410 o subtree: A subtree selection filter identifies one or more 411 datastore subtrees. When specified, update records will only come 412 from the datastore nodes of selected datastore subtree(s). The 413 syntax and semantics correspond to that specified for [RFC6241] 414 section 6. 416 o xpath: An xpath selection filter is an XPath expression that 417 returns a node set. When specified, updates will only come from 418 the selected data nodes. 420 These filters are intended to be used as selectors that define which 421 objects are within the scope of a subscription. A publisher MUST 422 support at least one type of selection filter. 424 Selection filters are not intended to be used for property value 425 filtering for non-key objects. Supporting non-key property value 426 filtering so would have a number of implications that would result in 427 significant complexity. While it is possible to define extensions in 428 the future that will support selection filtering based on values, 429 this is not supported in this version of yang-push and a publisher 430 MAY reject a subscription request that contains a filter for object 431 values. 433 Xpath itself provides powerful filtering constructs, and care must be 434 used in filter definition. As an example, consider an xpath filter 435 with a boolean result; such a result will not provide an easily 436 interpretable subset of a datastore. Beyond the boolean example, it 437 is quite possible to define an xpath filter where results are easy 438 for an application to mis-interpret. Consider an xpath filter which 439 only passes a datastore object when an interface is up. It is up to 440 the receiver to understand implications of the presence or absence of 441 objects in each update. 443 When the set of selection filtering criteria is applied for periodic 444 subscription, all selected datastore nodes for which a receiver has 445 access are provided to a receiver. If the same filtering criteria is 446 applied to an on-change subscription, only the subset of those 447 datastore nodes supporting on-change are provided. A datastore node 448 which doesn't support on-change is never sent as part of an on-change 449 subscription's "push-update" or "push-change-update". 451 3.7. Streaming Updates 453 Contrary to traditional data retrieval requests, datastore 454 subscription enables an unbounded series of update records to be 455 streamed over time. Two generic YANG notifications for update 456 records have been defined for this: "push-update" and "push-change- 457 update". 459 A "push-update" notification defines a complete, filtered update of 460 the datastore per the terms of a subscription. This type of YANG 461 notification is used for continuous updates of periodic 462 subscriptions. A "push-update" notification can also be used for the 463 on-change subscriptions in two cases. First it will be used as the 464 initial "push-update" if there is a need to synchronize the receiver 465 at the start of a new subscription. It also MAY be sent if the 466 publisher later chooses to resynch an on-change subscription. The 467 "push-update" update record contains a data snippet that contains an 468 instantiated datastore subtree with the subscribed contents. The 469 content of the update record is equivalent to the contents that would 470 be obtained had the same data been explicitly retrieved using e.g., a 471 NETCONF "get" operation, with the same filters applied. 473 A "push-change-update" notification is the most common type of update 474 for on-change subscriptions. The update record in this case contains 475 a data snippet that indicates the set of changes that datastore nodes 476 have undergone since the last notification message. In other words, 477 this indicates which datastore nodes have been created, deleted, or 478 have had changes to their values. In cases where multiple changes 479 have occurred and the object has not been deleted, the object's most 480 current value is reported. (In other words, for each object, only 481 one change is reported, not its entire history. Doing so would 482 defeat the purpose of the dampening period.) 484 These new "push-update" or "push-change-update" are encoded and 485 placed within notification messages, and ultimately queued for egress 486 over the specified transport. 488 The following is an example of a notification message for a 489 subscription tracking the operational status of a single Ethernet 490 port (per [RFC7223]). This notification message is encoded XML over 491 NETCONF as per [I-D.draft-ietf-netconf-netconf-event-notifications]. 493 494 2017-10-25T08:00:11.22Z 495 496 1011 497 498 499 500 eth0 501 up 502 503 504 505 506 508 Figure 1: Push example 510 The following is an example of an on-change notification message for 511 the same subscription. 513 514 2017-10-25T08:22:33.44Z 515 516 89 517 518 519 1 520 521 edit1 522 merge 523 /ietf-interfaces:interfaces-state 524 525 526 527 eth0 528 down 529 530 531 532 533 534 535 536 538 Figure 2: Push example for on change 540 Of Note in the above example is the 'patch-id' with a value of '1'. 541 Per [RFC8072], the 'patch-id' is an arbitrary string. With YANG 542 Push, the publisher SHOULD put into the 'patch-id' a counter starting 543 at '1' which increments with every 'push-change-update' generated for 544 a subscription. If used as a counter, this counter MUST be reset to 545 '1' anytime a resynchronization occurs (i.e., with the sending of a 546 'push-update'). Also if used as a counter, the counter MUST be reset 547 to '1' the after passing a maximum value of '99999'. Such a 548 mechanism allows easy identification of lost or out-of-sequence 549 update records. 551 3.8. Subscription Management 553 The RPCs defined within 554 [I-D.draft-ietf-netconf-subscribed-notifications] have been enhanced 555 to support datastore subscription negotiation. Included in these 556 enhancements are error codes which can indicate why a datastore 557 subscription attempt has failed. 559 A datastore subscription can be rejected for multiple reasons. This 560 includes a too large subtree request, or the inability of the 561 publisher push update records as frequently as requested. In such 562 cases, no subscription is established. Instead, the subscription- 563 result with the failure reason is returned as part of the RPC 564 response. As part of this response, a set of alternative 565 subscription parameters MAY be returned that would likely have 566 resulted in acceptance of the subscription request. The subscriber 567 may consider these as part of future subscription attempts. 569 For instance, for the following request: 571 573 576 577 ds:operational 578 579 581 /ex:foo 582 583 584 500 585 586 587 589 Figure 3: Establish-Subscription example 591 the publisher might return: 593 595 598 yp:period-unsupported 599 600 601 2000 602 603 605 Figure 4: Error response example 607 As can be seen above the rejected subscription does not result in the 608 generation of an rpc-reply with an rpc-error element. YANG-push 609 specific errors and negotiation hints part are returned as part of 610 normal RPC operations. 612 3.9. Receiver Authorization 614 A receiver of subscription data MUST only be sent updates for which 615 they have proper authorization. A publisher MUST ensure that no non- 616 authorized data is included in push updates. To do so, it needs to 617 apply all corresponding checks applicable at the time of a specific 618 pushed update and if necessary silently remove any non-authorized 619 data from datastore subtrees. This enables YANG data pushed based on 620 subscriptions to be authorized equivalently to a regular data 621 retrieval (get) operation. 623 A publisher MUST allow for the possibility that a subscription's 624 selection filter references non-existent or access-protected data. 625 Such support permits a receiver the ability to monitor the entire 626 lifecyle of some datastore tree. In this case, all "push-update" 627 notifications must be sent empty, and no "push-change-update" 628 notifications will be sent until some data becomes visible for a 629 receiver. 631 A publisher MAY choose reject an establish-subscription request which 632 selects non-existent or access-protected data. In addition, a 633 publisher MAY choose to terminate a dynamic subscription or suspend a 634 configured receiver when the authorization privileges of a receiver 635 change, or the access controls for subscribed objects change. Such a 636 capability enables the publisher to avoid having to support a 637 continuous, and total filtering of an entire subscription's content. 639 In these cases above, the error identity "data-unavailable" SHOULD be 640 returned. This reduces the possibility of leakage of access 641 controlled objects. 643 The conceptual authorization model for datastores is the NETCONF 644 Access Control Model [RFC6536bis], Section 3.2.4. A clarification to 645 this is that each of the individual nodes in a resulting update 646 record MUST also have applied access control to resulting pushed 647 messages. This includes validating that read access is ok for any 648 nodes newly selected since the last update record for each receiver. 650 +-----------------+ +--------------------+ 651 push-update or --> | datastore node | yes | add datastore node | 652 push-change-update | access allowed? | ---> | to update message | 653 +-----------------+ +--------------------+ 655 Figure 5: Access control for push updates 657 If read access into previously accessible nodes has been lost due to 658 a receiver permissions change, this SHOULD be reported as a patch 659 "delete" operation for on-change subscriptions. If not capable of 660 handling such receiver permission changes with such a "delete", 661 publisher implementations MUST force dynamic subscription re- 662 establishment or configured subscription re-initialization so that 663 appropriate filtering is installed. 665 3.10. On-change Notifiable YANG objects 667 In some cases, a publisher supporting on-change notifications may not 668 be able to push updates for some object types on-change. Reasons for 669 this might be that the value of the datastore node changes frequently 670 (e.g., [RFC7223]'s in-octets counter), that small object changes are 671 frequent and meaningless (e.g., a temperature gauge changing 0.1 672 degrees), or that the implementation is not capable of on-change 673 notification for a particular object. 675 Support for on-change notification is specific to the individual YANG 676 model and/or implementation, and is useful to define in design time. 677 System integrators need this information (without reading any data 678 from a live node). 680 The default assumption is that no datastore nodes support on-change 681 notification. Schema nodes and subtrees that support on-change 682 notifications MUST be marked by accordingly with the YANG extension 683 "notifiable-on-change". This extension is defined in the data model 684 below. 686 When an on-change subscription is established, data-nodes are 687 automatically excluded unless they are marked with notifiable-on- 688 change as true. This also means that authorization checks SHALL NOT 689 be performed on them. A subscriber can identify which nodes may be 690 included in on-change updates by retrieving the datastore nodes in 691 the subscription's scope and checking for which notifiable-on-change 692 is marked as true. 694 In theory, adding "notifiable-on-change" markings can be done within 695 corresponding YANG models. But a more extensible way to avoid having 696 to modify existing module definitions is to add "notifiable-on- 697 change" markings within separate module deviations. This means that 698 when a YANG model designer wants to add a "notifiable-on-change" 699 marking to nodes of an existing module without modifying the module 700 definitions, a new module is introduced that contains deviation 701 statements which add "notifiable-on-change" statements as applicable. 703 deviation /sys:system/sys:system-time { 704 deviate add { 705 yp:notifiable-on-change false; 706 } 707 } 709 Figure 6: Deviation Example 711 3.11. Other Considerations 713 3.11.1. Robustness and reliability 715 Particularly in the case of on-change updates, it is important that 716 these updates do not get lost. Or in case the loss of an update is 717 unavoidable, it is critical that the receiver is notified 718 accordingly. 720 Update records for a single subscription MAY NOT be resequenced prior 721 to transport. 723 It is conceivable that under certain circumstances, a publisher will 724 recognize that it is unable to include within an update record the 725 full set of objects desired per the terms of a subscription. In this 726 case, the publisher MUST take one or more of the following actions. 728 o A publisher MUST set the "updates-not-sent" flag on any update 729 record which is known to be missing information. 731 o It MAY choose to suspend a subscription as per 732 [I-D.draft-ietf-netconf-subscribed-notifications]. 734 o When resuming an on-change subscription, the publisher SHOULD 735 generate a complete patch from the previous update record. If 736 this is not possible and the "no-synch-on-start" option is not 737 present for the subscription, then the full datastore contents MAY 738 be sent via a "push-update" instead (effectively replacing the 739 previous contents). If neither of these are possible, then an 740 "updates-not-sent" flag MUST be included on the next "push-change- 741 update". 743 Note: It is perfectly acceptable to have a series of "push-change- 744 update" notifications (and even "push update" notifications) serially 745 queued at the transport layer awaiting transmission. It is not 746 required to merge pending update messages. I.e., the dampening 747 period applies to update record creation, not transmission. 749 3.11.2. Publisher capacity 751 It is far preferable to decline a subscription request than to accept 752 such a request when it cannot be met. 754 Whether or not a subscription can be supported will be determined by 755 a combination of several factors such as the subscription trigger 756 (on-change or periodic), the period in which to report changes (one 757 second periods will consume more resources than one hour periods), 758 the amount of data in the datastore subtree that is being subscribed 759 to, and the number and combination of other subscriptions that are 760 concurrently being serviced. 762 4. A YANG data model for management of datastore push subscriptions 764 4.1. Overview 766 The YANG data model for datastore push subscriptions is depicted in 767 the following figure. Following YANG tree convention in the 768 depiction, brackets enclose list keys, "rw" means configuration, "ro" 769 operational state data, "?" designates optional nodes, "*" designates 770 nodes that can have multiple instances. Parentheses with a name in 771 the middle enclose choice and case nodes. New schema objects defined 772 here (i.e., beyond those from 773 [I-D.draft-ietf-netconf-subscribed-notifications]) are identified 774 with "yp". 776 module: ietf-subscribed-notifications 777 +--rw streams 778 | +--rw stream* [name] 779 | +--rw name string 780 | +--rw description string 781 | +--rw replay-support? empty {replay}? 782 | +--rw replay-log-creation-time? yang:date-and-time {replay}? 783 | +--rw replay-log-aged-time? yang:date-and-time {replay}? 784 +--rw filters 785 | +--rw stream-filter* [identifier] 786 | | +--rw identifier filter-id 787 | | +--rw (filter-spec)? 788 | | +--:(stream-subtree-filter) 789 | | | +--rw stream-subtree-filter? {subtree}? 790 | | +--:(stream-xpath-filter) 791 | | +--rw stream-xpath-filter? yang:xpath1.0 {xpath}? 792 | +--rw yp:selection-filter* [identifier] 793 | +--rw yp:identifier sn:filter-id 794 | +--rw (yp:filter-spec)? 795 | +--:(yp:datastore-subtree-filter) 796 | | +--rw yp:datastore-subtree-filter? {sn:subtree}? 797 | +--:(yp:datastore-xpath-filter) 798 | +--rw yp:datastore-xpath-filter? 799 | yang:xpath1.0 {sn:xpath}? 800 +--rw subscription-config {configured}? 801 | +--rw subscription* [identifier] 802 | +--rw identifier subscription-id 803 | +--rw purpose? string 804 | +--rw protocol transport {configured}? 805 | +--rw encoding encoding 806 | +--rw (target) 807 | | +--:(stream) 808 | | | +--rw (stream-filter)? 809 | | | | +--:(by-reference) 810 | | | | | +--rw stream-filter-ref stream-filter-ref 811 | | | | +--:(within-subscription) 812 | | | | +--rw (filter-spec)? 813 | | | | +--:(stream-subtree-filter) 814 | | | | | +--rw stream-subtree-filter? {subtree}? 815 | | | | +--:(stream-xpath-filter) 816 | | | | +--rw stream-xpath-filter? 817 | | | | yang:xpath1.0 {sn:xpath}? 818 | | | +--rw stream? stream-ref 819 | | | +--rw replay-start-time? yang:date-and-time {replay}? 820 | | +--:(yp:datastore) 821 | | +--rw yp:datastore identityref 822 | | +--rw (yp:selected-content)? 823 | | +--:(yp:by-reference) 824 | | | +--rw yp:selection-filter-ref selection-filter-ref 825 | | +--:(yp:within-subscription) 826 | | +--rw (yp:filter-spec)? 827 | | +--:(yp:datastore-subtree-filter) 828 | | | +--rw yp:datastore-subtree-filter? 829 | | {sn:subtree}? 830 | | +--:(yp:datastore-xpath-filter) 831 | | +--rw yp:datastore-xpath-filter? 832 | | yang:xpath1.0 {sn:xpath}? 833 | +--rw stop-time? yang:date-and-time 834 | +--rw dscp? inet:dscp {qos}? 835 | +--rw weighting? uint8 {qos}? 836 | +--rw dependency? sn:subscription-id {qos}? 837 | +--rw (notification-message-origin)? 838 | | +--:(interface-originated) 839 | | | +--rw source-interface? if:interface-ref 840 | | +--:(address-originated) 841 | | +--rw source-vrf? -> /ni:network-instances/ 842 | | network-instance/name {supports-vrf}? 843 | | +--rw source-address? inet:ip-address-no-zone 844 | +--rw receivers 845 | | +--rw receiver* [address port] 846 | | +--rw address inet:host 847 | | +--rw port inet:port-number 848 | +--rw (yp:update-trigger) 849 | +--:(yp:periodic) 850 | | +--rw yp:periodic! 851 | | +--rw yp:period yang:timeticks 852 | | +--rw yp:anchor-time? yang:date-and-time 853 | +--:(yp:on-change) {on-change}? 854 | +--rw yp:on-change! 855 | +--rw yp:dampening-period? yang:timeticks 856 | +--rw yp:no-synch-on-start? empty 857 | +--rw yp:excluded-change* change-type 858 +--ro subscriptions 859 +--ro subscription* [identifier] 860 +--ro identifier subscription-id 861 +--ro configured-subscription-state? enumeration {configured}? 862 +--ro purpose? string {configured}? 863 +--ro protocol transport {configured}? 864 +--ro encoding encoding 865 +--ro (target) 866 | +--:(stream) 867 | | +--ro (stream-filter)? 868 | | | +--:(by-reference) 869 | | | | +--ro stream-filter-ref stream-filter-ref 870 | | | +--:(within-subscription) 871 | | | +--ro (filter-spec)? 872 | | | +--:(stream-subtree-filter) 873 | | | | +--ro stream-subtree-filter? {subtree}? 874 | | | +--:(stream-xpath-filter) 875 | | | +--ro stream-xpath-filter? 876 | | | yang:xpath1.0 {sn:xpath}? 877 | | +--ro stream? stream-ref 878 | | +--ro replay-start-time? yang:date-and-time {replay}? 879 | +--:(yp:datastore) 880 | +--ro yp:datastore identityref 881 | +--ro (yp:selected-content)? 882 | +--:(yp:by-reference) 883 | | +--ro yp:selection-filter-ref selection-filter-ref 884 | +--:(yp:within-subscription) 885 | +--ro (yp:filter-spec)? 886 | +--:(yp:datastore-subtree-filter) 887 | | +--ro yp:datastore-subtree-filter? 888 | {sn:subtree}? 889 | +--:(yp:datastore-xpath-filter) 890 | +--ro yp:datastore-xpath-filter? 891 | yang:xpath1.0 {sn:xpath}? 892 +--ro stop-time? yang:date-and-time 893 +--ro dscp? inet:dscp {qos}? 894 +--ro weighting? uint8 {qos}? 895 +--ro dependency? sn:subscription-id {qos}? 896 +--ro (notification-message-origin)? 897 | +--:(interface-originated) 898 | | +--ro source-interface? if:interface-ref 899 | +--:(address-originated) 900 | +--ro source-vrf? -> /ni:network-instances/ 901 | | network-instance/name {supports-vrf}? 902 | +--ro source-address? inet:ip-address-no-zone 903 +--ro receivers 904 | +--ro receiver* [address port] 905 | +--ro address inet:host 906 | +--ro port inet:port-number 907 | +--ro pushed-notifications? yang:counter64 908 | +--ro excluded-notifications? yang:counter64 909 | +--ro status enumeration 910 | +---x reset 911 | +--ro output 912 | +--ro time yang:date-and-time 913 +--ro (yp:update-trigger) 914 +--:(yp:periodic) 915 | +--ro yp:periodic! 916 | +--ro yp:period yang:timeticks 917 | +--ro yp:anchor-time? yang:date-and-time 918 +--:(yp:on-change) {on-change}? 919 +--ro yp:on-change! 920 +--ro yp:dampening-period? yang:timeticks 921 +--ro yp:no-synch-on-start? empty 922 +--ro yp:excluded-change* change-type 924 rpcs: 925 +---x establish-subscription 926 | +---w input 927 | | +---w encoding? encoding 928 | | +---w (target) 929 | | | +--:(stream) 930 | | | | +---w (stream-filter)? 931 | | | | | +--:(by-reference) 932 | | | | | | +---w stream-filter-ref stream-filter-ref 933 | | | | | +--:(within-subscription) 934 | | | | | +---w (filter-spec)? 935 | | | | | +--:(stream-subtree-filter) 936 | | | | | | +---w stream-subtree-filter? {subtree}? 937 | | | | | +--:(stream-xpath-filter) 938 | | | | | +---w stream-xpath-filter? 939 | | | | | yang:xpath1.0 {sn:xpath}? 940 | | | | +---w stream? stream-ref 941 | | | | +---w replay-start-time? yang:date-and-time {replay}? 942 | | | +--:(yp:datastore) 943 | | | +---w yp:datastore identityref 944 | | | +---w (yp:selected-content)? 945 | | | +--:(yp:by-reference) 946 | | | | +---w yp:selection-filter-ref selection-filter-ref 947 | | | +--:(yp:within-subscription) 948 | | | +---w (yp:filter-spec)? 949 | | | +--:(yp:datastore-subtree-filter) 950 | | | | +---w yp:datastore-subtree-filter? 951 | | | | {sn:subtree}? 952 | | | +--:(yp:datastore-xpath-filter) 953 | | | +---w yp:datastore-xpath-filter? 954 | | | yang:xpath1.0 {sn:xpath}? 955 | | +---w stop-time? yang:date-and-time 956 | | +---w dscp? inet:dscp {qos}? 957 | | +---w weighting? uint8 {qos}? 958 | | +---w dependency? sn:subscription-id {qos}? 959 | | +---w (yp:update-trigger) 960 | | +--:(yp:periodic) 961 | | | +---w yp:periodic! 962 | | | +---w yp:period yang:timeticks 963 | | | +---w yp:anchor-time? yang:date-and-time 964 | | +--:(yp:on-change) {on-change}? 965 | | +---w yp:on-change! 966 | | +---w yp:dampening-period? yang:timeticks 967 | | +---w yp:no-synch-on-start? empty 968 | | +---w yp:excluded-change* change-type 969 | +--ro output 970 | +--ro subscription-result subscription-result 971 | +--ro (result)? 972 | +--:(no-success) 973 | | +--ro filter-failure? string 974 | | +--ro replay-start-time-hint? yang:date-and-time 975 | | +--ro yp:period-hint? yang:timeticks 976 | | +--ro yp:error-path? string 977 | | +--ro yp:object-count-estimate? uint32 978 | | +--ro yp:object-count-limit? uint32 979 | | +--ro yp:kilobytes-estimate? uint32 980 | | +--ro yp:kilobytes-limit? uint32 981 | +--:(success) 982 | +--ro identifier subscription-id 983 +---x modify-subscription 984 | +---w input 985 | | +---w identifier? subscription-id 986 | | +---w (target) 987 | | | +--:(stream) 988 | | | | +---w (stream-filter)? 989 | | | | +--:(by-reference) 990 | | | | | +---w stream-filter-ref stream-filter-ref 991 | | | | +--:(within-subscription) 992 | | | | +---w (filter-spec)? 993 | | | | +--:(stream-subtree-filter) 994 | | | | | +---w stream-subtree-filter? {subtree}? 995 | | | | +--:(stream-xpath-filter) 996 | | | | +---w stream-xpath-filter? 997 | | | | yang:xpath1.0 {sn:xpath}? 998 | | | +--:(yp:datastore) 999 | | | +---w (yp:selected-content)? 1000 | | | +--:(yp:by-reference) 1001 | | | | +---w yp:selection-filter-ref selection-filter-ref 1002 | | | +--:(yp:within-subscription) 1003 | | | +---w (yp:filter-spec)? 1004 | | | +--:(yp:datastore-subtree-filter) 1005 | | | | +---w yp:datastore-subtree-filter? 1006 | | | | {sn:subtree}? 1007 | | | +--:(yp:datastore-xpath-filter) 1008 | | | +---w yp:datastore-xpath-filter? 1009 | | | yang:xpath1.0 {sn:xpath}? 1010 | | +---w stop-time? yang:date-and-time 1011 | | +---w (yp:update-trigger) 1012 | | +--:(yp:periodic) 1013 | | | +---w yp:periodic! 1014 | | | +---w yp:period yang:timeticks 1015 | | | +---w yp:anchor-time? yang:date-and-time 1016 | | +--:(yp:on-change) {on-change}? 1017 | | +---w yp:on-change! 1018 | | +---w yp:dampening-period? yang:timeticks 1019 | +--ro output 1020 | +--ro subscription-result subscription-result 1021 | +--ro (result)? 1022 | +--:(no-success) 1023 | +--ro filter-failure? string 1024 | +--ro yp:period-hint? yang:timeticks 1025 | +--ro yp:error-path? string 1026 | +--ro yp:object-count-estimate? uint32 1027 | +--ro yp:object-count-limit? uint32 1028 | +--ro yp:kilobytes-estimate? uint32 1029 | +--ro yp:kilobytes-limit? uint32 1030 +---x delete-subscription 1031 | +---w input 1032 | | +---w identifier subscription-id 1033 | +--ro output 1034 | +--ro subscription-result subscription-result 1035 +---x kill-subscription 1036 +---w input 1037 | +---w identifier subscription-id 1038 +--ro output 1039 +--ro subscription-result subscription-result 1041 notifications: 1042 +---n replay-completed {replay}? 1043 | +--ro identifier subscription-id 1044 +---n subscription-completed 1045 | +--ro identifier subscription-id 1046 +---n subscription-started {configured}? 1047 | +--ro identifier subscription-id 1048 | +--ro protocol transport {configured}? 1049 | +--ro encoding encoding 1050 | +--ro (target) 1051 | | +--:(stream) 1052 | | | +--ro (stream-filter)? 1053 | | | | +--:(by-reference) 1054 | | | | | +--ro stream-filter-ref stream-filter-ref 1055 | | | | +--:(within-subscription) 1056 | | | | +--ro (filter-spec)? 1057 | | | | +--:(stream-subtree-filter) 1058 | | | | | +--ro stream-subtree-filter? {subtree}? 1059 | | | | +--:(stream-xpath-filter) 1060 | | | | +--ro stream-xpath-filter? 1061 | | | | yang:xpath1.0 {sn:xpath}? 1062 | | | +--ro stream? stream-ref 1063 | | | +--ro replay-start-time? yang:date-and-time {replay}? 1064 | | +--:(yp:datastore) 1065 | | +--ro yp:datastore identityref 1066 | | +--ro (yp:selected-content)? 1067 | | +--:(yp:by-reference) 1068 | | | +--ro yp:selection-filter-ref selection-filter-ref 1069 | | +--:(yp:within-subscription) 1070 | | +--ro (yp:filter-spec)? 1071 | | +--:(yp:datastore-subtree-filter) 1072 | | | +--ro yp:datastore-subtree-filter?{sn:subtree}? 1073 | | +--:(yp:datastore-xpath-filter) 1074 | | +--ro yp:datastore-xpath-filter? 1075 | | yang:xpath1.0 {sn:xpath}? 1076 | +--ro stop-time? yang:date-and-time 1077 | +--ro dscp? inet:dscp {qos}? 1078 | +--ro weighting? uint8 {qos}? 1079 | +--ro dependency? sn:subscription-id {qos}? 1080 | +--ro (yp:update-trigger) 1081 | +--:(yp:periodic) 1082 | | +--ro yp:periodic! 1083 | | +--ro yp:period yang:timeticks 1084 | | +--ro yp:anchor-time? yang:date-and-time 1085 | +--:(yp:on-change) {on-change}? 1086 | +--ro yp:on-change! 1087 | +--ro yp:dampening-period? yang:timeticks 1088 | +--ro yp:no-synch-on-start? empty 1089 | +--ro yp:excluded-change* change-type 1090 +---n subscription-resumed 1091 | +--ro identifier subscription-id 1092 +---n subscription-modified 1093 | +--ro identifier subscription-id 1094 | +--ro protocol transport {configured}? 1095 | +--ro encoding encoding 1096 | +--ro (target) 1097 | | +--:(stream) 1098 | | | +--ro (stream-filter)? 1099 | | | | +--:(by-reference) 1100 | | | | | +--ro stream-filter-ref stream-filter-ref 1101 | | | | +--:(within-subscription) 1102 | | | | +--ro (filter-spec)? 1103 | | | | +--:(stream-subtree-filter) 1104 | | | | | +--ro stream-subtree-filter? {subtree}? 1105 | | | | +--:(stream-xpath-filter) 1106 | | | | +--ro stream-xpath-filter? 1107 | | | | yang:xpath1.0 {sn:xpath}? 1108 | | | +--ro stream? stream-ref 1109 | | | +--ro replay-start-time? yang:date-and-time {replay}? 1110 | | +--:(yp:datastore) 1111 | | +--ro yp:datastore identityref 1112 | | +--ro (yp:selected-content)? 1113 | | +--:(yp:by-reference) 1114 | | | +--ro yp:selection-filter-ref selection-filter-ref 1115 | | +--:(yp:within-subscription) 1116 | | +--ro (yp:filter-spec)? 1117 | | +--:(yp:datastore-subtree-filter) 1118 | | | +--ro yp:datastore-subtree-filter?{sn:subtree}? 1119 | | +--:(yp:datastore-xpath-filter) 1120 | | +--ro yp:datastore-xpath-filter? 1121 | | yang:xpath1.0 {sn:xpath}? 1122 | +--ro stop-time? yang:date-and-time 1123 | +--ro dscp? inet:dscp {qos}? 1124 | +--ro weighting? uint8 {qos}? 1125 | +--ro dependency? sn:subscription-id {qos}? 1126 | +--ro (yp:update-trigger) 1127 | +--:(yp:periodic) 1128 | | +--ro yp:periodic! 1129 | | +--ro yp:period yang:timeticks 1130 | | +--ro yp:anchor-time? yang:date-and-time 1131 | +--:(yp:on-change) {on-change}? 1132 | +--ro yp:on-change! 1133 | +--ro yp:dampening-period? yang:timeticks 1134 | +--ro yp:no-synch-on-start? empty 1135 | +--ro yp:excluded-change* change-type 1136 +---n subscription-terminated 1137 | +--ro identifier subscription-id 1138 | +--ro error-id subscription-errors 1139 | +--ro filter-failure? string 1140 +---n subscription-suspended 1141 +--ro identifier subscription-id 1142 +--ro error-id subscription-errors 1143 +--ro filter-failure? string 1145 module: ietf-yang-push 1147 rpcs: 1148 +---x resynch-subscription {on-change}? 1149 +---w input 1150 | +---w identifier sn:subscription-id 1151 +--ro output 1152 +--ro subscription-result sn:subscription-result 1154 notifications: 1155 +---n push-update 1156 | +--ro subscription-id? sn:subscription-id 1157 | +--ro updates-not-sent? empty 1158 | +--ro datastore-contents? 1159 +---n push-change-update {on-change}? 1160 +--ro subscription-id? sn:subscription-id 1161 +--ro updates-not-sent? empty 1162 +--ro datastore-changes? 1164 Figure 7: Model structure 1166 Selected components of the model are summarized below. 1168 4.2. Subscription configuration 1170 Both configured and dynamic subscriptions are represented within the 1171 list subscription. But only configured subscriptions are listed 1172 within list subscription-config. In both lists, each subscription 1173 has own list elements. New and enhanced parameters extending the 1174 basic subscription data model in 1175 [I-D.draft-ietf-netconf-subscribed-notifications] include: 1177 o The targeted datastore from which the selection is being made. 1178 The potential datastores include those from 1180 [I-D.draft-ietf-netmod-revised-datastores]. A platform may also 1181 choose to support a custom datastore. 1183 o A selection filter identifying yang nodes of interest within a 1184 datastore. Filter contents are specified via a reference to an 1185 existing filter, or via an in-line definition for only that 1186 subscription. Referenced filters allows an implementation to 1187 avoid evaluating filter acceptability during a dynamic 1188 subscription request. The case statement differentiates the 1189 options. 1191 o For periodic subscriptions, triggered updates will occur at the 1192 boundaries of a specified time interval. These boundaries many be 1193 calculated from the periodic parameters: 1195 * a "period" which defines duration between period push updates. 1197 * an "anchor-time"; update intervals always fall on the points in 1198 time that are a multiple of a "period" from an "anchor-time". 1199 If "anchor-time" is not provided, then the "anchor-time" MUST 1200 be set with the creation time of the initial update record. 1202 o For on-change subscriptions, assuming any dampening period has 1203 completed, triggering occurs whenever a change in the subscribed 1204 information is detected. On-change subscriptions have more 1205 complex semantics that is guided by its own set of parameters: 1207 * a "dampening-period" specifies the interval that must pass 1208 before a successive update for the subscription is sent. If no 1209 dampening period is in effect, the update is sent immediately. 1210 If a subsequent change is detected, another update is only sent 1211 once the dampening period has passed for this subscription. 1213 * an "excluded-change" flag which allows restriction of the types 1214 of changes for which updates should be sent (e.g., only add to 1215 an update record on object creation). 1217 * a "no-synch-on-start" flag which specifies whether a complete 1218 update with all the subscribed data is to be sent at the 1219 beginning of a subscription. 1221 4.3. YANG Notifications 1223 4.3.1. State Change Notifications 1225 Subscription state notifications and mechanism are reused from 1226 [I-D.draft-ietf-netconf-subscribed-notifications]. Some have been 1227 augmented to include the datastore specific objects. 1229 4.3.2. Notifications for Subscribed Content 1231 Along with the subscribed content, there are other objects which 1232 might be part of a "push-update" or "push-change-update" 1234 A "subscription-id" MUST be transported along with the subscribed 1235 contents. An [RFC5277] Section 4 one-way notification MAY be used 1236 for encoding updates. Where it is, the relevant "subscription-id" 1237 MUST be encoded as the first element within each "push-update" or 1238 "push-change-update". This allows a receiver to differentiate which 1239 subscription resulted in a particular push. 1241 A "time-of-update" which represents the time an update record 1242 snapshot was generated. A receiver MAY assume that a publisher's 1243 objects have these pushed values at this point in time. 1245 An "updates-not-sent" object. This object indicates that not all 1246 changes which have occurred since the last update are actually 1247 included with this update. In other words, the publisher has failed 1248 to fulfill its full subscription obligations. (For example a 1249 datastore was unable to providing the full set of datastore nodes to 1250 a publisher process.) To facilitate re-synchronization of on-change 1251 subscriptions, a publisher MAY subsequently send a "push-update" 1252 containing a full selection snapshot of subscribed data. 1254 4.4. YANG RPCs 1256 YANG-Push subscriptions are established, modified, and deleted using 1257 RPCs augmented from 1258 [I-D.draft-ietf-netconf-subscribed-notifications]. 1260 4.4.1. Establish-subscription RPC 1262 The subscriber sends an establish-subscription RPC with the 1263 parameters in section 3.1. An example might look like: 1265 1267 1270 1271 1272 ds:operational 1273 1274 1277 1278 1279 500 1280 1281 1282 1284 Figure 8: Establish-subscription RPC 1286 The publisher MUST respond explicitly positively (i.e., subscription 1287 accepted) or negatively (i.e., subscription rejected) to the request. 1288 Positive responses include the "identifier" of the accepted 1289 subscription. In that case a publisher MAY respond: 1291 1293 1295 ok 1296 1297 1299 52 1300 1301 1303 Figure 9: Establish-subscription positive RPC response 1305 A subscription can be rejected for multiple reasons, including the 1306 lack of authorization to establish a subscription, no capacity to 1307 serve the subscription at the publisher, or the inability of the 1308 publisher to select datastore content at the requested cadence. 1310 If a request is rejected because the publisher is not able to serve 1311 it, the publisher SHOULD include in the returned error hints ar what 1312 subscription parameters might have been accepted for the request. 1314 However, there are no guarantee that subsequent requests using this 1315 info will in fact be accepted. 1317 For example, for the following request: 1319 1321 1324 1326 ds:operational 1327 1328 1330 /ex:foo 1331 1332 1333 10 1334 1335 1336 1338 Figure 10: Establish-subscription request example 2 1340 a publisher that cannot serve on-change updates but periodic updates 1341 might return the following: 1343 1345 1348 yp:period-unsupported 1349 1350 1351 100 1352 1353 1355 Figure 11: Establish-subscription error response example 2 1357 4.4.2. Modify-subscription RPC 1359 The subscriber MAY invoke the "modify-subscription" RPC for a 1360 subscription it previously established. The subscriber will include 1361 newly desired values in the "modify-subscription" RPC. Parameters 1362 not included MUST remain unmodified. Below is an example where a 1363 subscriber attempts to modify the "period" of a subscription. 1365 1367 1370 1011 1371 1373 ds:operational 1374 1375 1377 /ex:bar 1378 1379 1380 250 1381 1382 1383 1385 Figure 12: Modify subscription request 1387 The publisher MUST respond explicitly positively or negatively to the 1388 request. A response to a successful modification might look like: 1390 1392 1394 ok 1395 1396 1398 Figure 13: Modify subscription response 1400 If the subscription modification is rejected, the publisher MUST send 1401 a response like it does for an "establish-subscription" and maintain 1402 the subscription as it was before the modification request. 1403 Responses MAY include hints. A subscription MAY be modified multiple 1404 times. 1406 A configured subscription cannot be modified using "modify- 1407 subscription" RPC. Instead, the configuration needs to be edited as 1408 needed. 1410 4.4.3. Delete-subscription RPC 1412 To stop receiving updates from a subscription and effectively delete 1413 a subscription that had previously been established using an 1414 "establish-subscription" RPC, a subscriber can send a "delete- 1415 subscription" RPC, which takes as only input the subscription's 1416 "identifier". 1418 Configured subscriptions cannot be deleted via RPC, but have to be 1419 removed from the configuration. This RPC is identical to the RPC 1420 from [I-D.draft-ietf-netconf-subscribed-notifications]. 1422 4.4.4. Resynch-subscription RPC 1424 This RPC is only applicable only for on-change subscriptions 1425 previously been established using an "establish-subscription" RPC. 1426 On receipt, a publisher must either reply "ok" and quickly follow 1427 with a "push-update", or send an appropriate error such as "on- 1428 change-synch-unsupported". For example: 1430 1432 1435 1011 1436 1437 1439 1441 1444 sn:ok 1445 1446 1448 Resynch subscription 1450 4.4.5. YANG Module Synchronization 1452 To make subscription requests, the subscriber needs to know the YANG 1453 module library available on the publisher. The YANG 1.0 module 1454 library information is sent by a NETCONF server in the NETCONF 1455 "hello" message. For YANG 1.1 modules and all modules used with the 1456 RESTCONF [RFC8040] protocol, this information is provided by the YANG 1457 Library module (ietf-yang-library.yang from [RFC7895]. This YANG 1458 library information is important for the receiver to reproduce the 1459 set of object definitions used within the publisher. 1461 The YANG library includes a module list with the name, revision, 1462 enabled features, and applied deviations for each YANG module 1463 implemented by the publisher. The receiver is expected to know the 1464 YANG library information before starting a subscription. The 1465 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module 1466 can be used to cache the YANG library information. 1468 The set of modules, revisions, features, and deviations can change at 1469 run-time (if supported by the publisher implementation). In this 1470 case, the receiver needs to be informed of module changes before 1471 datastore nodes from changed modules can be processed correctly. The 1472 YANG library provides a simple "yang-library-change" notification 1473 that informs the subscriber that the library has changed. The 1474 receiver then needs to re-read the entire YANG library data for the 1475 replicated publisher in order to detect the specific YANG library 1476 changes. The "ietf-netconf-notifications" module defined in 1477 [RFC6470] contains a "netconf-capability-change" notification that 1478 can identify specific module changes. For example, the module URI 1479 capability of a newly loaded module will be listed in the "added- 1480 capability" leaf-list, and the module URI capability of an removed 1481 module will be listed in the "deleted-capability" leaf-list. 1483 5. YANG module 1485 ; file "ietf-yang-push.yang" 1486 module ietf-yang-push { 1487 yang-version 1.1; 1488 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1489 prefix yp; 1491 import ietf-yang-types { 1492 prefix yang; 1493 } 1494 import ietf-subscribed-notifications { 1495 prefix sn; 1496 } 1497 import ietf-datastores { 1498 prefix ds; 1499 } 1501 organization "IETF"; 1502 contact 1503 "WG Web: 1504 WG List: 1505 Editor: Alexander Clemm 1506 1508 Editor: Eric Voit 1509 1511 Editor: Alberto Gonzalez Prieto 1512 1514 Editor: Ambika Prasad Tripathy 1515 1517 Editor: Einar Nilsen-Nygaard 1518 1520 Editor: Andy Bierman 1521 1523 Editor: Balazs Lengyel 1524 "; 1526 description 1527 "This module contains YANG specifications for YANG push."; 1529 revision 2017-12-20 { 1530 description 1531 "Initial revision."; 1532 reference 1533 "draft-ietf-netconf-yang-push-12"; 1534 } 1536 /* 1537 * EXTENSIONS 1538 */ 1540 extension notifiable-on-change { 1541 argument "value"; 1542 description 1543 "Indicates whether changes to the datastore node are reportable in 1544 on-change subscriptions. 1546 The statement MUST only be a substatement of the leaf, leaf-list, 1547 container, list, anyxml, anydata statements. Zero or One 1548 notifiable-on-change statement is allowed per parent statement. 1549 NO substatements are allowed. 1551 The argument is a boolean value indicating whether on-change 1552 notifications are supported. If notifiable-on-change is not 1553 specified, the default is the same as the parent datastore node's 1554 value. For top level datastore nodes the default value is false."; 1555 } 1557 /* 1558 * FEATURES 1559 */ 1561 feature on-change { 1562 description 1563 "This feature indicates that on-change triggered subscriptions 1564 are supported."; 1565 } 1567 /* 1568 * IDENTITIES 1569 */ 1571 /* Error type identities for datastore subscription */ 1572 identity period-unsupported { 1573 base sn:error; 1574 description 1575 "Requested time period is too short. This can be for both 1576 periodic and on-change dampening."; 1577 } 1579 identity on-change-unsupported { 1580 base sn:error; 1581 description 1582 "On-change is not supported for any objects which are selectable 1583 by this filter."; 1584 } 1586 identity on-change-synch-unsupported { 1587 base sn:error; 1588 description 1589 "Neither synch on start nor resynchonization are supported for 1590 this subscription. This error will be used for two reasons. First 1591 if an 'establish-subscription' RPC doesn't include 1592 'no-synch-on-start', yet the publisher can't support sending a 1593 'push update' for this subscription for reasons other that 1594 'on-change-unsupported' or 'result-too-big'. And second, if the 1595 'resynch-subscription' RPC is invoked either for an existing 1596 periodic subscription, or for an on-change subscription which 1597 can't support resynchronization."; 1598 } 1600 identity data-unavailable { 1601 base sn:error; 1602 description 1603 "Referenced datatree node or subtree doesn't exist, or read 1604 access is not permitted."; 1605 } 1607 identity result-too-big { 1608 base sn:error; 1609 description 1610 "Resulting periodic or on-change push updates may exceed a size 1611 limit during normal conditions."; 1612 } 1614 identity synchronization-size { 1615 base sn:error; 1616 description 1617 "The resulting synch-on-start or resynchronization would push a 1618 datatree which exceeds size limit for a one-time update."; 1619 } 1621 identity datastore-not-subscribable { 1622 base sn:error; 1623 description 1624 "This is not a subscribable datastore."; 1625 } 1627 /* 1628 * TYPE DEFINITIONS 1629 */ 1631 typedef change-type { 1632 type enumeration { 1633 enum "create" { 1634 description 1635 "Create a new data resource if it does not already exist. If 1636 it already exists, replace."; 1637 } 1638 enum "delete" { 1639 description 1640 "Delete a data resource if it already exists. If it does not 1641 exists, take no action."; 1642 } 1643 enum "insert" { 1644 description 1645 "Insert a new user-ordered data resource"; 1646 } 1647 enum "merge" { 1648 description 1649 "merge the edit value with the target data resource; create 1650 if it does not already exist"; 1651 } 1652 enum "move" { 1653 description 1654 "Reorder the target data resource"; 1655 } 1656 enum "replace" { 1657 description 1658 "Replace the target data resource with the edit value"; 1659 } 1660 enum "remove" { 1661 description 1662 "Remove a data resource if it already exists "; 1663 } 1664 } 1665 description 1666 "Specifies different types of datastore changes."; 1667 reference 1668 "RFC 8072 section 2.5, with a delta that it is valid for a 1669 receiver to process an update record which performs a create 1670 operation on a datastore node the receiver believes exists, or to 1671 process a delete on a datastore node the receiver believes is 1672 missing."; 1673 } 1675 typedef selection-filter-ref { 1676 type leafref { 1677 path "/sn:filters/yp:selection-filter/yp:identifier"; 1678 } 1679 description 1680 "This type is used to reference a selection filter."; 1681 } 1683 /* 1684 * GROUP DEFINITIONS 1685 */ 1687 grouping datastore-criteria { 1688 description 1689 "A grouping to define criteria for which selected objects from 1690 a targeted datastore should be included in push updates."; 1691 leaf datastore { 1692 type identityref { 1693 base ds:datastore; 1694 } 1695 mandatory true; 1696 description 1697 "Datastore from which to retrieve data."; 1698 } 1699 uses selection-filter-objects; 1700 } 1702 grouping selection-filter-types { 1703 description 1704 "This grouping defines a selector for objects from a 1705 datastore."; 1706 choice filter-spec { 1707 description 1708 "The content filter specification for this request."; 1709 anydata datastore-subtree-filter { 1710 if-feature "sn:subtree"; 1711 description 1712 "This parameter identifies the portions of the 1713 target datastore to retrieve."; 1714 } 1715 leaf datastore-xpath-filter { 1716 if-feature "sn:xpath"; 1717 type yang:xpath1.0; 1718 description 1719 "This parameter contains an XPath expression identifying the 1720 portions of the target datastore to retrieve. 1722 If the expression returns a node-set, all nodes in the 1723 node-set are selected by the filter. Otherwise, if the 1724 expression does not return a node-set, the filter 1725 doesn't select any nodes. 1727 The expression is evaluated in the following XPath context: 1729 o The set of namespace declarations are those in scope on 1730 the 'xpath-filter' leaf element. 1732 o The set of variable bindings is empty. 1734 o The function library is the core function library, and 1735 the XPath functions defined in section 10 in RFC 7950. 1737 o The context node is the root node of the target 1738 datastore."; 1739 } 1740 } 1741 } 1743 grouping selection-filter-objects { 1744 description 1745 "This grouping defines a selector for objects from a 1746 datastore."; 1747 choice selected-content { 1748 description 1749 "The source of the selection filter applied to the subscription. 1750 This will come either referenced from a global list, or be 1751 provided within the subscription itself."; 1752 case by-reference { 1753 description 1754 "Incorporate a filter that has been configured separately."; 1755 leaf selection-filter-ref { 1756 type selection-filter-ref; 1757 mandatory true; 1758 description 1759 "References an existing selection filter which is to be 1760 applied to the subscription."; 1761 } 1762 } 1763 case within-subscription { 1764 description 1765 "Local definition allows a filter to have the same lifecycle 1766 as the subscription."; 1767 uses selection-filter-types; 1769 } 1770 } 1771 } 1773 grouping update-policy-modifiable { 1774 description 1775 "This grouping describes the datastore specific subscription 1776 conditions that can be changed during the lifetime of the 1777 subscription."; 1778 choice update-trigger { 1779 when "../yp:target/yp:datastore/yp:datastore"; 1780 mandatory true; 1781 description 1782 "Defines necessary conditions for sending an event record to 1783 the subscriber."; 1784 case periodic { 1785 container periodic { 1786 presence "indicates an periodic subscription"; 1787 description 1788 "The publisher is requested to notify periodically the 1789 current values of the datastore as defined by the selection 1790 filter."; 1791 leaf period { 1792 type yang:timeticks; 1793 mandatory true; 1794 description 1795 "Duration of time which should occur between periodic 1796 push updates. Where the anchor-time is 1797 available, the push will include the objects and their 1798 values which exist at an exact multiple of timeticks 1799 aligning to this start-time anchor."; 1800 } 1801 leaf anchor-time { 1802 type yang:date-and-time; 1803 description 1804 "Designates a timestamp before or after which a series of 1805 periodic push updates are determined. The next update 1806 will take place at a whole multiple interval from the 1807 anchor time. For example, for an anchor time is set for 1808 the top of a particular minute and a period interval of a 1809 minute, updates will be sent at the top of every minute 1810 this subscription is active."; 1811 } 1812 } 1813 } 1814 case on-change { 1815 if-feature "on-change"; 1816 container on-change { 1817 presence "indicates an on-change subscription"; 1818 description 1819 "The publisher is requested to notify changes in values in 1820 the datastore subset as defined by a selection filter."; 1821 leaf dampening-period { 1822 type yang:timeticks; 1823 default 0; 1824 description 1825 "Specifies the minimum interval between the assembly of 1826 successive update records for a single receiver of a 1827 subscription. Whenever subscribed objects change, and a 1828 dampening period interval (which may be zero) has elapsed 1829 since the previous update record creation for a receiver, 1830 then any subscribed objects and properties which have 1831 changed since the previous update record will have their 1832 current values marshalled and placed into a new update 1833 record."; 1834 } 1835 } 1836 } 1837 } 1838 } 1840 grouping update-policy { 1841 description 1842 "This grouping describes the datastore specific subscription 1843 conditions of a subscription."; 1844 uses update-policy-modifiable { 1845 augment "update-trigger/on-change/on-change" { 1846 description 1847 "Includes objects not modifiable once subscription is 1848 established."; 1849 leaf no-synch-on-start { 1850 type empty; 1851 description 1852 "The presence of this object restricts an on-change 1853 subscription from sending push-update notifications. When 1854 present, pushing a full selection per the terms of the 1855 selection filter MUST NOT be done for this subscription. 1856 Only updates about changes, i.e. only push-change-update 1857 notifications are sent. When absent (default behavior), 1858 in order to facilitate a receiver's synchronization, a full 1859 update is sent when the subscription starts using a 1860 push-update notification, just like in the case of a 1861 periodic subscription. After that, push-change-update 1862 notifications are exclusively sent unless the publisher 1863 chooses to resynch the subscription via a new push-update 1864 notification."; 1865 } 1866 leaf-list excluded-change { 1867 type change-type; 1868 description 1869 "Use to restrict which changes trigger an update. 1870 For example, if modify is excluded, only creation and 1871 deletion of objects is reported."; 1872 } 1873 } 1874 } 1875 } 1877 grouping update-error-hints { 1878 description 1879 "Allow return additional negotiation hints that apply 1880 specifically to push updates."; 1881 leaf period-hint { 1882 type yang:timeticks; 1883 description 1884 "Returned when the requested time period is too short. This 1885 hint can assert an viable period for both periodic push 1886 cadence and on-change dampening."; 1887 } 1888 leaf error-path { 1889 type string; 1890 description 1891 "Reference to a YANG path which is associated with the error 1892 being returned."; 1893 } 1894 leaf object-count-estimate { 1895 type uint32; 1896 description 1897 "If there are too many objects which could potentially be 1898 returned by the selection filter, this identifies the estimate 1899 of the number of objects which the filter would potentially 1900 pass."; 1901 } 1902 leaf object-count-limit { 1903 type uint32; 1904 description 1905 "If there are too many objects which could be returned by the 1906 selection filter, this identifies the upper limit of the 1907 publisher's ability to service for this subscription."; 1908 } 1909 leaf kilobytes-estimate { 1910 type uint32; 1911 description 1912 "If the returned information could be beyond the capacity of 1913 the publisher, this would identify the data size which could 1914 result from this selection filter."; 1915 } 1916 leaf kilobytes-limit { 1917 type uint32; 1918 description 1919 "If the returned information would be beyond the capacity of 1920 the publisher, this identifies the upper limit of the 1921 publisher's ability to service for this subscription."; 1922 } 1923 } 1925 /* 1926 * RPCs 1927 */ 1929 rpc resynch-subscription { 1930 if-feature "on-change"; 1931 description 1932 "This RPC allows a subscriber of an active on-change 1933 subscription to request a full push of objects in there current 1934 state. A successful result would be the set of YANG objects 1935 equivalent to a Get using the existing selection criteria. This 1936 request may only come from the same subscriber using the 1937 establish-subscription RPC."; 1938 input { 1939 leaf identifier { 1940 type sn:subscription-id; 1941 mandatory true; 1942 description 1943 "Identifier of the subscription that is to be resynched."; 1944 } 1945 } 1946 output { 1947 leaf subscription-result { 1948 type sn:subscription-result; 1949 mandatory true; 1950 description 1951 "Indicates whether the request for the subscription resynch 1952 has been accepted, or why it has been denied."; 1953 } 1954 } 1955 } 1957 /* 1958 * DATA NODES 1959 */ 1961 augment "/sn:establish-subscription/sn:input" { 1962 when "sn:target/yp:datastore/yp:datastore"; 1963 description 1964 "This augmentation adds additional subscription parameters that 1965 apply specifically to datastore updates to RPC input."; 1966 uses update-policy; 1967 } 1968 augment "/sn:establish-subscription/sn:input/sn:target" { 1969 description 1970 "This augmentation adds the datastore as a valid parameter object 1971 for the subscription to RPC input. This provides a target for 1972 the filter."; 1973 case datastore { 1974 uses datastore-criteria; 1975 } 1976 } 1977 augment "/sn:establish-subscription/sn:output/"+ 1978 "sn:result/sn:no-success" { 1979 description 1980 "This augmentation adds datastore specific error info 1981 and hints to RPC output."; 1982 uses update-error-hints; 1983 } 1984 augment "/sn:modify-subscription/sn:input" { 1985 description 1986 "This augmentation adds additional subscription parameters 1987 specific to datastore updates."; 1988 uses update-policy-modifiable; 1989 } 1990 augment "/sn:modify-subscription/sn:input/sn:target" { 1991 description 1992 "This augmentation adds the datastore as a valid parameter object 1993 for the subscription to RPC input. This provides a target for 1994 the filter."; 1995 case datastore { 1996 uses selection-filter-objects; 1997 } 1998 } 1999 augment "/sn:modify-subscription/sn:output/"+ 2000 "sn:result/sn:no-success" { 2001 description 2002 "This augmentation adds push datastore error info and hints to 2003 RPC output."; 2004 uses update-error-hints; 2005 } 2007 notification push-update { 2008 description 2009 "This notification contains a push update, containing data 2010 subscribed to via a subscription. This notification is sent for 2011 periodic updates, for a periodic subscription. It can also be 2012 used for synchronization updates of an on-change subscription. 2013 This notification shall only be sent to receivers of a 2014 subscription; it does not constitute a general-purpose 2015 notification."; 2016 leaf subscription-id { 2017 type sn:subscription-id; 2018 description 2019 "This references the subscription which drove the notification 2020 to be sent."; 2021 } 2022 leaf updates-not-sent { 2023 type empty; 2024 description 2025 "This is a flag which indicates that not all datastore nodes 2026 subscribed to are included with this update. In other words, 2027 the publisher has failed to fulfill its full subscription 2028 obligations, and despite its best efforts is providing an 2029 incomplete set of objects."; 2030 } 2031 anydata datastore-contents { 2032 description 2033 "This contains the updated data. It constitutes a snapshot 2034 at the time-of-update of the set of data that has been 2035 subscribed to. The format and syntax of the data 2036 corresponds to the format and syntax of data that would be 2037 returned in a corresponding get operation with the same 2038 selection filter parameters applied."; 2039 } 2040 } 2042 notification push-change-update { 2043 if-feature "on-change"; 2044 description 2045 "This notification contains an on-change push update. This 2046 notification shall only be sent to the receivers of a 2047 subscription; it does not constitute a general-purpose 2048 notification."; 2049 leaf subscription-id { 2050 type sn:subscription-id; 2051 description 2052 "This references the subscription which drove the notification 2053 to be sent."; 2054 } 2055 leaf updates-not-sent { 2056 type empty; 2057 description 2058 "The presence of this object indicates not all changes which 2059 have occurred since the last update are included with this 2060 update. In other words, the publisher has failed to 2061 fulfill its full subscription obligations, for example in 2062 cases where it was not able to keep up with a change burst."; 2063 } 2064 anydata datastore-changes { 2065 description 2066 "This contains the set of datastore changes needed 2067 to update a remote datastore starting at the time of the 2068 previous update, per the terms of the subscription. Changes 2069 are encoded analogous to the syntax of a corresponding yang- 2070 patch operation, i.e. a yang-patch operation applied to the 2071 datastore implied by the previous update to result in the 2072 current state."; 2073 reference 2074 "RFC 8072 section 2.5, with a delta that it is ok to receive 2075 ability create on an existing node, or receive a delete on a 2076 missing node."; 2077 } 2078 } 2080 augment "/sn:subscription-started" { 2081 description 2082 "This augmentation adds many datastore specific objects to 2083 the notification that a subscription has started."; 2084 uses update-policy; 2085 } 2086 augment "/sn:subscription-started/sn:target" { 2087 description 2088 "This augmentation allows the datastore to be included as part 2089 of the notification that a subscription has started."; 2090 case datastore { 2091 uses datastore-criteria { 2092 refine "selected-content/within-subscription" { 2093 description 2094 "Specifies where the selection filter, and where came from 2095 within the subscription and then populated within this 2096 notification. If the 'selection-filter-ref' is populated, 2097 the filter within the subscription came from the 'filters' 2098 container. Otherwise it is populated in-line as part of the 2099 subscription itself."; 2100 } 2101 } 2102 } 2103 } 2105 augment "/sn:filters" { 2106 description 2107 "This augmentation allows the datastore to be included as part 2108 of the selection filtering criteria for a subscription."; 2109 list selection-filter { 2110 key "identifier"; 2111 description 2112 "A list of pre-positioned filters that can be applied 2113 to datastore subscriptions."; 2114 leaf identifier { 2115 type sn:filter-id; 2116 description 2117 "An identifier to differentiate between selection filters."; 2118 } 2119 uses selection-filter-types; 2120 } 2121 } 2122 augment "/sn:subscription-modified" { 2123 description 2124 "This augmentation adds many datastore specific objects to 2125 the notification that a subscription has been modified."; 2126 uses update-policy; 2127 } 2128 augment "/sn:subscription-modified/sn:target" { 2129 description 2130 "This augmentation allows the datastore to be included as part 2131 of the notification that a subscription has been modified."; 2132 case datastore { 2133 uses datastore-criteria { 2134 refine "selected-content/within-subscription" { 2135 description 2136 "Specifies where the selection filter, and where came from 2137 within the subscription and then populated within this 2138 notification. If the 'selection-filter-ref' is populated, 2139 the filter within the subscription came from the 'filters' 2140 container. Otherwise it is populated in-line as part of the 2141 subscription itself."; 2142 } 2143 } 2144 } 2145 } 2147 augment "/sn:subscription-config/sn:subscription" { 2148 description 2149 "This augmentation adds many datastore specific objects 2150 which can be configured as opposed to established via RPC."; 2151 uses update-policy; 2152 } 2153 augment "/sn:subscription-config/sn:subscription/sn:target" { 2154 description 2155 "This augmentation adds the datastore to the selection filtering 2156 criteria for a subscription."; 2157 case datastore { 2158 uses datastore-criteria; 2159 } 2160 } 2161 augment "/sn:subscriptions/sn:subscription" { 2162 yp:notifiable-on-change true; 2163 description 2164 "This augmentation adds many datastore specific objects to a 2165 subscription."; 2166 uses update-policy; 2167 } 2168 augment "/sn:subscriptions/sn:subscription/sn:target" { 2169 description 2170 "This augmentation allows the datastore to be included as part 2171 of the selection filtering criteria for a subscription."; 2172 case datastore { 2173 uses datastore-criteria; 2174 } 2175 } 2177 /* YANG Parser Pyang crashing on syntax below, due to fixed bug 2178 https://github.com/mbj4668/pyang/issues/300 2180 deviation "/sn:subscriptions/sn:subscription/sn:receivers/" 2181 + "sn:receiver/sn:pushed-notifications" { 2182 deviate add { 2183 yp:notifiable-on-change false; 2184 } 2185 } 2186 deviation "/sn:subscriptions/sn:subscription/sn:receivers/" 2187 + "sn:receiver/sn:excluded-notifications" { 2188 deviate add { 2189 yp:notifiable-on-change false; 2190 } 2191 } 2192 YANG Parser Pyang crashing on syntax above */ 2193 } 2195 2197 6. IANA Considerations 2199 This document registers the following namespace URI in the "IETF XML 2200 Registry" [RFC3688]: 2202 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push 2203 Registrant Contact: The IESG. 2204 XML: N/A; the requested URI is an XML namespace. 2206 This document registers the following YANG module in the "YANG Module 2207 Names" registry [RFC6020]: 2209 Name: ietf-yang-push 2210 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push 2211 Prefix: yp 2212 Reference: draft-ietf-netconf-yang-push-12.txt (RFC form) 2214 7. Security Considerations 2216 All security considerations from 2217 [I-D.draft-ietf-netconf-subscribed-notifications] are relevant for 2218 datastores. In addition there are specific security considerations 2219 for receivers defined in Section 3.9 2221 If the access control permissions on subscribed YANG nodes change 2222 during the lifecycle of a subscription, a publisher MUST either 2223 transparently conform to the new access control permissions, or must 2224 terminate or restart the subscriptions so that new access control 2225 permissions are re-established. 2227 The NETCONF Authorization Control Model SHOULD be used to restrict 2228 the delivery of YANG nodes for which the receiver has no access. 2230 8. Acknowledgments 2232 For their valuable comments, discussions, and feedback, we wish to 2233 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei 2234 Guo, Michael Scharf, Martin Bjorklund, and Guangying Zheng. 2236 9. References 2238 9.1. Normative References 2240 [I-D.draft-ietf-netconf-subscribed-notifications] 2241 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 2242 and E. Nilsen-Nygaard, "Custom Subscription to Event 2243 Streams", draft-ietf-netconf-subscribed-notifications-06 2244 (work in progress), October 2017. 2246 [I-D.draft-ietf-netmod-revised-datastores] 2247 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2248 and R. Wilton, "Network Management Datastore 2249 Architecture", draft-ietf-netmod-revised-datastores-04 2250 (work in progress), August 2017. 2252 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2253 DOI 10.17487/RFC3688, January 2004, 2254 . 2256 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2257 the Network Configuration Protocol (NETCONF)", RFC 6020, 2258 DOI 10.17487/RFC6020, October 2010, 2259 . 2261 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2262 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 2263 February 2012, . 2265 [RFC6536bis] 2266 Bierman, A. and M. Bjorklund, "Network Configuration 2267 Protocol (NETCONF) Access Control Model", draft-ietf- 2268 netconf-rfc6536bis-05 (work in progress), September 2017. 2270 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 2271 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 2272 . 2274 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2275 Media Type", RFC 8072, DOI 10.17487/RFC8072, February 2276 2017, . 2278 9.2. Informative References 2280 [I-D.draft-ietf-netconf-netconf-event-notifications] 2281 Gonzalez Prieto, A., Clemm, A., Voit, E., Nilsen-Nygaard, 2282 E., and A. Tripathy, "NETCONF Support for Event 2283 Notifications", September 2017. 2285 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2286 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 2287 . 2289 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2290 and A. Bierman, Ed., "Network Configuration Protocol 2291 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2292 . 2294 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2295 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 2296 . 2298 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2299 for Subscription to YANG Datastores", RFC 7923, 2300 DOI 10.17487/RFC7923, June 2016, 2301 . 2303 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2304 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2305 . 2307 Appendix A. Changes between revisions 2309 (To be removed by RFC editor prior to publication) 2311 v11 - v12 2313 o Included Martin's review clarifications. 2315 o QoS moved to subscribed-notifications 2316 o time-of-update removed as it is redundant with RFC5277's 2317 eventTime, and other times from notification-messages. 2319 v10 - v11 2321 o Promise model reference added. 2323 o Error added for no-such-datastore 2325 o Inherited changes from subscribed notifications (such as optional 2326 feature definitions). 2328 o scrubbed the examples for proper encodings 2330 v09 - v10 2332 o Returned to the explicit filter subtyping of v00-v05 2334 o identityref to ds:datastore made explicit 2336 o Returned ability to modify a selection filter via RPC. 2338 v08 - v09 2340 o Minor tweaks cleaning up text, removing appendicies, and making 2341 reference to revised-datastores. 2343 o Subscription-id optional in push updates, except when encoded in 2344 RFC5277, Section 4 one-way notification. 2346 o Finished adding the text descibing the resynch subscription RPC. 2348 o Removed relationships to other drafts and future technology 2349 appendicies as this work is being explored elsewhere. 2351 o Deferred the multi-line card issue to new drafts 2353 o Simplified the NACM interactions. 2355 v07 - v08 2357 o Updated YANG models with minor tweaks to accommodate changes of 2358 ietf-subscribed-notifications. 2360 v06 - v07 2362 o Clarifying text tweaks. 2364 o Clarification that filters act as selectors for subscribed 2365 datastore nodes; support for value filters not included but 2366 possible as a future extension 2368 o Filters don't have to be matched to existing YANG objects 2370 v05 - v06 2372 o Security considerations updated. 2374 o Base YANG model in [subscribe] updated as part of move to 2375 identities, YANG augmentations in this doc matched up 2377 o Terms refined and text updates throughout 2379 o Appendix talking about relationship to other drafts added. 2381 o Datastore replaces stream 2383 o Definitions of filters improved 2385 v04 to v05 2387 o Referenced based subscription document changed to Subscribed 2388 Notifications from 5277bis. 2390 o Getting operational data from filters 2392 o Extension notifiable-on-change added 2394 o New appendix on potential futures. Moved text into there from 2395 several drafts. 2397 o Subscription configuration section now just includes changed 2398 parameters from Subscribed Notifications 2400 o Subscription monitoring moved into Subscribed Notifications 2402 o New error and hint mechanisms included in text and in the yang 2403 model. 2405 o Updated examples based on the error definitions 2407 o Groupings updated for consistency 2409 o Text updates throughout 2411 v03 to v04 2412 o Updates-not-sent flag added 2414 o Not notifiable extension added 2416 o Dampening period is for whole subscription, not single objects 2418 o Moved start/stop into rfc5277bis 2420 o Client and Server changed to subscriber, publisher, and receiver 2422 o Anchor time for periodic 2424 o Message format for synchronization (i.e. synch-on-start) 2426 o Material moved into 5277bis 2428 o QoS parameters supported, by not allowed to be modified by RPC 2430 o Text updates throughout 2432 Authors' Addresses 2434 Alexander Clemm 2435 Huawei 2437 Email: ludwig@clemm.org 2439 Eric Voit 2440 Cisco Systems 2442 Email: evoit@cisco.com 2444 Alberto Gonzalez Prieto 2445 VMware 2447 Email: agonzalezpri@vmware.com 2449 Ambika Prasad Tripathy 2450 Cisco Systems 2452 Email: ambtripa@cisco.com 2453 Einar Nilsen-Nygaard 2454 Cisco Systems 2456 Email: einarnn@cisco.com 2458 Andy Bierman 2459 YumaWorks 2461 Email: andy@yumaworks.com 2463 Balazs Lengyel 2464 Ericsson 2466 Email: balazs.lengyel@ericsson.com