idnits 2.17.1 draft-ietf-netconf-yang-push-08.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 8 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 253: '...cription request SHOULD be declined ba...' RFC 2119 keyword, line 262: '... subscriptions SHOULD support a simp...' RFC 2119 keyword, line 265: '...-success message SHOULD include in the...' RFC 2119 keyword, line 292: '... MAY accept an on-change subscriptio...' RFC 2119 keyword, line 303: '...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 814 has weird spacing: '...er-type eve...' == Line 825 has weird spacing: '...er-type sel...' == Line 871 has weird spacing: '...er-type sel...' == Line 919 has weird spacing: '...er-type sel...' == Line 972 has weird spacing: '...-period yan...' == (9 more instances...) -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Update 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 (August 20, 2017) is 2433 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 2223, but no explicit reference was found in the text == Outdated reference: A later version (-09) exists of draft-ietf-netconf-rfc6536bis-04 -- 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: February 21, 2018 Cisco Systems 6 A. Gonzalez Prieto 7 VMware 8 A. Tripathy 9 E. Nilsen-Nygaard 10 Cisco Systems 11 A. Bierman 12 YumaWorks 13 B. Lengyel 14 Ericsson 15 August 20, 2017 17 Subscribing to YANG datastore push updates 18 draft-ietf-netconf-yang-push-08 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 February 21, 2018. 45 Copyright Notice 47 Copyright (c) 2017 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (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 . . . . . . . . . . . . . . . 24 92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 25 93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 26 94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 31 95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 46 97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47 98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 99 9.1. Normative References . . . . . . . . . . . . . . . . . . 47 100 9.2. Informative References . . . . . . . . . . . . . . . . . 48 101 Appendix A. Relationships to other drafts . . . . . . . . . . . 48 102 A.1. ietf-netconf-subscribed-notifications . . . . . . . . . . 49 103 A.2. ietf-netconf-netconf-event-notif . . . . . . . . . . . . 49 104 A.3. ietf-netconf-restconf-notif . . . . . . . . . . . . . . . 49 105 A.4. voit-notifications2 . . . . . . . . . . . . . . . . . . . 49 106 Appendix B. Technologies to be considered for future iterations 50 107 B.1. Proxy YANG Subscription when the Subscriber and Receiver 108 are different . . . . . . . . . . . . . . . . . . . . . . 50 109 B.2. OpState and Filters . . . . . . . . . . . . . . . . . . . 50 110 B.3. Splitting push updates . . . . . . . . . . . . . . . . . 51 111 B.4. Potential Subscription Parameters . . . . . . . . . . . . 52 112 Appendix C. Changes between revisions . . . . . . . . . . . . . 52 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54 115 1. Introduction 117 Traditional approaches to remote visibility have been built on 118 polling. With polling, data is periodically requested and retrieved 119 by a client from a server to stay up-to-date. However, there are 120 issues associated with polling-based management: 122 o Polling incurs significant latency. This latency prohibits many 123 application types. 125 o Polling cycles may be missed, requests may be delayed or get lost, 126 often when the network is under stress and the need for the data 127 is the greatest. 129 o Polling requests may undergo slight fluctuations, resulting in 130 intervals of different lengths. The resulting data is difficult 131 to calibrate and compare. 133 o For applications that monitor for changes, many remote polling 134 cycles place ultimately fruitless load on the network, devices, 135 and applications. 137 A more effective alternative to polling is for an application to 138 receive automatic and continuous updates from a targeted subset of a 139 datastore. Accordingly, there is a need for a service that allows 140 applications to subscribe to updates from a YANG datastore and that 141 enables the publisher to push and in effect stream those updates. 142 The requirements for such a service have been documented in 143 [RFC7923]. 145 This document defines a corresponding solution that is built on top 146 of "Custom Subscription to Event Notifications" [subscribe]. 147 Supplementing that work are YANG data model augmentations, extended 148 RPCs, and new datastore specific update notifications. Transport 149 options for [subscribe] will work seamlessly with this solution. 151 2. Definitions and Acronyms 153 The terms below supplement those defined in [subscribe]. 155 Data node: An instance of management information in a YANG datastore. 157 Data node update: A data item containing the current value/property 158 of a Data node at the time the data node update was created. 160 Datastore: A conceptual store of instantiated management information, 161 with individual data items represented by data nodes which are 162 arranged in hierarchical manner. 164 Data subtree: An instantiated data node and the data nodes that are 165 hierarchically contained within it. 167 Notification message: A transport encapsulated update record(s) and/ 168 or event notification(s) intended to be sent to a receiver. 170 Update notification message: A notification message that contains an 171 update record. 173 Update record: A representation data node update(s) resulting from 174 the application of a filter for a subscription. An update record 175 will include the value/property of one or more data nodes at a point 176 in time. It may contain the update type for each data node (e.g., 177 add, change, delete). Also included may be metadata/headers such as 178 a subscription-id. 180 Update trigger: A mechanism that determines when an update record 181 needs to be generated. 183 YANG-Push: The subscription and push mechanism for YANG datastores 184 that is specified in this document. 186 3. Solution Overview 188 This document specifies a solution for a push update subscription 189 service. This solution supports the dynamic as well as configured 190 subscriptions to information updates from YANG datastores. 191 Subscriptions specify when update notification messages should be 192 sent and what data to include in update records. YANG objects are 193 subsequently pushed from the publisher to the receiver per the terms 194 of the subscription. 196 3.1. Event Subscription Model 198 YANG-push subscriptions are defined using a data model that is itself 199 defined in YANG. This model enhances the event subscription model 200 defined in [subscribe] with capabilities that allow subscribers to 201 subscribe to data node updates, specifically to specify the triggers 202 when to generate update records as well as what to include in an 203 update record. Key enhancements include: 205 o Specification of selection filters which identify targeted YANG 206 data nodes and/or subtrees within a datastore for which updates 207 are to be pushed. 209 o An encoding (using anydata) for the contents of periodic and on- 210 change push updates. 212 o Specification of update policies that specify the conditions that 213 trigger the generation and pushing of new update records. There 214 are two types of subscriptions, periodic and on-change. 216 * For periodic subscriptions, the trigger is specified by two 217 parameters that define when updates are to be pushed. These 218 parameters are the period interval with which to report 219 updates, and an anchor time which can be used to calculate at 220 which point in time updates need to be assembled and sent. 222 * For on-change subscriptions, a trigger occurs whenever a change 223 in the subscribed information is detected. Included are 224 additional parameters such as: 226 + Dampening period: In an on-change subscription, the first 227 change that is detected results in an update to be sent 228 immediately. However, sending successive updates whenever 229 further changes are detected might result in quick 230 exhaustion of resources in case of very rapid changes. In 231 order to protect against that, a dampening period is used to 232 specify the interval which must pass before successive 233 update records for the same subscription are generated. The 234 dampening period collectively applies to the set of all data 235 nodes of a single subscription. This means that on change 236 of an object being subscribed to, an update record 237 containing that object is created either immediately when no 238 dampening period is already in effect, or at the end of a 239 dampening period. 241 + Change type: This parameter can be used to reduce the types 242 of datastore changes for which updates are sent (e.g., you 243 might only send when an object is created or deleted, but 244 not when an object value changes). 246 + No Synch on start: defines whether or not a complete push- 247 update of all subscribed data will be sent at the beginning 248 of a subscription. Such synchronization establishes the 249 frame of reference for subsequent updates. 251 3.2. Negotiation of Subscription Policies 253 A dynamic subscription request SHOULD be declined based on 254 publisher's assessment that it may be unable to provide update 255 records that would meet the terms of the request. However a 256 subscriber may quickly follow up with a new subscription request 257 using different parameters. 259 Random guessing at different parameters by a subscriber is to be 260 discouraged. Therefore, in order to minimize the number of 261 subscription iterations between subscriber and publisher, dynamic 262 subscriptions SHOULD support a simple negotiation between subscribers 263 and publishers for subscription parameters. This negotiation is in 264 the form of a no-success response to a failed establish or modify 265 subscription request. The no-success message SHOULD include in the 266 returned error response information that, when considered, increases 267 the likelihood of success for subsequent requests. However, there 268 are no guarantees that subsequent requests for this subscriber will 269 in fact be accepted. 271 Such negotiation information returned from a publisher beyond that 272 from [subscribe] includes hints at acceptable time intervals, size 273 estimates for the number or objects which would be returned from a 274 filter, and the names of targeted objects not found in the 275 publisher's YANG tree. 277 3.3. On-Change Considerations 279 On-change subscriptions allow subscribers to subscribe to updates 280 whenever changes to objects occur. As such, on-change subscriptions 281 are particularly effective for data that changes infrequently, yet 282 that requires applications to be notified whenever a change does 283 occur with minimal delay. 285 On-change subscriptions tend to be more difficult to implement than 286 periodic subscriptions. Accordingly, on-change subscriptions may not 287 be supported by all implementations or for every object. 289 Whether or not to accept or reject on-change subscription requests 290 when the scope of the subscription contains objects for which on- 291 change is not supported is up to the server implementation: A server 292 MAY accept an on-change subscription even when the scope of the 293 subscription contains objects for which on-change is not supported. 294 In that case, updates are sent only for those objects within the 295 scope that do support on-change updates whereas other objects are 296 excluded from update records, whether or not their values actually 297 change. In order for a client to determine whether objects support 298 on-change subcriptions, objects are marked accordingly by a server. 299 Accordingly, when subscribing, it is the responsibility of the client 300 to ensure it is aware of which objects support on-change and which do 301 not. For more on how objects are so marked, see Section 3.10. 303 Alternatively, a server MAY decide to simply reject an on-change 304 subscription in case the scope of the subscription contains objects 305 for which on-change is not supported. In case of a configured 306 subscription, the subsription can be marked as suspended respectively 307 inoperational. 309 To avoid flooding receivers with repeated updates for subscriptions 310 containing fast-changing objects, or objects with oscillating values, 311 an on-change subscription allows for the definition of a dampening 312 period. Once an update record for a given object is generated, no 313 other updates for this particular subscription will be created until 314 the end of the dampening period. Values sent at the end of the 315 dampening period are the current values of all changed objects which 316 are current at the time the dampening period expires. Changed 317 objects includes those which were deleted or newly created during 318 that dampening period. If an object has returned to its original 319 value (or even has been created and then deleted) during the 320 dampening-period, the last change will still be sent. This will 321 indicate churn is occuring on that object. 323 In cases where a client wants to have separate dampening periods for 324 different objects, multiple subscriptions with different objects in 325 subscription scope can be created. 327 On-change subscriptions can be refined to let users subscribe only to 328 certain types of changes, for example, only to object creations and 329 deletions, but not to modifications of object values. 331 3.4. Promise-Theory Considerations 333 A subscription to updates from a YANG datastore is intended to 334 obviate the need for polling. However, in order to do so, it is of 335 utmost importance that subscribers can rely on the subscription and 336 have confidence that they will indeed receive the subscribed updates 337 without having to worry updates being silently dropped. In other 338 words, a subscription constitutes a promise on the side of the server 339 to provide the receivers with updates per the terms of the 340 subscription. 342 Now, there are many reasons why a server may at some point no longer 343 be able to fulfill the terms of the subscription, even if the 344 subscription had been entered into with good faith. For example, the 345 volume of data objects may be larger than anticipated, the interval 346 may prove too short to send full updates in rapid succession, or an 347 internal problem may prevent updates from being collected. If for 348 some reason the server of a subscription is not able to keep its 349 promise, receivers MUST be notified immediately and reliably. The 350 server MUST also update the state of the subscription to indicate 351 that the subscription is in a detrimental state. 353 A server SHOULD reject a request for a subscription if it is unlikely 354 that the server will be able fulfill the terms of the subscription. 355 In such cases, it is preferable to have a client request another 356 subscription that is less resource intensive (for example, a 357 subscription with longer periodic update intervals), than to 358 subsequently frustrate the receiver with `frequent subscription 359 suspensions. 361 3.5. Data Encodings 363 Subscribed data is encoded in either XML or JSON format. A publisher 364 MUST support XML encoding and MAY support JSON encoding. 366 3.5.1. Periodic Subscriptions 368 In a periodic subscription, the data included as part of an update 369 corresponds to data that could have been simply retrieved using a get 370 operation and is encoded in the same way. XML encoding rules for 371 data nodes are defined in [RFC7950]. JSON encoding rules are defined 372 in [RFC7951]. 374 3.5.2. On-Change Subscriptions 376 In an on-change subscription, updates need to indicate not only 377 values of changed data nodes but also the types of changes that 378 occurred since the last update. Therefore encoding rules for data in 379 on-change updates will follow YANG-patch operation as specified in 380 [RFC8072]. The YANG-patch will describe what needs to be applied to 381 the earlier state reported by the preceding update, to result in the 382 now-current state. Note that contrary to [RFC8072], objects 383 encapsulated are not restricted to configuration objects only. 385 3.6. Datastore filters 387 Subscription policy specifies both the filters and the datastores 388 against which the filters will be applied. The result is the push of 389 information necessary to remotely maintain an extract of publisher's 390 datastore. 392 Only a single filter can be applied to a subscription at a time. The 393 following selection filter types are included in the yang-push data 394 model, and may be applied against a datastore: 396 o subtree: A subtree filter identifies one or more subtrees. When 397 specified, updates will only come from the data nodes of selected 398 YANG subtree(s). The syntax and semantics correspond to that 399 specified for [RFC6241] section 6. 401 o xpath: An xpath filter is an XPath expression which may be 402 meaningfully applied to a datastore. It is the results of this 403 expression which will be pushed. 405 Filters are intended to be used as selectors that define which 406 objects are within the scope of a subscription. Filters are not 407 intended to be used to store objects based on their current value. 408 Doing so would have a number of implications that would result in 409 significant additional complexity. For example, withough extending 410 encodings for on-change subscriptions, a receiver would not be able 411 to distinguish cases in which an object is no longer included in an 412 update because it was deleted, as opposed to its value simply no 413 longer meeting the filter criteria. While it is possible to define 414 extensions in the future that will support filtering based on values, 415 this is not supported in this version of yang-push and a server MAY 416 reject a subscription request that contains a filter for object 417 values. 419 Xpath itself provides powerful filtering constructs, and care must be 420 used in filter definition. As an example, consider an xpath filter 421 with a boolean result; such a result will not provide an easily 422 interpretable subset of a datastore. Beyond the boolean example, it 423 is quite possible to define an xpath filter where results are easy 424 for an application to mis-interpret. Consider an xpath filter which 425 only passes a datastore object when interface=up. It is up to the 426 receiver to understand implications of the presence or absence of 427 objects in each update. 429 It is not expected that implementations will support comprehensive 430 filter syntax and boundless complexity. It will be up to 431 implementations to describe what is viable, but the goal is to 432 provide equivalent capabilities to what is available with a GET. 433 Implementations MUST reject dynamic subscriptions or suspend 434 configured subscriptions if they include filters which are 435 unsupportable on a platform. 437 3.7. Streaming updates 439 Contrary to traditional data retrieval requests, datastore 440 subscription enables an unbounded series of update records to be 441 streamed over time. Two generic notifications for update records 442 have been defined for this: "push-update" and "push-change-update". 444 A push-update notification defines a complete, filtered update of the 445 datastore per the terms of a subscription. This type of notification 446 is used for continuous updates of periodic subscriptions. A push- 447 update notification can also used be for the on-change subscriptions 448 in two cases. First it will be used as the initial push-update if 449 there is a need to synchronize the receiver at the start of a new 450 subscription. It also MAY be sent if the publisher later chooses to 451 resynch an on-change subscription. The push-update record contains a 452 data snippet that contains an instantiated subtree with the 453 subscribed contents. The content of the update record is equivalent 454 to the contents that would be obtained had the same data been 455 explicitly retrieved using e.g., a NETCONF "get" operation, with the 456 same filters applied. 458 A push-change-update notification is the most common type of update 459 for on-change subscriptions. The update record in this case contains 460 a data snippet that indicates the set of changes that data nodes have 461 undergone since the last notification of YANG objects. In other 462 words, this indicates which data nodes have been created, deleted, or 463 have had changes to their values. In cases where multiple changes 464 have occurred and the object has not been deleted, the object's most 465 current value is reported. (In other words, for each object, only 466 one change is reported, not its entire history. Doing so would 467 defeat the purpose of the dampening period.) 469 These new YANG notifications are encoded and placed within 470 notification messages, which are then queued for egress over the 471 specified transport. The following is an example of an XML encoded 472 notification message over NETCONF transport as per [netconf-notif]. 474 476 2015-03-09T19:14:56Z 477 479 1011 480 2015-03-09T19:14:56.233Z 481 482 483 some_string 484 485 486 487 489 Figure 1: Push example 491 The following is an example of an on-change notification. It 492 contains an update for subscription 89, including a new value for a 493 leaf called beta, which is a child of a top-level container called 494 alpha: 496 498 2015-03-09T19:14:56Z 499 501 89 502 2015-03-09T19:14:56.233Z 503 504 505 1500 506 507 508 509 511 Figure 2: Push example for on change 513 The equivalent update when requesting json encoding: 515 517 2015-03-09T19:14:56Z 518 520 89 521 2015-03-09T19:14:56.233Z 522 523 { 524 "ietf-yang-patch:yang-patch": { 525 "patch-id": [ 526 null 527 ], 528 "edit": [ 529 { 530 "edit-id": "edit1", 531 "operation": "merge", 532 "target": "/alpha/beta", 533 "value": { 534 "beta": 1500 535 } 536 } 537 ] 538 } 539 } 540 541 542 544 Figure 3: Push example for on change with JSON 546 When the beta leaf is deleted, the publisher may send 547 549 2015-03-09T19:14:56Z 550 552 89 553 2015-03-09T19:14:56.233Z 554 555 556 558 559 560 561 563 Figure 4: 2nd push example for on change update 565 3.8. Subscription management 567 [subscribe] has been enhanced to support YANG datastore subscription 568 negotiation. These enhancements provide information on why a 569 datastore subscription attempt has failed. 571 A datastore subscription can be rejected for multiple reasons. This 572 includes the lack of read authorization on a requested data node, or 573 the inability of the publisher push update records as frequently as 574 requested. In such cases, no subscription is established. Instead, 575 the subscription-result with the failure reason is returned as part 576 of the RPC response. As part of this response, a set of alternative 577 subscription parameters MAY be returned that would likely have 578 resulted in acceptance of the subscription request. The subscriber 579 may consider these as part of future subscription attempts. 581 It should be noted that a rejected subscription does not result in 582 the generation of an rpc-reply with an rpc-error element, as neither 583 the specification of YANG-push specific errors nor the specification 584 of additional data parameters to be returned in an error case are 585 supported as part of a YANG data model. 587 For instance, for the following request: 589 591 593 push-update 594 597 500 598 encode-xml 599 600 602 Figure 5: Establish-Subscription example 604 the publisher might return: 606 608 610 error-insufficient-resources 611 612 2000 613 615 Figure 6: Error response example 617 3.9. Receiver Authorization 619 A receiver of subscription data MUST only be sent updates for which 620 they have proper authorization. A server MUST ensure that no non- 621 authorized data is included in push updates. To do so, it needs to 622 apply all corresponding checks applicable at the time of a specific 623 pushed update and if necessary silently remove any non-authorized 624 data from subtrees. This enables YANG data pushed based on 625 subscriptions to be authorized equivalently to a regular data 626 retrieval (get) operation. 628 Alternatively, a server that wants to avoid having to perform 629 filtering of authorized content on each update MAY instead simply 630 reject a subscription request that contains non-authorized data. It 631 MAY subsequently suspend a subscription in case new objects are 632 created during the course of the subscription for which the receiver 633 does not have the necessary authorization, or in case the 634 authorization privileges of a receiver change over the course of the 635 subscription. 637 The contextual authorization model for data in YANG datastores is the 638 NETCONF Access Control Model [RFC6536bis], Section 3.2.3. However, 639 there are some differences. 641 One of these clarifications is that datastore selection MUST NOT 642 return continuous errors as part of an on-change subscription. This 643 includes errors such as when there is not read access to every data 644 node specifically named within the filter. Non-authorized data needs 645 to be either simply dropped or, alternatively, the subscription 646 SHOULD be suspended. 648 +-------------+ +-------------+ 649 establish / | protocol | | filter | 650 modify --> | operation | -------------> | data node | 651 subscription | allowed? | datastore | access | 652 +-------------+ objects | allowed? | 653 +-------------+ 655 Figure 7: Access control for subscription 657 Another clarification to [RFC6536bis] is that each of the individual 658 nodes in a resulting update record MUST also have applied access 659 control to resulting pushed messages. This includes validating that 660 read access into new nodes added since the last update record. If 661 read access into previously accessible nodes not explicitly named in 662 the filter are lost mid-subscription, that can be treated as a 663 'delete' for on-change subscriptions. If not capable of handling 664 such permission changes for dynamic subscriptions, publisher 665 implementations MAY choose to terminate the subscription and to force 666 re-establishment with appropriate filtering. 668 +-------------+ +-------------------+ 669 push-update / --> | data node | yes | | 670 push-change-update | access | ---> | add data node | 671 | allowed? | | to update message | 672 +-------------+ +-------------------+ 674 Figure 8: Access control for push updates 676 3.10. On-change notifiable YANG objects 678 In some cases, a publisher supporting on-change notifications may not 679 be able to push updates for some object types on-change. Reasons for 680 this might be that the value of the data node changes frequently 681 (e.g., [RFC7223]'s in-octets counter), that small object changes are 682 frequent and meaningless (e.g., a temperature gauge changing 0.1 683 degrees), or that the implementation is not capable of on-change 684 notification for a particular object. 686 Support for on-change notification is usually specific to the 687 individual YANG model and/or implementation so it is possible to 688 define in design time. System integrators need this information 689 (without reading any data from a live node). 691 The default assumption is that no data nodes support on-change 692 notification. Schema nodes and subtrees that support on-change 693 notifications MUST be marked by accordingly with the YANG extension 694 "notifiable-on-change". This extension is defined in the data model 695 below. 697 When an on-change subscription is established, data-nodes are 698 automatically excluded unless they are marked with notifiable-on- 699 change as true. This also means that authorization checks SHALL NOT 700 be performed on them. A client can identify which nodes will be 701 included in on-change updated by retrieving the data nodes in the 702 subscription's scope and checking for which notifiable-on-change is 703 marked as true. 705 Adding notifiable-on-change markings will in general require updating 706 the corresponding YANG models. A simple way to avoid having to 707 modify existing module definitions is to add notifiable-on-change 708 markings by defining module deviations. This means that when a YANG 709 model designer wants to add a notifiable-on-change marking to nodes 710 of an existing module without modifying the module definitions, a new 711 module is introduced that contains deviation statements which add 712 "notifiable-on-change" statements as appicable. 714 deviation /sys:system/sys:system-time { 715 deviate add { 716 yp:notifiable-on-change false; 717 } 718 } 720 Figure 9: Deviation Example 722 3.11. Other considerations 724 3.11.1. Robustness and reliability 726 Particularly in the case of on-change push updates, it is important 727 that push updates do not get lost or, in case the loss of an update 728 is unavoidable, that the receiver is notified accordingly. 730 Update messages for a single subscription MAY NOT be resequenced. 732 It is conceivable that under certain circumstances, a publisher will 733 recognize that it is unable to include within an update record the 734 full set of objects desired per the terms of a subscription. In this 735 case, the publisher MUST take one or more of the following actions. 737 o A publisher MUST set the updates-not-sent flag on any update 738 record which is known to be missing information. 740 o It MAY choose to suspend a subscription as per [subscribe]. 742 o When resuming an on-change subscription, the publisher SHOULD 743 generate a complete patch from the previous update record. If 744 this is not possible and the synch-on-start option is configured, 745 then the full datastore contents MAY be sent instead (effectively 746 replacing the previous contents). If neither of these are 747 possible, then an updates-not-sent flag MUST be included on the 748 next push-change-update. 750 Note: It is perfectly acceptable to have a series of push-change- 751 updates (and even push updates) serially queued at the transport 752 layer awaiting transmission. It is not required to merge pending 753 update messages. I.e., the dampening period applies to update record 754 creation, not transmission. 756 3.11.2. Update size and fragmentation 758 Depending on the subscription, the volume of updates can become quite 759 large. Additionally, based on the platform, it is possible that 760 update records for a single subscription are best sent independently 761 from different line-cards. Therefore, it may not always be practical 762 to send the entire update record in a single chunk. Implementations 763 may therefore choose, at their discretion, to "chunk" update records, 764 breaking one subscription's objects across several update records. 765 In this case the updates-not-sent flag will indicate that no single 766 update record is complete, and it is permissible for multiple updates 767 to come into a receiver for a single periodic interval or on-change 768 dampening period. 770 Care must be taken in chunking as problems may arrise for objects 771 that have containment or referential dependencies. The publisher 772 must consider these issues if chunking is provided. 774 3.11.3. Publisher capacity 776 It is far preferable to decline a subscription request than to accept 777 such a request when it cannot be met. 779 Whether or not a subscription can be supported will be determined by 780 a combination of several factors such as the subscription policy (on- 781 change or periodic), the period in which to report changes (1 second 782 periods will consume more resources than 1 hour periods), the amount 783 of data in the subtree that is being subscribed to, and the number 784 and combination of other subscriptions that are concurrently being 785 serviced. 787 4. A YANG data model for management of datastore push subscriptions 789 4.1. Overview 791 The YANG data model for datastore push subscriptions is depicted in 792 the following figure. Following YANG tree convention in the 793 depiction, brackets enclose list keys, "rw" means configuration, "ro" 794 operational state data, "?" designates optional nodes, "*" designates 795 nodes that can have multiple instances. Parentheses with a name in 796 the middle enclose choice and case nodes. New YANG objects defined 797 here (i.e., beyond those from [subscribe]) are identified with "yp". 799 module: ietf-subscribed-notifications 800 +--ro streams 801 | +--ro stream* [stream] 802 | | +--ro stream stream 803 | | +--ro description string 804 | | +--ro replay-support? empty 805 | | +--ro replay-log-creation-time? yang:date-and-time 806 | | +--ro replay-log-aged-time? yang:date-and-time 807 | +--ro yp:datastores 808 | +--ro yp:datastore* datastore 809 +--rw filters 810 | +--rw filter* [identifier] 811 | +--rw identifier filter-id 812 | +--rw (filter-type)? 813 | +--:(event-filter) 814 | +--rw event-filter-type event-filter-type 815 | +--rw event-filter 816 +--rw subscription-config {configured-subscriptions}? 817 | +--rw subscription* [identifier] 818 | +--rw identifier subscription-id 819 | +--rw encoding? encoding 820 | +--rw (target) 821 | | +--:(event-stream) 822 | | | +--rw stream stream 823 | | +--:(yp:datastore) 824 | | +--rw yp:datastore datastore 825 | | +--rw yp:selection-filter-type selection-filter-type 826 | | +--rw yp:selection-filter 827 | +--rw (applied-filter) 828 | | +--:(by-reference) 829 | | | +--rw filter-ref filter-ref 830 | | +--:(within-subscription) 831 | | +--rw (filter-type)? 832 | | +--:(event-filter) 833 | | +--rw event-filter-type event-filter-type 834 | | +--rw event-filter 835 | +--rw stop-time? yang:date-and-time 836 | +--rw receivers 837 | | +--rw receiver* [address port] 838 | | +--rw address inet:host 839 | | +--rw port inet:port-number 840 | | +--rw protocol? transport-protocol 841 | +--rw (notification-origin)? 842 | | +--:(interface-originated) 843 | | | +--rw source-interface? if:interface-ref 844 | | +--:(address-originated) 845 | | +--rw source-vrf? string 846 | | +--rw source-address inet:ip-address-no-zone 847 | +--rw (yp:update-trigger)? 848 | | +--:(yp:periodic) 849 | | | +--rw yp:period yang:timeticks 850 | | | +--rw yp:anchor-time? yang:date-and-time 851 | | +--:(yp:on-change) {on-change}? 852 | | +--rw yp:dampening-period yang:timeticks 853 | | +--rw yp:no-synch-on-start? empty 854 | | +--rw yp:excluded-change* change-type 855 | +--rw yp:dscp? inet:dscp 856 | +--rw yp:weighting? uint8 857 | +--rw yp:dependency? sn:subscription-id 858 +--ro subscriptions 859 +--ro subscription* [identifier] 860 +--ro identifier subscription-id 861 +--ro configured-subscription? empty 862 | {configured-subscriptions}? 863 +--ro encoding? encoding 864 +--ro (target) 865 | +--:(event-stream) 866 | | +--ro stream stream 867 | | +--ro replay-start-time? yang:date-and-time 868 | | {replay}? 869 | +--:(yp:datastore) 870 | +--ro yp:datastore datastore 871 | +--ro yp:selection-filter-type selection-filter-type 872 | +--ro yp:selection-filter 873 +--ro (applied-filter) 874 | +--:(by-reference) 875 | | +--ro filter-ref filter-ref 876 | +--:(within-subscription) 877 | +--ro (filter-type)? 878 | +--:(event-filter) 879 | +--ro event-filter-type event-filter-type 880 | +--ro event-filter 881 +--ro stop-time? yang:date-and-time 882 +--ro (notification-origin)? 883 | +--:(interface-originated) 884 | | +--ro source-interface? if:interface-ref 885 | +--:(address-originated) 886 | +--ro source-vrf? string 887 | +--ro source-address inet:ip-address-no-zone 888 +--ro receivers 889 | +--ro receiver* [address port] 890 | +--ro address inet:host 891 | +--ro port inet:port-number 892 | +--ro protocol? transport-protocol 893 | +--ro pushed-notifications? yang:counter64 894 | +--ro excluded-notifications? yang:counter64 895 | +--ro status subscription-status 896 +--ro (yp:update-trigger)? 897 | +--:(yp:periodic) 898 | | +--ro yp:period yang:timeticks 899 | | +--ro yp:anchor-time? yang:date-and-time 900 | +--:(yp:on-change) {on-change}? 901 | +--ro yp:dampening-period yang:timeticks 902 | +--ro yp:no-synch-on-start? empty 903 | +--ro yp:excluded-change* change-type 904 +--ro yp:dscp? inet:dscp 905 +--ro yp:weighting? uint8 906 +--ro yp:dependency? sn:subscription-id 908 rpcs: 909 +---x establish-subscription 910 | +---w input 911 | | +---w encoding? encoding 912 | | +---w (target) 913 | | | +--:(event-stream) 914 | | | | +---w stream stream 915 | | | | +---w replay-start-time? yang:date-and-time 916 | | | | {replay}? 917 | | | +--:(yp:datastore) 918 | | | +---w yp:datastore datastore 919 | | | +---w yp:selection-filter-type selection-filter-type 920 | | | +---w yp:selection-filter 921 | | +---w (applied-filter) 922 | | | +--:(by-reference) 923 | | | | +---w filter-ref filter-ref 924 | | | +--:(within-subscription) 925 | | | +---w (filter-type)? 926 | | | +--:(event-filter) 927 | | | +---w event-filter-type event-filter-type 928 | | | +---w event-filter 929 | | +---w stop-time? yang:date-and-time 930 | | +---w (yp:update-trigger)? 931 | | | +--:(yp:periodic) 932 | | | | +---w yp:period yang:timeticks 933 | | | | +---w yp:anchor-time? yang:date-and-time 934 | | | +--:(yp:on-change) {on-change}? 935 | | | +---w yp:dampening-period yang:timeticks 936 | | | +---w yp:no-synch-on-start? empty 937 | | | +---w yp:excluded-change* change-type 938 | | +---w yp:dscp? inet:dscp 939 | | +---w yp:weighting? uint8 940 | | +---w yp:dependency? sn:subscription-id 941 | +--ro output 942 | +--ro subscription-result subscription-result 943 | +--ro (result)? 944 | +--:(no-success) 945 | | +--ro filter-failure? string 946 | | +--ro replay-start-time-hint? yang:date-and-time 947 | | +--ro yp:period-hint? yang:timeticks 948 | | +--ro yp:error-path? string 949 | | +--ro yp:object-count-estimate? uint32 950 | | +--ro yp:object-count-limit? uint32 951 | | +--ro yp:kilobytes-estimate? uint32 952 | | +--ro yp:kilobytes-limit? uint32 953 | +--:(success) 954 | +--ro identifier subscription-id 955 +---x modify-subscription 956 | +---w input 957 | | +---w identifier? subscription-id 958 | | +---w (applied-filter) 959 | | | +--:(by-reference) 960 | | | | +---w filter-ref filter-ref 961 | | | +--:(within-subscription) 962 | | | +---w (filter-type)? 963 | | | +--:(event-filter) 964 | | | +---w event-filter-type event-filter-type 965 | | | +---w event-filter 966 | | +---w stop-time? yang:date-and-time 967 | | +---w (yp:update-trigger)? 968 | | +--:(yp:periodic) 969 | | | +---w yp:period yang:timeticks 970 | | | +---w yp:anchor-time? yang:date-and-time 971 | | +--:(yp:on-change) {on-change}? 972 | | +---w yp:dampening-period yang:timeticks 973 | +--ro output 974 | +--ro subscription-result subscription-result 975 | +--ro (result)? 976 | +--:(no-success) 977 | +--ro filter-failure? string 978 | +--ro yp:period-hint? yang:timeticks 979 | +--ro yp:error-path? string 980 | +--ro yp:object-count-estimate? uint32 981 | +--ro yp:object-count-limit? uint32 982 | +--ro yp:kilobytes-estimate? uint32 983 | +--ro yp:kilobytes-limit? uint32 984 +---x delete-subscription 985 | +---w input 986 | | +---w identifier subscription-id 987 | +--ro output 988 | +--ro subscription-result subscription-result 989 +---x kill-subscription 990 +---w input 991 | +---w identifier subscription-id 992 +--ro output 993 +--ro subscription-result subscription-result 995 notifications: 996 +---n replay-complete 997 | +--ro identifier subscription-id 998 +---n notification-complete 999 | +--ro identifier subscription-id 1000 +---n subscription-started 1001 | +--ro identifier subscription-id 1002 | +--ro encoding? encoding 1003 | +--ro (target) 1004 | | +--:(event-stream) 1005 | | | +--ro stream stream 1006 | | | +--ro replay-start-time? yang:date-and-time 1007 | | | {replay}? 1008 | | +--:(yp:datastore) 1009 | | +--ro yp:datastore datastore 1010 | | +--ro yp:selection-filter-type selection-filter-type 1011 | | +--ro yp:selection-filter 1012 | +--ro (applied-filter) 1013 | | +--:(by-reference) 1014 | | | +--ro filter-ref filter-ref 1015 | | +--:(within-subscription) 1016 | | +--ro (filter-type)? 1017 | | +--:(event-filter) 1018 | | +--ro event-filter-type event-filter-type 1019 | | +--ro event-filter 1020 | +--ro stop-time? yang:date-and-time 1021 | +--ro (yp:update-trigger)? 1022 | | +--:(yp:periodic) 1023 | | | +--ro yp:period yang:timeticks 1024 | | | +--ro yp:anchor-time? yang:date-and-time 1025 | | +--:(yp:on-change) {on-change}? 1026 | | +--ro yp:dampening-period yang:timeticks 1027 | | +--ro yp:no-synch-on-start? empty 1028 | | +--ro yp:excluded-change* change-type 1029 | +--ro yp:dscp? inet:dscp 1030 | +--ro yp:weighting? uint8 1031 | +--ro yp:dependency? sn:subscription-id 1032 +---n subscription-resumed 1033 | +--ro identifier subscription-id 1034 +---n subscription-modified 1035 | +--ro identifier subscription-id 1036 | +--ro encoding? encoding 1037 | +--ro (target) 1038 | | +--:(event-stream) 1039 | | +--ro stream stream 1040 | | +--ro replay-start-time? yang:date-and-time {replay}? 1041 | +--ro (applied-filter) 1042 | | +--:(by-reference) 1043 | | | +--ro filter-ref filter-ref 1044 | | +--:(within-subscription) 1045 | | +--ro (filter-type)? 1046 | | +--:(event-filter) 1047 | | +--ro event-filter-type event-filter-type 1048 | | +--ro event-filter 1049 | +--ro stop-time? yang:date-and-time 1050 | +--ro (yp:update-trigger)? 1051 | | +--:(yp:periodic) 1052 | | | +--ro yp:period yang:timeticks 1053 | | | +--ro yp:anchor-time? yang:date-and-time 1054 | | +--:(yp:on-change) {on-change}? 1055 | | +--ro yp:dampening-period yang:timeticks 1056 | | +--ro yp:no-synch-on-start? empty 1057 | | +--ro yp:excluded-change* change-type 1058 | +--ro yp:dscp? inet:dscp 1059 | +--ro yp:weighting? uint8 1060 | +--ro yp:dependency? sn:subscription-id 1061 +---n subscription-terminated 1062 | +--ro identifier subscription-id 1063 | +--ro error-id subscription-errors 1064 | +--ro filter-failure? string 1065 +---n subscription-suspended 1066 +--ro identifier subscription-id 1067 +--ro error-id subscription-errors 1068 +--ro filter-failure? string 1070 module: ietf-yang-push 1072 notifications: 1073 +---n push-update 1074 | +--ro subscription-id sn:subscription-id 1075 | +--ro time-of-update? yang:date-and-time 1076 | +--ro updates-not-sent? empty 1077 | +--ro datastore-contents? 1078 +---n push-change-update {on-change}? 1079 +--ro subscription-id sn:subscription-id 1080 +--ro time-of-update? yang:date-and-time 1081 +--ro updates-not-sent? empty 1082 +--ro datastore-changes? 1084 Figure 10: Model structure 1086 Selected components of the model are summarized below. 1088 4.2. Subscription configuration 1090 Both configured and dynamic subscriptions are represented within the 1091 list subscription-config. Each subscription has own list elements. 1092 New and enhanced parameters extending the basic subscription data 1093 model in [subscribe] include: 1095 o An update filter identifying yang nodes of interest. Filter 1096 contents are specified via a reference to an existing filter, or 1097 via an in-line definition for only that subscription. This 1098 facilitates the reuse of filter definitions, which can be 1099 important in case of complex filter conditions. Referenced 1100 filters can also allow an implementation to avoid evaluating 1101 filter acceptability during a dynamic subscription request. The 1102 case statement differentiates the options. 1104 o For periodic subscriptions, triggered updates will occur at the 1105 boundaries of a specified time interval. These boundaries many be 1106 calculated from the periodic parameters: 1108 * a "period" which defines duration between period push updates. 1110 * an "anchor-time"; update intervals always fall on the points in 1111 time that are a multiple of a period after the anchor time. If 1112 anchor time is not provided, then the anchor time MUST be set 1113 with the creation time of the initial update record. 1115 o For on-change subscriptions, assuming the dampening period has 1116 completed, triggered occurs whenever a change in the subscribed 1117 information is detected. On-change subscriptions have more 1118 complex semantics that is guided by its own set of parameters: 1120 * a "dampening-period" specifies the interval that must pass 1121 before a successive update for the subscription is sent. If no 1122 dampening period is in effect, the update is sent immediately. 1123 If a subsequent change is detected, another update is only sent 1124 once the dampening period has passed for this subscription. 1126 * an "excluded-change" flag which allows restriction of the types 1127 of changes for which updates should be sent (e.g., only add to 1128 an update record on object creation). 1130 * a "no-synch-on-start" flag which specifies whether a complete 1131 update with all the subscribed data is to be sent at the 1132 beginning of a subscription. 1134 o Optional qos parameters to indicate the treatment of a 1135 subscription relative to other traffic between publisher and 1136 receiver. These include: 1138 * A "dscp" QoS marking which MUST be stamped on notification 1139 messages to differentiate network QoS behavior. 1141 * A "weighting" so that bandwidth proportional to this weighting 1142 can be allocated to this subscription relative to others for 1143 that receiver. 1145 * a "dependency" upon another subscription. Notification 1146 messages MUST NOT be sent prior to other notification messages 1147 containing update record(s) for the referenced subscription. 1149 o A subscription's weighting MUST work identically to stream 1150 dependency weighting as described within RFC 7540, section 5.3.2. 1152 o A subscription's dependency MUST work identically to stream 1153 dependency as described within RFC 7540, sections 5.3.1, 5.3.3, 1154 and 5.3.4. If a dependency is attempted via an RPC, but the 1155 referenced subscription does not exist, the dependency will be 1156 removed. 1158 4.3. YANG Notifications 1159 4.3.1. Monitoring and OAM Notifications 1161 OAM notifications and mechanism are reused from [subscribe]. Some 1162 have been augmented to include the YANG datastore specific objects. 1164 4.3.2. New Notifications for update records 1166 The data model introduces two YANG notifications to encode 1167 information for update records: "push-update" and "push-change- 1168 update". 1170 "Push-update" is used to send a complete snapshot of the filtered 1171 subscription data. This type of notification is used to carry the 1172 update records of a periodic subscription. The "push-update" 1173 notification is also used with on-change subscriptions for the 1174 purposes of allowing a receiver to "synch" on a complete set of 1175 subscribed datastore contents. This synching may be done the start 1176 of an on-change subscription, and then later in that subscription to 1177 force resynchronization. If the "updates-not-sent" flag is set, this 1178 indicates that the update record is incomplete. 1180 "Push-change-update" is used to send datastore changes that have 1181 occurred in subscribed data since the previous update. This 1182 notification is used only in conjunction with on-change 1183 subscriptions. This will be encoded as yang-patch data. 1185 If the application detects an informational discontinuity in either 1186 notification, the notification MUST include a flag "updates-not- 1187 sent". This flag which indicates that not all changes which have 1188 occurred since the last update are actually included with this 1189 update. In other words, the publisher has failed to fulfill its full 1190 subscription obligations. (For example a datastore missed a window 1191 in providing objects to a publisher process.) To facilitate 1192 synchronization, a publisher MAY subsequently send a push-update 1193 containing a full snapshot of subscribed data. 1195 4.4. YANG RPCs 1197 YANG-Push subscriptions are established, modified, and deleted using 1198 RPCs augmented from [subscribe]. 1200 4.4.1. Establish-subscription RPC 1202 The subscriber sends an establish-subscription RPC with the 1203 parameters in section 3.1. An example might look like: 1205 1207 1209 1212 500 1213 encode-xml 1214 1215 1217 Figure 11: Establish-subscription RPC 1219 The publisher MUST respond explicitly positively (i.e., subscription 1220 accepted) or negatively (i.e., subscription rejected) to the request. 1221 Positive responses include the subscription-id of the accepted 1222 subscription. In that case a publisher MAY respond: 1224 1226 1228 ok 1229 1230 1232 52 1233 1234 1236 Figure 12: Establish-subscription positive RPC response 1238 A subscription can be rejected for multiple reasons, including the 1239 lack of authorization to establish a subscription, the lack of read 1240 authorization on the requested data node, or the inability of the 1241 publisher to provide a stream with the requested semantics. 1243 When the requester is not authorized to read the requested data node, 1244 the returned information indicates the node is unavailable. For 1245 instance, if the above request was unauthorized to read node "ex:foo" 1246 the publisher may return: 1248 1250 1252 subtree-unavailable 1253 1254 1256 /ex:foo 1257 1258 1260 Figure 13: Establish-subscription access denied response 1262 If a request is rejected because the publisher is not able to serve 1263 it, the publisher SHOULD include in the returned error what 1264 subscription parameters would have been accepted for the request. 1265 However, there are no guarantee that subsequent requests using this 1266 info will in fact be accepted. 1268 For example, for the following request: 1270 1272 1274 running 1275 1278 10 1279 encode-xml 1280 1281 1283 Figure 14: Establish-subscription request example 2 1285 a publisher that cannot serve on-change updates but periodic updates 1286 might return the following: 1288 1290 1292 period-unsupported 1293 1294 100 1295 1297 Figure 15: Establish-subscription error response example 2 1299 4.4.2. Modify-subscription RPC 1301 The subscriber MAY invoke the modify-subscription RPC for a 1302 subscription it previously established. The subscriber will include 1303 newly desired values in the modify-subscription RPC. Parameters not 1304 included MUST remain unmodified. Below is an example where a 1305 subscriber attempts to modify the period of a subscription. 1307 1309 1311 running 1312 1313 1011 1314 1315 250 1316 1317 1319 Figure 16: Modify subscription request 1321 The publisher MUST respond explicitly positively or negatively to the 1322 request. A response to a successful modification might look like: 1324 1326 1328 ok 1329 1330 1332 Figure 17: Modify subscription response 1334 If the subscription modification is rejected, the publisher MUST send 1335 a response like it does for an establish-subscription and maintain 1336 the subscription as it was before the modification request. 1337 Responses MAY include hints. A subscription MAY be modified multiple 1338 times. 1340 A configured subscription cannot be modified using modify- 1341 subscription RPC. Instead, the configuration needs to be edited as 1342 needed. 1344 4.4.3. Delete-subscription RPC 1346 To stop receiving updates from a subscription and effectively delete 1347 a subscription that had previously been established using an 1348 establish-subscription RPC, a subscriber can send a delete- 1349 subscription RPC, which takes as only input the subscription-id. For 1350 example: 1352 1354 1356 1357 1011 1358 1359 1360 1362 1364 1366 ok 1367 1368 1370 Figure 18: Delete subscription 1372 Configured subscriptions cannot be deleted via RPC, but have to be 1373 removed from the configuration. 1375 4.4.4. YANG Module Synchronization 1377 To make subscription requests, the subscriber needs to know the YANG 1378 module library available on the publisher. The YANG 1.0 module 1379 library information is sent by a NETCONF server in the NETCONF 1380 'hello' message. For YANG 1.1 modules and all modules used with the 1381 RESTCONF [RFC8040] protocol, this information is provided by the YANG 1382 Library module (ietf-yang-library.yang from [RFC7895]. The YANG 1383 library information is important for the receiver to reproduce the 1384 set of object definitions used by the replicated datastore. 1386 The YANG library includes a module list with the name, revision, 1387 enabled features, and applied deviations for each YANG module 1388 implemented by the publisher. The receiver is expected to know the 1389 YANG library information before starting a subscription. The 1390 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module 1391 can be used to cache the YANG library information. 1393 The set of modules, revisions, features, and deviations can change at 1394 run-time (if supported by the server implementation). In this case, 1395 the receiver needs to be informed of module changes before data nodes 1396 from changed modules can be processed correctly. The YANG library 1397 provides a simple "yang-library-change" notification that informs the 1398 client that the library has changed. The receiver then needs to re- 1399 read the entire YANG library data for the replicated server in order 1400 to detect the specific YANG library changes. The "ietf-netconf- 1401 notifications" module defined in [RFC6470] contains a "netconf- 1402 capability-change" notification that can identify specific module 1403 changes. For example, the module URI capability of a newly loaded 1404 module will be listed in the "added-capability" leaf-list, and the 1405 module URI capability of an removed module will be listed in the 1406 "deleted-capability" leaf-list. 1408 5. YANG module 1410 ; file "ietf-yang-push@2017-08-20.yang" 1411 module ietf-yang-push { 1412 yang-version 1.1; 1413 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1414 prefix yp; 1416 import ietf-inet-types { 1417 prefix inet; 1418 } 1419 import ietf-yang-types { 1420 prefix yang; 1421 } 1422 import ietf-subscribed-notifications { 1423 prefix sn; 1424 } 1426 organization "IETF"; 1427 contact 1428 "WG Web: 1429 WG List: 1430 WG Chair: Mahesh Jethanandani 1431 1433 WG Chair: Kent Watsen 1434 1436 Editor: Alexander Clemm 1437 1439 Editor: Eric Voit 1440 1442 Editor: Alberto Gonzalez Prieto 1443 1445 Editor: Ambika Prasad Tripathy 1446 1448 Editor: Einar Nilsen-Nygaard 1449 1451 Editor: Andy Bierman 1452 1454 Editor: Balazs Lengyel 1455 "; 1457 description 1458 "This module contains conceptual YANG specifications 1459 for YANG push."; 1461 revision 2017-08-20 { 1462 description 1463 "Initial revision."; 1464 reference 1465 "YANG Datastore Push, draft-ietf-netconf-yang-push-08"; 1466 } 1468 /* 1469 * EXTENSIONS 1470 */ 1472 extension notifiable-on-change { 1473 argument "value"; 1474 description 1475 "Indicates whether changes to the data node are reportable in 1476 on-change subscriptions. 1478 The statement MUST only be a substatement of the leaf, leaf-list, 1479 container, list, anyxml, anydata statements. Zero or One 1480 notifiable-on-change statement is allowed per parent statement. 1481 NO substatements are allowed. 1483 The argument is a boolean value indicating whether on-change 1484 notifications are supported. If notifiable-on-change is not 1485 specified, the default is the same as the parent data node's 1486 value. For top level data nodes the default value is false."; 1487 } 1489 /* 1490 * FEATURES 1491 */ 1493 feature on-change { 1494 description 1495 "This feature indicates that on-change updates are 1496 supported."; 1497 } 1499 /* 1500 * IDENTITIES 1501 */ 1503 /* Error type identities for datastore subscription */ 1504 identity period-unsupported { 1505 base sn:error; 1506 description 1507 "Requested time period is too short. This can be for both 1508 periodic and on-change dampening."; 1509 } 1511 identity qos-unsupported { 1512 base sn:error; 1513 description 1514 "Subscription QoS parameters not supported on this platform."; 1515 } 1517 identity dscp-unavailable { 1518 base sn:error; 1519 description 1520 "Requested DSCP marking not allocatable."; 1521 } 1523 identity on-change-unsupported { 1524 base sn:error; 1525 description 1526 "On-change not supported."; 1527 } 1529 identity synch-on-start-unsupported { 1530 base sn:error; 1531 description 1532 "On-change synch-on-start not supported."; 1533 } 1535 identity synch-on-start-datatree-size { 1536 base sn:error; 1537 description 1538 "Synch-on-start would push a datatree which exceeds size limit."; 1539 } 1541 identity reference-mismatch { 1542 base sn:error; 1543 description 1544 "Mismatch in filter key and referenced yang subtree."; 1545 } 1547 identity data-unavailable { 1548 base sn:error; 1549 description 1550 "Referenced yang node or subtree doesn't exist, or read 1551 access is not permitted."; 1552 } 1554 identity datatree-size { 1555 base sn:error; 1556 description 1557 "Resulting push updates would exceed size limit."; 1558 } 1560 /* Datastore identities */ 1561 identity datastore { 1562 description 1563 "Abstract base identity for datastore identities. More are in the 1564 process of being defined within 1565 draft-ietf-netmod-revised-datastores. "; 1566 } 1567 identity candidate { 1568 base datastore; 1569 description 1570 "The candidate datastore per RFC-6241."; 1571 reference "RFC-6241, #5.1"; 1572 } 1573 identity running { 1574 base datastore; 1575 description 1576 "The running datastore per RFC-6241."; 1577 reference "RFC-6241, #5.1"; 1578 } 1579 identity startup { 1580 base datastore; 1581 description 1582 "The startup datastore per RFC-6241."; 1583 reference "RFC-6241, #5.1"; 1584 } 1585 identity operational { 1586 base datastore; 1587 description 1588 "The operational datastore contains all configuration data 1589 actually used by the system, including all applied configuration, 1590 system-provided configuration and values defined by any supported 1591 data models. In addition, the operational datastore also 1592 contains state data."; 1593 reference 1594 "the original text came from draft-ietf-netmod-revised-datastores 1595 -01, section #4.3. This definition is expected to remain stable 1596 meaning later reconciliation between the drafts unnecessary."; 1597 } 1598 identity intended { 1599 base datastore; 1600 description 1601 "The intended datastore per draft-ietf-netmod-revised-datastores."; 1602 reference 1603 "draft-ietf-netmod-revised-datastores"; 1604 } 1605 identity custom-datastore { 1606 base datastore; 1607 description 1608 "Another datastore not defined via an identity in this model"; 1609 } 1611 /* Selection filter identities */ 1612 identity selection-filter { 1613 description 1614 "Evaluation criteria encoded in a syntax which allows the 1615 selection of nodes from a target. If the filter is applied 1616 against a datastore for periodic extracts, the resulting node-set 1617 result is passed along. If the filter is applied against a 1618 datastore looking for changes, deltas from the last update in the 1619 form of a patch result are passed along. An empty node set is a 1620 valid result of this filter type."; 1621 } 1622 identity subtree-selection-filter { 1623 base selection-filter; 1624 description 1625 "An RFC-6241 based selection-filter which may be used to select 1626 nodes within a datastore."; 1627 reference "RFC-6241, #5.1"; 1628 } 1629 identity xpath-selection-filter { 1630 base selection-filter; 1631 description 1632 "A selection-filter which may be applied to a datastore which 1633 follows the syntax specified in yang:xpath1.0. Nodes that evaluate 1634 to true are included in the selection."; 1635 reference "XPATH: http://www.w3.org/TR/1999/REC-xpath-19991116"; 1636 } 1638 /* 1639 * TYPE DEFINITIONS 1640 */ 1642 typedef change-type { 1643 type enumeration { 1644 enum "create" { 1645 description 1646 "Create a new data resource if it does not already exist. If 1647 it already exists, replace."; 1648 } 1649 enum "delete" { 1650 description 1651 "Delete a data resource if it already exists. If it does not 1652 exists, take no action."; 1653 } 1654 enum "insert" { 1655 description 1656 "Insert a new user-ordered data resource"; 1657 } 1658 enum "merge" { 1659 description 1660 "merge the edit value with the target data resource; create 1661 if it does not already exist"; 1662 } 1663 enum "move" { 1664 description 1665 "Reorder the target data resource"; 1666 } 1667 enum "replace" { 1668 description 1669 "Replace the target data resource with the edit value"; 1671 } 1672 enum "remove" { 1673 description 1674 "Remove a data resource if it already exists "; 1675 } 1676 } 1677 description 1678 "Specifies different types of datastore changes."; 1679 reference 1680 "RFC 8072 section 2.5, with a delta that it is ok to receive 1681 ability create on an existing node, or recieve a delete on a 1682 missing node."; 1683 } 1685 typedef datastore { 1686 type identityref { 1687 base datastore; 1688 } 1689 description 1690 "Specifies a system-provided datastore. May also specify ability 1691 portion of a datastore, so as to reduce the filtering effort."; 1692 } 1694 typedef selection-filter-type { 1695 type identityref { 1696 base selection-filter; 1697 } 1698 description 1699 "Specifies a known type of selection filter."; 1700 } 1702 /* 1703 * GROUP DEFINITIONS 1704 */ 1706 grouping datastore-criteria { 1707 description 1708 "A grouping to define criteria for which objects from which 1709 datastore to include in push updates."; 1710 leaf datastore { 1711 type datastore; 1712 mandatory true; 1713 description 1714 "Datastore against which the subscription has been 1715 applied."; 1716 } 1717 uses selection-filter-objects; 1719 } 1721 grouping selection-filter-objects { 1722 description 1723 "This grouping defines a selector for objects from a 1724 datastore."; 1725 leaf selection-filter-type { 1726 type selection-filter-type; 1727 mandatory true; 1728 description 1729 "A filter needs to be a known and understood syntax if it is 1730 to be interpretable by a device."; 1731 } 1732 anyxml selection-filter { 1733 mandatory true; 1734 description 1735 "Datastore evaluation criteria encoded in a syntax of a 1736 supported type of selection filter."; 1737 } 1738 } 1740 grouping update-policy-modifiable { 1741 description 1742 "This grouping describes the datastore specific subscription 1743 conditions that can be changed during the lifetime of the 1744 subscription."; 1745 choice update-trigger { 1746 description 1747 "Defines necessary conditions for sending an event to 1748 the subscriber."; 1749 case periodic { 1750 description 1751 "The agent is requested to notify periodically the current 1752 values of the datastore as defined by the selection filter."; 1753 leaf period { 1754 type yang:timeticks; 1755 mandatory true; 1756 description 1757 "Duration of time which should occur between periodic 1758 push updates. Where the anchor of a start-time is 1759 available, the push will include the objects and their 1760 values which exist at an exact multiple of timeticks 1761 aligning to this start-time anchor."; 1762 } 1763 leaf anchor-time { 1764 type yang:date-and-time; 1765 description 1766 "Designates a timestamp from which the series of periodic 1767 push updates are computed. The next update will take place 1768 at the next period interval from the anchor time. For 1769 example, for an anchor time at the top of a minute and a 1770 period interval of a minute, the next update will be sent 1771 at the top of the next minute."; 1772 } 1773 } 1774 case on-change { 1775 if-feature "on-change"; 1776 description 1777 "The agent is requested to notify changes in values in the 1778 datastore subset as defined by a selection filter."; 1779 leaf dampening-period { 1780 type yang:timeticks; 1781 mandatory true; 1782 description 1783 "The shortest time duration which is allowed between the 1784 creation of independent yang object update messages. 1785 Effectively this is the amount of time that needs to have 1786 passed since the last update."; 1787 } 1788 } 1789 } 1790 } 1792 grouping update-policy { 1793 description 1794 "This grouping describes the datastore specific subscription 1795 conditions of a subscription."; 1796 uses update-policy-modifiable { 1797 augment "update-trigger/on-change" { 1798 description 1799 "Includes objects not modifiable once subscription is 1800 established."; 1801 leaf no-synch-on-start { 1802 type empty; 1803 description 1804 "This leaf acts as a flag that determines behavior at the 1805 start of the subscription. When present, synchronization 1806 of state at the beginning of the subscription is outside 1807 the scope of the subscription. Only updates about changes 1808 that are observed from the start time, i.e. only push- 1809 change-update notifications are sent. When absent (default 1810 behavior), in order to facilitate a receiver's 1811 synchronization, a full update is sent when the 1812 subscription starts using a push-update notification, just 1813 like in the case of a periodic subscription. After that, 1814 push-change-update notifications only are sent unless the 1815 Publisher chooses to resynch the subscription again."; 1816 } 1817 leaf-list excluded-change { 1818 type change-type; 1819 description 1820 "Use to restrict which changes trigger an update. 1821 For example, if modify is excluded, only creation and 1822 deletion of objects is reported."; 1823 } 1824 } 1825 } 1826 } 1828 grouping update-qos { 1829 description 1830 "This grouping describes Quality of Service information 1831 concerning a subscription. This information is passed to lower 1832 layers for transport prioritization and treatment"; 1833 leaf dscp { 1834 type inet:dscp; 1835 default "0"; 1836 description 1837 "The push update's IP packet transport priority. This is made 1838 visible across network hops to receiver. The transport 1839 priority is shared for all receivers of a given subscription."; 1840 } 1841 leaf weighting { 1842 type uint8 { 1843 range "0 .. 255"; 1844 } 1845 description 1846 "Relative weighting for a subscription. Allows an underlying 1847 transport layer perform informed load balance allocations 1848 between various subscriptions"; 1849 reference 1850 "RFC-7540, section 5.3.2"; 1851 } 1852 leaf dependency { 1853 type sn:subscription-id; 1854 description 1855 "Provides the Subscription ID of a parent subscription which 1856 has absolute priority should that parent have push updates 1857 ready to egress the publisher. In other words, there should be 1858 no streaming of objects from the current subscription if of 1859 the parent has something ready to push."; 1860 reference 1861 "RFC-7540, section 5.3.1"; 1862 } 1864 } 1866 grouping update-error-hints { 1867 description 1868 "Allow return additional negotiation hints that apply 1869 specifically to push updates."; 1870 leaf period-hint { 1871 type yang:timeticks; 1872 description 1873 "Returned when the requested time period is too short. This 1874 hint can assert an viable period for both periodic push 1875 cadence and on-change dampening."; 1876 } 1877 leaf error-path { 1878 type string; 1879 description 1880 "Reference to a YANG path which is associated with the error 1881 being returned."; 1882 } 1883 leaf object-count-estimate { 1884 type uint32; 1885 description 1886 "If there are too many objects which could potentially be 1887 returned by the selection filter, this identifies the estimate 1888 of the number of objects which the filter would potentially 1889 pass."; 1890 } 1891 leaf object-count-limit { 1892 type uint32; 1893 description 1894 "If there are too many objects which could be returned by the 1895 selection filter, this identifies the upper limit of the 1896 publisher's ability to service for this subscription."; 1897 } 1898 leaf kilobytes-estimate { 1899 type uint32; 1900 description 1901 "If the returned information could be beyond the capacity of 1902 the publisher, this would identify the data size which could 1903 result from this selection filter."; 1904 } 1905 leaf kilobytes-limit { 1906 type uint32; 1907 description 1908 "If the returned information would be beyond the capacity of 1909 the publisher, this identifies the upper limit of the 1910 publisher's ability to service for this subscription."; 1911 } 1913 } 1915 /* 1916 * DATA NODES 1917 */ 1919 augment "/sn:streams" { 1920 description 1921 "This augmentation adds datastores to the list of items that 1922 can be subscribed."; 1923 container datastores { 1924 config false; 1925 description 1926 "This container contains a leaf list of built-in 1927 streams that are provided by the system."; 1928 leaf-list datastore { 1929 type datastore; 1930 description 1931 "Identifies the built-in datastores that are supported by 1932 the system. Built-in datastores are associated with their 1933 own identities. In case configurable custom datastores are 1934 supported, as indicated by the custom-datastore identity. 1935 The configuration and delivery of those custom datastores is 1936 provided separately."; 1937 } 1938 } 1939 } 1940 augment "/sn:establish-subscription/sn:input" { 1941 description 1942 "This augmentation adds additional subscription parameters that 1943 apply specifically to datastore updates to RPC input."; 1944 uses update-policy; 1945 uses update-qos; 1946 } 1947 augment "/sn:establish-subscription/sn:input/sn:target" { 1948 description 1949 "This augmentation adds the datastore as a valid parameter object 1950 for the subscription to RPC input. This provides a target for 1951 the filter."; 1952 case datastore { 1953 uses datastore-criteria; 1954 } 1955 } 1956 augment "/sn:establish-subscription/sn:output/"+ 1957 "sn:result/sn:no-success" { 1958 description 1959 "This augmentation adds datastore specific error info 1960 and hints to RPC output."; 1962 uses update-error-hints; 1963 } 1964 augment "/sn:modify-subscription/sn:input" { 1965 description 1966 "This augmentation adds additional subscription parameters 1967 specific to datastore updates."; 1968 uses update-policy-modifiable; 1969 } 1970 augment "/sn:modify-subscription/sn:output/"+ 1971 "sn:result/sn:no-success" { 1972 description 1973 "This augmentation adds push datastore error info and hints to 1974 RPC output."; 1975 uses update-error-hints; 1976 } 1977 notification push-update { 1978 description 1979 "This notification contains a push update, containing data 1980 subscribed to via a subscription. This notification is sent for 1981 periodic updates, for a periodic subscription. It can also be 1982 used for synchronization updates of an on-change subscription. 1983 This notification shall only be sent to receivers of a 1984 subscription; it does not constitute a general-purpose 1985 notification."; 1986 leaf subscription-id { 1987 type sn:subscription-id; 1988 mandatory true; 1989 description 1990 "This references the subscription because of which the 1991 notification is sent."; 1992 } 1993 leaf time-of-update { 1994 type yang:date-and-time; 1995 description 1996 "This leaf contains the time of the update."; 1997 } 1998 leaf updates-not-sent { 1999 type empty; 2000 description 2001 "This is a flag which indicates that not all data nodes 2002 subscribed to are included with this update. In other words, 2003 the publisher has failed to fulfill its full subscription 2004 obligations. This may lead to intermittent loss of 2005 synchronization of data at the client. Synchronization at the 2006 client can occur when the next push-update is received."; 2007 } 2008 anydata datastore-contents { 2009 description 2010 "This contains the updated data. It constitutes a snapshot 2011 at the time-of-update of the set of data that has been 2012 subscribed to. The format and syntax of the data 2013 corresponds to the format and syntax of data that would be 2014 returned in a corresponding get operation with the same 2015 selection filter parameters applied."; 2016 } 2017 } 2018 notification push-change-update { 2019 if-feature "on-change"; 2020 description 2021 "This notification contains an on-change push update. This 2022 notification shall only be sent to the receivers of a 2023 subscription; it does not constitute a general-purpose 2024 notification."; 2025 leaf subscription-id { 2026 type sn:subscription-id; 2027 mandatory true; 2028 description 2029 "This references the subscription because of which the 2030 notification is sent."; 2031 } 2032 leaf time-of-update { 2033 type yang:date-and-time; 2034 description 2035 "This leaf contains the time of the update, i.e. the time at 2036 which the change was observed."; 2037 } 2038 leaf updates-not-sent { 2039 type empty; 2040 description 2041 "This is a flag which indicates that not all changes which 2042 have occurred since the last update are included with this 2043 update. In other words, the publisher has failed to 2044 fulfill its full subscription obligations, for example in 2045 cases where it was not able to keep up with a change burst. 2046 To facilitate synchronization, a publisher may subsequently 2047 send a push-update containing a full snapshot of subscribed 2048 data. Such a push-update might also be triggered by a 2049 subscriber requesting an on-demand synchronization."; 2050 } 2051 anydata datastore-changes { 2052 description 2053 "This contains datastore contents that has changed since the 2054 previous update, per the terms of the subscription. Changes 2055 are encoded analogous to the syntax of a corresponding yang- 2056 patch operation, i.e. a yang-patch operation applied to the 2057 YANG datastore implied by the previous update to result in the 2058 current state (and assuming yang-patch could also be applied 2059 to operational data)."; 2060 } 2061 } 2062 augment "/sn:subscription-started" { 2063 description 2064 "This augmentation adds many yang datastore specific objects to 2065 the notification that a subscription has started."; 2066 uses update-policy; 2067 uses update-qos; 2068 } 2069 augment "/sn:subscription-started/sn:target" { 2070 description 2071 "This augmentation allows the datastore to be included as part 2072 of the notification that a subscription has started."; 2073 case datastore { 2074 uses datastore-criteria; 2075 } 2076 } 2077 augment "/sn:subscription-modified" { 2078 description 2079 "This augmentation adds many yang datastore specific objects to 2080 the notification that a subscription has been modified."; 2081 uses update-policy; 2082 uses update-qos; 2083 } 2084 augment "/sn:subscription-config/sn:subscription" { 2085 description 2086 "This augmentation adds many yang datastore specific objects 2087 which can be configured as opposed to established via RPC."; 2088 uses update-policy; 2089 uses update-qos; 2090 } 2091 augment "/sn:subscription-config/sn:subscription/sn:target" { 2092 description 2093 "This augmentation adds the datastore to the selection filtering 2094 criteria for a subscription."; 2095 case datastore { 2096 uses datastore-criteria; 2097 } 2098 } 2099 augment "/sn:subscriptions/sn:subscription" { 2100 yp:notifiable-on-change true; 2101 description 2102 "This augmentation adds many datastore specific objects to a 2103 subscription."; 2104 uses update-policy; 2105 uses update-qos; 2107 } 2108 augment "/sn:subscriptions/sn:subscription/sn:target" { 2109 description 2110 "This augmentation allows the datastore to be included as part 2111 of the selection filtering criteria for a subscription."; 2112 case datastore { 2113 uses datastore-criteria; 2114 } 2115 } 2116 } 2118 2120 6. IANA Considerations 2122 This document registers the following namespace URI in the "IETF XML 2123 Registry" [RFC3688]: 2125 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push 2126 Registrant Contact: The IESG. 2127 XML: N/A; the requested URI is an XML namespace. 2129 This document registers the following YANG module in the "YANG Module 2130 Names" registry [RFC6020]: 2132 Name: ietf-yang-push 2133 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push 2134 Prefix: yp 2135 Reference: draft-ietf-netconf-yang-push-08.txt (RFC form) 2137 7. Security Considerations 2139 All security considerations from [subscribe] are relevant for 2140 datastores. In addition there are specific security considerations 2141 for receviers defined in Section 3.9 2143 If the access control permissions on subscribed YANG nodes change 2144 during the lifecycle of a subscription, a publisher MUST either 2145 transparently conform to the new access control permissions, or must 2146 terminate or restart the subscriptions so that new access control 2147 permissions are re-established. 2149 The NETCONF Authorization Control Model SHOULD be used to restrict 2150 the delivery of YANG nodes for which the receiver has no access. 2152 8. Acknowledgments 2154 For their valuable comments, discussions, and feedback, we wish to 2155 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei 2156 Guo, Michael Scharf, Sharon Chisholm, and Guangying Zheng. 2158 9. References 2160 9.1. Normative References 2162 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2163 DOI 10.17487/RFC3688, January 2004, . 2166 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2167 the Network Configuration Protocol (NETCONF)", RFC 6020, 2168 DOI 10.17487/RFC6020, October 2010, . 2171 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2172 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 2173 February 2012, . 2175 [RFC6536bis] 2176 Bierman, A. and M. Bjorklund, "Network Configuration 2177 Protocol (NETCONF) Access Control Model", draft-ietf- 2178 netconf-rfc6536bis-04 (work in progress), June 2017. 2180 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 2181 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 2182 . 2184 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2185 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2186 . 2188 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2189 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2190 . 2192 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2193 Media Type", RFC 8072, DOI 10.17487/RFC8072, February 2194 2017, . 2196 [subscribe] 2197 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 2198 and E. Nilsen-Nygaard, "Custom Subscription to Event 2199 Notifications", draft-ietf-netconf-subscribed- 2200 notifications-03 (work in progress), July 2017. 2202 9.2. Informative References 2204 [http-notif] 2205 Voit, E., Gonzalez Prieto, A., Tripathy, A., Nilsen- 2206 Nygaard, E., Clemm, A., and A. Bierman, "Restconf and HTTP 2207 Transport for Event Notifications", August 2017. 2209 [netconf-notif] 2210 Gonzalez Prieto, A., Clemm, A., Voit, E., Nilsen-Nygaard, 2211 E., and A. Tripathy, "NETCONF Support for Event 2212 Notifications", July 2017. 2214 [notifications2] 2215 Voit, E., Bierman, A., Clemm, A., and T. Jenkins, "YANG 2216 Notification Headers and Bundles", July 2017. 2218 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2219 and A. Bierman, Ed., "Network Configuration Protocol 2220 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2221 . 2223 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2224 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 2225 . 2227 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2228 for Subscription to YANG Datastores", RFC 7923, 2229 DOI 10.17487/RFC7923, June 2016, . 2232 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2233 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2234 . 2236 Appendix A. Relationships to other drafts 2238 There are other related drafts which are progressing in the NETCONF 2239 WG. This section details the relationship of this draft to those 2240 others. 2242 A.1. ietf-netconf-subscribed-notifications 2244 The draft [subscribe] is the techical foundation around which the 2245 rest of the YANG push datastore specific mechanisms are layered. 2247 A.2. ietf-netconf-netconf-event-notif 2249 The [netconf-notif] draft supports yang-push by defining NETCONF 2250 transport specifics. Included are: 2252 o bindings for RPC communications and Event Notifications over 2253 NETCONF. 2255 o encoded examples 2257 A.3. ietf-netconf-restconf-notif 2259 The [http-notif] draft supports yang-push by defining transport 2260 specific guidance where some form of HTTP is used underneath. 2261 Included are: 2263 o bindings for RPC communications over RESTCONF 2265 o bindings for Event Notifications over HTTP2 and HTTP1.1 2267 o encoded examples 2269 o end-to-end deployment guidance for Call Home and TLS Heartbeat 2271 A.4. voit-notifications2 2273 The draft [notifications2] is not required to implement yang-push. 2274 Instead it defines data plane notification elements which improve the 2275 delivered experience. The following capabilities are specified: 2277 o Defines common encapsulation headers objects to support 2278 functionality such as event severity, message signing, message 2279 loss discovery, message de-duplication, originating process 2280 identification. 2282 o Defines how to bundle multiple event records into a single 2283 notification message. 2285 These capabilities would be delivered by adding the drafts newly 2286 proposed header objects to the push-update and push-change-update 2287 notifications defined here. This draft is not yet adopted by the 2288 NETCONF WG. 2290 Appendix B. Technologies to be considered for future iterations 2292 B.1. Proxy YANG Subscription when the Subscriber and Receiver are 2293 different 2295 The properties of Dynamic and Configured Subscriptions can be 2296 combined to enable deployment models where the Subscriber and 2297 Receiver are different. Such separation can be useful with some 2298 combination of: 2300 o An operator does not want the subscription to be dependent on the 2301 maintenance of transport level keep-alives. (Transport 2302 independence provides different scalability characteristics.) 2304 o There is not a transport session binding, and a transient 2305 Subscription needs to survive in an environment where there is 2306 unreliable connectivity with the Receiver and/or Subscriber. 2308 o An operator wants the Publisher to include highly restrictive 2309 capacity management and Subscription security mechanisms outside 2310 of domain of existing operational or programmatic interfaces. 2312 To build a Proxy Subscription, first the necessary information must 2313 be signaled as part of the . Using this set 2314 of Subscriber provided information; the same process described within 2315 section 3 will be followed. 2317 After a successful establishment, if the Subscriber wishes to track 2318 the state of Receiver subscriptions, it may choose to place a 2319 separate on-change Subscription into the "Subscriptions" subtree of 2320 the YANG Datastore on the Publisher. 2322 B.2. OpState and Filters 2324 Currently the concept of datastores is undergoing a transformation. 2325 A new Network Management Datastore Architecture (NMDA) is currently 2326 being defined that will allow for improved handling and distinction 2327 of intended versus applied configurations. It will also extend the 2328 notion of a datastore to operational data. For implementations that 2329 are NMDA compliant in the future, some of the objects that are 2330 currently defined as operational data will no longer be required 2331 because they will in effect be redundant. Specifically, this 2332 concerns many of the objects in the read-only subscriptions branch of 2333 the tree. By omitting those objects, the model could be optimized 2334 further. However, there is no harm in the redundant objects and they 2335 allow for common management of YANG-Push subscriptions whether or not 2336 the underlying platform is fully NMDA-compliant, as opposed to 2337 exposing client applications to heterogeneity in platform NMDA 2338 capabilities. 2340 It is conceivable that filters are defined that apply to metadata, 2341 such as data nodes for which metadata has been defined that meets a 2342 certain criteria. 2344 It is also conceivable to define in the future filters that are 2345 applied to actual data node values. Doing so would allow 2346 applications to subscribe to updates that are sent only when object 2347 values meet certain criteria, such as being outside a certain range. 2349 Defining any such subscription filters at this point would be highly 2350 speculative in nature. However, it should be noted that 2351 corresponding extensions may be defined in future specifications. 2352 Any such extensions will be straightforward to accommodate by 2353 introducing a model that defines new filter types, and augmenting the 2354 new filter type into the subscription model. 2356 B.3. Splitting push updates 2358 Push updates may become fairly large and extend across multiple 2359 subsystems in a YANG-Push Server. As a result, it conceivable to not 2360 combine all updates into a single update message, but to split 2361 updates into multiple separate update messages. Such splitting could 2362 occur along multiple criteria: limiting the number of data nodes 2363 contained in a single update, grouping updates by subtree, grouping 2364 updates by internal subsystems (e.g., by line card), or grouping them 2365 by other criteria. 2367 Splitting updates bears some resemblance to fragmenting packets. In 2368 effect, it can be seen as fragmenting update messages at an 2369 application level. However, from a transport perspective, splitting 2370 of update messages is not required as long as the transport does not 2371 impose a size limitation or provides its own fragmentation mechanism 2372 if needed. We assume this to be the case for YANG-Push. In the case 2373 of NETCONF, RESTCONF, HTTP/2, no limit on message size is imposed. 2374 In case of other transports, any message size limitations need to be 2375 handled by the corresponding transport mapping. 2377 There may be some scenarios in which splitting updates might still 2378 make sense. For example, if updates are collected from multiple 2379 independent subsystems, those updates could be sent separately 2380 without need for combining. However, if updates were to be split, 2381 other issues arise. Examples include indicating the number of 2382 updates to the receiver, distinguishing a missed fragment from a 2383 missed update, and the ordering with which updates are received. 2384 Proper addressing those issues would result in considerable 2385 complexity, while resulting in only very limited gains. In addition, 2386 if a subscription is found to result in updates that are too large, a 2387 publisher can always reject the request for a subscription while the 2388 subscriber is always free to break a subscription up into multiple 2389 subscriptions. 2391 B.4. Potential Subscription Parameters 2393 A possible is the introduction of an additional parameter "changes- 2394 only" for periodic subscription. Including this flag would results 2395 in sending at the end of each period an update containing only 2396 changes since the last update (i.e. a change-update as in the case of 2397 an on-change subscription), not a full snapshot of the subscribed 2398 information. Such an option might be interesting in case of data 2399 that is largely static and bandwidth-constrained environments. 2401 Appendix C. Changes between revisions 2403 (To be removed by RFC editor prior to publication) 2405 v07 - v08 2407 o Updated YANG models with minor tweaks to accommodate changes of 2408 ietf-subscribed-notifications. 2410 v06 - v07 2412 o Clarifying text tweaks. 2414 o Clarification that filters act as selectors for subscribed data 2415 nodes; support for value filters not included but possible as a 2416 future extension 2418 o Filters don't have to be matched to existing YANG objects 2420 v05 - v06 2422 o Security considerations updated. 2424 o Base YANG model in [sn] updated as part of move to identities, 2425 YANG augmentations in this doc matched up 2427 o Terms refined and text updates throughout 2429 o Appendix talking about relationship to other drafts added. 2431 o Datastore replaces stream 2432 o Definitions of filters improved 2434 v04 to v05 2436 o Referenced based subscription document changed to Subscribed 2437 Notifications from 5277bis. 2439 o Getting operational data from filters 2441 o Extension notifiable-on-change added 2443 o New appendix on potential futures. Moved text into there from 2444 several drafts. 2446 o Subscription configuration section now just includes changed 2447 parameters from Subscribed Notifications 2449 o Subscription monitoring moved into Subscribed Notifications 2451 o New error and hint mechanisms included in text and in the yang 2452 model. 2454 o Updated examples based on the error definitions 2456 o Groupings updated for consistency 2458 o Text updates throughout 2460 v03 to v04 2462 o Updates-not-sent flag added 2464 o Not notifiable extension added 2466 o Dampening period is for whole subscription, not single objects 2468 o Moved start/stop into rfc5277bis 2470 o Client and Server changed to subscriber, publisher, and receiver 2472 o Anchor time for periodic 2474 o Message format for synchronization (i.e. synch-on-start) 2476 o Material moved into 5277bis 2478 o QoS parameters supported, by not allowed to be modified by RPC 2479 o Text updates throughout 2481 Authors' Addresses 2483 Alexander Clemm 2484 Huawei 2486 Email: ludwig@clemm.org 2488 Eric Voit 2489 Cisco Systems 2491 Email: evoit@cisco.com 2493 Alberto Gonzalez Prieto 2494 VMware 2496 Email: agonzalezpri@vmware.com 2498 Ambika Prasad Tripathy 2499 Cisco Systems 2501 Email: ambtripa@cisco.com 2503 Einar Nilsen-Nygaard 2504 Cisco Systems 2506 Email: einarnn@cisco.com 2508 Andy Bierman 2509 YumaWorks 2511 Email: andy@yumaworks.com 2513 Balazs Lengyel 2514 Ericsson 2516 Email: balazs.lengyel@ericsson.com