idnits 2.17.1 draft-ietf-netconf-yang-push-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 242: '...cription request SHOULD be declined if...' RFC 2119 keyword, line 250: '... subscriptions SHOULD support a simp...' RFC 2119 keyword, line 253: '...-success message SHOULD include in the...' RFC 2119 keyword, line 280: '... publisher MAY accept an on-change s...' RFC 2119 keyword, line 292: '...ely, a publisher MAY decide to simply ...' (48 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 998 has weird spacing: '...ntifier sub...' == Line 1000 has weird spacing: '...-result sub...' == Line 1003 has weird spacing: '...ntifier sub...' == Line 1005 has weird spacing: '...-result sub...' == Line 1009 has weird spacing: '...ntifier sub...' == (7 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 (October 2, 2017) is 2397 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 2303, but no explicit reference was found in the text == Outdated reference: A later version (-09) exists of draft-ietf-netconf-rfc6536bis-05 -- Possible downref: Normative reference to a draft: ref. 'RFC6536bis' ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 2 errors (**), 0 flaws (~~), 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: April 5, 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 October 2, 2017 17 Subscribing to YANG datastore push updates 18 draft-ietf-netconf-yang-push-10 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 https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on April 5, 2018. 45 Copyright Notice 47 Copyright (c) 2017 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 This document may contain material from IETF Documents or IETF 61 Contributions published or made publicly available before November 62 10, 2008. The person(s) controlling the copyright in some of this 63 material may not have granted the IETF Trust the right to allow 64 modifications of such material outside the IETF Standards Process. 65 Without obtaining an adequate license from the person(s) controlling 66 the copyright in such materials, this document may not be modified 67 outside the IETF Standards Process, and derivative works of it may 68 not be created outside the IETF Standards Process, except to format 69 it for publication as an RFC or to translate it into languages other 70 than English. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 75 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4 76 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 4 77 3.1. 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 . . . . . . . . . . . . . . 7 81 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 8 82 3.6. Datastore Selection Filters . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . 16 87 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 17 88 4. A YANG data model for management of datastore push 89 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 18 90 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 18 91 4.2. Subscription configuration . . . . . . . . . . . . . . . 25 92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 27 93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 28 94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 33 95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 48 97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49 98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 99 9.1. Normative References . . . . . . . . . . . . . . . . . . 49 100 9.2. Informative References . . . . . . . . . . . . . . . . . 50 101 Appendix A. Changes between revisions . . . . . . . . . . . . . 50 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 53 104 1. Introduction 106 Traditional approaches to remote visibility have been built on 107 polling. With polling, data is periodically requested and retrieved 108 by a client from a server to stay up-to-date. However, there are 109 issues associated with polling-based management: 111 o Polling incurs significant latency. This latency prohibits many 112 application types. 114 o Polling cycles may be missed, requests may be delayed or get lost, 115 often when the network is under stress and the need for the data 116 is the greatest. 118 o Polling requests may undergo slight fluctuations, resulting in 119 intervals of different lengths. The resulting data is difficult 120 to calibrate and compare. 122 o For applications that monitor for changes, many remote polling 123 cycles place ultimately fruitless load on the network, devices, 124 and applications. 126 A more effective alternative to polling is for an application to 127 receive automatic and continuous updates from a targeted subset of a 128 datastore. Accordingly, there is a need for a service that allows 129 applications to subscribe to updates from a YANG datastore and that 130 enables the publisher to push and in effect stream those updates. 131 The requirements for such a service have been documented in 132 [RFC7923]. 134 This document defines a corresponding solution that is built on top 135 of "Custom Subscription to Event Notifications" [subscribe]. 136 Supplementing that work are YANG data model augmentations, extended 137 RPCs, and new datastore specific update notifications. Transport 138 options for [subscribe] will work seamlessly with this solution. 140 2. Definitions and Acronyms 142 The terms below supplement those defined in [subscribe]. 144 Data node: An instance of management information in a YANG datastore. 146 Data node update: A data item containing the current value/property 147 of a Data node at the time the data node update was created. 149 Datastore: A conceptual store of instantiated management information, 150 with individual data items represented by data nodes which are 151 arranged in hierarchical manner. 153 Data subtree: An instantiated data node and the data nodes that are 154 hierarchically contained within it. 156 Notification message: A transport encapsulated update record(s) and/ 157 or event notification(s) intended to be sent to a receiver. 159 Update notification message: A notification message that contains an 160 update record. 162 Update record: A representation data node update(s) resulting from 163 the application of a filter for a subscription. An update record 164 will include the value/property of one or more data nodes at a point 165 in time. It may contain the update type for each data node (e.g., 166 add, change, delete). Also included may be metadata/headers such as 167 a subscription-id. 169 Update trigger: A mechanism that determines when an update record 170 needs to be generated. 172 YANG-Push: The subscription and push mechanism for YANG datastores 173 that is specified in this document. 175 3. Solution Overview 177 This document specifies a solution for a push update subscription 178 service. This solution supports the dynamic as well as configured 179 subscriptions to information updates from YANG datastores. 180 Subscriptions specify when update notification messages should be 181 sent and what data to include in update records. YANG objects are 182 subsequently pushed from the publisher to the receiver per the terms 183 of the subscription. 185 3.1. Event Subscription Model 187 YANG-push subscriptions are defined using a data model that is itself 188 defined in YANG. This model enhances the event subscription model 189 defined in [subscribe] with capabilities that allow subscribers to 190 subscribe to data node updates, specifically to specify the triggers 191 defining when to generate update records as well as what to include 192 in an update record. Key enhancements include: 194 o Specification of selection filters which identify targeted YANG 195 data nodes and/or subtrees within a datastore for which updates 196 are to be pushed. 198 o An encoding (using anydata) for the contents of periodic and on- 199 change push updates. 201 o Specification of update policies contain conditions which trigger 202 the generation and pushing of new update records. There are two 203 types of triggers for subscriptions: periodic and on-change. 205 * For periodic subscriptions, the trigger is specified by two 206 parameters that define when updates are to be pushed. These 207 parameters are the period interval with which to report 208 updates, and an anchor time which can be used to calculate at 209 which point in time updates need to be assembled and sent. 211 * For on-change subscriptions, a trigger occurs whenever a change 212 in the subscribed information is detected. Included are 213 additional parameters such as: 215 + Dampening period: In an on-change subscription, the first 216 change that is detected results in an update to be sent 217 immediately. However, sending successive updates whenever 218 further changes are detected might result in quick 219 exhaustion of resources in case of very rapid changes. In 220 order to protect against that, a dampening period is used to 221 specify the interval which must pass before successive 222 update records for the same subscription are generated. The 223 dampening period collectively applies to the set of all data 224 nodes of a single subscription. This means that when there 225 is a change to a subscribed object, an update record 226 containing that object is created either immediately when no 227 dampening period is already in effect, or at the end of a 228 dampening period. 230 + Change type: This parameter can be used to reduce the types 231 of datastore changes for which updates are sent (e.g., you 232 might only send when an object is created or deleted, but 233 not when an object value changes). 235 + No Synch on start: defines whether or not a complete push- 236 update of all subscribed data will be sent at the beginning 237 of a subscription. Such early synchronization establishes 238 the frame of reference for subsequent updates. 240 3.2. Negotiation of Subscription Policies 242 A dynamic subscription request SHOULD be declined if a publisher's 243 assessment is that it may be unable to provide update records meeting 244 the terms of the request. In this case, a subscriber may quickly 245 follow up with a new subscription request using different parameters. 247 Random guessing at different parameters by a subscriber is to be 248 discouraged. Therefore, in order to minimize the number of 249 subscription iterations between subscriber and publisher, dynamic 250 subscriptions SHOULD support a simple negotiation between subscribers 251 and publishers for subscription parameters. This negotiation is in 252 the form of a no-success response to a failed establish or modify 253 subscription request. The no-success message SHOULD include in the 254 returned error response information that, when considered, increases 255 the likelihood of success for subsequent requests. However, there 256 are no guarantees that subsequent requests for this subscriber will 257 be accepted. 259 [subscribe] contains several negotiable subscription parameters. 260 Additional yang-push negotiation information defined in this 261 specification includes hints at acceptable time intervals, size 262 estimates for the number or objects which would be returned from a 263 filter, and the location of an error in a provided filter. 265 3.3. On-Change Considerations 267 On-change subscriptions allow subscribers to subscribe to updates 268 whenever changes to targeted objects occur. As such, on-change 269 subscriptions are particularly effective for data that changes 270 infrequently, yet for which applications need to be quickly notified 271 whenever a change does occur with minimal delay. 273 On-change subscriptions tend to be more difficult to implement than 274 periodic subscriptions. Accordingly, on-change subscriptions may not 275 be supported by all implementations or for every object. 277 Whether or not to accept or reject on-change subscription requests 278 when the scope of the subscription contains objects for which on- 279 change is not supported is up to the publisher implementation. A 280 publisher MAY accept an on-change subscription even when the scope of 281 the subscription contains objects for which on-change is not 282 supported. In that case, updates are sent only for those objects 283 within the scope that do support on-change updates whereas other 284 objects are excluded from update records, whether or not their values 285 actually change. In order for a subscriber to determine whether 286 objects support on-change subscriptions, objects are marked 287 accordingly on a publisher. Accordingly, when subscribing, it is the 288 responsibility of the subscriber to ensure it is aware of which 289 objects support on-change and which do not. For more on how objects 290 are so marked, see Section 3.10. 292 Alternatively, a publisher MAY decide to simply reject an on-change 293 subscription in case the scope of the subscription contains objects 294 for which on-change is not supported. In case of a configured 295 subscription, the subscription MAY be suspended. 297 To avoid flooding receivers with repeated updates for subscriptions 298 containing fast-changing objects, or objects with oscillating values, 299 an on-change subscription allows for the definition of a dampening 300 period. Once an update record for a given object is generated, no 301 other updates for this particular subscription will be created until 302 the end of the dampening period. Values sent at the end of the 303 dampening period are the current values of all changed objects which 304 are current at the time the dampening period expires. Changed 305 objects include those which were deleted or newly created during that 306 dampening period. If an object has returned to its original value 307 (or even has been created and then deleted) during the dampening- 308 period, the last change will still be sent. This will indicate churn 309 is occurring on that object. 311 In cases where a subscriber wants to have separate dampening periods 312 for different objects, multiple subscriptions with different objects 313 in a selection filter can be created. 315 On-change subscriptions can be refined to let users subscribe only to 316 certain types of changes. For example, a subscriber might only want 317 object creations and deletions, but not modifications of object 318 values. 320 3.4. Promise-Theory Considerations 322 A subscription to updates from a YANG datastore is intended to 323 obviate the need for polling. However, in order to do so, it is 324 critical that subscribers can rely on the subscription and have 325 confidence that they will indeed receive the subscribed updates 326 without having to worry updates being silently dropped. In other 327 words, a subscription constitutes a promise on the side of the 328 publisher to provide the receivers with updates per the terms of the 329 subscription. 331 Now, there are many reasons why a publisher may at some point no 332 longer be able to fulfill the terms of the subscription, even if the 333 subscription had been entered into with good faith. For example, the 334 volume of data objects may be larger than anticipated, the interval 335 may prove too short to send full updates in rapid succession, or an 336 internal problem may prevent objects from being collected. If for 337 some reason the publisher of a subscription is not able to keep its 338 promise, receivers MUST be notified immediately and reliably. The 339 publisher MAY also suspend the subscription. 341 A publisher SHOULD reject a request for a subscription if it is 342 unlikely that the publisher will be able fulfill the terms of that 343 subscription request. In such cases, it is preferable to have a 344 subscriber request a less resource intensive subscription than to 345 deal with frequently degraded behavior. 347 3.5. Data Encodings 349 A publisher MUST support XML encoding and MAY support other encodings 350 such as JSON encoding. 352 3.5.1. Periodic Subscriptions 354 In a periodic subscription, the data included as part of an update 355 corresponds to data that could have been simply retrieved using a get 356 operation and is encoded in the same way. XML encoding rules for 357 data nodes are defined in [RFC7950]. JSON encoding rules are defined 358 in [RFC7951]. 360 3.5.2. On-Change Subscriptions 362 In an on-change subscription, updates need to indicate not only 363 values of changed data nodes but also the types of changes that 364 occurred since the last update. Therefore encoding rules for data in 365 on-change updates will follow YANG-patch operation as specified in 366 [RFC8072]. The YANG-patch will describe what needs to be applied to 367 the earlier state reported by the preceding update, to result in the 368 now-current state. Note that contrary to [RFC8072], objects 369 encapsulated are not restricted to configuration objects only. 371 3.6. Datastore Selection Filters 373 Subscription policy specifies both the selection filters and the 374 datastores against which these selection filters will be applied. 376 The result is the push of information necessary to remotely maintain 377 an extract of the publisher's datastore. 379 Only a single selection filter can be applied to a subscription at a 380 time. The following selection filter types are included in the yang- 381 push data model, and may be applied against a datastore: 383 o subtree: A subtree selection filter identifies one or more 384 subtrees. When specified, updates will only come from the data 385 nodes of selected YANG subtree(s). The syntax and semantics 386 correspond to that specified for [RFC6241] section 6. 388 o xpath: An xpath selection filter is an XPath expression which may 389 be meaningfully applied to a datastore. It is the results of this 390 expression which will be pushed. 392 These filters are intended to be used as selectors that define which 393 objects are within the scope of a subscription. Filters are not 394 intended to be used to filter objects based on a non-key property. 395 Supporting non-key property filtering so would have a number of 396 implications that would result in significant complexity. While it 397 is possible to define extensions in the future that will support 398 selection filtering based on values, this is not supported in this 399 version of yang-push and a publisher MAY reject a subscription 400 request that contains a filter for object values. 402 Xpath itself provides powerful filtering constructs, and care must be 403 used in filter definition. As an example, consider an xpath filter 404 with a boolean result; such a result will not provide an easily 405 interpretable subset of a datastore. Beyond the boolean example, it 406 is quite possible to define an xpath filter where results are easy 407 for an application to mis-interpret. Consider an xpath filter which 408 only passes a datastore object when an interface is up. It is up to 409 the receiver to understand implications of the presence or absence of 410 objects in each update. 412 It is not expected that implementations will support comprehensive 413 filter syntax and boundless complexity. It will be up to 414 implementations to describe what is viable, but the goal is to 415 provide equivalent capabilities to what is available with a GET. 416 Implementations MUST reject dynamic subscriptions or suspend 417 configured subscriptions if they include filters which are 418 unsupportable on a platform. 420 3.7. Streaming Updates 422 Contrary to traditional data retrieval requests, datastore 423 subscription enables an unbounded series of update records to be 424 streamed over time. Two generic notifications for update records 425 have been defined for this: "push-update" and "push-change-update". 427 A push-update notification defines a complete, filtered update of the 428 datastore per the terms of a subscription. This type of notification 429 is used for continuous updates of periodic subscriptions. A push- 430 update notification can also be used for the on-change subscriptions 431 in two cases. First it will be used as the initial push-update if 432 there is a need to synchronize the receiver at the start of a new 433 subscription. It also MAY be sent if the publisher later chooses to 434 resynch an on-change subscription. The push-update record contains a 435 data snippet that contains an instantiated subtree with the 436 subscribed contents. The content of the update record is equivalent 437 to the contents that would be obtained had the same data been 438 explicitly retrieved using e.g., a NETCONF "get" operation, with the 439 same filters applied. 441 A push-change-update notification is the most common type of update 442 for on-change subscriptions. The update record in this case contains 443 a data snippet that indicates the set of changes that data nodes have 444 undergone since the last notification of YANG objects. In other 445 words, this indicates which data nodes have been created, deleted, or 446 have had changes to their values. In cases where multiple changes 447 have occurred and the object has not been deleted, the object's most 448 current value is reported. (In other words, for each object, only 449 one change is reported, not its entire history. Doing so would 450 defeat the purpose of the dampening period.) 452 These new push-update or push-change-update are encoded and placed 453 within notification messages, and ultimately queued for egress over 454 the specified transport. 456 The following is an example of an XML encoded notification message 457 over NETCONF transport as per [netconf-notif]. 459 461 2015-03-09T19:14:56Z 462 464 1011 465 2015-03-09T19:14:55.233Z 466 467 468 some_string 469 470 471 472 474 Figure 1: Push example 476 The following is an example of an on-change notification. It 477 contains an update for subscription 89, including a new value for a 478 leaf called beta, which is a child of a top-level container called 479 alpha: 481 483 2015-03-09T19:14:56Z 484 486 89 487 2015-03-09T19:14:55.233Z 488 489 490 1500 491 492 493 494 496 Figure 2: Push example for on change 498 The equivalent update when requesting json encoding: 500 502 2015-03-09T19:14:56Z 503 505 89 506 2015-03-09T19:14:55.233Z 507 508 { 509 "ietf-yang-patch:yang-patch": { 510 "patch-id": [ 511 null 512 ], 513 "edit": [ 514 { 515 "edit-id": "edit1", 516 "operation": "merge", 517 "target": "/alpha/beta", 518 "value": { 519 "beta": 1500 520 } 521 } 522 ] 523 } 524 } 525 526 527 529 Figure 3: Push example for on change with JSON 531 When the beta leaf is deleted, the publisher may send 532 534 2015-03-09T19:14:56Z 535 537 89 538 2015-03-09T19:14:55.233Z 539 540 541 543 544 545 546 548 Figure 4: 2nd push example for on change update 550 3.8. Subscription Management 552 The RPCs defined within [subscribe] have been enhanced to support 553 YANG datastore subscription negotiation. Included in these 554 enhancements are error codes which can indicate why a datastore 555 subscription attempt has failed. 557 A datastore subscription can be rejected for multiple reasons. This 558 includes a too large subtree request, or the inability of the 559 publisher push update records as frequently as requested. In such 560 cases, no subscription is established. Instead, the subscription- 561 result with the failure reason is returned as part of the RPC 562 response. As part of this response, a set of alternative 563 subscription parameters MAY be returned that would likely have 564 resulted in acceptance of the subscription request. The subscriber 565 may consider these as part of future subscription attempts. 567 For instance, for the following request: 569 571 573 574 operational 575 578 579 500 580 encode-xml 581 582 584 Figure 5: Establish-Subscription example 586 the publisher might return: 588 590 592 error-insufficient-resources 593 594 2000 595 597 Figure 6: Error response example 599 As can be seen above the rejected subscription does not result in the 600 generation of an rpc-reply with an rpc-error element. YANG-push 601 specific errors and negotiation hints part are returned as part of 602 normal RPC operations. 604 3.9. Receiver Authorization 606 A receiver of subscription data MUST only be sent updates for which 607 they have proper authorization. A publisher MUST ensure that no non- 608 authorized data is included in push updates. To do so, it needs to 609 apply all corresponding checks applicable at the time of a specific 610 pushed update and if necessary silently remove any non-authorized 611 data from subtrees. This enables YANG data pushed based on 612 subscriptions to be authorized equivalently to a regular data 613 retrieval (get) operation. 615 A publisher MAY allow subscriptions which select non-existent or 616 access-protected data. Such a capability permits a receiver the 617 ability to monitor the entire lifecyle of the data. In this case, 618 all push-updates must be sent empty, and no push-change-updates will 619 be sent until the data becomes visible for a receiver. 621 A publisher MAY alternatively choose not to allow subscriptions which 622 select non-existent or access-protected data. Such a capability 623 enables the publisher to avoid having to perform filtering of 624 authorized content on each update. Relevant scenarios here include: 626 o the rejecting of a subscription request to access-protected 627 objects, 629 o the suspension of a subscription where new access-controlled 630 objects are selected mid-subscription for which the receiver does 631 not have the necessary authorization, or 633 o the authorization privileges of a receiver change over the course 634 of the subscription. 636 In all these cases, the error identity "data-unavailable" SHOULD be 637 returned. This reduces the possibility of access permission leakage. 639 The contextual authorization model for data in YANG datastores is the 640 NETCONF Access Control Model [RFC6536bis], Section 3.2.4. A 641 clarification to this is that each of the individual nodes in a 642 resulting update record MUST also have applied access control to 643 resulting pushed messages. This includes validating that read access 644 is ok for any nodes newly selected since the last update record for 645 each receiver. 647 +-------------+ +-------------------+ 648 push-update / --> | data node | yes | | 649 push-change-update | access | ---> | add data node | 650 | allowed? | | to update message | 651 +-------------+ +-------------------+ 653 Figure 7: Access control for push updates 655 If read access into previously accessible nodes has been lost due to 656 a receiver permissions change, this SHOULD be reported as node 657 'delete' operations for on-change subscriptions. If not capable of 658 handling such receiver permission changes with such a 'delete', 659 publisher implementations MUST force dynamic subscription re- 660 establishment or configured subscription re-initialization so that 661 appropriate filtering is installed. 663 3.10. On-change Notifiable YANG objects 665 In some cases, a publisher supporting on-change notifications may not 666 be able to push updates for some object types on-change. Reasons for 667 this might be that the value of the data node changes frequently 668 (e.g., [RFC7223]'s in-octets counter), that small object changes are 669 frequent and meaningless (e.g., a temperature gauge changing 0.1 670 degrees), or that the implementation is not capable of on-change 671 notification for a particular object. 673 Support for on-change notification is usually specific to the 674 individual YANG model and/or implementation so it is possible to 675 define in design time. System integrators need this information 676 (without reading any data from a live node). 678 The default assumption is that no data nodes support on-change 679 notification. Schema nodes and subtrees that support on-change 680 notifications MUST be marked by accordingly with the YANG extension 681 "notifiable-on-change". This extension is defined in the data model 682 below. 684 When an on-change subscription is established, data-nodes are 685 automatically excluded unless they are marked with notifiable-on- 686 change as true. This also means that authorization checks SHALL NOT 687 be performed on them. A subscriber can identify which nodes may be 688 included in on-change updates by retrieving the data nodes in the 689 subscription's scope and checking for which notifiable-on-change is 690 marked as true. 692 In theory, adding notifiable-on-change markings can be done within 693 corresponding YANG models. But a more extensible way to avoid having 694 to modify existing module definitions is to add notifiable-on-change 695 markings within separate module deviations. This means that when a 696 YANG model designer wants to add a notifiable-on-change marking to 697 nodes of an existing module without modifying the module definitions, 698 a new module is introduced that contains deviation statements which 699 add "notifiable-on-change" statements as applicable. 701 deviation /sys:system/sys:system-time { 702 deviate add { 703 yp:notifiable-on-change false; 704 } 705 } 707 Figure 8: Deviation Example 709 3.11. Other Considerations 711 3.11.1. Robustness and reliability 713 Particularly in the case of on-change push updates, it is important 714 that push updates do not get lost or, in case the loss of an update 715 is unavoidable, that the receiver is notified accordingly. 717 Update messages for a single subscription MAY NOT be resequenced. 719 It is conceivable that under certain circumstances, a publisher will 720 recognize that it is unable to include within an update record the 721 full set of objects desired per the terms of a subscription. In this 722 case, the publisher MUST take one or more of the following actions. 724 o A publisher MUST set the updates-not-sent flag on any update 725 record which is known to be missing information. 727 o It MAY choose to suspend a subscription as per [subscribe]. 729 o When resuming an on-change subscription, the publisher SHOULD 730 generate a complete patch from the previous update record. If 731 this is not possible and the synch-on-start option is configured, 732 then the full datastore contents MAY be sent via a push-update 733 instead (effectively replacing the previous contents). If neither 734 of these are possible, then an updates-not-sent flag MUST be 735 included on the next push-change-update. 737 Note: It is perfectly acceptable to have a series of push-change- 738 updates (and even push updates) serially queued at the transport 739 layer awaiting transmission. It is not required to merge pending 740 update messages. I.e., the dampening period applies to update record 741 creation, not transmission. 743 3.11.2. Publisher capacity 745 It is far preferable to decline a subscription request than to accept 746 such a request when it cannot be met. 748 Whether or not a subscription can be supported will be determined by 749 a combination of several factors such as the subscription trigger 750 (on-change or periodic), the period in which to report changes (1 751 second periods will consume more resources than 1 hour periods), the 752 amount of data in the subtree that is being subscribed to, and the 753 number and combination of other subscriptions that are concurrently 754 being serviced. 756 4. A YANG data model for management of datastore push subscriptions 758 4.1. Overview 760 The YANG data model for datastore push subscriptions is depicted in 761 the following figure. Following YANG tree convention in the 762 depiction, brackets enclose list keys, "rw" means configuration, "ro" 763 operational state data, "?" designates optional nodes, "*" designates 764 nodes that can have multiple instances. Parentheses with a name in 765 the middle enclose choice and case nodes. New YANG objects defined 766 here (i.e., beyond those from [subscribe]) are identified with "yp". 768 module: ietf-subscribed-notifications 769 +--ro streams 770 | +--ro stream* [name] 771 | +--ro name stream 772 | +--ro description string 773 | +--ro replay-support? empty {replay}? 774 | +--ro replay-log-creation-time? yang:date-and-time {replay}? 775 | +--ro replay-log-aged-time? yang:date-and-time {replay}? 776 +--rw filters 777 | +--rw event-filter* [identifier] 778 | | +--rw identifier filter-id 779 | | +--rw (filter-spec)? 780 | | +--:(subtree-filter) 781 | | | +--rw subtree-filter? 782 | | +--:(xpath-filter) 783 | | +--rw xpath-filter? yang:xpath1.0 784 | +--rw yp:selection-filter* [identifier] 785 | +--rw yp:identifier sn:filter-id 786 | +--rw (yp:filter-spec)? 787 | +--:(yp:subtree-filter) 788 | | +--rw yp:subtree-filter? 789 | +--:(yp:xpath-filter) 790 | +--rw yp:xpath-filter? yang:xpath1.0 791 +--rw subscription-config {configured-subscriptions}? 792 | +--rw subscription* [identifier] 793 | +--rw identifier subscription-id 794 | +--rw encoding? encoding 795 | +--rw (target) 796 | | +--:(stream) 797 | | | +--rw (event-filter)? 798 | | | | +--:(by-reference) 799 | | | | | +--rw event-filter-ref event-filter-ref 800 | | | | +--:(within-subscription) 801 | | | | +--rw (filter-spec)? 802 | | | | +--:(subtree-filter) 803 | | | | | +--rw subtree-filter? 804 | | | | +--:(xpath-filter) 805 | | | | +--rw xpath-filter? yang:xpath1.0 806 | | | +--rw stream stream 807 | | | +--rw replay-start-time? yang:date-and-time {replay}? 808 | | +--:(yp:datastore) 809 | | +--rw yp:source identityref 810 | | +--rw (yp:selected-content)? 811 | | +--:(yp:by-reference) 812 | | | +--rw yp:selection-filter-ref selection-filter-ref 813 | | +--:(yp:within-subscription) 814 | | +--rw (yp:filter-spec)? 815 | | +--:(yp:subtree-filter) 816 | | | +--rw yp:subtree-filter? 817 | | +--:(yp:xpath-filter) 818 | | +--rw yp:xpath-filter? yang:xpath1.0 819 | +--rw stop-time? yang:date-and-time 820 | +--rw receivers 821 | | +--rw receiver* [address port] 822 | | +--rw address inet:host 823 | | +--rw port inet:port-number 824 | | +--rw protocol? transport-protocol 825 | +--rw (notification-origin)? 826 | | +--:(interface-originated) 827 | | | +--rw source-interface? if:interface-ref 828 | | +--:(address-originated) 829 | | +--rw source-vrf? string 830 | | +--rw source-address? inet:ip-address-no-zone 831 | +--rw (yp:update-trigger)? 832 | | +--:(yp:periodic) 833 | | | +--rw yp:period yang:timeticks 834 | | | +--rw yp:anchor-time? yang:date-and-time 835 | | +--:(yp:on-change) {on-change}? 836 | | +--rw yp:dampening-period yang:timeticks 837 | | +--rw yp:no-synch-on-start? empty 838 | | +--rw yp:excluded-change* change-type 839 | +--rw yp:dscp? inet:dscp 840 | +--rw yp:weighting? uint8 841 | +--rw yp:dependency? sn:subscription-id 842 +--ro subscriptions 843 +--ro subscription* [identifier] 844 +--ro identifier subscription-id 845 +--ro configured-subscription? 846 | empty {configured-subscriptions}? 847 +--ro encoding? encoding 848 +--ro (target) 849 | +--:(stream) 850 | | +--ro (event-filter)? 851 | | | +--:(by-reference) 852 | | | | +--ro event-filter-ref event-filter-ref 853 | | | +--:(within-subscription) 854 | | | +--ro (filter-spec)? 855 | | | +--:(subtree-filter) 856 | | | | +--ro subtree-filter? 857 | | | +--:(xpath-filter) 858 | | | +--ro xpath-filter? yang:xpath1.0 859 | | +--ro stream stream 860 | | +--ro replay-start-time? yang:date-and-time {replay}? 861 | +--:(yp:datastore) 862 | +--ro yp:source identityref 863 | +--ro (yp:selected-content)? 864 | +--:(yp:by-reference) 865 | | +--ro yp:selection-filter-ref selection-filter-ref 866 | +--:(yp:within-subscription) 867 | +--ro (yp:filter-spec)? 868 | +--:(yp:subtree-filter) 869 | | +--ro yp:subtree-filter? 870 | +--:(yp:xpath-filter) 871 | +--ro yp:xpath-filter? yang:xpath1.0 872 +--ro stop-time? yang:date-and-time 873 +--ro (notification-origin)? 874 | +--:(interface-originated) 875 | | +--ro source-interface? if:interface-ref 876 | +--:(address-originated) 877 | +--ro source-vrf? string 878 | +--ro source-address? inet:ip-address-no-zone 879 +--ro receivers 880 | +--ro receiver* [address port] 881 | +--ro address inet:host 882 | +--ro port inet:port-number 883 | +--ro protocol? transport-protocol 884 | +--ro pushed-notifications? yang:counter64 885 | +--ro excluded-notifications? yang:counter64 886 | +--ro status subscription-status 887 +--ro (yp:update-trigger)? 888 | +--:(yp:periodic) 889 | | +--ro yp:period yang:timeticks 890 | | +--ro yp:anchor-time? yang:date-and-time 891 | +--:(yp:on-change) {on-change}? 892 | +--ro yp:dampening-period yang:timeticks 893 | +--ro yp:no-synch-on-start? empty 894 | +--ro yp:excluded-change* change-type 895 +--ro yp:dscp? inet:dscp 896 +--ro yp:weighting? uint8 897 +--ro yp:dependency? sn:subscription-id 899 rpcs: 901 +---x establish-subscription 902 | +---w input 903 | | +---w encoding? encoding 904 | | +---w (target) 905 | | | +--:(stream) 906 | | | | +---w (event-filter)? 907 | | | | | +--:(by-reference) 908 | | | | | | +---w event-filter-ref event-filter-ref 909 | | | | | +--:(within-subscription) 910 | | | | | +---w (filter-spec)? 911 | | | | | +--:(subtree-filter) 912 | | | | | | +---w subtree-filter? 913 | | | | | +--:(xpath-filter) 914 | | | | | +---w xpath-filter? yang:xpath1.0 915 | | | | +---w stream stream 916 | | | | +---w replay-start-time? yang:date-and-time {replay}? 917 | | | +--:(yp:datastore) 918 | | | +---w yp:source identityref 919 | | | +---w (yp:selected-content)? 920 | | | +--:(yp:by-reference) 921 | | | | +---w yp:selection-filter-ref selection-filter-ref 922 | | | +--:(yp:within-subscription) 923 | | | +---w (yp:filter-spec)? 924 | | | +--:(yp:subtree-filter) 925 | | | | +---w yp:subtree-filter? 926 | | | +--:(yp:xpath-filter) 927 | | | +---w yp:xpath-filter? yang:xpath1.0 928 | | +---w stop-time? yang:date-and-time 929 | | +---w (yp:update-trigger)? 930 | | | +--:(yp:periodic) 931 | | | | +---w yp:period yang:timeticks 932 | | | | +---w yp:anchor-time? yang:date-and-time 933 | | | +--:(yp:on-change) {on-change}? 934 | | | +---w yp:dampening-period yang:timeticks 935 | | | +---w yp:no-synch-on-start? empty 936 | | | +---w yp:excluded-change* change-type 937 | | +---w yp:dscp? inet:dscp 938 | | +---w yp:weighting? uint8 939 | | +---w yp:dependency? sn:subscription-id 940 | +--ro output 941 | +--ro subscription-result subscription-result 942 | +--ro (result)? 943 | +--:(no-success) 944 | | +--ro filter-failure? string 945 | | +--ro replay-start-time-hint? yang:date-and-time 946 | | +--ro yp:period-hint? yang:timeticks 947 | | +--ro yp:error-path? string 948 | | +--ro yp:object-count-estimate? uint32 949 | | +--ro yp:object-count-limit? uint32 950 | | +--ro yp:kilobytes-estimate? uint32 951 | | +--ro yp:kilobytes-limit? uint32 952 | +--:(success) 953 | +--ro identifier subscription-id 954 +---x modify-subscription 955 | +---w input 956 | | +---w identifier? subscription-id 957 | | +---w (target) 958 | | | +--:(stream) 959 | | | | +---w (event-filter)? 960 | | | | +--:(by-reference) 961 | | | | | +---w event-filter-ref event-filter-ref 962 | | | | +--:(within-subscription) 963 | | | | +---w (filter-spec)? 964 | | | | +--:(subtree-filter) 965 | | | | | +---w subtree-filter? 966 | | | | +--:(xpath-filter) 967 | | | | +---w xpath-filter? yang:xpath1.0 968 | | | +--:(yp:datastore) 969 | | | +---w (yp:selected-content)? 970 | | | +--:(yp:by-reference) 971 | | | | +---w yp:selection-filter-ref selection-filter-ref 972 | | | +--:(yp:within-subscription) 973 | | | +---w (yp:filter-spec)? 974 | | | +--:(yp:subtree-filter) 975 | | | | +---w yp:subtree-filter? 976 | | | +--:(yp:xpath-filter) 977 | | | +---w yp:xpath-filter? yang:xpath1.0 978 | | +---w stop-time? yang:date-and-time 979 | | +---w (yp:update-trigger)? 980 | | +--:(yp:periodic) 981 | | | +---w yp:period yang:timeticks 982 | | | +---w yp:anchor-time? yang:date-and-time 983 | | +--:(yp:on-change) {on-change}? 984 | | +---w yp:dampening-period yang:timeticks 985 | +--ro output 986 | +--ro subscription-result subscription-result 987 | +--ro (result)? 988 | +--:(no-success) 989 | +--ro filter-failure? string 990 | +--ro yp:period-hint? yang:timeticks 991 | +--ro yp:error-path? string 992 | +--ro yp:object-count-estimate? uint32 993 | +--ro yp:object-count-limit? uint32 994 | +--ro yp:kilobytes-estimate? uint32 995 | +--ro yp:kilobytes-limit? uint32 996 +---x delete-subscription 997 | +---w input 998 | | +---w identifier subscription-id 999 | +--ro output 1000 | +--ro subscription-result subscription-result 1001 +---x kill-subscription 1002 +---w input 1003 | +---w identifier subscription-id 1004 +--ro output 1005 +--ro subscription-result subscription-result 1007 notifications: 1008 +---n replay-completed 1009 | +--ro identifier subscription-id 1010 +---n subscription-completed 1011 | +--ro identifier subscription-id 1012 +---n subscription-started 1013 | +--ro identifier subscription-id 1014 | +--ro encoding? encoding 1015 | +--ro (target) 1016 | | +--:(stream) 1017 | | | +--ro (event-filter)? 1018 | | | | +--:(by-reference) 1019 | | | | | +--ro event-filter-ref event-filter-ref 1020 | | | | +--:(within-subscription) 1021 | | | | +--ro (filter-spec)? 1022 | | | | +--:(subtree-filter) 1023 | | | | | +--ro subtree-filter? 1024 | | | | +--:(xpath-filter) 1025 | | | | +--ro xpath-filter? yang:xpath1.0 1026 | | | +--ro stream stream 1027 | | | +--ro replay-start-time? yang:date-and-time {replay}? 1028 | | +--:(yp:datastore) 1029 | | +--ro yp:source identityref 1030 | | +--ro (yp:selected-content)? 1031 | | +--:(yp:by-reference) 1032 | | | +--ro yp:selection-filter-ref selection-filter-ref 1033 | | +--:(yp:within-subscription) 1034 | | +--ro (yp:filter-spec)? 1035 | | +--:(yp:subtree-filter) 1036 | | | +--ro yp:subtree-filter? 1037 | | +--:(yp:xpath-filter) 1038 | | +--ro yp:xpath-filter? yang:xpath1.0 1039 | +--ro stop-time? yang:date-and-time 1040 | +--ro (yp:update-trigger)? 1041 | | +--:(yp:periodic) 1042 | | | +--ro yp:period yang:timeticks 1043 | | | +--ro yp:anchor-time? yang:date-and-time 1044 | | +--:(yp:on-change) {on-change}? 1045 | | +--ro yp:dampening-period yang:timeticks 1046 | | +--ro yp:no-synch-on-start? empty 1047 | | +--ro yp:excluded-change* change-type 1048 | +--ro yp:dscp? inet:dscp 1049 | +--ro yp:weighting? uint8 1050 | +--ro yp:dependency? sn:subscription-id 1051 +---n subscription-resumed 1052 | +--ro identifier subscription-id 1053 +---n subscription-modified 1054 | +--ro identifier subscription-id 1055 | +--ro encoding? encoding 1056 | +--ro (target) 1057 | | +--:(stream) 1058 | | | +--ro (event-filter)? 1059 | | | | +--:(by-reference) 1060 | | | | | +--ro event-filter-ref event-filter-ref 1061 | | | | +--:(within-subscription) 1062 | | | | +--ro (filter-spec)? 1063 | | | | +--:(subtree-filter) 1064 | | | | | +--ro subtree-filter? 1065 | | | | +--:(xpath-filter) 1066 | | | | +--ro xpath-filter? yang:xpath1.0 1067 | | | +--ro stream stream 1068 | | | +--ro replay-start-time? yang:date-and-time {replay}? 1069 | | +--:(yp:datastore) 1070 | | +--ro yp:source identityref 1071 | | +--ro (yp:selected-content)? 1072 | | +--:(yp:by-reference) 1073 | | | +--ro yp:selection-filter-ref selection-filter-ref 1074 | | +--:(yp:within-subscription) 1075 | | +--ro (yp:filter-spec)? 1076 | | +--:(yp:subtree-filter) 1077 | | | +--ro yp:subtree-filter? 1078 | | +--:(yp:xpath-filter) 1079 | | +--ro yp:xpath-filter? yang:xpath1.0 1080 | +--ro stop-time? yang:date-and-time 1081 | +--ro (yp:update-trigger)? 1082 | | +--:(yp:periodic) 1083 | | | +--ro yp:period yang:timeticks 1084 | | | +--ro yp:anchor-time? yang:date-and-time 1085 | | +--:(yp:on-change) {on-change}? 1086 | | +--ro yp:dampening-period yang:timeticks 1087 | | +--ro yp:no-synch-on-start? empty 1088 | | +--ro yp:excluded-change* change-type 1089 | +--ro yp:dscp? inet:dscp 1090 | +--ro yp:weighting? uint8 1091 | +--ro yp:dependency? sn:subscription-id 1092 +---n subscription-terminated 1093 | +--ro identifier subscription-id 1094 | +--ro error-id subscription-errors 1095 | +--ro filter-failure? string 1096 +---n subscription-suspended 1097 +--ro identifier subscription-id 1098 +--ro error-id subscription-errors 1099 +--ro filter-failure? string 1101 module: ietf-yang-push 1103 rpcs: 1104 +---x resynch-subscription {on-change}? 1105 +---w input 1106 | +---w identifier sn:subscription-id 1107 +--ro output 1108 +--ro subscription-result sn:subscription-result 1110 notifications: 1111 +---n push-update 1112 | +--ro subscription-id? sn:subscription-id 1113 | +--ro time-of-update? yang:date-and-time 1114 | +--ro updates-not-sent? empty 1115 | +--ro datastore-contents? 1116 +---n push-change-update {on-change}? 1117 +--ro subscription-id? sn:subscription-id 1118 +--ro time-of-update? yang:date-and-time 1119 +--ro updates-not-sent? empty 1120 +--ro datastore-changes? 1122 Figure 9: Model structure 1124 Selected components of the model are summarized below. 1126 4.2. Subscription configuration 1128 Both configured and dynamic subscriptions are represented within the 1129 list subscription. But only configured subscriptions are listed 1130 within list subscription-config. In both lists, each subscription 1131 has own list elements. New and enhanced parameters extending the 1132 basic subscription data model in [subscribe] include: 1134 o The targeted datastore from which the selection is being made. 1135 The potential datastores include those from [revised-datastores]. 1136 A platform may also choose to support a custom datastore. 1138 o A selection filter identifying yang nodes of interest within a 1139 datastore. Filter contents are specified via a reference to an 1140 existing filter, or via an in-line definition for only that 1141 subscription. Referenced filters allows an implementation to 1142 avoid evaluating filter acceptability during a dynamic 1143 subscription request. The case statement differentiates the 1144 options. 1146 o For periodic subscriptions, triggered updates will occur at the 1147 boundaries of a specified time interval. These boundaries many be 1148 calculated from the periodic parameters: 1150 * a "period" which defines duration between period push updates. 1152 * an "anchor-time"; update intervals always fall on the points in 1153 time that are a multiple of a period from an anchor time. If 1154 anchor time is not provided, then the anchor time MUST be set 1155 with the creation time of the initial update record. 1157 o For on-change subscriptions, assuming the dampening period has 1158 completed, triggering occurs whenever a change in the subscribed 1159 information is detected. On-change subscriptions have more 1160 complex semantics that is guided by its own set of parameters: 1162 * a "dampening-period" specifies the interval that must pass 1163 before a successive update for the subscription is sent. If no 1164 dampening period is in effect, the update is sent immediately. 1165 If a subsequent change is detected, another update is only sent 1166 once the dampening period has passed for this subscription. 1168 * an "excluded-change" flag which allows restriction of the types 1169 of changes for which updates should be sent (e.g., only add to 1170 an update record on object creation). 1172 * a "no-synch-on-start" flag which specifies whether a complete 1173 update with all the subscribed data is to be sent at the 1174 beginning of a subscription. 1176 o Optional QoS parameters to indicate the treatment of a 1177 subscription relative to other traffic between publisher and 1178 receiver. These include: 1180 * A "dscp" QoS marking which MUST be stamped on notification 1181 messages to differentiate network QoS behavior. 1183 * A "weighting" so that bandwidth proportional to this weighting 1184 can be allocated to this subscription relative to other 1185 subscriptions destined for that receiver. 1187 * a "dependency" upon another subscription. Notification 1188 messages MUST NOT be sent prior to other notification messages 1189 containing update record(s) for the referenced subscription. 1191 o A subscription's weighting MUST work identically to stream 1192 dependency weighting as described within RFC 7540, section 5.3.2. 1194 o A subscription's dependency MUST work identically to stream 1195 dependency as described within RFC 7540, sections 5.3.1, 5.3.3, 1196 and 5.3.4. If a dependency is attempted via an RPC, but the 1197 referenced subscription does not exist, the dependency will be 1198 removed. 1200 4.3. YANG Notifications 1202 4.3.1. State Change Notifications 1204 Subscription state notifications and mechanism are reused from 1205 [subscribe]. Some have been augmented to include the YANG datastore 1206 specific objects. 1208 4.3.2. Notifications for Subscribed Content 1210 Along with the subscribed content, there are other objects which 1211 might be part of a push-update or push-change-update 1213 A subscription-id MUST be transported along with the subscribed 1214 contents. An [RFC5277] Section 4 one-way notification MAY be used 1215 for encoding updates. Where it is, the relevant subscription-id MUST 1216 be encoded as the first element within each push-update or push- 1217 change-update. This allows a receiver to differentiate which 1218 subscription resulted in a particular push. 1220 A "time-of-update" which represents the time an update record 1221 snapshot was generated. A receiver MAY assume that a publisher's 1222 objects have these pushed values at this point in time. 1224 An "updates-not-sent" flag is set, which indicates that the update 1225 record is incomplete. If the application detects an informational 1226 discontinuity in either notification, the notification MUST include a 1227 flag "updates-not-sent". This flag which indicates that not all 1228 changes which have occurred since the last update are actually 1229 included with this update. In other words, the publisher has failed 1230 to fulfill its full subscription obligations. (For example a 1231 datastore missed a window in providing objects to a publisher 1232 process.) To facilitate re-synchronization of on-change 1233 subscriptions, a publisher MAY subsequently send a push-update 1234 containing a full selection snapshot of subscribed data. 1236 4.4. YANG RPCs 1238 YANG-Push subscriptions are established, modified, and deleted using 1239 RPCs augmented from [subscribe]. 1241 4.4.1. Establish-subscription RPC 1243 The subscriber sends an establish-subscription RPC with the 1244 parameters in section 3.1. An example might look like: 1246 1248 1250 1251 operational 1252 1255 1256 500 1257 encode-xml 1258 1259 1261 Figure 10: Establish-subscription RPC 1263 The publisher MUST respond explicitly positively (i.e., subscription 1264 accepted) or negatively (i.e., subscription rejected) to the request. 1265 Positive responses include the subscription-id of the accepted 1266 subscription. In that case a publisher MAY respond: 1268 1270 1272 ok 1273 1274 1276 52 1277 1278 1280 Figure 11: Establish-subscription positive RPC response 1282 A subscription can be rejected for multiple reasons, including the 1283 lack of authorization to establish a subscription, the lack of read 1284 authorization on the requested data node, or the inability of the 1285 publisher to provide a stream with the requested semantics. 1287 When the requester is not authorized to read the requested data node, 1288 the returned information indicates the node is unavailable. For 1289 instance, if the above request was unauthorized to read node "ex:foo" 1290 the publisher may return: 1292 1294 1296 subtree-unavailable 1297 1298 1300 /ex:foo 1301 1302 1304 Figure 12: Establish-subscription access denied response 1306 If a request is rejected because the publisher is not able to serve 1307 it, the publisher SHOULD include in the returned error what 1308 subscription parameters would have been accepted for the request. 1309 However, there are no guarantee that subsequent requests using this 1310 info will in fact be accepted. 1312 For example, for the following request: 1314 1316 1318 1319 running 1320 1323 1324 10 1325 encode-xml 1326 1327 1329 Figure 13: Establish-subscription request example 2 1331 a publisher that cannot serve on-change updates but periodic updates 1332 might return the following: 1334 1336 1338 period-unsupported 1339 1340 100 1341 1343 Figure 14: Establish-subscription error response example 2 1345 4.4.2. Modify-subscription RPC 1347 The subscriber MAY invoke the modify-subscription RPC for a 1348 subscription it previously established. The subscriber will include 1349 newly desired values in the modify-subscription RPC. Parameters not 1350 included MUST remain unmodified. Below is an example where a 1351 subscriber attempts to modify the period of a subscription. 1353 1355 1357 1358 1361 1362 1363 1011 1364 1365 250 1366 1367 1369 Figure 15: Modify subscription request 1371 The publisher MUST respond explicitly positively or negatively to the 1372 request. A response to a successful modification might look like: 1374 1376 1378 ok 1379 1380 1382 Figure 16: Modify subscription response 1384 If the subscription modification is rejected, the publisher MUST send 1385 a response like it does for an establish-subscription and maintain 1386 the subscription as it was before the modification request. 1387 Responses MAY include hints. A subscription MAY be modified multiple 1388 times. 1390 A configured subscription cannot be modified using modify- 1391 subscription RPC. Instead, the configuration needs to be edited as 1392 needed. 1394 4.4.3. Delete-subscription RPC 1396 To stop receiving updates from a subscription and effectively delete 1397 a subscription that had previously been established using an 1398 establish-subscription RPC, a subscriber can send a delete- 1399 subscription RPC, which takes as only input the subscription-id. 1401 Configured subscriptions cannot be deleted via RPC, but have to be 1402 removed from the configuration. This RPC is identical to the RPC 1403 from [subscribe]. 1405 4.4.4. Resynch-subscription RPC 1407 This RPC is only applicable only for on-change subscriptions 1408 previously been established using an establish-subscription RPC. On 1409 receipt, a publisher must either reply 'ok' and quickly follow with a 1410 push-update, or send an appropriate error such as on-change-synch- 1411 unsupported. For example: 1413 1415 1417 1418 1011 1419 1420 1421 1423 1425 1427 ok 1428 1429 1431 Resynch subscription 1433 4.4.5. YANG Module Synchronization 1435 To make subscription requests, the subscriber needs to know the YANG 1436 module library available on the publisher. The YANG 1.0 module 1437 library information is sent by a NETCONF server in the NETCONF 1438 'hello' message. For YANG 1.1 modules and all modules used with the 1439 RESTCONF [RFC8040] protocol, this information is provided by the YANG 1440 Library module (ietf-yang-library.yang from [RFC7895]. This YANG 1441 library information is important for the receiver to reproduce the 1442 set of object definitions used within the publisher. 1444 The YANG library includes a module list with the name, revision, 1445 enabled features, and applied deviations for each YANG module 1446 implemented by the publisher. The receiver is expected to know the 1447 YANG library information before starting a subscription. The 1448 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module 1449 can be used to cache the YANG library information. 1451 The set of modules, revisions, features, and deviations can change at 1452 run-time (if supported by the publisher implementation). In this 1453 case, the receiver needs to be informed of module changes before data 1454 nodes from changed modules can be processed correctly. The YANG 1455 library provides a simple "yang-library-change" notification that 1456 informs the subscriber that the library has changed. The receiver 1457 then needs to re-read the entire YANG library data for the replicated 1458 publisher in order to detect the specific YANG library changes. The 1459 "ietf-netconf-notifications" module defined in [RFC6470] contains a 1460 "netconf-capability-change" notification that can identify specific 1461 module changes. For example, the module URI capability of a newly 1462 loaded module will be listed in the "added-capability" leaf-list, and 1463 the module URI capability of an removed module will be listed in the 1464 "deleted-capability" leaf-list. 1466 5. YANG module 1468 ; file "ietf-yang-push.yang" 1469 module ietf-yang-push { 1470 yang-version 1.1; 1471 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1472 prefix yp; 1474 import ietf-inet-types { 1475 prefix inet; 1476 } 1477 import ietf-yang-types { 1478 prefix yang; 1479 } 1480 import ietf-subscribed-notifications { 1481 prefix sn; 1482 } 1483 import ietf-datastores { 1484 prefix ds; 1485 } 1487 organization "IETF"; 1488 contact 1489 "WG Web: 1490 WG List: 1492 Editor: Alexander Clemm 1493 1495 Editor: Eric Voit 1496 1498 Editor: Alberto Gonzalez Prieto 1499 1501 Editor: Ambika Prasad Tripathy 1502 1504 Editor: Einar Nilsen-Nygaard 1505 1507 Editor: Andy Bierman 1508 1510 Editor: Balazs Lengyel 1511 "; 1513 description 1514 "This module contains conceptual YANG specifications 1515 for YANG push."; 1517 revision 2017-10-02 { 1518 description 1519 "Initial revision."; 1520 reference 1521 "YANG Datastore Push, draft-ietf-netconf-yang-push-09"; 1522 } 1524 /* 1525 * EXTENSIONS 1526 */ 1528 extension notifiable-on-change { 1529 argument "value"; 1530 description 1531 "Indicates whether changes to the data node are reportable in 1532 on-change subscriptions. 1534 The statement MUST only be a substatement of the leaf, leaf-list, 1535 container, list, anyxml, anydata statements. Zero or One 1536 notifiable-on-change statement is allowed per parent statement. 1537 NO substatements are allowed. 1539 The argument is a boolean value indicating whether on-change 1540 notifications are supported. If notifiable-on-change is not 1541 specified, the default is the same as the parent data node's 1542 value. For top level data nodes the default value is false."; 1543 } 1545 /* 1546 * FEATURES 1547 */ 1549 feature on-change { 1550 description 1551 "This feature indicates that on-change triggered subscriptions 1552 are supported."; 1553 } 1555 /* 1556 * IDENTITIES 1557 */ 1558 /* Error type identities for datastore subscription */ 1559 identity period-unsupported { 1560 base sn:error; 1561 description 1562 "Requested time period is too short. This can be for both 1563 periodic and on-change dampening."; 1564 } 1566 identity qos-unsupported { 1567 base sn:error; 1568 description 1569 "Subscription QoS parameters not supported on this platform."; 1570 } 1572 identity dscp-unavailable { 1573 base sn:error; 1574 description 1575 "Requested DSCP marking not allocatable."; 1576 } 1578 identity on-change-unsupported { 1579 base sn:error; 1580 description 1581 "On-change not supported."; 1582 } 1584 identity on-change-synch-unsupported { 1585 base sn:error; 1586 description 1587 "On-change synch-on-start and resynchonization not supported."; 1588 } 1590 identity reference-mismatch { 1591 base sn:error; 1592 description 1593 "Mismatch in filter key and referenced yang subtree."; 1594 } 1596 identity data-unavailable { 1597 base sn:error; 1598 description 1599 "Referenced yang node or subtree doesn't exist, or read 1600 access is not permitted."; 1601 } 1603 identity datatree-size { 1604 base sn:error; 1605 description 1606 "Resulting periodic or on-change push updates may exceed a size 1607 limit during normal conditions."; 1608 } 1610 identity synchronization-datatree-size { 1611 base sn:error; 1612 description 1613 "The resulting Synch-on-start or resynchronization would push a 1614 datatree which exceeds size limit for a one-time update."; 1615 } 1617 /* Datastore identities */ 1619 identity custom-datastore { 1620 base ds:datastore; 1621 description 1622 "A datastore with boundaries not defined within 1623 draft-ietf-netmod-revised-datastores"; 1624 } 1626 /* 1627 * TYPE DEFINITIONS 1628 */ 1630 typedef change-type { 1631 type enumeration { 1632 enum "create" { 1633 description 1634 "Create a new data resource if it does not already exist. If 1635 it already exists, replace."; 1636 } 1637 enum "delete" { 1638 description 1639 "Delete a data resource if it already exists. If it does not 1640 exists, take no action."; 1641 } 1642 enum "insert" { 1643 description 1644 "Insert a new user-ordered data resource"; 1645 } 1646 enum "merge" { 1647 description 1648 "merge the edit value with the target data resource; create 1649 if it does not already exist"; 1650 } 1651 enum "move" { 1652 description 1653 "Reorder the target data resource"; 1654 } 1655 enum "replace" { 1656 description 1657 "Replace the target data resource with the edit value"; 1658 } 1659 enum "remove" { 1660 description 1661 "Remove a data resource if it already exists "; 1662 } 1663 } 1664 description 1665 "Specifies different types of datastore changes."; 1666 reference 1667 "RFC 8072 section 2.5, with a delta that it is ok to receive 1668 ability create on an existing node, or receive a delete on a 1669 missing node."; 1670 } 1672 typedef selection-filter-ref { 1673 type leafref { 1674 path "/sn:filters/yp:selection-filter/yp:identifier"; 1675 } 1676 description 1677 "This type is used to reference a selection filter."; 1678 } 1680 /* 1681 * GROUP DEFINITIONS 1682 */ 1684 grouping datastore-criteria { 1685 description 1686 "A grouping to define criteria for which selected objects from 1687 a targeted datastore should be included in push updates."; 1688 leaf source { 1689 type identityref { 1690 base ds:datastore; 1691 } 1692 mandatory true; 1693 description 1694 "Datastore from which to retrieve data."; 1695 } 1696 uses selection-filter-objects; 1697 } 1699 grouping selection-filter-types { 1700 description 1701 "This grouping defines a selector for objects from a 1702 datastore."; 1703 choice filter-spec { 1704 description 1705 "The content filter specification for this request."; 1706 anydata subtree-filter { 1707 description 1708 "This parameter identifies the portions of the 1709 target datastore to retrieve."; 1710 reference "RFC 6241, Section 6."; 1711 } 1712 leaf xpath-filter { 1713 type yang:xpath1.0; 1714 description 1715 "This parameter contains an XPath expression identifying the 1716 portions of the target datastore to retrieve."; 1717 reference "http://www.w3.org/TR/1999/REC-xpath-19991116"; 1718 } 1719 } 1720 } 1722 grouping selection-filter-objects { 1723 description 1724 "This grouping defines a selector for objects from a 1725 datastore."; 1726 choice selected-content { 1727 description 1728 "The source of the selection filter applied to the subscription. 1729 This will come either referenced from a global list, or be 1730 provided within the subscription itself."; 1731 case by-reference { 1732 description 1733 "Incorporate a filter that has been configured separately."; 1734 leaf selection-filter-ref { 1735 type selection-filter-ref; 1736 mandatory true; 1737 description 1738 "References an existing selection filter which is to be 1739 applied to the subscription."; 1740 } 1741 } 1742 case within-subscription { 1743 description 1744 "Local definition allows a filter to have the same lifecycle 1745 as the subscription."; 1746 uses selection-filter-types; 1748 } 1750 } 1751 } 1753 grouping update-policy-modifiable { 1754 description 1755 "This grouping describes the datastore specific subscription 1756 conditions that can be changed during the lifetime of the 1757 subscription."; 1758 choice update-trigger { 1759 description 1760 "Defines necessary conditions for sending an event to 1761 the subscriber."; 1762 case periodic { 1763 description 1764 "The agent is requested to notify periodically the current 1765 values of the datastore as defined by the selection filter."; 1766 leaf period { 1767 type yang:timeticks; 1768 mandatory true; 1769 description 1770 "Duration of time which should occur between periodic 1771 push updates. Where the anchor-time is 1772 available, the push will include the objects and their 1773 values which exist at an exact multiple of timeticks 1774 aligning to this start-time anchor."; 1775 } 1776 leaf anchor-time { 1777 type yang:date-and-time; 1778 description 1779 "Designates a timestamp before or after which a series of 1780 periodic push updates are determined. The next update will 1781 take place at a whole multiple interval from the anchor 1782 time. For example, for an anchor time is set for the top 1783 of a particular minute and a period interval of a minute, 1784 updates will be sent at the top of every minute this 1785 subscription is active."; 1786 } 1787 } 1788 case on-change { 1789 if-feature "on-change"; 1790 description 1791 "The agent is requested to notify changes in values in the 1792 datastore subset as defined by a selection filter."; 1793 leaf dampening-period { 1794 type yang:timeticks; 1795 mandatory true; 1796 description 1797 "The shortest time duration which is allowed between the 1798 creation of independent yang object update messages. 1799 Effectively this is the amount of time that needs to have 1800 passed since the last update. Zero indicates no delay."; 1801 } 1802 } 1803 } 1804 } 1806 grouping update-policy { 1807 description 1808 "This grouping describes the datastore specific subscription 1809 conditions of a subscription."; 1810 uses update-policy-modifiable { 1811 augment "update-trigger/on-change" { 1812 description 1813 "Includes objects not modifiable once subscription is 1814 established."; 1815 leaf no-synch-on-start { 1816 type empty; 1817 description 1818 "This leaf acts as a flag that determines behavior at the 1819 start of the subscription. When present, synchronization 1820 of state at the beginning of the subscription is outside 1821 the scope of the subscription. Only updates about changes 1822 that are observed from the start time, i.e. only push- 1823 change-update notifications are sent. When absent (default 1824 behavior), in order to facilitate a receiver's 1825 synchronization, a full update is sent when the 1826 subscription starts using a push-update notification, just 1827 like in the case of a periodic subscription. After that, 1828 push-change-update notifications only are sent unless the 1829 Publisher chooses to resynch the subscription again."; 1830 } 1831 leaf-list excluded-change { 1832 type change-type; 1833 description 1834 "Use to restrict which changes trigger an update. 1835 For example, if modify is excluded, only creation and 1836 deletion of objects is reported."; 1837 } 1838 } 1839 } 1840 } 1842 grouping update-qos { 1843 description 1844 "This grouping describes Quality of Service information 1845 concerning a subscription. This information is passed to lower 1846 layers for transport prioritization and treatment"; 1847 leaf dscp { 1848 type inet:dscp; 1849 default "0"; 1850 description 1851 "The push update's IP packet transport priority. This is made 1852 visible across network hops to receiver. The transport 1853 priority is shared for all receivers of a given subscription."; 1854 } 1855 leaf weighting { 1856 type uint8 { 1857 range "0 .. 255"; 1858 } 1859 description 1860 "Relative weighting for a subscription. Allows an underlying 1861 transport layer perform informed load balance allocations 1862 between various subscriptions"; 1863 reference 1864 "RFC-7540, section 5.3.2"; 1865 } 1866 leaf dependency { 1867 type sn:subscription-id; 1868 description 1869 "Provides the Subscription ID of a parent subscription which 1870 has absolute priority should that parent have push updates 1871 ready to egress the publisher. In other words, there should be 1872 no streaming of objects from the current subscription if 1873 the parent has something ready to push."; 1874 reference 1875 "RFC-7540, section 5.3.1"; 1876 } 1877 } 1879 grouping update-error-hints { 1880 description 1881 "Allow return additional negotiation hints that apply 1882 specifically to push updates."; 1883 leaf period-hint { 1884 type yang:timeticks; 1885 description 1886 "Returned when the requested time period is too short. This 1887 hint can assert an viable period for both periodic push 1888 cadence and on-change dampening."; 1889 } 1890 leaf error-path { 1891 type string; 1892 description 1893 "Reference to a YANG path which is associated with the error 1894 being returned."; 1895 } 1896 leaf object-count-estimate { 1897 type uint32; 1898 description 1899 "If there are too many objects which could potentially be 1900 returned by the selection filter, this identifies the estimate 1901 of the number of objects which the filter would potentially 1902 pass."; 1903 } 1904 leaf object-count-limit { 1905 type uint32; 1906 description 1907 "If there are too many objects which could be returned by the 1908 selection filter, this identifies the upper limit of the 1909 publisher's ability to service for this subscription."; 1910 } 1911 leaf kilobytes-estimate { 1912 type uint32; 1913 description 1914 "If the returned information could be beyond the capacity of 1915 the publisher, this would identify the data size which could 1916 result from this selection filter."; 1917 } 1918 leaf kilobytes-limit { 1919 type uint32; 1920 description 1921 "If the returned information would be beyond the capacity of 1922 the publisher, this identifies the upper limit of the 1923 publisher's ability to service for this subscription."; 1924 } 1925 } 1927 /* 1928 * RPCs 1929 */ 1931 rpc resynch-subscription { 1932 if-feature "on-change"; 1933 description 1934 "This RPC allows a subscriber of an active on-change 1935 subscription to request a full push of objects in there current 1936 state. A successful result would be the set of YANG objects 1937 equivalent to a Get using the existing selection criteria. This 1938 request may only come from the same subscriber using the 1939 establish-subscription RPC."; 1940 input { 1941 leaf identifier { 1942 type sn:subscription-id; 1943 mandatory true; 1944 description 1945 "Identifier of the subscription that is to be resynched."; 1946 } 1947 } 1948 output { 1949 leaf subscription-result { 1950 type sn:subscription-result; 1951 mandatory true; 1952 description 1953 "Indicates whether the request for the subscription resynch 1954 has been accepted, or why it has been denied."; 1955 } 1956 } 1957 } 1959 /* 1960 * DATA NODES 1961 */ 1963 augment "/sn:establish-subscription/sn:input" { 1964 description 1965 "This augmentation adds additional subscription parameters that 1966 apply specifically to datastore updates to RPC input."; 1967 uses update-policy; 1968 uses update-qos; 1969 } 1970 augment "/sn:establish-subscription/sn:input/sn:target" { 1971 description 1972 "This augmentation adds the datastore as a valid parameter object 1973 for the subscription to RPC input. This provides a target for 1974 the filter."; 1975 case datastore { 1976 uses datastore-criteria; 1977 } 1978 } 1979 augment "/sn:establish-subscription/sn:output/"+ 1980 "sn:result/sn:no-success" { 1981 description 1982 "This augmentation adds datastore specific error info 1983 and hints to RPC output."; 1984 uses update-error-hints; 1985 } 1986 augment "/sn:modify-subscription/sn:input" { 1987 description 1988 "This augmentation adds additional subscription parameters 1989 specific to datastore updates."; 1991 uses update-policy-modifiable; 1992 } 1993 augment "/sn:modify-subscription/sn:input/sn:target" { 1994 description 1995 "This augmentation adds the datastore as a valid parameter object 1996 for the subscription to RPC input. This provides a target for 1997 the filter."; 1998 case datastore { 1999 uses selection-filter-objects; 2000 } 2001 } 2002 augment "/sn:modify-subscription/sn:output/"+ 2003 "sn:result/sn:no-success" { 2004 description 2005 "This augmentation adds push datastore error info and hints to 2006 RPC output."; 2007 uses update-error-hints; 2008 } 2010 notification push-update { 2011 description 2012 "This notification contains a push update, containing data 2013 subscribed to via a subscription. This notification is sent for 2014 periodic updates, for a periodic subscription. It can also be 2015 used for synchronization updates of an on-change subscription. 2016 This notification shall only be sent to receivers of a 2017 subscription; it does not constitute a general-purpose 2018 notification."; 2019 leaf subscription-id { 2020 type sn:subscription-id; 2021 description 2022 "This references the subscription which drove the notification 2023 to be sent."; 2024 } 2025 leaf time-of-update { 2026 type yang:date-and-time; 2027 description 2028 "This leaf identifies the generation time of the datastore 2029 selection within a push-update."; 2030 } 2031 leaf updates-not-sent { 2032 type empty; 2033 description 2034 "This is a flag which indicates that not all data nodes 2035 subscribed to are included with this update. In other words, 2036 the publisher has failed to fulfill its full subscription 2037 obligations. The result is intermittent loss of 2038 synchronization of data at the receiver."; 2040 } 2041 anydata datastore-contents { 2042 description 2043 "This contains the updated data. It constitutes a snapshot 2044 at the time-of-update of the set of data that has been 2045 subscribed to. The format and syntax of the data 2046 corresponds to the format and syntax of data that would be 2047 returned in a corresponding get operation with the same 2048 selection filter parameters applied."; 2049 } 2050 } 2052 notification push-change-update { 2053 if-feature "on-change"; 2054 description 2055 "This notification contains an on-change push update. This 2056 notification shall only be sent to the receivers of a 2057 subscription; it does not constitute a general-purpose 2058 notification."; 2059 leaf subscription-id { 2060 type sn:subscription-id; 2061 description 2062 "This references the subscription which drove the notification 2063 to be sent."; 2064 } 2065 leaf time-of-update { 2066 type yang:date-and-time; 2067 description 2068 "This leaf identifies the generation time of the datastore 2069 changes extract. If a dampening-period was in effect before 2070 the notification was generated, this may not be the time any of 2071 the datastore-changes were actually made."; 2072 } 2073 leaf updates-not-sent { 2074 type empty; 2075 description 2076 "This is a flag which indicates that not all changes which 2077 have occurred since the last update are included with this 2078 update. In other words, the publisher has failed to 2079 fulfill its full subscription obligations, for example in 2080 cases where it was not able to keep up with a change burst."; 2081 } 2082 anydata datastore-changes { 2083 description 2084 "This contains an incremental set of datastore changes needed 2085 to update a remote datastore starting at the time of the 2086 previous update, per the terms of the subscription. Changes 2087 are encoded analogous to the syntax of a corresponding yang- 2088 patch operation, i.e. a yang-patch operation applied to the 2089 YANG datastore implied by the previous update to result in the 2090 current state."; 2091 reference 2092 "RFC 8072 section 2.5, with a delta that it is ok to receive 2093 ability create on an existing node, or receive a delete on a 2094 missing node."; 2095 } 2096 } 2098 augment "/sn:subscription-started" { 2099 description 2100 "This augmentation adds many yang datastore specific objects to 2101 the notification that a subscription has started."; 2102 uses update-policy; 2103 uses update-qos; 2104 } 2105 augment "/sn:subscription-started/sn:target" { 2106 description 2107 "This augmentation allows the datastore to be included as part 2108 of the notification that a subscription has started."; 2109 case datastore { 2110 uses datastore-criteria; 2111 } 2112 } 2113 augment "/sn:filters" { 2114 description 2115 "This augmentation allows the datastore to be included as part 2116 of the selection filtering criteria for a subscription."; 2117 list selection-filter { 2118 key "identifier"; 2119 description 2120 "A list of pre-positioned filters that can be applied 2121 to datastore subscriptions."; 2122 leaf identifier { 2123 type sn:filter-id; 2124 description 2125 "An identifier to differentiate between selection filters."; 2126 } 2127 uses selection-filter-types; 2128 } 2129 } 2130 augment "/sn:subscription-modified" { 2131 description 2132 "This augmentation adds many yang datastore specific objects to 2133 the notification that a subscription has been modified."; 2134 uses update-policy; 2135 uses update-qos; 2137 } 2138 augment "/sn:subscription-modified/sn:target" { 2139 description 2140 "This augmentation allows the datastore to be included as part 2141 of the notification that a subscription has been modified."; 2142 case datastore { 2143 uses datastore-criteria; 2144 } 2145 } 2146 augment "/sn:subscription-config/sn:subscription" { 2147 description 2148 "This augmentation adds many yang datastore specific objects 2149 which can be configured as opposed to established via RPC."; 2150 uses update-policy; 2151 uses update-qos; 2152 } 2153 augment "/sn:subscription-config/sn:subscription/sn:target" { 2154 description 2155 "This augmentation adds the datastore to the selection filtering 2156 criteria for a subscription."; 2157 case datastore { 2158 uses datastore-criteria; 2159 } 2160 } 2161 augment "/sn:subscriptions/sn:subscription" { 2162 yp:notifiable-on-change true; 2163 description 2164 "This augmentation adds many datastore specific objects to a 2165 subscription."; 2166 uses update-policy; 2167 uses update-qos; 2168 } 2169 augment "/sn:subscriptions/sn:subscription/sn:target" { 2170 description 2171 "This augmentation allows the datastore to be included as part 2172 of the selection filtering criteria for a subscription."; 2173 case datastore { 2174 uses datastore-criteria; 2175 } 2176 } 2178 /* YANG Parser Pyang crashing on syntax below, due to fixed bug 2179 https://github.com/mbj4668/pyang/issues/300 2181 deviation "/sn:subscriptions/sn:subscription/sn:receivers/" 2182 + "sn:receiver/sn:pushed-notifications" { 2183 deviate add { 2184 yp:notifiable-on-change false; 2186 } 2187 } 2188 deviation "/sn:subscriptions/sn:subscription/sn:receivers/" 2189 + "sn:receiver/sn:excluded-notifications" { 2190 deviate add { 2191 yp:notifiable-on-change false; 2192 } 2193 } 2194 YANG Parser Pyang crashing on syntax above */ 2195 } 2197 2199 6. IANA Considerations 2201 This document registers the following namespace URI in the "IETF XML 2202 Registry" [RFC3688]: 2204 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push 2205 Registrant Contact: The IESG. 2206 XML: N/A; the requested URI is an XML namespace. 2208 This document registers the following YANG module in the "YANG Module 2209 Names" registry [RFC6020]: 2211 Name: ietf-yang-push 2212 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push 2213 Prefix: yp 2214 Reference: draft-ietf-netconf-yang-push-08.txt (RFC form) 2216 7. Security Considerations 2218 All security considerations from [subscribe] are relevant for 2219 datastores. In addition there are specific security considerations 2220 for receivers defined in Section 3.9 2222 If the access control permissions on subscribed YANG nodes change 2223 during the lifecycle of a subscription, a publisher MUST either 2224 transparently conform to the new access control permissions, or must 2225 terminate or restart the subscriptions so that new access control 2226 permissions are re-established. 2228 The NETCONF Authorization Control Model SHOULD be used to restrict 2229 the delivery of YANG nodes for which the receiver has no access. 2231 8. Acknowledgments 2233 For their valuable comments, discussions, and feedback, we wish to 2234 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei 2235 Guo, Michael Scharf, Sharon Chisholm, and Guangying Zheng. 2237 9. References 2239 9.1. Normative References 2241 [revised-datastores] 2242 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2243 and R. Wilton, "Network Management Datastore 2244 Architecture", draft-ietf-netmod-revised-datastores-04 2245 (work in progress), August 2017. 2247 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2248 DOI 10.17487/RFC3688, January 2004, 2249 . 2251 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2252 the Network Configuration Protocol (NETCONF)", RFC 6020, 2253 DOI 10.17487/RFC6020, October 2010, 2254 . 2256 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2257 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 2258 February 2012, . 2260 [RFC6536bis] 2261 Bierman, A. and M. Bjorklund, "Network Configuration 2262 Protocol (NETCONF) Access Control Model", draft-ietf- 2263 netconf-rfc6536bis-05 (work in progress), September 2017. 2265 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 2266 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 2267 . 2269 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2270 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2271 . 2273 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2274 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2275 . 2277 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2278 Media Type", RFC 8072, DOI 10.17487/RFC8072, February 2279 2017, . 2281 [subscribe] 2282 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 2283 and E. Nilsen-Nygaard, "Custom Subscription to Event 2284 Notifications", draft-ietf-netconf-subscribed- 2285 notifications-04 (work in progress), September 2017. 2287 9.2. Informative References 2289 [netconf-notif] 2290 Gonzalez Prieto, A., Clemm, A., Voit, E., Nilsen-Nygaard, 2291 E., and A. Tripathy, "NETCONF Support for Event 2292 Notifications", September 2017. 2294 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2295 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 2296 . 2298 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2299 and A. Bierman, Ed., "Network Configuration Protocol 2300 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2301 . 2303 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2304 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 2305 . 2307 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2308 for Subscription to YANG Datastores", RFC 7923, 2309 DOI 10.17487/RFC7923, June 2016, 2310 . 2312 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2313 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2314 . 2316 Appendix A. Changes between revisions 2318 (To be removed by RFC editor prior to publication) 2320 v09 - v10 2322 o Returned to the explicit filter subtyping of v00-v05 2324 o identityref to ds:datastore made explicit 2325 o Returned ability to modify a selection filter via RPC. 2327 v08 - v09 2329 o Minor tweaks cleaning up text, removing appendicies, and making 2330 reference to revised-datastores. 2332 o Subscription-id optional in push updates, except when encoded in 2333 RFC5277, Section 4 one-way notification. 2335 o Finished adding the text descibing the resynch subscription RPC. 2337 o Removed relationships to other drafts and future technology 2338 appendicies as this work is being explored elsewhere. 2340 o Deferred the multi-line card issue to new drafts 2342 o Simplified the NACM interactions. 2344 v07 - v08 2346 o Updated YANG models with minor tweaks to accommodate changes of 2347 ietf-subscribed-notifications. 2349 v06 - v07 2351 o Clarifying text tweaks. 2353 o Clarification that filters act as selectors for subscribed data 2354 nodes; support for value filters not included but possible as a 2355 future extension 2357 o Filters don't have to be matched to existing YANG objects 2359 v05 - v06 2361 o Security considerations updated. 2363 o Base YANG model in [subscribe] updated as part of move to 2364 identities, YANG augmentations in this doc matched up 2366 o Terms refined and text updates throughout 2368 o Appendix talking about relationship to other drafts added. 2370 o Datastore replaces stream 2372 o Definitions of filters improved 2373 v04 to v05 2375 o Referenced based subscription document changed to Subscribed 2376 Notifications from 5277bis. 2378 o Getting operational data from filters 2380 o Extension notifiable-on-change added 2382 o New appendix on potential futures. Moved text into there from 2383 several drafts. 2385 o Subscription configuration section now just includes changed 2386 parameters from Subscribed Notifications 2388 o Subscription monitoring moved into Subscribed Notifications 2390 o New error and hint mechanisms included in text and in the yang 2391 model. 2393 o Updated examples based on the error definitions 2395 o Groupings updated for consistency 2397 o Text updates throughout 2399 v03 to v04 2401 o Updates-not-sent flag added 2403 o Not notifiable extension added 2405 o Dampening period is for whole subscription, not single objects 2407 o Moved start/stop into rfc5277bis 2409 o Client and Server changed to subscriber, publisher, and receiver 2411 o Anchor time for periodic 2413 o Message format for synchronization (i.e. synch-on-start) 2415 o Material moved into 5277bis 2417 o QoS parameters supported, by not allowed to be modified by RPC 2419 o Text updates throughout 2421 Authors' Addresses 2423 Alexander Clemm 2424 Huawei 2426 Email: ludwig@clemm.org 2428 Eric Voit 2429 Cisco Systems 2431 Email: evoit@cisco.com 2433 Alberto Gonzalez Prieto 2434 VMware 2436 Email: agonzalezpri@vmware.com 2438 Ambika Prasad Tripathy 2439 Cisco Systems 2441 Email: ambtripa@cisco.com 2443 Einar Nilsen-Nygaard 2444 Cisco Systems 2446 Email: einarnn@cisco.com 2448 Andy Bierman 2449 YumaWorks 2451 Email: andy@yumaworks.com 2453 Balazs Lengyel 2454 Ericsson 2456 Email: balazs.lengyel@ericsson.com