idnits 2.17.1 draft-ietf-netconf-yang-push-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 9 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 254: '...cription request SHOULD be declined ba...' RFC 2119 keyword, line 263: '... subscriptions SHOULD support a simp...' RFC 2119 keyword, line 266: '...-success message SHOULD include in the...' RFC 2119 keyword, line 293: '... MAY accept an on-change subscriptio...' RFC 2119 keyword, line 304: '...tively, a server MAY decide to simply ...' (43 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 804 has weird spacing: '...er-type fil...' == Line 946 has weird spacing: '...-period yan...' == Line 960 has weird spacing: '...ntifier sub...' == Line 962 has weird spacing: '...-result sub...' == Line 965 has weird spacing: '...ntifier sub...' == (5 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 messages for a single subscription MAY NOT be resequenced. == 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 (June 26, 2017) is 2496 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC7223' is defined on line 2119, but no explicit reference was found in the text == Outdated reference: A later version (-09) exists of draft-ietf-netconf-rfc6536bis-01 -- 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: 3 errors (**), 0 flaws (~~), 11 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: December 28, 2017 Cisco Systems 6 A. Gonzalez Prieto 8 A. Tripathy 9 E. Nilsen-Nygaard 10 Cisco Systems 11 A. Bierman 12 YumaWorks 13 B. Lengyel 14 Ericsson 15 June 26, 2017 17 Subscribing to YANG datastore push updates 18 draft-ietf-netconf-yang-push-07 20 Abstract 22 Providing rapid visibility into changes made on YANG configuration 23 and operational objects enables new capabilities such as remote 24 mirroring of configuration and operational state. Via the mechanism 25 described in this document, subscriber applications may request a 26 continuous, customized stream of updates from a YANG datastore. 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 http://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 December 28, 2017. 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 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 This document may contain material from IETF Documents or IETF 61 Contributions published or made publicly available before November 62 10, 2008. The person(s) controlling the copyright in some of this 63 material may not have granted the IETF Trust the right to allow 64 modifications of such material outside the IETF Standards Process. 65 Without obtaining an adequate license from the person(s) controlling 66 the copyright in such materials, this document may not be modified 67 outside the IETF Standards Process, and derivative works of it may 68 not be created outside the IETF Standards Process, except to format 69 it for publication as an RFC or to translate it into languages other 70 than English. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 75 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4 76 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 5 77 3.1. Event Subscription Model . . . . . . . . . . . . . . . . 5 78 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6 79 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 6 80 3.4. Promise-Theory Considerations . . . . . . . . . . . . . . 8 81 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 8 82 3.6. Datastore filters . . . . . . . . . . . . . . . . . . . . 9 83 3.7. Streaming updates . . . . . . . . . . . . . . . . . . . . 10 84 3.8. Subscription management . . . . . . . . . . . . . . . . . 13 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 . . . . . . . . . . . . . . . . . . . . . . . . 18 90 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 18 91 4.2. Subscription configuration . . . . . . . . . . . . . . . 23 92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 25 93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 26 94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 30 95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 44 97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44 98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 99 9.1. Normative References . . . . . . . . . . . . . . . . . . 44 100 9.2. Informative References . . . . . . . . . . . . . . . . . 45 101 Appendix A. Relationships to other drafts . . . . . . . . . . . 46 102 A.1. ietf-netconf-subscribed-notifications . . . . . . . . . . 46 103 A.2. ietf-netconf-netconf-event-notif . . . . . . . . . . . . 46 104 A.3. ietf-netconf-restconf-notif . . . . . . . . . . . . . . . 46 105 A.4. voit-notifications2 . . . . . . . . . . . . . . . . . . . 47 106 Appendix B. Technologies to be considered for future iterations 47 107 B.1. Proxy YANG Subscription when the Subscriber and Receiver 108 are different . . . . . . . . . . . . . . . . . . . . . . 47 109 B.2. OpState and Filters . . . . . . . . . . . . . . . . . . . 48 110 B.3. Splitting push updates . . . . . . . . . . . . . . . . . 48 111 B.4. Potential Subscription Parameters . . . . . . . . . . . . 49 112 Appendix C. Issues that are currently being worked and resolved 49 113 Appendix D. Changes between revisions . . . . . . . . . . . . . 49 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 116 1. Introduction 118 Traditional approaches to remote visibility have been built on 119 polling. With polling, data is periodically requested and retrieved 120 by a client from a server to stay up-to-date. However, there are 121 issues associated with polling-based management: 123 o Polling incurs significant latency. This latency prohibits many 124 application types. 126 o Polling cycles may be missed, requests may be delayed or get lost, 127 often when the network is under stress and the need for the data 128 is the greatest. 130 o Polling requests may undergo slight fluctuations, resulting in 131 intervals of different lengths. The resulting data is difficult 132 to calibrate and compare. 134 o For applications that monitor for changes, many remote polling 135 cycles place ultimately fruitless load on the network, devices, 136 and applications. 138 A more effective alternative to polling is for an application to 139 receive automatic and continuous updates from a targeted subset of a 140 datastore. Accordingly, there is a need for a service that allows 141 applications to subscribe to updates from a YANG datastore and that 142 enables the publisher to push and in effect stream those updates. 143 The requirements for such a service have been documented in 144 [RFC7923]. 146 This document defines a corresponding solution that is built on top 147 of "Custom Subscription to Event Notifications" [subscribe]. 148 Supplementing that work are YANG data model augmentations, extended 149 RPCs, and new datastore specific update notifications. Transport 150 options for [subscribe] will work seamlessly with this solution. 152 2. Definitions and Acronyms 154 The terms below supplement those defined in [subscribe]. 156 Data node: An instance of management information in a YANG datastore. 158 Data node update: A data item containing the current value/property 159 of a Data node at the time the data node update was created. 161 Datastore: A conceptual store of instantiated management information, 162 with individual data items represented by data nodes which are 163 arranged in hierarchical manner. 165 Data subtree: An instantiated data node and the data nodes that are 166 hierarchically contained within it. 168 Notification message: A transport encapsulated update record(s) and/ 169 or event notification(s) intended to be sent to a receiver. 171 Update notification message: A notification message that contains an 172 update record. 174 Update record: A representation data node update(s) resulting from 175 the application of a filter for a subscription. An update record 176 will include the value/property of one or more data nodes at a point 177 in time. It may contain the update type for each data node (e.g., 178 add, change, delete). Also included may be metadata/headers such as 179 a subscription-id. 181 Update trigger: A mechanism that determines when an update record 182 needs to be generated. 184 YANG-Push: The subscription and push mechanism for YANG datastores 185 that is specified in this document. 187 3. Solution Overview 189 This document specifies a solution for a push update subscription 190 service. This solution supports the dynamic as well as configured 191 subscriptions to information updates from YANG datastores. 192 Subscriptions specify when update notification messages should be 193 sent and what data to include in update records. YANG objects are 194 subsequently pushed from the publisher to the receiver per the terms 195 of the subscription. 197 3.1. Event Subscription Model 199 YANG-push subscriptions are defined using a data model that is itself 200 defined in YANG. This model enhances the event subscription model 201 defined in [subscribe] with capabilities that allow subscribers to 202 subscribe to data node updates, specifically to specify the triggers 203 when to generate update records as well as what to include in an 204 update record. Key enhancements include: 206 o Specification of selection filters which identify targeted YANG 207 data nodes and/or subtrees within a datastore for which updates 208 are to be pushed. 210 o An encoding (using anydata) for the contents of periodic and on- 211 change push updates. 213 o Specification of update policies that specify the conditions that 214 trigger the generation and pushing of new update records. There 215 are two types of subscriptions, periodic and on-change. 217 * For periodic subscriptions, the trigger is specified by two 218 parameters that define when updates are to be pushed. These 219 parameters are the period interval with which to report 220 updates, and an anchor time which can be used to calculate at 221 which point in time updates need to be assembled and sent. 223 * For on-change subscriptions, a trigger occurs whenever a change 224 in the subscribed information is detected. Included are 225 additional parameters such as: 227 + Dampening period: In an on-change subscription, the first 228 change that is detected results in an update to be sent 229 immediately. However, sending successive updates whenever 230 further changes are detected might result in quick 231 exhaustion of resources in case of very rapid changes. In 232 order to protect against that, a dampening period is used to 233 specify the interval which must pass before successive 234 update records for the same subscription are generated. The 235 dampening period collectively applies to the set of all data 236 nodes of a single subscription. This means that on change 237 of an object being subscribed to, an update record 238 containing that object is created either immediately when no 239 dampening period is already in effect, or at the end of a 240 dampening period. 242 + Change type: This parameter can be used to reduce the types 243 of datastore changes for which updates are sent (e.g., you 244 might only send when an object is created or deleted, but 245 not when an object value changes). 247 + No Synch on start: defines whether or not a complete push- 248 update of all subscribed data will be sent at the beginning 249 of a subscription. Such synchronization establishes the 250 frame of reference for subsequent updates. 252 3.2. Negotiation of Subscription Policies 254 A dynamic subscription request SHOULD be declined based on 255 publisher's assessment that it may be unable to provide update 256 records that would meet the terms of the request. However a 257 subscriber may quickly follow up with a new subscription request 258 using different parameters. 260 Random guessing at different parameters by a subscriber is to be 261 discouraged. Therefore, in order to minimize the number of 262 subscription iterations between subscriber and publisher, dynamic 263 subscriptions SHOULD support a simple negotiation between subscribers 264 and publishers for subscription parameters. This negotiation is in 265 the form of a no-success response to a failed establish or modify 266 subscription request. The no-success message SHOULD include in the 267 returned error response information that, when considered, increases 268 the likelihood of success for subsequent requests. However, there 269 are no guarantees that subsequent requests for this subscriber will 270 in fact be accepted. 272 Such negotiation information returned from a publisher beyond that 273 from [subscribe] includes hints at acceptable time intervals, size 274 estimates for the number or objects which would be returned from a 275 filter, and the names of targeted objects not found in the 276 publisher's YANG tree. 278 3.3. On-Change Considerations 280 On-change subscriptions allow subscribers to subscribe to updates 281 whenever changes to objects occur. As such, on-change subscriptions 282 are particularly effective for data that changes infrequently, yet 283 that requires applications to be notified whenever a change does 284 occur with minimal delay. 286 On-change subscriptions tend to be more difficult to implement than 287 periodic subscriptions. Accordingly, on-change subscriptions may not 288 be supported by all implementations or for every object. 290 Whether or not to accept or reject on-change subscription requests 291 when the scope of the subscription contains objects for which on- 292 change is not supported is up to the server implementation: A server 293 MAY accept an on-change subscription even when the scope of the 294 subscription contains objects for which on-change is not supported. 295 In that case, updates are sent only for those objects within the 296 scope that do support on-change updates whereas other objects are 297 excluded from update records, whether or not their values actually 298 change. In order for a client to determine whether objects support 299 on-change subcriptions, objects are marked accordingly by a server. 300 Accordingly, when subscribing, it is the responsibility of the client 301 to ensure it is aware of which objects support on-change and which do 302 not. For more on how objects are so marked, see Section 3.10. 304 Alternatively, a server MAY decide to simply reject an on-change 305 subscription in case the scope of the subscription contains objects 306 for which on-change is not supported. In case of a configured 307 subscription, the subsription can be marked as suspended respectively 308 inoperational. 310 To avoid flooding receivers with repeated updates for subscriptions 311 containing fast-changing objects, or objects with oscillating values, 312 an on-change subscription allows for the definition of a dampening 313 period. Once an update record for a given object is generated, no 314 other updates for this particular subscription will be created until 315 the end of the dampening period. Values sent at the end of the 316 dampening period are the current values of all changed objects which 317 are current at the time the dampening period expires. Changed 318 objects includes those which were deleted or newly created during 319 that dampening period. If an object has returned to its original 320 value (or even has been created and then deleted) during the 321 dampening-period, the last change will still be sent. This will 322 indicate churn is occuring on that object. 324 In cases where a client wants to have separate dampening periods for 325 different objects, multiple subscriptions with different objects in 326 subscription scope can be created. 328 On-change subscriptions can be refined to let users subscribe only to 329 certain types of changes, for example, only to object creations and 330 deletions, but not to modifications of object values. 332 3.4. Promise-Theory Considerations 334 A subscription to updates from a YANG datastore is intended to 335 obviate the need for polling. However, in order to do so, it is of 336 utmost importance that subscribers can rely on the subscription and 337 have confidence that they will indeed receive the subscribed updates 338 without having to worry updates being silently dropped. In other 339 words, a subscription constitutes a promise on the side of the server 340 to provide the receivers with updates per the terms of the 341 subscription. 343 Now, there are many reasons why a server may at some point no longer 344 be able to fulfill the terms of the subscription, even if the 345 subscription had been entered into with good faith. For example, the 346 volume of data objects may be larger than anticipated, the interval 347 may prove too short to send full updates in rapid succession, or an 348 internal problem may prevent updates from being collected. If for 349 some reason the server of a subscription is not able to keep its 350 promise, receivers MUST be notified immediately and reliably. The 351 server MUST also update the state of the subscription to indicate 352 that the subscription is in a detrimental state. 354 A server SHOULD reject a request for a subscription if it is unlikely 355 that the server will be able fulfill the terms of the subscription. 356 In such cases, it is preferable to have a client request another 357 subscription that is less resource intensive (for example, a 358 subscription with longer periodic update intervals), than to 359 subsequently frustrate the receiver with `frequent subscription 360 suspensions. 362 3.5. Data Encodings 364 Subscribed data is encoded in either XML or JSON format. A publisher 365 MUST support XML encoding and MAY support JSON encoding. 367 3.5.1. Periodic Subscriptions 369 In a periodic subscription, the data included as part of an update 370 corresponds to data that could have been simply retrieved using a get 371 operation and is encoded in the same way. XML encoding rules for 372 data nodes are defined in [RFC7950]. JSON encoding rules are defined 373 in [RFC7951]. 375 3.5.2. On-Change Subscriptions 377 In an on-change subscription, updates need to indicate not only 378 values of changed data nodes but also the types of changes that 379 occurred since the last update. Therefore encoding rules for data in 380 on-change updates will follow YANG-patch operation as specified in 381 [RFC8072]. The YANG-patch will describe what needs to be applied to 382 the earlier state reported by the preceding update, to result in the 383 now-current state. Note that contrary to [RFC8072], objects 384 encapsulated are not restricted to configuration objects only. 386 3.6. Datastore filters 388 Subscription policy specifies both the filters and the datastores 389 against which the filters will be applied. The result is the push of 390 information necessary to remotely maintain an extract of publisher's 391 datastore. 393 Only a single filter can be applied to a subscription at a time. The 394 following selection filter types are included in the yang-push data 395 model, and may be applied against a datastore: 397 o subtree: A subtree filter identifies one or more subtrees. When 398 specified, updates will only come from the data nodes of selected 399 YANG subtree(s). The syntax and semantics correspond to that 400 specified for [RFC6241] section 6. 402 o xpath: An xpath filter is an XPath expression which may be 403 meaningfully applied to a datastore. It is the results of this 404 expression which will be pushed. 406 Filters are intended to be used as selectors that define which 407 objects are within the scope of a subscription. Filters are not 408 intended to be used to store objects based on their current value. 409 Doing so would have a number of implications that would result in 410 significant additional complexity. For example, withough extending 411 encodings for on-change subscriptions, a receiver would not be able 412 to distinguish cases in which an object is no longer included in an 413 update because it was deleted, as opposed to its value simply no 414 longer meeting the filter criteria. While it is possible to define 415 extensions in the future that will support filtering based on values, 416 this is not supported in this version of yang-push and a server MAY 417 reject a subscription request that contains a filter for object 418 values. 420 Xpath itself provides powerful filtering constructs, and care must be 421 used in filter definition. As an example, consider an xpath filter 422 with a boolean result; such a result will not provide an easily 423 interpretable subset of a datastore. Beyond the boolean example, it 424 is quite possible to define an xpath filter where results are easy 425 for an application to mis-interpret. Consider an xpath filter which 426 only passes a datastore object when interface=up. It is up to the 427 receiver to understand implications of the presence or absence of 428 objects in each update. 430 It is not expected that implementations will support comprehensive 431 filter syntax and boundless complexity. It will be up to 432 implementations to describe what is viable, but the goal is to 433 provide equivalent capabilities to what is available with a GET. 434 Implementations MUST reject dynamic subscriptions or suspend 435 configured subscriptions if they include filters which are 436 unsupportable on a platform. 438 3.7. Streaming updates 440 Contrary to traditional data retrieval requests, datastore 441 subscription enables an unbounded series of update records to be 442 streamed over time. Two generic notifications for update records 443 have been defined for this: "push-update" and "push-change-update". 445 A push-update notification defines a complete, filtered update of the 446 datastore per the terms of a subscription. This type of notification 447 is used for continuous updates of periodic subscriptions. A push- 448 update notification can also used be for the on-change subscriptions 449 in two cases. First it will be used as the initial push-update if 450 there is a need to synchronize the receiver at the start of a new 451 subscription. It also MAY be sent if the publisher later chooses to 452 resynch an on-change subscription. The push-update record contains a 453 data snippet that contains an instantiated subtree with the 454 subscribed contents. The content of the update record is equivalent 455 to the contents that would be obtained had the same data been 456 explicitly retrieved using e.g., a NETCONF "get" operation, with the 457 same filters applied. 459 A push-change-update notification is the most common type of update 460 for on-change subscriptions. The update record in this case contains 461 a data snippet that indicates the set of changes that data nodes have 462 undergone since the last notification of YANG objects. In other 463 words, this indicates which data nodes have been created, deleted, or 464 have had changes to their values. In cases where multiple changes 465 have occurred and the object has not been deleted, the object's most 466 current value is reported. (In other words, for each object, only 467 one change is reported, not its entire history. Doing so would 468 defeat the purpose of the dampening period.) 470 These new YANG notifications are encoded and placed within 471 notification messages, which are then queued for egress over the 472 specified transport. The following is an example of an XML encoded 473 notification message over NETCONF transport as per [netconf-notif]. 475 477 2015-03-09T19:14:56Z 478 480 1011 481 2015-03-09T19:14:56.233Z 482 483 484 some_string 485 486 487 488 490 Figure 1: Push example 492 The following is an example of an on-change notification. It 493 contains an update for subscription 89, including a new value for a 494 leaf called beta, which is a child of a top-level container called 495 alpha: 497 499 2015-03-09T19:14:56Z 500 502 89 503 2015-03-09T19:14:56.233Z 504 505 506 1500 507 508 509 510 512 Figure 2: Push example for on change 514 The equivalent update when requesting json encoding: 516 518 2015-03-09T19:14:56Z 519 521 89 522 2015-03-09T19:14:56.233Z 523 524 { 525 "ietf-yang-patch:yang-patch": { 526 "patch-id": [ 527 null 528 ], 529 "edit": [ 530 { 531 "edit-id": "edit1", 532 "operation": "merge", 533 "target": "/alpha/beta", 534 "value": { 535 "beta": 1500 536 } 537 } 538 ] 539 } 540 } 541 542 543 545 Figure 3: Push example for on change with JSON 547 When the beta leaf is deleted, the publisher may send 548 550 2015-03-09T19:14:56Z 551 553 89 554 2015-03-09T19:14:56.233Z 555 556 557 559 560 561 562 564 Figure 4: 2nd push example for on change update 566 3.8. Subscription management 568 [subscribe] has been enhanced to support YANG datastore subscription 569 negotiation. These enhancements provide information on why a 570 datastore subscription attempt has failed. 572 A datastore subscription can be rejected for multiple reasons. This 573 includes the lack of read authorization on a requested data node, or 574 the inability of the publisher push update records as frequently as 575 requested. In such cases, no subscription is established. Instead, 576 the subscription-result with the failure reason is returned as part 577 of the RPC response. As part of this response, a set of alternative 578 subscription parameters MAY be returned that would likely have 579 resulted in acceptance of the subscription request. The subscriber 580 may consider these as part of future subscription attempts. 582 It should be noted that a rejected subscription does not result in 583 the generation of an rpc-reply with an rpc-error element, as neither 584 the specification of YANG-push specific errors nor the specification 585 of additional data parameters to be returned in an error case are 586 supported as part of a YANG data model. 588 For instance, for the following request: 590 592 594 push-update 595 598 500 599 encode-xml 600 601 603 Figure 5: Establish-Subscription example 605 the publisher might return: 607 609 611 error-insufficient-resources 612 613 2000 614 616 Figure 6: Error response example 618 3.9. Receiver Authorization 620 A receiver of subscription data MUST only be sent updates for which 621 they have proper authorization. A server MUST ensure that no non- 622 authorized data is included in push updates. To do so, it needs to 623 apply all corresponding checks applicable at the time of a specific 624 pushed update and if necessary silently remove any non-authorized 625 data from subtrees. This enables YANG data pushed based on 626 subscriptions to be authorized equivalently to a regular data 627 retrieval (get) operation. 629 Alternatively, a server that wants to avoid having to perform 630 filtering of authorized content on each update MAY instead simply 631 reject a subscription request that contains non-authorized data. It 632 MAY subsequently suspend a subscription in case new objects are 633 created during the course of the subscription for which the receiver 634 does not have the necessary authorization, or in case the 635 authorization privileges of a receiver change over the course of the 636 subscription. 638 The contextual authorization model for data in YANG datastores is the 639 NETCONF Access Control Model [RFC6536bis], Section 3.2.3. However, 640 there are some differences. 642 One of these clarifications is that datastore selection MUST NOT 643 return continuous errors as part of an on-change subscription. This 644 includes errors such as when there is not read access to every data 645 node specifically named within the filter. Non-authorized data needs 646 to be either simply dropped or, alternatively, the subscription 647 SHOULD be suspended. 649 +-------------+ +-------------+ 650 establish / | protocol | | filter | 651 modify --> | operation | -------------> | data node | 652 subscription | allowed? | datastore | access | 653 +-------------+ objects | allowed? | 654 +-------------+ 656 Figure 7: Access control for subscription 658 Another clarification to [RFC6536bis] is that each of the individual 659 nodes in a resulting update record MUST also have applied access 660 control to resulting pushed messages. This includes validating that 661 read access into new nodes added since the last update record. If 662 read access into previously accessible nodes not explicitly named in 663 the filter are lost mid-subscription, that can be treated as a 664 'delete' for on-change subscriptions. If not capable of handling 665 such permission changes for dynamic subscriptions, publisher 666 implementations MAY choose to terminate the subscription and to force 667 re-establishment with appropriate filtering. 669 +-------------+ +-------------------+ 670 push-update / --> | data node | yes | | 671 push-change-update | access | ---> | add data node | 672 | allowed? | | to update message | 673 +-------------+ +-------------------+ 675 Figure 8: Access control for push updates 677 3.10. On-change notifiable YANG objects 679 In some cases, a publisher supporting on-change notifications may not 680 be able to push updates for some object types on-change. Reasons for 681 this might be that the value of the data node changes frequently 682 (e.g., [RFC7223]'s in-octets counter), that small object changes are 683 frequent and meaningless (e.g., a temperature gauge changing 0.1 684 degrees), or that the implementation is not capable of on-change 685 notification for a particular object. 687 Support for on-change notification is usually specific to the 688 individual YANG model and/or implementation so it is possible to 689 define in design time. System integrators need this information 690 (without reading any data from a live node). 692 The default assumption is that no data nodes support on-change 693 notification. Schema nodes and subtrees that support on-change 694 notifications MUST be marked by accordingly with the YANG extension 695 "notifiable-on-change". This extension is defined in the data model 696 below. 698 When an on-change subscription is established, data-nodes are 699 automatically excluded unless they are marked with notifiable-on- 700 change as true. This also means that authorization checks SHALL NOT 701 be performed on them. A client can identify which nodes will be 702 included in on-change updated by retrieving the data nodes in the 703 subscription's scope and checking for which notifiable-on-change is 704 marked as true. 706 Adding notifiable-on-change markings will in general require updating 707 the corresponding YANG models. A simple way to avoid having to 708 modify existing module definitions is to add notifiable-on-change 709 markings by defining module deviations. This means that when a YANG 710 model designer wants to add a notifiable-on-change marking to nodes 711 of an existing module without modifying the module definitions, a new 712 module is introduced that contains deviation statements which add 713 "notifiable-on-change" statements as appicable. 715 deviation /sys:system/sys:system-time { 716 deviate add { 717 yp:notifiable-on-change false; 718 } 719 } 721 Figure 9: Deviation Example 723 3.11. Other considerations 725 3.11.1. Robustness and reliability 727 Particularly in the case of on-change push updates, it is important 728 that push updates do not get lost or, in case the loss of an update 729 is unavoidable, that the receiver is notified accordingly. 731 Update messages for a single subscription MAY NOT be resequenced. 733 It is conceivable that under certain circumstances, a publisher will 734 recognize that it is unable to include within an update record the 735 full set of objects desired per the terms of a subscription. In this 736 case, the publisher MUST take one or more of the following actions. 738 o A publisher MUST set the updates-not-sent flag on any update 739 record which is known to be missing information. 741 o It MAY choose to suspend a subscription as per [subscribe]. 743 o When resuming an on-change subscription, the publisher SHOULD 744 generate a complete patch from the previous update record. If 745 this is not possible and the synch-on-start option is configured, 746 then the full datastore contents MAY be sent instead (effectively 747 replacing the previous contents). If neither of these are 748 possible, then an updates-not-sent flag MUST be included on the 749 next push-change-update. 751 Note: It is perfectly acceptable to have a series of push-change- 752 updates (and even push updates) serially queued at the transport 753 layer awaiting transmission. It is not required to merge pending 754 update messages. I.e., the dampening period applies to update record 755 creation, not transmission. 757 3.11.2. Update size and fragmentation 759 Depending on the subscription, the volume of updates can become quite 760 large. Additionally, based on the platform, it is possible that 761 update records for a single subscription are best sent independently 762 from different line-cards. Therefore, it may not always be practical 763 to send the entire update record in a single chunk. Implementations 764 may therefore choose, at their discretion, to "chunk" update records, 765 breaking one subscription's objects across several update records. 766 In this case the updates-not-sent flag will indicate that no single 767 update record is complete, and it is permissible for multiple updates 768 to come into a receiver for a single periodic interval or on-change 769 dampening period. 771 Care must be taken in chunking as problems may arrise for objects 772 that have containment or referential dependencies. The publisher 773 must consider these issues if chunking is provided. 775 3.11.3. Publisher capacity 777 It is far preferable to decline a subscription request than to accept 778 such a request when it cannot be met. 780 Whether or not a subscription can be supported will be determined by 781 a combination of several factors such as the subscription policy (on- 782 change or periodic), the period in which to report changes (1 second 783 periods will consume more resources than 1 hour periods), the amount 784 of data in the subtree that is being subscribed to, and the number 785 and combination of other subscriptions that are concurrently being 786 serviced. 788 4. A YANG data model for management of datastore push subscriptions 790 4.1. Overview 792 The YANG data model for datastore push subscriptions is depicted in 793 the following figure. Following YANG tree convention in the 794 depiction, brackets enclose list keys, "rw" means configuration, "ro" 795 operational state data, "?" designates optional nodes, "*" designates 796 nodes that can have multiple instances. Parentheses with a name in 797 the middle enclose choice and case nodes. New YANG objects defined 798 here (i.e., beyond those from [subscribe]) are identified with "yp". 800 module: ietf-subscribed-notifications 801 +--rw filters 802 | +--rw filter* [identifier] 803 | +--rw identifier filter-id 804 | +--rw filter-type filter-type 805 | +--rw filter 806 +--rw subscription-config {configured-subscriptions}? 807 | +--rw subscription* [identifier] 808 | +--rw identifier subscription-id 809 | +--rw encoding? encoding 810 | +--rw (target) 811 | | +--:(event-stream) 812 | | | +--rw stream stream 813 | | +--:(yp:datastore) 814 | | +--rw yp:datastore datastore 815 | +--rw (applied-filter) 816 | | +--:(by-reference) 817 | | | +--rw filter-ref filter-ref 818 | | +--:(locally-configured) 819 | | +--rw filter-type filter-type 820 | | +--rw filter 821 | +--rw stop-time? yang:date-and-time 822 | +--rw receivers 823 | | +--rw receiver* [address port] 824 | | +--rw address inet:host 825 | | +--rw port inet:port-number 826 | | +--rw protocol? transport-protocol 827 | +--rw (notification-origin)? 828 | | +--:(interface-originated) 829 | | | +--rw source-interface? if:interface-ref 830 | | +--:(address-originated) 831 | | +--rw source-vrf? string 832 | | +--rw source-address inet:ip-address-no-zone 833 | +--rw (yp:update-trigger)? 834 | | +--:(yp:periodic) 835 | | | +--rw yp:period yang:timeticks 836 | | | +--rw yp:anchor-time? yang:date-and-time 837 | | +--:(yp:on-change) {on-change}? 838 | | +--rw yp:dampening-period yang:timeticks 839 | | +--rw yp:no-synch-on-start? empty 840 | | +--rw yp:excluded-change* change-type 841 | +--rw yp:dscp? inet:dscp 842 | +--rw yp:weighting? uint8 843 | +--rw yp:dependency? sn:subscription-id 844 +--ro subscriptions 845 +--ro subscription* [identifier] 846 +--ro identifier subscription-id 847 +--ro configured-subscription? 848 | empty {configured-subscriptions}? 849 +--ro encoding? encoding 850 +--ro (target) 851 | +--:(event-stream) 852 | | +--ro stream stream 853 | | +--ro replay-start-time? yang:date-and-time {replay}? 854 | +--:(yp:datastore) 855 | +--ro yp:datastore datastore 856 +--ro (applied-filter) 857 | +--:(by-reference) 858 | | +--ro filter-ref filter-ref 859 | +--:(locally-configured) 860 | +--ro filter-type filter-type 861 | +--ro filter 862 +--ro stop-time? yang:date-and-time 863 +--ro (notification-origin)? 864 | +--:(interface-originated) 865 | | +--ro source-interface? if:interface-ref 866 | +--:(address-originated) 867 | +--ro source-vrf? string 868 | +--ro source-address inet:ip-address-no-zone 869 +--ro receivers 870 | +--ro receiver* [address port] 871 | +--ro address inet:host 872 | +--ro port inet:port-number 873 | +--ro protocol? transport-protocol 874 | +--ro pushed-notifications? yang:counter64 875 | +--ro excluded-notifications? yang:counter64 876 | +--ro status subscription-status 877 +--ro (yp:update-trigger)? 878 | +--:(yp:periodic) 879 | | +--ro yp:period yang:timeticks 880 | | +--ro yp:anchor-time? yang:date-and-time 881 | +--:(yp:on-change) {on-change}? 882 | +--ro yp:dampening-period yang:timeticks 883 | +--ro yp:no-synch-on-start? empty 884 | +--ro yp:excluded-change* change-type 885 +--ro yp:dscp? inet:dscp 886 +--ro yp:weighting? uint8 887 +--ro yp:dependency? sn:subscription-id 889 rpcs: 890 +---x establish-subscription 891 | +---w input 892 | | +---w encoding? encoding 893 | | +---w (target) 894 | | | +--:(event-stream) 895 | | | | +---w stream stream 896 | | | | +---w replay-start-time? yang:date-and-time {replay}? 897 | | | +--:(yp:datastore) 898 | | | +---w yp:datastore datastore 899 | | +---w (applied-filter) 900 | | | +--:(by-reference) 901 | | | | +---w filter-ref filter-ref 902 | | | +--:(locally-configured) 903 | | | +---w filter-type filter-type 904 | | | +---w filter 905 | | +---w stop-time? yang:date-and-time 906 | | +---w (yp:update-trigger)? 907 | | | +--:(yp:periodic) 908 | | | | +---w yp:period yang:timeticks 909 | | | | +---w yp:anchor-time? yang:date-and-time 910 | | | +--:(yp:on-change) {on-change}? 911 | | | +---w yp:dampening-period yang:timeticks 912 | | | +---w yp:no-synch-on-start? empty 913 | | | +---w yp:excluded-change* change-type 914 | | +---w yp:dscp? inet:dscp 915 | | +---w yp:weighting? uint8 916 | | +---w yp:dependency? sn:subscription-id 917 | +--ro output 918 | +--ro subscription-result subscription-result 919 | +--ro (result)? 920 | +--:(no-success) 921 | | +--ro filter-failure? string 922 | | +--ro replay-start-time-hint? yang:date-and-time 923 | | +--ro yp:period-hint? yang:timeticks 924 | | +--ro yp:error-path? string 925 | | +--ro yp:object-count-estimate? uint32 926 | | +--ro yp:object-count-limit? uint32 927 | | +--ro yp:kilobytes-estimate? uint32 928 | | +--ro yp:kilobytes-limit? uint32 929 | +--:(success) 930 | +--ro identifier subscription-id 931 +---x modify-subscription 932 | +---w input 933 | | +---w identifier? subscription-id 934 | | +---w (applied-filter) 935 | | | +--:(by-reference) 936 | | | | +---w filter-ref filter-ref 937 | | | +--:(locally-configured) 938 | | | +---w filter-type filter-type 939 | | | +---w filter 940 | | +---w stop-time? yang:date-and-time 941 | | +---w (yp:update-trigger)? 942 | | +--:(yp:periodic) 943 | | | +---w yp:period yang:timeticks 944 | | | +---w yp:anchor-time? yang:date-and-time 945 | | +--:(yp:on-change) {on-change}? 946 | | +---w yp:dampening-period yang:timeticks 947 | +--ro output 948 | +--ro subscription-result subscription-result 949 | +--ro (result)? 950 | +--:(no-success) 951 | +--ro filter-failure? string 952 | +--ro yp:period-hint? yang:timeticks 953 | +--ro yp:error-path? string 954 | +--ro yp:object-count-estimate? uint32 955 | +--ro yp:object-count-limit? uint32 956 | +--ro yp:kilobytes-estimate? uint32 957 | +--ro yp:kilobytes-limit? uint32 958 +---x delete-subscription 959 | +---w input 960 | | +---w identifier subscription-id 961 | +--ro output 962 | +--ro subscription-result subscription-result 963 +---x kill-subscription 964 +---w input 965 | +---w identifier subscription-id 966 +--ro output 967 +--ro subscription-result subscription-result 969 notifications: 970 +---n replay-complete 971 | +--ro identifier subscription-id 972 +---n notification-complete 973 | +--ro identifier subscription-id 974 +---n subscription-started 975 | +--ro identifier subscription-id 976 | +--ro encoding? encoding 977 | +--ro (target) 978 | | +--:(event-stream) 979 | | | +--ro stream stream 980 | | | +--ro replay-start-time? yang:date-and-time {replay}? 981 | | +--:(yp:datastore) 982 | | +--ro yp:datastore datastore 983 | +--ro (applied-filter) 984 | | +--:(by-reference) 985 | | | +--ro filter-ref filter-ref 986 | | +--:(locally-configured) 987 | | +--ro filter-type filter-type 988 | | +--ro filter 989 | +--ro stop-time? yang:date-and-time 990 | +--ro (yp:update-trigger)? 991 | | +--:(yp:periodic) 992 | | | +--ro yp:period yang:timeticks 993 | | | +--ro yp:anchor-time? yang:date-and-time 994 | | +--:(yp:on-change) {on-change}? 995 | | +--ro yp:dampening-period yang:timeticks 996 | | +--ro yp:no-synch-on-start? empty 997 | | +--ro yp:excluded-change* change-type 998 | +--ro yp:dscp? inet:dscp 999 | +--ro yp:weighting? uint8 1000 | +--ro yp:dependency? sn:subscription-id 1001 +---n subscription-resumed 1002 | +--ro identifier subscription-id 1003 +---n subscription-modified 1004 | +--ro identifier subscription-id 1005 | +--ro encoding? encoding 1006 | +--ro (target) 1007 | | +--:(event-stream) 1008 | | +--ro stream stream 1009 | | +--ro replay-start-time? yang:date-and-time {replay}? 1010 | +--ro (applied-filter) 1011 | | +--:(by-reference) 1012 | | | +--ro filter-ref filter-ref 1013 | | +--:(locally-configured) 1014 | | +--ro filter-type filter-type 1015 | | +--ro filter 1016 | +--ro stop-time? yang:date-and-time 1017 | +--ro (yp:update-trigger)? 1018 | | +--:(yp:periodic) 1019 | | | +--ro yp:period yang:timeticks 1020 | | | +--ro yp:anchor-time? yang:date-and-time 1021 | | +--:(yp:on-change) {on-change}? 1022 | | +--ro yp:dampening-period yang:timeticks 1023 | | +--ro yp:no-synch-on-start? empty 1024 | | +--ro yp:excluded-change* change-type 1025 | +--ro yp:dscp? inet:dscp 1026 | +--ro yp:weighting? uint8 1027 | +--ro yp:dependency? sn:subscription-id 1028 +---n subscription-terminated 1029 | +--ro identifier subscription-id 1030 | +--ro error-id subscription-errors 1031 | +--ro filter-failure? string 1032 +---n subscription-suspended 1033 +--ro identifier subscription-id 1034 +--ro error-id subscription-errors 1035 +--ro filter-failure? string 1037 module: ietf-yang-push 1038 notifications: 1039 +---n push-update 1040 | +--ro subscription-id sn:subscription-id 1041 | +--ro time-of-update? yang:date-and-time 1042 | +--ro updates-not-sent? empty 1043 | +--ro datastore-contents? 1044 +---n push-change-update {on-change}? 1045 +--ro subscription-id sn:subscription-id 1046 +--ro time-of-update? yang:date-and-time 1047 +--ro updates-not-sent? empty 1048 +--ro datastore-changes? 1050 Figure 10: Model structure 1052 Selected components of the model are summarized below. 1054 4.2. Subscription configuration 1056 Both configured and dynamic subscriptions are represented within the 1057 list subscription-config. Each subscription has own list elements. 1058 New and enhanced parameters extending the basic subscription data 1059 model in [subscribe] include: 1061 o An update filter identifying yang nodes of interest. Filter 1062 contents are specified via a reference to an existing filter, or 1063 via an in-line definition for only that subscription. This 1064 facilitates the reuse of filter definitions, which can be 1065 important in case of complex filter conditions. Referenced 1066 filters can also allow an implementation to avoid evaluating 1067 filter acceptability during a dynamic subscription request. The 1068 case statement differentiates the options. 1070 o For periodic subscriptions, triggered updates will occur at the 1071 boundaries of a specified time interval. These boundaries many be 1072 calculated from the periodic parameters: 1074 * a "period" which defines duration between period push updates. 1076 * an "anchor-time"; update intervals always fall on the points in 1077 time that are a multiple of a period after the anchor time. If 1078 anchor time is not provided, then the anchor time MUST be set 1079 with the creation time of the initial update record. 1081 o For on-change subscriptions, assuming the dampening period has 1082 completed, triggered occurs whenever a change in the subscribed 1083 information is detected. On-change subscriptions have more 1084 complex semantics that is guided by its own set of parameters: 1086 * a "dampening-period" specifies the interval that must pass 1087 before a successive update for the subscription is sent. If no 1088 dampening period is in effect, the update is sent immediately. 1089 If a subsequent change is detected, another update is only sent 1090 once the dampening period has passed for this subscription. 1092 * an "excluded-change" flag which allows restriction of the types 1093 of changes for which updates should be sent (e.g., only add to 1094 an update record on object creation). 1096 * a "no-synch-on-start" flag which specifies whether a complete 1097 update with all the subscribed data is to be sent at the 1098 beginning of a subscription. 1100 o Optional qos parameters to indicate the treatment of a 1101 subscription relative to other traffic between publisher and 1102 receiver. These include: 1104 * A "dscp" QoS marking which MUST be stamped on notification 1105 messages to differentiate network QoS behavior. 1107 * A "weighting" so that bandwidth proportional to this weighting 1108 can be allocated to this subscription relative to others for 1109 that receiver. 1111 * a "dependency" upon another subscription. Notification 1112 messages MUST NOT be sent prior to other notification messages 1113 containing update record(s) for the referenced subscription. 1115 o A subscription's weighting MUST work identically to stream 1116 dependency weighting as described within RFC 7540, section 5.3.2. 1118 o A subscription's dependency MUST work identically to stream 1119 dependency as described within RFC 7540, sections 5.3.1, 5.3.3, 1120 and 5.3.4. If a dependency is attempted via an RPC, but the 1121 referenced subscription does not exist, the dependency will be 1122 removed. 1124 4.3. YANG Notifications 1126 4.3.1. Monitoring and OAM Notifications 1128 OAM notifications and mechanism are reused from [subscribe]. Some 1129 have been augmented to include the YANG datastore specific objects. 1131 4.3.2. New Notifications for update records 1133 The data model introduces two YANG notifications to encode 1134 information for update records: "push-update" and "push-change- 1135 update". 1137 "Push-update" is used to send a complete snapshot of the filtered 1138 subscription data. This type of notification is used to carry the 1139 update records of a periodic subscription. The "push-update" 1140 notification is also used with on-change subscriptions for the 1141 purposes of allowing a receiver to "synch" on a complete set of 1142 subscribed datastore contents. This synching may be done the start 1143 of an on-change subscription, and then later in that subscription to 1144 force resynchronization. If the "updates-not-sent" flag is set, this 1145 indicates that the update record is incomplete. 1147 "Push-change-update" is used to send datastore changes that have 1148 occurred in subscribed data since the previous update. This 1149 notification is used only in conjunction with on-change 1150 subscriptions. This will be encoded as yang-patch data. 1152 If the application detects an informational discontinuity in either 1153 notification, the notification MUST include a flag "updates-not- 1154 sent". This flag which indicates that not all changes which have 1155 occurred since the last update are actually included with this 1156 update. In other words, the publisher has failed to fulfill its full 1157 subscription obligations. (For example a datastore missed a window 1158 in providing objects to a publisher process.) To facilitate 1159 synchronization, a publisher MAY subsequently send a push-update 1160 containing a full snapshot of subscribed data. 1162 4.4. YANG RPCs 1164 YANG-Push subscriptions are established, modified, and deleted using 1165 RPCs augmented from [subscribe]. 1167 4.4.1. Establish-subscription RPC 1169 The subscriber sends an establish-subscription RPC with the 1170 parameters in section 3.1. An example might look like: 1172 1174 1176 1179 500 1180 encode-xml 1181 1182 1184 Figure 11: Establish-subscription RPC 1186 The publisher MUST respond explicitly positively (i.e., subscription 1187 accepted) or negatively (i.e., subscription rejected) to the request. 1188 Positive responses include the subscription-id of the accepted 1189 subscription. In that case a publisher MAY respond: 1191 1193 1195 ok 1196 1197 1199 52 1200 1201 1203 Figure 12: Establish-subscription positive RPC response 1205 A subscription can be rejected for multiple reasons, including the 1206 lack of authorization to establish a subscription, the lack of read 1207 authorization on the requested data node, or the inability of the 1208 publisher to provide a stream with the requested semantics. 1210 When the requester is not authorized to read the requested data node, 1211 the returned information indicates the node is unavailable. For 1212 instance, if the above request was unauthorized to read node "ex:foo" 1213 the publisher may return: 1215 1217 1219 subtree-unavailable 1220 1221 1223 /ex:foo 1224 1225 1227 Figure 13: Establish-subscription access denied response 1229 If a request is rejected because the publisher is not able to serve 1230 it, the publisher SHOULD include in the returned error what 1231 subscription parameters would have been accepted for the request. 1232 However, there are no guarantee that subsequent requests using this 1233 info will in fact be accepted. 1235 For example, for the following request: 1237 1239 1241 running 1242 1245 10 1246 encode-xml 1247 1248 1250 Figure 14: Establish-subscription request example 2 1252 a publisher that cannot serve on-change updates but periodic updates 1253 might return the following: 1255 1257 1259 period-unsupported 1260 1261 100 1262 1264 Figure 15: Establish-subscription error response example 2 1266 4.4.2. Modify-subscription RPC 1268 The subscriber MAY invoke the modify-subscription RPC for a 1269 subscription it previously established. The subscriber will include 1270 newly desired values in the modify-subscription RPC. Parameters not 1271 included MUST remain unmodified. Below is an example where a 1272 subscriber attempts to modify the period of a subscription. 1274 1276 1278 running 1279 1280 1011 1281 1282 250 1283 1284 1286 Figure 16: Modify subscription request 1288 The publisher MUST respond explicitly positively or negatively to the 1289 request. A response to a successful modification might look like: 1291 1293 1295 ok 1296 1297 1299 Figure 17: Modify subscription response 1301 If the subscription modification is rejected, the publisher MUST send 1302 a response like it does for an establish-subscription and maintain 1303 the subscription as it was before the modification request. 1304 Responses MAY include hints. A subscription MAY be modified multiple 1305 times. 1307 A configured subscription cannot be modified using modify- 1308 subscription RPC. Instead, the configuration needs to be edited as 1309 needed. 1311 4.4.3. Delete-subscription RPC 1313 To stop receiving updates from a subscription and effectively delete 1314 a subscription that had previously been established using an 1315 establish-subscription RPC, a subscriber can send a delete- 1316 subscription RPC, which takes as only input the subscription-id. For 1317 example: 1319 1321 1323 1324 1011 1325 1326 1327 1329 1331 1333 ok 1334 1335 1337 Figure 18: Delete subscription 1339 Configured subscriptions cannot be deleted via RPC, but have to be 1340 removed from the configuration. 1342 4.4.4. YANG Module Synchronization 1344 To make subscription requests, the subscriber needs to know the YANG 1345 module library available on the publisher. The YANG 1.0 module 1346 library information is sent by a NETCONF server in the NETCONF 1347 'hello' message. For YANG 1.1 modules and all modules used with the 1348 RESTCONF [RFC8040] protocol, this information is provided by the YANG 1349 Library module (ietf-yang-library.yang from [RFC7895]. The YANG 1350 library information is important for the receiver to reproduce the 1351 set of object definitions used by the replicated datastore. 1353 The YANG library includes a module list with the name, revision, 1354 enabled features, and applied deviations for each YANG module 1355 implemented by the publisher. The receiver is expected to know the 1356 YANG library information before starting a subscription. The 1357 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module 1358 can be used to cache the YANG library information. 1360 The set of modules, revisions, features, and deviations can change at 1361 run-time (if supported by the server implementation). In this case, 1362 the receiver needs to be informed of module changes before data nodes 1363 from changed modules can be processed correctly. The YANG library 1364 provides a simple "yang-library-change" notification that informs the 1365 client that the library has changed. The receiver then needs to re- 1366 read the entire YANG library data for the replicated server in order 1367 to detect the specific YANG library changes. The "ietf-netconf- 1368 notifications" module defined in [RFC6470] contains a "netconf- 1369 capability-change" notification that can identify specific module 1370 changes. For example, the module URI capability of a newly loaded 1371 module will be listed in the "added-capability" leaf-list, and the 1372 module URI capability of an removed module will be listed in the 1373 "deleted-capability" leaf-list. 1375 5. YANG module 1377 ; file "ietf-yang-push@2017-06-26.yang" 1378 module ietf-yang-push { 1379 yang-version 1.1; 1380 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1381 prefix yp; 1383 import ietf-inet-types { 1384 prefix inet; 1385 } 1386 import ietf-yang-types { 1387 prefix yang; 1388 } 1389 import ietf-subscribed-notifications { 1390 prefix sn; 1391 } 1393 organization "IETF"; 1394 contact 1395 "WG Web: 1396 WG List: 1397 WG Chair: Mahesh Jethanandani 1398 1400 WG Chair: Mehmet Ersue 1401 1403 Editor: Alexander Clemm 1404 1406 Editor: Eric Voit 1407 1409 Editor: Alberto Gonzalez Prieto 1410 1412 Editor: Ambika Prasad Tripathy 1413 1415 Editor: Einar Nilsen-Nygaard 1416 1418 Editor: Andy Bierman 1419 1421 Editor: Balazs Lengyel 1422 "; 1424 description 1425 "This module contains conceptual YANG specifications 1426 for YANG push."; 1428 revision 2017-06-26 { 1429 description 1430 "Move to identities for filters, datastores."; 1431 reference 1432 "YANG Datastore Push, draft-ietf-netconf-yang-push-07"; 1433 } 1435 /* 1436 * EXTENSIONS 1437 */ 1439 extension notifiable-on-change { 1440 argument "value"; 1441 description 1442 "Indicates whether changes to the data node are reportable in 1443 on-change subscriptions. 1445 The statement MUST only be a substatement of the leaf, leaf-list, 1446 container, list, anyxml, anydata statements. Zero or One 1447 notifiable-on-change statement is allowed per parent statement. 1448 NO substatements are allowed. 1450 The argument is a boolean value indicating whether on-change 1451 notifications are supported. If notifiable-on-change is not 1452 specified, the default is the same as the parent data node's 1453 value. For top level data nodes the default value is false."; 1454 } 1456 /* 1457 * FEATURES 1458 */ 1460 feature on-change { 1461 description 1462 "This feature indicates that on-change updates are 1463 supported."; 1464 } 1466 /* 1467 * IDENTITIES 1468 */ 1470 /* Error type identities for datastore subscription */ 1471 identity period-unsupported { 1472 base sn:error; 1473 description 1474 "Requested time period is too short. This can be for both 1475 periodic and on-change dampening."; 1476 } 1478 identity qos-unsupported { 1479 base sn:error; 1480 description 1481 "Subscription QoS parameters not supported on this platform."; 1482 } 1484 identity dscp-unavailable { 1485 base sn:error; 1486 description 1487 "Requested DSCP marking not allocatable."; 1488 } 1490 identity on-change-unsupported { 1491 base sn:error; 1492 description 1493 "On-change not supported."; 1494 } 1496 identity synch-on-start-unsupported { 1497 base sn:error; 1498 description 1499 "On-change synch-on-start not supported."; 1500 } 1502 identity synch-on-start-datatree-size { 1503 base sn:error; 1504 description 1505 "Synch-on-start would push a datatree which exceeds size limit."; 1506 } 1508 identity reference-mismatch { 1509 base sn:error; 1510 description 1511 "Mismatch in filter key and referenced yang subtree."; 1512 } 1514 identity data-unavailable { 1515 base sn:error; 1516 description 1517 "Referenced yang node or subtree doesn't exist, or read 1518 access is not permitted."; 1519 } 1521 identity datatree-size { 1522 base sn:error; 1523 description 1524 "Resulting push updates would exceed size limit."; 1525 } 1527 /* Datastore identities */ 1528 identity datastore { 1529 description 1530 "A datastore."; 1531 } 1532 identity candidate { 1533 base datastore; 1534 description 1535 "The candidate datastore per RFC-6241."; 1536 reference "RFC-6241, #5.1"; 1537 } 1538 identity running { 1539 base datastore; 1540 description 1541 "The running datastore per RFC-6241."; 1542 reference "RFC-6241, #5.1"; 1543 } 1544 identity startup { 1545 base datastore; 1546 description 1547 "The startup datastore per RFC-6241."; 1548 reference "RFC-6241, #5.1"; 1549 } 1550 identity operational { 1551 base datastore; 1552 description 1553 "The operational datastore contains all configuration data 1554 actually used by the system, including all applied configuration, 1555 system-provided configuration and values defined by any supported 1556 data models. In addition, the operational datastore also 1557 contains state data."; 1558 reference 1559 "the original text came from draft-ietf-netmod-revised-datastores 1560 -01, section #4.3. This definition is expected to remain stable 1561 meaning later reconciliation between the drafts unnecessary."; 1562 } 1564 /* New filter identities (adds to 'sn') */ 1565 identity subtree { 1566 base sn:filter; 1567 description 1568 "A filter which follows the subtree filter syntax specified 1569 in RFC 6241."; 1570 reference "RFC 6241 section 6"; 1571 } 1573 /* 1574 * TYPE DEFINITIONS 1575 */ 1577 typedef change-type { 1578 type enumeration { 1579 enum "create" { 1580 description 1581 "Create a new data resource if it does not already exist. If 1582 it already exists, replace."; 1583 } 1584 enum "delete" { 1585 description 1586 "Delete a data resource if it already exists. If it does not 1587 exists, take no action."; 1588 } 1589 enum "insert" { 1590 description 1591 "Insert a new user-ordered data resource"; 1592 } 1593 enum "merge" { 1594 description 1595 "merge the edit value with the target data resource; create 1596 if it does not already exist"; 1597 } 1598 enum "move" { 1599 description 1600 "Reorder the target data resource"; 1601 } 1602 enum "replace" { 1603 description 1604 "Replace the target data resource with the edit value"; 1605 } 1606 enum "remove" { 1607 description 1608 "Remove a data resource if it already exists "; 1609 } 1610 } 1611 description 1612 "Specifies different types of datastore changes."; 1613 reference 1614 "RFC 8072 section 2.5, with a delta that it is ok to receive 1615 ability create on an existing node, or recieve a delete on a 1616 missing node."; 1617 } 1619 typedef datastore { 1620 type identityref { 1621 base datastore; 1622 } 1623 description 1624 "Specifies a system-provided datastore. May also specify ability 1625 portion of a datastore, so as to reduce the filtering effort."; 1626 } 1628 /* 1629 * GROUP DEFINITIONS 1630 */ 1632 grouping datastore-criteria { 1633 description 1634 "A reusable place to define the meaning of datastore."; 1635 leaf datastore { 1636 type datastore; 1637 mandatory true; 1638 description 1639 "Datastore against which the subscription has been applied."; 1640 } 1641 } 1643 grouping update-policy-modifiable { 1644 description 1645 "This grouping describes the datastore specific subscription 1646 conditions that can be changed during the lifetime of the 1647 subscription."; 1648 choice update-trigger { 1649 description 1650 "Defines necessary conditions for sending an event to 1651 the subscriber."; 1652 case periodic { 1653 description 1654 "The agent is requested to notify periodically the current 1655 values of the datastore as defined by the filter."; 1656 leaf period { 1657 type yang:timeticks; 1658 mandatory true; 1659 description 1660 "Duration of time which should occur between periodic 1661 push updates. Where the anchor of a start-time is 1662 available, the push will include the objects and their 1663 values which exist at an exact multiple of timeticks 1664 aligning to this start-time anchor."; 1665 } 1666 leaf anchor-time { 1667 type yang:date-and-time; 1668 description 1669 "Designates a timestamp from which the series of periodic 1670 push updates are computed. The next update will take place 1671 at the next period interval from the anchor time. For 1672 example, for an anchor time at the top of a minute and a 1673 period interval of a minute, the next update will be sent 1674 at the top of the next minute."; 1675 } 1676 } 1677 case on-change { 1678 if-feature "on-change"; 1679 description 1680 "The agent is requested to notify changes in values in the 1681 datastore subset as defined by a filter."; 1682 leaf dampening-period { 1683 type yang:timeticks; 1684 mandatory true; 1685 description 1686 "The shortest time duration which is allowed between the 1687 creation of independent yang object update messages. 1688 Effectively this is the amount of time that needs to have 1689 passed since the last update."; 1690 } 1691 } 1692 } 1693 } 1695 grouping update-policy { 1696 description 1697 "This grouping describes the datastore specific subscription 1698 conditions of a subscription."; 1699 uses update-policy-modifiable { 1700 augment "update-trigger/on-change" { 1701 description 1702 "Includes objects not modifiable once subscription is 1703 established."; 1704 leaf no-synch-on-start { 1705 type empty; 1706 description 1707 "This leaf acts as a flag that determines behavior at the 1708 start of the subscription. When present, synchronization 1709 of state at the beginning of the subscription is outside 1710 the scope of the subscription. Only updates about changes 1711 that are observed from the start time, i.e. only push- 1712 change-update notifications are sent. When absent (default 1713 behavior), in order to facilitate a receiver's 1714 synchronization, a full update is sent when the 1715 subscription starts using a push-update notification, just 1716 like in the case of a periodic subscription. After that, 1717 push-change-update notifications only are sent unless the 1718 Publisher chooses to resynch the subscription again."; 1719 } 1720 leaf-list excluded-change { 1721 type change-type; 1722 description 1723 "Use to restrict which changes trigger an update. 1724 For example, if modify is excluded, only creation and 1725 deletion of objects is reported."; 1726 } 1727 } 1728 } 1729 } 1731 grouping update-qos { 1732 description 1733 "This grouping describes Quality of Service information 1734 concerning a subscription. This information is passed to lower 1735 layers for transport prioritization and treatment"; 1736 leaf dscp { 1737 type inet:dscp; 1738 default "0"; 1739 description 1740 "The push update's IP packet transport priority. This is made 1741 visible across network hops to receiver. The transport 1742 priority is shared for all receivers of a given subscription."; 1743 } 1744 leaf weighting { 1745 type uint8 { 1746 range "0 .. 255"; 1747 } 1748 description 1749 "Relative weighting for a subscription. Allows an underlying 1750 transport layer perform informed load balance allocations 1751 between various subscriptions"; 1752 reference 1753 "RFC-7540, section 5.3.2"; 1754 } 1755 leaf dependency { 1756 type sn:subscription-id; 1757 description 1758 "Provides the Subscription ID of a parent subscription which 1759 has absolute priority should that parent have push updates 1760 ready to egress the publisher. In other words, there should be 1761 no streaming of objects from the current subscription if of 1762 the parent has something ready to push."; 1763 reference 1764 "RFC-7540, section 5.3.1"; 1765 } 1766 } 1768 grouping update-error-hints { 1769 description 1770 "Allow return additional negotiation hints that apply 1771 specifically to push updates."; 1772 leaf period-hint { 1773 type yang:timeticks; 1774 description 1775 "Returned when the requested time period is too short. This 1776 hint can assert an viable period for both periodic push 1777 cadence and on-change dampening."; 1778 } 1779 leaf error-path { 1780 type string; 1781 description 1782 "Reference to a YANG path which is associated with the error 1783 being returned."; 1784 } 1785 leaf object-count-estimate { 1786 type uint32; 1787 description 1788 "If there are too many objects which could potentially be 1789 returned by the filter, this identifies the estimate of the 1790 number of objects which the filter would potentially pass."; 1791 } 1792 leaf object-count-limit { 1793 type uint32; 1794 description 1795 "If there are too many objects which could be returned by the 1796 filter, this identifies the upper limit of the publisher's 1797 ability to service for this subscription."; 1798 } 1799 leaf kilobytes-estimate { 1800 type uint32; 1801 description 1802 "If the returned information could be beyond the capacity of 1803 the publisher, this would identify the data size which could 1804 result from this filter."; 1805 } 1806 leaf kilobytes-limit { 1807 type uint32; 1808 description 1809 "If the returned information would be beyond the capacity of 1810 the publisher, this identifies the upper limit of the 1811 publisher's ability to service for this subscription."; 1812 } 1813 } 1815 /* 1816 * DATA NODES 1817 */ 1819 augment "/sn:establish-subscription/sn:input" { 1820 description 1821 "This augmentation adds additional subscription parameters that 1822 apply specifically to datastore updates to RPC input."; 1823 uses update-policy; 1824 uses update-qos; 1825 } 1826 augment "/sn:establish-subscription/sn:input/sn:target" { 1827 description 1828 "This augmentation adds the datastore as a valid parameter object 1829 for the subscription to RPC input. This provides a target for 1830 the filter."; 1831 case datastore { 1832 uses datastore-criteria; 1833 } 1834 } 1835 augment "/sn:establish-subscription/sn:output/"+ 1836 "sn:result/sn:no-success" { 1837 description 1838 "This augmentation adds datastore specific error info 1839 and hints to RPC output."; 1840 uses update-error-hints; 1841 } 1842 augment "/sn:modify-subscription/sn:input" { 1843 description 1844 "This augmentation adds additional subscription parameters 1845 specific to datastore updates."; 1846 uses update-policy-modifiable; 1847 } 1848 augment "/sn:modify-subscription/sn:output/"+ 1849 "sn:result/sn:no-success" { 1850 description 1851 "This augmentation adds push datastore error info and hints to 1852 RPC output."; 1853 uses update-error-hints; 1854 } 1856 notification push-update { 1857 description 1858 "This notification contains a push update, containing data 1859 subscribed to via a subscription. This notification is sent for 1860 periodic updates, for a periodic subscription. It can also be 1861 used for synchronization updates of an on-change subscription. 1862 This notification shall only be sent to receivers of a 1863 subscription; it does not constitute a general-purpose 1864 notification."; 1865 leaf subscription-id { 1866 type sn:subscription-id; 1867 mandatory true; 1868 description 1869 "This references the subscription because of which the 1870 notification is sent."; 1871 } 1872 leaf time-of-update { 1873 type yang:date-and-time; 1874 description 1875 "This leaf contains the time of the update."; 1876 } 1877 leaf updates-not-sent { 1878 type empty; 1879 description 1880 "This is a flag which indicates that not all data nodes 1881 subscribed to are included with this update. In other words, 1882 the publisher has failed to fulfill its full subscription 1883 obligations. This may lead to intermittent loss of 1884 synchronization of data at the client. Synchronization at the 1885 client can occur when the next push-update is received."; 1886 } 1887 anydata datastore-contents { 1888 description 1889 "This contains the updated data. It constitutes a snapshot 1890 at the time-of-update of the set of data that has been 1891 subscribed to. The format and syntax of the data 1892 corresponds to the format and syntax of data that would be 1893 returned in a corresponding get operation with the same 1894 filter parameters applied."; 1895 } 1896 } 1897 notification push-change-update { 1898 if-feature "on-change"; 1899 description 1900 "This notification contains an on-change push update. This 1901 notification shall only be sent to the receivers of a 1902 subscription; it does not constitute a general-purpose 1903 notification."; 1904 leaf subscription-id { 1905 type sn:subscription-id; 1906 mandatory true; 1907 description 1908 "This references the subscription because of which the 1909 notification is sent."; 1910 } 1911 leaf time-of-update { 1912 type yang:date-and-time; 1913 description 1914 "This leaf contains the time of the update, i.e. the time at 1915 which the change was observed."; 1916 } 1917 leaf updates-not-sent { 1918 type empty; 1919 description 1920 "This is a flag which indicates that not all changes which 1921 have occurred since the last update are included with this 1922 update. In other words, the publisher has failed to 1923 fulfill its full subscription obligations, for example in 1924 cases where it was not able to keep up with a change burst. 1926 To facilitate synchronization, a publisher may subsequently 1927 send a push-update containing a full snapshot of subscribed 1928 data. Such a push-update might also be triggered by a 1929 subscriber requesting an on-demand synchronization."; 1930 } 1931 anydata datastore-changes { 1932 description 1933 "This contains datastore contents that has changed since the 1934 previous update, per the terms of the subscription. Changes 1935 are encoded analogous to the syntax of a corresponding yang- 1936 patch operation, i.e. a yang-patch operation applied to the 1937 YANG datastore implied by the previous update to result in the 1938 current state (and assuming yang-patch could also be applied 1939 to operational data)."; 1940 } 1941 } 1943 augment "/sn:subscription-started" { 1944 description 1945 "This augmentation adds many yang datastore specific objects to 1946 the notification that a subscription has started."; 1947 uses update-policy; 1948 uses update-qos; 1949 } 1950 augment "/sn:subscription-started/sn:target" { 1951 description 1952 "This augmentation allows the datastore to be included as part 1953 of the notification that a subscription has started."; 1954 case datastore { 1955 uses datastore-criteria; 1956 } 1957 } 1958 augment "/sn:subscription-modified" { 1959 description 1960 "This augmentation adds many yang datastore specific objects to 1961 the notification that a subscription has been modified."; 1962 uses update-policy; 1963 uses update-qos; 1964 } 1966 augment "/sn:subscription-config/sn:subscription" { 1967 description 1968 "This augmentation adds many yang datastore specific objects 1969 which can be configured as opposed to established via RPC."; 1970 uses update-policy; 1971 uses update-qos; 1972 } 1973 augment "/sn:subscription-config/sn:subscription/sn:target" { 1974 description 1975 "This augmentation adds the datastore to the filtering 1976 criteria for a subscription."; 1977 case datastore { 1978 uses datastore-criteria; 1979 } 1980 } 1981 augment "/sn:subscriptions/sn:subscription" { 1982 yp:notifiable-on-change true; 1983 description 1984 "This augmentation adds many datastore specific objects to a 1985 subscription."; 1986 uses update-policy; 1987 uses update-qos; 1988 } 1989 augment "/sn:subscriptions/sn:subscription/sn:target" { 1990 description 1991 "This augmentation allows the datastore to be displayed as part 1992 of the filtering criteria for a subscription."; 1993 case datastore { 1994 uses datastore-criteria; 1995 } 1996 } 1997 /* YANG Parser Pyang crashing below, due to fixed bug 1998 https://github.com/mbj4668/pyang/issues/300 2000 deviation "/sn:subscriptions/sn:subscription/sn:receivers/" 2001 + "sn:receiver/sn:pushed-notifications" { 2002 deviate add { 2003 yp:notifiable-on-change false; 2004 } 2005 } 2006 deviation "/sn:subscriptions/sn:subscription/sn:receivers/" 2007 + "sn:receiver/sn:excluded-notifications" { 2008 deviate add { 2009 yp:notifiable-on-change false; 2010 } 2011 } 2012 YANG Parser Pyang crashing on the following syntax above */ 2013 } 2014 2016 6. IANA Considerations 2018 This document registers the following namespace URI in the "IETF XML 2019 Registry" [RFC3688]: 2021 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push 2022 Registrant Contact: The IESG. 2023 XML: N/A; the requested URI is an XML namespace. 2025 This document registers the following YANG module in the "YANG Module 2026 Names" registry [RFC6020]: 2028 Name: ietf-yang-push 2029 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push 2030 Prefix: yp 2031 Reference: draft-ietf-netconf-yang-push-07.txt (RFC form) 2033 7. Security Considerations 2035 All security considerations from [subscribe] are relevant for 2036 datastores. In addition there are specific security considerations 2037 for receviers defined in Section 3.9 2039 If the access control permissions on subscribed YANG nodes change 2040 during the lifecycle of a subscription, a publisher MUST either 2041 transparently conform to the new access control permissions, or must 2042 terminate or restart the subscriptions so that new access control 2043 permissions are re-established. 2045 The NETCONF Authorization Control Model SHOULD be used to restrict 2046 the delivery of YANG nodes for which the receiver has no access. 2048 8. Acknowledgments 2050 For their valuable comments, discussions, and feedback, we wish to 2051 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei 2052 Guo, Michael Scharf, Sharon Chisholm, and Guangying Zheng. 2054 9. References 2056 9.1. Normative References 2058 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2059 DOI 10.17487/RFC3688, January 2004, 2060 . 2062 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2063 the Network Configuration Protocol (NETCONF)", RFC 6020, 2064 DOI 10.17487/RFC6020, October 2010, 2065 . 2067 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2068 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 2069 February 2012, . 2071 [RFC6536bis] 2072 Bierman, A. and M. Bjorklund, "Network Configuration 2073 Protocol (NETCONF) Access Control Model", draft-ietf- 2074 netconf-rfc6536bis-01 (work in progress), March 2017. 2076 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 2077 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 2078 . 2080 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2081 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2082 . 2084 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2085 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2086 . 2088 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2089 Media Type", RFC 8072, DOI 10.17487/RFC8072, February 2090 2017, . 2092 [subscribe] 2093 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 2094 and E. Nilsen-Nygaard, "Custom Subscription to Event 2095 Notifications", draft-ietf-netconf-subscribed- 2096 notifications-01 (work in progress), April 2017. 2098 9.2. Informative References 2100 [http-notif] 2101 Voit, E., Gonzalez Prieto, A., Tripathy, A., Nilsen- 2102 Nygaard, E., Clemm, A., and A. Bierman, "Restconf and HTTP 2103 Transport for Event Notifications", March 2017. 2105 [netconf-notif] 2106 Gonzalez Prieto, A., Clemm, A., Voit, E., Tripathy, A., 2107 Nilsen-Nygaard, E., Chisholm, S., and H. Trevino, "NETCONF 2108 Support for Event Notifications", October 2016. 2110 [notifications2] 2111 Voit, E., Bierman, A., Clemm, A., and T. Jenkins, "YANG 2112 Notification Headers and Bundles", April 2017. 2114 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2115 and A. Bierman, Ed., "Network Configuration Protocol 2116 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2117 . 2119 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2120 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 2121 . 2123 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2124 for Subscription to YANG Datastores", RFC 7923, 2125 DOI 10.17487/RFC7923, June 2016, 2126 . 2128 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2129 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2130 . 2132 Appendix A. Relationships to other drafts 2134 There are other related drafts which are progressing in the NETCONF 2135 WG. This section details the relationship of this draft to those 2136 others. 2138 A.1. ietf-netconf-subscribed-notifications 2140 The draft [subscribe] is the techical foundation around which the 2141 rest of the YANG push datastore specific mechanisms are layered. 2143 A.2. ietf-netconf-netconf-event-notif 2145 The [netconf-notif] draft supports yang-push by defining NETCONF 2146 transport specifics. Included are: 2148 o bindings for RPC communications and Event Notifications over 2149 NETCONF. 2151 o encoded examples 2153 A.3. ietf-netconf-restconf-notif 2155 The [http-notif] draft supports yang-push by defining transport 2156 specific guidance where some form of HTTP is used underneath. 2157 Included are: 2159 o bindings for RPC communications over RESTCONF 2161 o bindings for Event Notifications over HTTP2 and HTTP1.1 2162 o encoded examples 2164 o end-to-end deployment guidance for Call Home and TLS Heartbeat 2166 A.4. voit-notifications2 2168 The draft [notifications2] is not required to implement yang-push. 2169 Instead it defines data plane notification elements which improve the 2170 delivered experience. The following capabilities are specified: 2172 o Defines common encapsulation headers objects to support 2173 functionality such as event severity, message signing, message 2174 loss discovery, message de-duplication, originating process 2175 identification. 2177 o Defines how to bundle multiple event records into a single 2178 notification message. 2180 These capabilities would be delivered by adding the drafts newly 2181 proposed header objects to the push-update and push-change-update 2182 notifications defined here. This draft is not yet adopted by the 2183 NETCONF WG. 2185 Appendix B. Technologies to be considered for future iterations 2187 B.1. Proxy YANG Subscription when the Subscriber and Receiver are 2188 different 2190 The properties of Dynamic and Configured Subscriptions can be 2191 combined to enable deployment models where the Subscriber and 2192 Receiver are different. Such separation can be useful with some 2193 combination of: 2195 o An operator does not want the subscription to be dependent on the 2196 maintenance of transport level keep-alives. (Transport 2197 independence provides different scalability characteristics.) 2199 o There is not a transport session binding, and a transient 2200 Subscription needs to survive in an environment where there is 2201 unreliable connectivity with the Receiver and/or Subscriber. 2203 o An operator wants the Publisher to include highly restrictive 2204 capacity management and Subscription security mechanisms outside 2205 of domain of existing operational or programmatic interfaces. 2207 To build a Proxy Subscription, first the necessary information must 2208 be signaled as part of the . Using this set 2209 of Subscriber provided information; the same process described within 2210 section 3 will be followed. 2212 After a successful establishment, if the Subscriber wishes to track 2213 the state of Receiver subscriptions, it may choose to place a 2214 separate on-change Subscription into the "Subscriptions" subtree of 2215 the YANG Datastore on the Publisher. 2217 B.2. OpState and Filters 2219 Currently there are ongoing discussions to revise the concept of 2220 datastores, allowing for proper handling and distinction of intended 2221 versus applied configurations and extending the notion of a datastore 2222 to operational data. When finalized, the new concept may open up the 2223 possibility for new types of subscription filters, for example, 2224 targeting specific datastores and targeting (potentially) differences 2225 in datatrees across different datastores. 2227 Likewise, it is conceivable that filters are defined that apply to 2228 metadata, such as data nodes for which metadata has been defined that 2229 meets a certain criteria. 2231 Defining any such subscription filters at this point would be highly 2232 speculative in nature. However, it should be noted that 2233 corresponding extensions may be defined in future specifications. 2234 Any such extensions will be straightforward to accommodate by 2235 introducing a model that defines new filter types, and augmenting the 2236 new filter type into the subscription model. 2238 B.3. Splitting push updates 2240 Push updates may become fairly large and extend across multiple 2241 subsystems in a YANG-Push Server. As a result, it conceivable to not 2242 combine all updates into a single update message, but to split 2243 updates into multiple separate update messages. Such splitting could 2244 occur along multiple criteria: limiting the number of data nodes 2245 contained in a single update, grouping updates by subtree, grouping 2246 updates by internal subsystems (e.g., by line card), or grouping them 2247 by other criteria. 2249 Splitting updates bears some resemblance to fragmenting packets. In 2250 effect, it can be seen as fragmenting update messages at an 2251 application level. However, from a transport perspective, splitting 2252 of update messages is not required as long as the transport does not 2253 impose a size limitation or provides its own fragmentation mechanism 2254 if needed. We assume this to be the case for YANG-Push. In the case 2255 of NETCONF, RESTCONF, HTTP/2, no limit on message size is imposed. 2257 In case of other transports, any message size limitations need to be 2258 handled by the corresponding transport mapping. 2260 There may be some scenarios in which splitting updates might still 2261 make sense. For example, if updates are collected from multiple 2262 independent subsystems, those updates could be sent separately 2263 without need for combining. However, if updates were to be split, 2264 other issues arise. Examples include indicating the number of 2265 updates to the receiver, distinguishing a missed fragment from a 2266 missed update, and the ordering with which updates are received. 2267 Proper addressing those issues would result in considerable 2268 complexity, while resulting in only very limited gains. In addition, 2269 if a subscription is found to result in updates that are too large, a 2270 publisher can always reject the request for a subscription while the 2271 subscriber is always free to break a subscription up into multiple 2272 subscriptions. 2274 B.4. Potential Subscription Parameters 2276 A possible is the introduction of an additional parameter "changes- 2277 only" for periodic subscription. Including this flag would results 2278 in sending at the end of each period an update containing only 2279 changes since the last update (i.e. a change-update as in the case of 2280 an on-change subscription), not a full snapshot of the subscribed 2281 information. Such an option might be interesting in case of data 2282 that is largely static and bandwidth-constrained environments. 2284 Appendix C. Issues that are currently being worked and resolved 2286 (To be removed by RFC editor prior to publication) 2288 Issue #6: Data plane notifications and layered headers. Specifically 2289 how do we want to enable standard header unification and bundle 2290 support vs. the data plane notifications currently defined. 2292 Appendix D. Changes between revisions 2294 (To be removed by RFC editor prior to publication) 2296 v06 - v07 2298 o Clarifying text tweaks. 2300 o Clarification that filters act as selectors for subscribed data 2301 nodes; support for value filters not included but possible as a 2302 future extension 2304 o Filters don't have to be matched to existing YANG objects 2305 v05 - v06 2307 o Security considerations updated. 2309 o Base YANG model in [sn] updated as part of move to identities, 2310 YANG augmentations in this doc matched up 2312 o Terms refined and text updates throughout 2314 o Appendix talking about relationship to other drafts added. 2316 o Datastore replaces stream 2318 o Definitions of filters improved 2320 v04 to v05 2322 o Referenced based subscription document changed to Subscribed 2323 Notifications from 5277bis. 2325 o Getting operational data from filters 2327 o Extension notifiable-on-change added 2329 o New appendix on potential futures. Moved text into there from 2330 several drafts. 2332 o Subscription configuration section now just includes changed 2333 parameters from Subscribed Notifications 2335 o Subscription monitoring moved into Subscribed Notifications 2337 o New error and hint mechanisms included in text and in the yang 2338 model. 2340 o Updated examples based on the error definitions 2342 o Groupings updated for consistency 2344 o Text updates throughout 2346 v03 to v04 2348 o Updates-not-sent flag added 2350 o Not notifiable extension added 2352 o Dampening period is for whole subscription, not single objects 2353 o Moved start/stop into rfc5277bis 2355 o Client and Server changed to subscriber, publisher, and receiver 2357 o Anchor time for periodic 2359 o Message format for synchronization (i.e. synch-on-start) 2361 o Material moved into 5277bis 2363 o QoS parameters supported, by not allowed to be modified by RPC 2365 o Text updates throughout 2367 Authors' Addresses 2369 Alexander Clemm 2370 Huawei 2372 Email: ludwig@clemm.org 2374 Eric Voit 2375 Cisco Systems 2377 Email: evoit@cisco.com 2379 Alberto Gonzalez Prieto 2381 Email: albert.gonzalezprieto@yahoo.com 2383 Ambika Prasad Tripathy 2384 Cisco Systems 2386 Email: ambtripa@cisco.com 2388 Einar Nilsen-Nygaard 2389 Cisco Systems 2391 Email: einarnn@cisco.com 2392 Andy Bierman 2393 YumaWorks 2395 Email: andy@yumaworks.com 2397 Balazs Lengyel 2398 Ericsson 2400 Email: balazs.lengyel@ericsson.com