idnits 2.17.1 draft-ietf-netconf-yang-push-09.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 782 has weird spacing: '...er-type sel...' == Line 962 has weird spacing: '...ntifier sub...' == Line 964 has weird spacing: '...-result sub...' == Line 967 has weird spacing: '...ntifier sub...' == Line 969 has weird spacing: '...-result sub...' == (8 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 (September 19, 2017) is 2404 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 2249, 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: March 23, 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 September 19, 2017 17 Subscribing to YANG datastore push updates 18 draft-ietf-netconf-yang-push-09 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 March 23, 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 . . . . . . . . . . . . . . . 24 92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 26 93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 27 94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 31 95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 47 97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47 98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 99 9.1. Normative References . . . . . . . . . . . . . . . . . . 47 100 9.2. Informative References . . . . . . . . . . . . . . . . . 49 101 Appendix A. Changes between revisions . . . . . . . . . . . . . 49 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 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 push-update 574 577 500 578 encode-xml 579 580 582 Figure 5: Establish-Subscription example 584 the publisher might return: 586 588 590 error-insufficient-resources 591 592 2000 593 595 Figure 6: Error response example 597 As can be seen above the rejected subscription does not result in the 598 generation of an rpc-reply with an rpc-error element. YANG-push 599 specific errors and negotiation hints part are returned as part of 600 normal RPC operations. 602 3.9. Receiver Authorization 604 A receiver of subscription data MUST only be sent updates for which 605 they have proper authorization. A publisher MUST ensure that no non- 606 authorized data is included in push updates. To do so, it needs to 607 apply all corresponding checks applicable at the time of a specific 608 pushed update and if necessary silently remove any non-authorized 609 data from subtrees. This enables YANG data pushed based on 610 subscriptions to be authorized equivalently to a regular data 611 retrieval (get) operation. 613 A publisher MAY allow subscriptions which select non-existent or 614 access-protected data. Such a capability permits a receiver the 615 ability to monitor the entire lifecyle of the data. In this case, 616 all push-updates must be sent empty, and no push-change-updates will 617 be sent until the data becomes visible for a receiver. 619 A publisher MAY alternatively choose not to allow subscriptions which 620 select non-existent or access-protected data. Such a capability 621 enables the publisher to avoid having to perform filtering of 622 authorized content on each update. Relevant scenarios here include: 624 o the rejecting of a subscription request to access-protected 625 objects, 627 o the suspension of a subscription where new access-controlled 628 objects are selected mid-subscription for which the receiver does 629 not have the necessary authorization, or 631 o the authorization privileges of a receiver change over the course 632 of the subscription. 634 In all these cases, the error identity "data-unavailable" SHOULD be 635 returned. This reduces the possibility of access permission leakage. 637 The contextual authorization model for data in YANG datastores is the 638 NETCONF Access Control Model [RFC6536bis], Section 3.2.4. A 639 clarification to this is that each of the individual nodes in a 640 resulting update record MUST also have applied access control to 641 resulting pushed messages. This includes validating that read access 642 is ok for any nodes newly selected since the last update record for 643 each receiver. 645 +-------------+ +-------------------+ 646 push-update / --> | data node | yes | | 647 push-change-update | access | ---> | add data node | 648 | allowed? | | to update message | 649 +-------------+ +-------------------+ 651 Figure 7: Access control for push updates 653 If read access into previously accessible nodes has been lost due to 654 a receiver permissions change, this SHOULD be reported as node 655 'delete' operations for on-change subscriptions. If not capable of 656 handling such receiver permission changes with such a 'delete', 657 publisher implementations MUST force dynamic subscription re- 658 establishment or configured subscription re-initialization so that 659 appropriate filtering is installed. 661 3.10. On-change Notifiable YANG objects 663 In some cases, a publisher supporting on-change notifications may not 664 be able to push updates for some object types on-change. Reasons for 665 this might be that the value of the data node changes frequently 666 (e.g., [RFC7223]'s in-octets counter), that small object changes are 667 frequent and meaningless (e.g., a temperature gauge changing 0.1 668 degrees), or that the implementation is not capable of on-change 669 notification for a particular object. 671 Support for on-change notification is usually specific to the 672 individual YANG model and/or implementation so it is possible to 673 define in design time. System integrators need this information 674 (without reading any data from a live node). 676 The default assumption is that no data nodes support on-change 677 notification. Schema nodes and subtrees that support on-change 678 notifications MUST be marked by accordingly with the YANG extension 679 "notifiable-on-change". This extension is defined in the data model 680 below. 682 When an on-change subscription is established, data-nodes are 683 automatically excluded unless they are marked with notifiable-on- 684 change as true. This also means that authorization checks SHALL NOT 685 be performed on them. A subscriber can identify which nodes may be 686 included in on-change updates by retrieving the data nodes in the 687 subscription's scope and checking for which notifiable-on-change is 688 marked as true. 690 In theory, adding notifiable-on-change markings can be done within 691 corresponding YANG models. But a more extensible way to avoid having 692 to modify existing module definitions is to add notifiable-on-change 693 markings within separate module deviations. This means that when a 694 YANG model designer wants to add a notifiable-on-change marking to 695 nodes of an existing module without modifying the module definitions, 696 a new module is introduced that contains deviation statements which 697 add "notifiable-on-change" statements as applicable. 699 deviation /sys:system/sys:system-time { 700 deviate add { 701 yp:notifiable-on-change false; 702 } 703 } 705 Figure 8: Deviation Example 707 3.11. Other Considerations 709 3.11.1. Robustness and reliability 711 Particularly in the case of on-change push updates, it is important 712 that push updates do not get lost or, in case the loss of an update 713 is unavoidable, that the receiver is notified accordingly. 715 Update messages for a single subscription MAY NOT be resequenced. 717 It is conceivable that under certain circumstances, a publisher will 718 recognize that it is unable to include within an update record the 719 full set of objects desired per the terms of a subscription. In this 720 case, the publisher MUST take one or more of the following actions. 722 o A publisher MUST set the updates-not-sent flag on any update 723 record which is known to be missing information. 725 o It MAY choose to suspend a subscription as per [subscribe]. 727 o When resuming an on-change subscription, the publisher SHOULD 728 generate a complete patch from the previous update record. If 729 this is not possible and the synch-on-start option is configured, 730 then the full datastore contents MAY be sent via a push-update 731 instead (effectively replacing the previous contents). If neither 732 of these are possible, then an updates-not-sent flag MUST be 733 included on the next push-change-update. 735 Note: It is perfectly acceptable to have a series of push-change- 736 updates (and even push updates) serially queued at the transport 737 layer awaiting transmission. It is not required to merge pending 738 update messages. I.e., the dampening period applies to update record 739 creation, not transmission. 741 3.11.2. Publisher capacity 743 It is far preferable to decline a subscription request than to accept 744 such a request when it cannot be met. 746 Whether or not a subscription can be supported will be determined by 747 a combination of several factors such as the subscription trigger 748 (on-change or periodic), the period in which to report changes (1 749 second periods will consume more resources than 1 hour periods), the 750 amount of data in the subtree that is being subscribed to, and the 751 number and combination of other subscriptions that are concurrently 752 being serviced. 754 4. A YANG data model for management of datastore push subscriptions 756 4.1. Overview 758 The YANG data model for datastore push subscriptions is depicted in 759 the following figure. Following YANG tree convention in the 760 depiction, brackets enclose list keys, "rw" means configuration, "ro" 761 operational state data, "?" designates optional nodes, "*" designates 762 nodes that can have multiple instances. Parentheses with a name in 763 the middle enclose choice and case nodes. New YANG objects defined 764 here (i.e., beyond those from [subscribe]) are identified with "yp". 766 module: ietf-subscribed-notifications 767 +--ro streams 768 | +--ro stream* [stream] 769 | +--ro stream stream 770 | +--ro description string 771 | +--ro replay-support? empty 772 | +--ro replay-log-creation-time? yang:date-and-time 773 | +--ro replay-log-aged-time? yang:date-and-time 774 +--rw filters 775 | +--rw filter* [identifier] 776 | +--rw identifier filter-id 777 | +--rw (filter-type)? 778 | +--:(event-filter) 779 | | +--rw event-filter-type event-filter-type 780 | | +--rw event-filter-contents 781 | +--:(yp:datastore) 782 | +--rw yp:selection-filter-type selection-filter-type 783 | +--rw yp:selection-filter 784 +--rw subscription-config {configured-subscriptions}? 785 | +--rw subscription* [identifier] 786 | +--rw identifier subscription-id 787 | +--rw encoding? encoding 788 | +--rw (target) 789 | | +--:(stream) 790 | | | +--rw (event-filter)? 791 | | | | +--:(by-reference) 792 | | | | | +--rw filter-ref filter-ref 793 | | | | +--:(within-subscription) 794 | | | | +--rw event-filter-type event-filter-type 795 | | | | +--rw event-filter-contents 796 | | | +--rw stream stream 797 | | | +--rw replay-start-time? yang:date-and-time {replay}? 798 | | +--:(yp:datastore) 799 | | +--rw yp:datastore identityref 800 | | +--rw (yp:selected-content)? 801 | | +--:(yp:by-reference) 802 | | | +--rw yp:filter-ref sn:filter-ref 803 | | +--:(yp:within-subscription) 804 | | +--rw yp:selection-filter-type 805 | | | selection-filter-type 806 | | +--rw yp:selection-filter 807 | +--rw stop-time? yang:date-and-time 808 | +--rw receivers 809 | | +--rw receiver* [address port] 810 | | +--rw address inet:host 811 | | +--rw port inet:port-number 812 | | +--rw protocol? transport-protocol 813 | +--rw (notification-origin)? 814 | | +--:(interface-originated) 815 | | | +--rw source-interface? if:interface-ref 816 | | +--:(address-originated) 817 | | +--rw source-vrf? string 818 | | +--rw source-address inet:ip-address-no-zone 819 | +--rw (yp:update-trigger)? 820 | | +--:(yp:periodic) 821 | | | +--rw yp:period yang:timeticks 822 | | | +--rw yp:anchor-time? yang:date-and-time 823 | | +--:(yp:on-change) {on-change}? 824 | | +--rw yp:dampening-period yang:timeticks 825 | | +--rw yp:no-synch-on-start? empty 826 | | +--rw yp:excluded-change* change-type 827 | +--rw yp:dscp? inet:dscp 828 | +--rw yp:weighting? uint8 829 | +--rw yp:dependency? sn:subscription-id 830 +--ro subscriptions 831 +--ro subscription* [identifier] 832 +--ro identifier subscription-id 833 +--ro configured-subscription? 834 | empty {configured-subscriptions}? 835 +--ro encoding? encoding 836 +--ro (target) 837 | +--:(stream) 838 | | +--ro (event-filter)? 839 | | | +--:(by-reference) 840 | | | | +--ro filter-ref filter-ref 841 | | | +--:(within-subscription) 842 | | | +--ro event-filter-type event-filter-type 843 | | | +--ro event-filter-contents 844 | | +--ro stream stream 845 | | +--ro replay-start-time? yang:date-and-time {replay}? 846 | +--:(yp:datastore) 847 | +--ro yp:datastore identityref 848 | +--ro (yp:selected-content)? 849 | +--:(yp:by-reference) 850 | | +--ro yp:filter-ref sn:filter-ref 851 | +--:(yp:within-subscription) 852 | +--ro yp:selection-filter-type 853 | selection-filter-type 854 | +--ro yp:selection-filter 855 +--ro stop-time? yang:date-and-time 856 +--ro (notification-origin)? 857 | +--:(interface-originated) 858 | | +--ro source-interface? if:interface-ref 859 | +--:(address-originated) 860 | +--ro source-vrf? string 861 | +--ro source-address inet:ip-address-no-zone 862 +--ro receivers 863 | +--ro receiver* [address port] 864 | +--ro address inet:host 865 | +--ro port inet:port-number 866 | +--ro protocol? transport-protocol 867 | +--ro pushed-notifications? yang:counter64 868 | +--ro excluded-notifications? yang:counter64 869 | +--ro status subscription-status 870 +--ro (yp:update-trigger)? 871 | +--:(yp:periodic) 872 | | +--ro yp:period yang:timeticks 873 | | +--ro yp:anchor-time? yang:date-and-time 874 | +--:(yp:on-change) {on-change}? 875 | +--ro yp:dampening-period yang:timeticks 876 | +--ro yp:no-synch-on-start? empty 877 | +--ro yp:excluded-change* change-type 878 +--ro yp:dscp? inet:dscp 879 +--ro yp:weighting? uint8 880 +--ro yp:dependency? sn:subscription-id 882 rpcs: 883 +---x establish-subscription 884 | +---w input 885 | | +---w encoding? encoding 886 | | +---w (target) 887 | | | +--:(stream) 888 | | | | +---w (event-filter)? 889 | | | | | +--:(by-reference) 890 | | | | | | +---w filter-ref filter-ref 891 | | | | | +--:(within-subscription) 892 | | | | | +---w event-filter-type event-filter-type 893 | | | | | +---w event-filter-contents 894 | | | | +---w stream stream 895 | | | | +---w replay-start-time? yang:date-and-time {replay}? 896 | | | +--:(yp:datastore) 897 | | | +---w yp:datastore identityref 898 | | | +---w (yp:selected-content)? 899 | | | +--:(yp:by-reference) 900 | | | | +---w yp:filter-ref sn:filter-ref 901 | | | +--:(yp:within-subscription) 902 | | | +---w yp:selection-filter-type 903 | | | | selection-filter-type 904 | | | +---w yp:selection-filter 905 | | +---w stop-time? yang:date-and-time 906 | | +---w (yp:update-trigger)? 907 | | | +--:(yp:periodic) 908 | | | | +---w yp:period yang:timeticks 909 | | | | +---w yp:anchor-time? yang:date-and-time 910 | | | +--:(yp:on-change) {on-change}? 911 | | | +---w yp:dampening-period yang:timeticks 912 | | | +---w yp:no-synch-on-start? empty 913 | | | +---w yp:excluded-change* change-type 914 | | +---w yp:dscp? inet:dscp 915 | | +---w yp:weighting? uint8 916 | | +---w yp:dependency? sn:subscription-id 917 | +--ro output 918 | +--ro subscription-result subscription-result 919 | +--ro (result)? 920 | +--:(no-success) 921 | | +--ro filter-failure? string 922 | | +--ro replay-start-time-hint? yang:date-and-time 923 | | +--ro yp:period-hint? yang:timeticks 924 | | +--ro yp:error-path? string 925 | | +--ro yp:object-count-estimate? uint32 926 | | +--ro yp:object-count-limit? uint32 927 | | +--ro yp:kilobytes-estimate? uint32 928 | | +--ro yp:kilobytes-limit? uint32 929 | +--:(success) 930 | +--ro identifier subscription-id 931 +---x modify-subscription 932 | +---w input 933 | | +---w identifier? subscription-id 934 | | +---w (target) 935 | | | +--:(stream) 936 | | | +---w (event-filter)? 937 | | | +--:(by-reference) 938 | | | | +---w filter-ref filter-ref 939 | | | +--:(within-subscription) 940 | | | +---w event-filter-type event-filter-type 941 | | | +---w event-filter-contents 942 | | +---w stop-time? yang:date-and-time 943 | | +---w (yp:update-trigger)? 944 | | +--:(yp:periodic) 945 | | | +---w yp:period yang:timeticks 946 | | | +---w yp:anchor-time? yang:date-and-time 947 | | +--:(yp:on-change) {on-change}? 948 | | +---w yp:dampening-period yang:timeticks 949 | +--ro output 950 | +--ro subscription-result subscription-result 951 | +--ro (result)? 952 | +--:(no-success) 953 | +--ro filter-failure? string 954 | +--ro yp:period-hint? yang:timeticks 955 | +--ro yp:error-path? string 956 | +--ro yp:object-count-estimate? uint32 957 | +--ro yp:object-count-limit? uint32 958 | +--ro yp:kilobytes-estimate? uint32 959 | +--ro yp:kilobytes-limit? uint32 960 +---x delete-subscription 961 | +---w input 962 | | +---w identifier subscription-id 963 | +--ro output 964 | +--ro subscription-result subscription-result 965 +---x kill-subscription 966 +---w input 967 | +---w identifier subscription-id 968 +--ro output 969 +--ro subscription-result subscription-result 971 notifications: 972 +---n replay-completed 973 | +--ro identifier subscription-id 974 +---n subscription-completed 975 | +--ro identifier subscription-id 976 +---n subscription-started 977 | +--ro identifier subscription-id 978 | +--ro encoding? encoding 979 | +--ro (target) 980 | | +--:(stream) 981 | | | +--ro (event-filter)? 982 | | | | +--:(by-reference) 983 | | | | | +--ro filter-ref filter-ref 984 | | | | +--:(within-subscription) 985 | | | | +--ro event-filter-type event-filter-type 986 | | | | +--ro event-filter-contents 987 | | | +--ro stream stream 988 | | | +--ro replay-start-time? yang:date-and-time {replay}? 989 | | +--:(yp:datastore) 990 | | +--ro yp:datastore identityref 991 | | +--ro (yp:selected-content)? 992 | | +--:(yp:by-reference) 993 | | | +--ro yp:filter-ref sn:filter-ref 994 | | +--:(yp:within-subscription) 995 | | +--ro yp:selection-filter-type selection-filter-type 996 | | +--ro yp:selection-filter 997 | +--ro stop-time? yang:date-and-time 998 | +--ro (yp:update-trigger)? 999 | | +--:(yp:periodic) 1000 | | | +--ro yp:period yang:timeticks 1001 | | | +--ro yp:anchor-time? yang:date-and-time 1002 | | +--:(yp:on-change) {on-change}? 1003 | | +--ro yp:dampening-period yang:timeticks 1004 | | +--ro yp:no-synch-on-start? empty 1005 | | +--ro yp:excluded-change* change-type 1006 | +--ro yp:dscp? inet:dscp 1007 | +--ro yp:weighting? uint8 1008 | +--ro yp:dependency? sn:subscription-id 1009 +---n subscription-resumed 1010 | +--ro identifier subscription-id 1011 +---n subscription-modified 1012 | +--ro identifier subscription-id 1013 | +--ro encoding? encoding 1014 | +--ro (target) 1015 | | +--:(stream) 1016 | | | +--ro (event-filter)? 1017 | | | | +--:(by-reference) 1018 | | | | | +--ro filter-ref filter-ref 1019 | | | | +--:(within-subscription) 1020 | | | | +--ro event-filter-type event-filter-type 1021 | | | | +--ro event-filter-contents 1022 | | | +--ro stream stream 1023 | | | +--ro replay-start-time? yang:date-and-time {replay}? 1024 | | +--:(yp:datastore) 1025 | | +--ro yp:datastore identityref 1026 | | +--ro (yp:selected-content)? 1027 | | +--:(yp:by-reference) 1028 | | | +--ro yp:filter-ref sn:filter-ref 1029 | | +--:(yp:within-subscription) 1030 | | +--ro yp:selection-filter-type selection-filter-type 1031 | | +--ro yp:selection-filter 1032 | +--ro stop-time? yang:date-and-time 1033 | +--ro (yp:update-trigger)? 1034 | | +--:(yp:periodic) 1035 | | | +--ro yp:period yang:timeticks 1036 | | | +--ro yp:anchor-time? yang:date-and-time 1037 | | +--:(yp:on-change) {on-change}? 1038 | | +--ro yp:dampening-period yang:timeticks 1039 | | +--ro yp:no-synch-on-start? empty 1040 | | +--ro yp:excluded-change* change-type 1041 | +--ro yp:dscp? inet:dscp 1042 | +--ro yp:weighting? uint8 1043 | +--ro yp:dependency? sn:subscription-id 1044 +---n subscription-terminated 1045 | +--ro identifier subscription-id 1046 | +--ro error-id subscription-errors 1047 | +--ro filter-failure? string 1048 +---n subscription-suspended 1049 +--ro identifier subscription-id 1050 +--ro error-id subscription-errors 1051 +--ro filter-failure? string 1053 module: ietf-yang-push 1055 rpcs: 1056 +---x resynch-subscription {on-change}? 1057 +---w input 1058 | +---w identifier sn:subscription-id 1059 +--ro output 1060 +--ro subscription-result sn:subscription-result 1062 notifications: 1063 +---n push-update 1064 | +--ro subscription-id sn:subscription-id 1065 | +--ro time-of-update? yang:date-and-time 1066 | +--ro updates-not-sent? empty 1067 | +--ro datastore-contents? 1068 +---n push-change-update {on-change}? 1069 +--ro subscription-id sn:subscription-id 1070 +--ro time-of-update? yang:date-and-time 1071 +--ro updates-not-sent? empty 1072 +--ro datastore-changes? 1074 Figure 9: Model structure 1076 Selected components of the model are summarized below. 1078 4.2. Subscription configuration 1080 Both configured and dynamic subscriptions are represented within the 1081 list subscription. But only configured subscriptions are listed 1082 within list subscription-config. In both lists, each subscription 1083 has own list elements. New and enhanced parameters extending the 1084 basic subscription data model in [subscribe] include: 1086 o The targeted datastore from which the selection is being made. 1087 The potential datastores include those from [revised-datastores]. 1088 A platform may also choose to support a custom datastore. 1090 o A selection filter identifying yang nodes of interest within a 1091 datastore. Filter contents are specified via a reference to an 1092 existing filter, or via an in-line definition for only that 1093 subscription. Referenced filters allows an implementation to 1094 avoid evaluating filter acceptability during a dynamic 1095 subscription request. The case statement differentiates the 1096 options. 1098 o For periodic subscriptions, triggered updates will occur at the 1099 boundaries of a specified time interval. These boundaries many be 1100 calculated from the periodic parameters: 1102 * a "period" which defines duration between period push updates. 1104 * an "anchor-time"; update intervals always fall on the points in 1105 time that are a multiple of a period from an anchor time. If 1106 anchor time is not provided, then the anchor time MUST be set 1107 with the creation time of the initial update record. 1109 o For on-change subscriptions, assuming the dampening period has 1110 completed, triggering occurs whenever a change in the subscribed 1111 information is detected. On-change subscriptions have more 1112 complex semantics that is guided by its own set of parameters: 1114 * a "dampening-period" specifies the interval that must pass 1115 before a successive update for the subscription is sent. If no 1116 dampening period is in effect, the update is sent immediately. 1117 If a subsequent change is detected, another update is only sent 1118 once the dampening period has passed for this subscription. 1120 * an "excluded-change" flag which allows restriction of the types 1121 of changes for which updates should be sent (e.g., only add to 1122 an update record on object creation). 1124 * a "no-synch-on-start" flag which specifies whether a complete 1125 update with all the subscribed data is to be sent at the 1126 beginning of a subscription. 1128 o Optional QoS parameters to indicate the treatment of a 1129 subscription relative to other traffic between publisher and 1130 receiver. These include: 1132 * A "dscp" QoS marking which MUST be stamped on notification 1133 messages to differentiate network QoS behavior. 1135 * A "weighting" so that bandwidth proportional to this weighting 1136 can be allocated to this subscription relative to other 1137 subscriptions destined for that receiver. 1139 * a "dependency" upon another subscription. Notification 1140 messages MUST NOT be sent prior to other notification messages 1141 containing update record(s) for the referenced subscription. 1143 o A subscription's weighting MUST work identically to stream 1144 dependency weighting as described within RFC 7540, section 5.3.2. 1146 o A subscription's dependency MUST work identically to stream 1147 dependency as described within RFC 7540, sections 5.3.1, 5.3.3, 1148 and 5.3.4. If a dependency is attempted via an RPC, but the 1149 referenced subscription does not exist, the dependency will be 1150 removed. 1152 4.3. YANG Notifications 1154 4.3.1. State Change Notifications 1156 Subscription state notifications and mechanism are reused from 1157 [subscribe]. Some have been augmented to include the YANG datastore 1158 specific objects. 1160 4.3.2. Notifications for Subscribed Content 1162 Along with the subscribed content, there are other objects which 1163 might be part of a push-update or push-change-update 1165 A subscription-id MUST be transported along with the subscribed 1166 contents. An [RFC5277] Section 4 one-way notification MAY be used 1167 for encoding updates. Where it is, the relevant subscription-id MUST 1168 be encoded as the first element within each push-update or push- 1169 change-update. This allows a receiver to differentiate which 1170 subscription resulted in a particular push. 1172 A "time-of-update" which represents the time an update record 1173 snapshot was generated. A receiver MAY assume that a publisher's 1174 objects have these pushed values at this point in time. 1176 An "updates-not-sent" flag is set, which indicates that the update 1177 record is incomplete. If the application detects an informational 1178 discontinuity in either notification, the notification MUST include a 1179 flag "updates-not-sent". This flag which indicates that not all 1180 changes which have occurred since the last update are actually 1181 included with this update. In other words, the publisher has failed 1182 to fulfill its full subscription obligations. (For example a 1183 datastore missed a window in providing objects to a publisher 1184 process.) To facilitate re-synchronization of on-change 1185 subscriptions, a publisher MAY subsequently send a push-update 1186 containing a full selection snapshot of subscribed data. 1188 4.4. YANG RPCs 1190 YANG-Push subscriptions are established, modified, and deleted using 1191 RPCs augmented from [subscribe]. 1193 4.4.1. Establish-subscription RPC 1195 The subscriber sends an establish-subscription RPC with the 1196 parameters in section 3.1. An example might look like: 1198 1200 1202 1205 500 1206 encode-xml 1207 1208 1210 Figure 10: Establish-subscription RPC 1212 The publisher MUST respond explicitly positively (i.e., subscription 1213 accepted) or negatively (i.e., subscription rejected) to the request. 1214 Positive responses include the subscription-id of the accepted 1215 subscription. In that case a publisher MAY respond: 1217 1219 1221 ok 1222 1223 1225 52 1226 1227 1229 Figure 11: Establish-subscription positive RPC response 1231 A subscription can be rejected for multiple reasons, including the 1232 lack of authorization to establish a subscription, the lack of read 1233 authorization on the requested data node, or the inability of the 1234 publisher to provide a stream with the requested semantics. 1236 When the requester is not authorized to read the requested data node, 1237 the returned information indicates the node is unavailable. For 1238 instance, if the above request was unauthorized to read node "ex:foo" 1239 the publisher may return: 1241 1243 1245 subtree-unavailable 1246 1247 1249 /ex:foo 1250 1251 1253 Figure 12: Establish-subscription access denied response 1255 If a request is rejected because the publisher is not able to serve 1256 it, the publisher SHOULD include in the returned error what 1257 subscription parameters would have been accepted for the request. 1258 However, there are no guarantee that subsequent requests using this 1259 info will in fact be accepted. 1261 For example, for the following request: 1263 1265 1267 running 1268 1271 10 1272 encode-xml 1273 1274 1276 Figure 13: Establish-subscription request example 2 1278 a publisher that cannot serve on-change updates but periodic updates 1279 might return the following: 1281 1283 1285 period-unsupported 1286 1287 100 1288 1290 Figure 14: Establish-subscription error response example 2 1292 4.4.2. Modify-subscription RPC 1294 The subscriber MAY invoke the modify-subscription RPC for a 1295 subscription it previously established. The subscriber will include 1296 newly desired values in the modify-subscription RPC. Parameters not 1297 included MUST remain unmodified. Below is an example where a 1298 subscriber attempts to modify the period of a subscription. 1300 1302 1304 running 1305 1306 1011 1307 1308 250 1309 1310 1312 Figure 15: Modify subscription request 1314 The publisher MUST respond explicitly positively or negatively to the 1315 request. A response to a successful modification might look like: 1317 1319 1321 ok 1322 1323 1325 Figure 16: Modify subscription response 1327 If the subscription modification is rejected, the publisher MUST send 1328 a response like it does for an establish-subscription and maintain 1329 the subscription as it was before the modification request. 1330 Responses MAY include hints. A subscription MAY be modified multiple 1331 times. 1333 A configured subscription cannot be modified using modify- 1334 subscription RPC. Instead, the configuration needs to be edited as 1335 needed. 1337 4.4.3. Delete-subscription RPC 1339 To stop receiving updates from a subscription and effectively delete 1340 a subscription that had previously been established using an 1341 establish-subscription RPC, a subscriber can send a delete- 1342 subscription RPC, which takes as only input the subscription-id. 1344 Configured subscriptions cannot be deleted via RPC, but have to be 1345 removed from the configuration. This RPC is identical to the RPC 1346 from [subscribe]. 1348 4.4.4. Resynch-subscription RPC 1350 This RPC is only applicable only for on-change subscriptions 1351 previously been established using an establish-subscription RPC. On 1352 receipt, a publisher must either reply 'ok' and quickly follow with a 1353 push-update, or send an appropriate error such as on-change-synch- 1354 unsupported. For example: 1356 1358 1360 1361 1011 1362 1363 1364 1366 1368 1370 ok 1371 1372 1374 Resynch subscription 1376 4.4.5. YANG Module Synchronization 1378 To make subscription requests, the subscriber needs to know the YANG 1379 module library available on the publisher. The YANG 1.0 module 1380 library information is sent by a NETCONF server in the NETCONF 1381 'hello' message. For YANG 1.1 modules and all modules used with the 1382 RESTCONF [RFC8040] protocol, this information is provided by the YANG 1383 Library module (ietf-yang-library.yang from [RFC7895]. This YANG 1384 library information is important for the receiver to reproduce the 1385 set of object definitions used within the publisher. 1387 The YANG library includes a module list with the name, revision, 1388 enabled features, and applied deviations for each YANG module 1389 implemented by the publisher. The receiver is expected to know the 1390 YANG library information before starting a subscription. The 1391 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module 1392 can be used to cache the YANG library information. 1394 The set of modules, revisions, features, and deviations can change at 1395 run-time (if supported by the publisher implementation). In this 1396 case, the receiver needs to be informed of module changes before data 1397 nodes from changed modules can be processed correctly. The YANG 1398 library provides a simple "yang-library-change" notification that 1399 informs the subscriber that the library has changed. The receiver 1400 then needs to re-read the entire YANG library data for the replicated 1401 publisher in order to detect the specific YANG library changes. The 1402 "ietf-netconf-notifications" module defined in [RFC6470] contains a 1403 "netconf-capability-change" notification that can identify specific 1404 module changes. For example, the module URI capability of a newly 1405 loaded module will be listed in the "added-capability" leaf-list, and 1406 the module URI capability of an removed module will be listed in the 1407 "deleted-capability" leaf-list. 1409 5. YANG module 1411 ; file "ietf-yang-push@2017-09-19.yang" 1412 module ietf-yang-push { 1413 yang-version 1.1; 1414 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1415 prefix yp; 1417 import ietf-inet-types { 1418 prefix inet; 1419 } 1420 import ietf-yang-types { 1421 prefix yang; 1422 } 1423 import ietf-subscribed-notifications { 1424 prefix sn; 1425 } 1427 import ietf-datastores { 1428 prefix ds; 1429 } 1431 organization "IETF"; 1432 contact 1433 "WG Web: 1434 WG List: 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-09-19 { 1462 description 1463 "Initial revision."; 1464 reference 1465 "YANG Datastore Push, draft-ietf-netconf-yang-push-09"; 1466 } 1468 /* 1469 * EXTENSIONS 1470 */ 1471 extension notifiable-on-change { 1472 argument "value"; 1473 description 1474 "Indicates whether changes to the data node are reportable in 1475 on-change subscriptions. 1477 The statement MUST only be a substatement of the leaf, leaf-list, 1478 container, list, anyxml, anydata statements. Zero or One 1479 notifiable-on-change statement is allowed per parent statement. 1480 NO substatements are allowed. 1482 The argument is a boolean value indicating whether on-change 1483 notifications are supported. If notifiable-on-change is not 1484 specified, the default is the same as the parent data node's 1485 value. For top level data nodes the default value is false."; 1486 } 1488 /* 1489 * FEATURES 1490 */ 1492 feature on-change { 1493 description 1494 "This feature indicates that on-change triggered subscriptions 1495 are supported."; 1496 } 1498 /* 1499 * IDENTITIES 1500 */ 1502 /* Error type identities for datastore subscription */ 1503 identity period-unsupported { 1504 base sn:error; 1505 description 1506 "Requested time period is too short. This can be for both 1507 periodic and on-change dampening."; 1508 } 1510 identity qos-unsupported { 1511 base sn:error; 1512 description 1513 "Subscription QoS parameters not supported on this platform."; 1514 } 1516 identity dscp-unavailable { 1517 base sn:error; 1518 description 1519 "Requested DSCP marking not allocatable."; 1520 } 1522 identity on-change-unsupported { 1523 base sn:error; 1524 description 1525 "On-change not supported."; 1526 } 1528 identity on-change-synch-unsupported { 1529 base sn:error; 1530 description 1531 "On-change synch-on-start and resynchonization not supported."; 1532 } 1534 identity reference-mismatch { 1535 base sn:error; 1536 description 1537 "Mismatch in filter key and referenced yang subtree."; 1538 } 1540 identity data-unavailable { 1541 base sn:error; 1542 description 1543 "Referenced yang node or subtree doesn't exist, or read 1544 access is not permitted."; 1545 } 1547 identity datatree-size { 1548 base sn:error; 1549 description 1550 "Resulting periodic or on-change push updates may exceed a size 1551 limit during normal conditions."; 1552 } 1554 identity synchronization-datatree-size { 1555 base sn:error; 1556 description 1557 "The resulting Synch-on-start or resynchronization would push a 1558 datatree which exceeds size limit for a one-time update."; 1559 } 1561 /* Datastore identities */ 1563 identity custom-datastore { 1564 base ds:datastore; 1565 description 1566 "A datastore with boundaries not defined within 1567 draft-ietf-netmod-revised-datastores"; 1568 } 1570 /* Selection filter identities */ 1571 identity selection-filter { 1572 description 1573 "Evaluation criteria encoded in a syntax which allows the 1574 selection of nodes from a target. If the filter is applied 1575 against a datastore for periodic extracts, the resulting node-set 1576 result is passed along. If the filter is applied against a 1577 datastore looking for changes, deltas from the last update in the 1578 form of a patch result are passed along. An empty node set is a 1579 valid result of this filter type."; 1580 } 1581 identity subtree-selection-filter { 1582 base selection-filter; 1583 description 1584 "An RFC-6241 based selection-filter which may be used to select 1585 nodes within a datastore."; 1586 reference "RFC-6241, #5.1"; 1587 } 1588 identity xpath-selection-filter { 1589 base selection-filter; 1590 description 1591 "A selection-filter which may be applied to a datastore which 1592 follows the syntax specified in yang:xpath1.0. Nodes that 1593 evaluate to true are included in the selection."; 1594 reference "XPATH: http://www.w3.org/TR/1999/REC-xpath-19991116"; 1595 } 1597 /* 1598 * TYPE DEFINITIONS 1599 */ 1601 typedef change-type { 1602 type enumeration { 1603 enum "create" { 1604 description 1605 "Create a new data resource if it does not already exist. If 1606 it already exists, replace."; 1607 } 1608 enum "delete" { 1609 description 1610 "Delete a data resource if it already exists. If it does not 1611 exists, take no action."; 1612 } 1613 enum "insert" { 1614 description 1615 "Insert a new user-ordered data resource"; 1616 } 1617 enum "merge" { 1618 description 1619 "merge the edit value with the target data resource; create 1620 if it does not already exist"; 1621 } 1622 enum "move" { 1623 description 1624 "Reorder the target data resource"; 1625 } 1626 enum "replace" { 1627 description 1628 "Replace the target data resource with the edit value"; 1629 } 1630 enum "remove" { 1631 description 1632 "Remove a data resource if it already exists "; 1633 } 1634 } 1635 description 1636 "Specifies different types of datastore changes."; 1637 reference 1638 "RFC 8072 section 2.5, with a delta that it is ok to receive 1639 ability create on an existing node, or receive a delete on a 1640 missing node."; 1641 } 1643 typedef selection-filter-type { 1644 type identityref { 1645 base selection-filter; 1646 } 1647 description 1648 "Specifies a known type of selection filter."; 1649 } 1651 /* 1652 * GROUP DEFINITIONS 1653 */ 1655 grouping datastore-criteria { 1656 description 1657 "A grouping to define criteria for which selected objects from 1658 a targeted datastore should be included in push updates."; 1659 leaf datastore { 1660 type identityref { 1661 base ds:datastore; 1662 } 1663 mandatory true; 1664 description 1665 "Specifies a system-provided datastore against which a selection 1666 filter will be applied"; 1667 } 1668 uses selection-filter-objects; 1669 } 1671 grouping selection-filter-elements { 1672 description 1673 "This grouping defines a selector for objects from a 1674 datastore."; 1675 leaf selection-filter-type { 1676 type selection-filter-type; 1677 mandatory true; 1678 description 1679 "A filter needs to be a known and understood syntax if it is 1680 to be interpretable by a device."; 1681 } 1682 anyxml selection-filter { 1683 mandatory true; 1684 description 1685 "Datastore evaluation criteria encoded in a syntax of a 1686 supported type of selection filter."; 1687 } 1688 } 1690 grouping selection-filter-objects { 1691 description 1692 "This grouping defines a selector for objects from a 1693 datastore."; 1694 choice selected-content { 1695 description 1696 "The source of the selection filter applied to the subscription. 1697 This will come either referenced from a global list, or be 1698 provided within the subscription itself."; 1699 case by-reference { 1700 description 1701 "Incorporate a filter that has been configured separately."; 1702 leaf filter-ref { 1703 type sn:filter-ref; 1704 mandatory true; 1705 description 1706 "References an existing selection filter which is to be 1707 applied to the subscription."; 1708 } 1710 } 1711 case within-subscription { 1712 description 1713 "Local definition allows a filter to have the same lifecycle 1714 as the subscription."; 1715 uses selection-filter-elements; 1717 } 1718 } 1719 } 1721 grouping update-policy-modifiable { 1722 description 1723 "This grouping describes the datastore specific subscription 1724 conditions that can be changed during the lifetime of the 1725 subscription."; 1726 choice update-trigger { 1727 description 1728 "Defines necessary conditions for sending an event to 1729 the subscriber."; 1730 case periodic { 1731 description 1732 "The agent is requested to notify periodically the current 1733 values of the datastore as defined by the selection filter."; 1734 leaf period { 1735 type yang:timeticks; 1736 mandatory true; 1737 description 1738 "Duration of time which should occur between periodic 1739 push updates. Where the anchor-time is 1740 available, the push will include the objects and their 1741 values which exist at an exact multiple of timeticks 1742 aligning to this start-time anchor."; 1743 } 1744 leaf anchor-time { 1745 type yang:date-and-time; 1746 description 1747 "Designates a timestamp before or after which a series of 1748 periodic push updates are determined. The next update will 1749 take place at a whole multiple interval from the anchor 1750 time. For example, for an anchor time is set for the top 1751 of a particular minute and a period interval of a minute, 1752 updates will be sent at the top of every minute this 1753 subscription is active."; 1754 } 1755 } 1756 case on-change { 1757 if-feature "on-change"; 1758 description 1759 "The agent is requested to notify changes in values in the 1760 datastore subset as defined by a selection filter."; 1761 leaf dampening-period { 1762 type yang:timeticks; 1763 mandatory true; 1764 description 1765 "The shortest time duration which is allowed between the 1766 creation of independent yang object update messages. 1767 Effectively this is the amount of time that needs to have 1768 passed since the last update. Zero indicates no delay."; 1769 } 1770 } 1771 } 1772 } 1774 grouping update-policy { 1775 description 1776 "This grouping describes the datastore specific subscription 1777 conditions of a subscription."; 1778 uses update-policy-modifiable { 1779 augment "update-trigger/on-change" { 1780 description 1781 "Includes objects not modifiable once subscription is 1782 established."; 1783 leaf no-synch-on-start { 1784 type empty; 1785 description 1786 "This leaf acts as a flag that determines behavior at the 1787 start of the subscription. When present, synchronization 1788 of state at the beginning of the subscription is outside 1789 the scope of the subscription. Only updates about changes 1790 that are observed from the start time, i.e. only push- 1791 change-update notifications are sent. When absent (default 1792 behavior), in order to facilitate a receiver's 1793 synchronization, a full update is sent when the 1794 subscription starts using a push-update notification, just 1795 like in the case of a periodic subscription. After that, 1796 push-change-update notifications only are sent unless the 1797 Publisher chooses to resynch the subscription again."; 1798 } 1799 leaf-list excluded-change { 1800 type change-type; 1801 description 1802 "Use to restrict which changes trigger an update. 1803 For example, if modify is excluded, only creation and 1804 deletion of objects is reported."; 1805 } 1807 } 1808 } 1809 } 1811 grouping update-qos { 1812 description 1813 "This grouping describes Quality of Service information 1814 concerning a subscription. This information is passed to lower 1815 layers for transport prioritization and treatment"; 1816 leaf dscp { 1817 type inet:dscp; 1818 default "0"; 1819 description 1820 "The push update's IP packet transport priority. This is made 1821 visible across network hops to receiver. The transport 1822 priority is shared for all receivers of a given subscription."; 1823 } 1824 leaf weighting { 1825 type uint8 { 1826 range "0 .. 255"; 1827 } 1828 description 1829 "Relative weighting for a subscription. Allows an underlying 1830 transport layer perform informed load balance allocations 1831 between various subscriptions"; 1832 reference 1833 "RFC-7540, section 5.3.2"; 1834 } 1835 leaf dependency { 1836 type sn:subscription-id; 1837 description 1838 "Provides the Subscription ID of a parent subscription which 1839 has absolute priority should that parent have push updates 1840 ready to egress the publisher. In other words, there should be 1841 no streaming of objects from the current subscription if 1842 the parent has something ready to push."; 1843 reference 1844 "RFC-7540, section 5.3.1"; 1845 } 1846 } 1848 grouping update-error-hints { 1849 description 1850 "Allow return additional negotiation hints that apply 1851 specifically to push updates."; 1852 leaf period-hint { 1853 type yang:timeticks; 1854 description 1855 "Returned when the requested time period is too short. This 1856 hint can assert an viable period for both periodic push 1857 cadence and on-change dampening."; 1858 } 1859 leaf error-path { 1860 type string; 1861 description 1862 "Reference to a YANG path which is associated with the error 1863 being returned."; 1864 } 1865 leaf object-count-estimate { 1866 type uint32; 1867 description 1868 "If there are too many objects which could potentially be 1869 returned by the selection filter, this identifies the estimate 1870 of the number of objects which the filter would potentially 1871 pass."; 1872 } 1873 leaf object-count-limit { 1874 type uint32; 1875 description 1876 "If there are too many objects which could be returned by the 1877 selection filter, this identifies the upper limit of the 1878 publisher's ability to service for this subscription."; 1879 } 1880 leaf kilobytes-estimate { 1881 type uint32; 1882 description 1883 "If the returned information could be beyond the capacity of 1884 the publisher, this would identify the data size which could 1885 result from this selection filter."; 1886 } 1887 leaf kilobytes-limit { 1888 type uint32; 1889 description 1890 "If the returned information would be beyond the capacity of 1891 the publisher, this identifies the upper limit of the 1892 publisher's ability to service for this subscription."; 1893 } 1894 } 1896 /* 1897 * RPCs 1898 */ 1900 rpc resynch-subscription { 1901 if-feature "on-change"; 1902 description 1903 "This RPC allows a subscriber of an active on-change 1904 subscription to request a full push of objects in there current 1905 state. A successful result would be the set of YANG objects 1906 equivalent to a Get using the existing selection criteria. This 1907 request may only come from the same subscriber using the 1908 establish-subscription RPC."; 1909 input { 1910 leaf identifier { 1911 type sn:subscription-id; 1912 mandatory true; 1913 description 1914 "Identifier of the subscription that is to be resynched."; 1915 } 1916 } 1917 output { 1918 leaf subscription-result { 1919 type sn:subscription-result; 1920 mandatory true; 1921 description 1922 "Indicates whether the request for the subscription resynch 1923 has been accepted, or why it has been denied."; 1924 } 1925 } 1926 } 1928 /* 1929 * DATA NODES 1930 */ 1932 augment "/sn:establish-subscription/sn:input" { 1933 description 1934 "This augmentation adds additional subscription parameters that 1935 apply specifically to datastore updates to RPC input."; 1936 uses update-policy; 1937 uses update-qos; 1938 } 1939 augment "/sn:establish-subscription/sn:input/sn:target" { 1940 description 1941 "This augmentation adds the datastore as a valid parameter object 1942 for the subscription to RPC input. This provides a target for 1943 the filter."; 1944 case datastore { 1945 uses datastore-criteria; 1946 } 1947 } 1948 augment "/sn:establish-subscription/sn:output/"+ 1949 "sn:result/sn:no-success" { 1950 description 1951 "This augmentation adds datastore specific error info 1952 and hints to RPC output."; 1953 uses update-error-hints; 1954 } 1955 augment "/sn:modify-subscription/sn:input" { 1956 description 1957 "This augmentation adds additional subscription parameters 1958 specific to datastore updates."; 1959 uses update-policy-modifiable; 1960 } 1961 augment "/sn:modify-subscription/sn:output/"+ 1962 "sn:result/sn:no-success" { 1963 description 1964 "This augmentation adds push datastore error info and hints to 1965 RPC output."; 1966 uses update-error-hints; 1967 } 1969 notification push-update { 1970 description 1971 "This notification contains a push update, containing data 1972 subscribed to via a subscription. This notification is sent for 1973 periodic updates, for a periodic subscription. It can also be 1974 used for synchronization updates of an on-change subscription. 1975 This notification shall only be sent to receivers of a 1976 subscription; it does not constitute a general-purpose 1977 notification."; 1978 leaf subscription-id { 1979 type sn:subscription-id; 1980 description 1981 "This references the subscription which drove the notification 1982 to be sent."; 1983 } 1984 leaf time-of-update { 1985 type yang:date-and-time; 1986 description 1987 "This leaf identifies the generation time of the datastore 1988 selection within a push-update."; 1989 } 1990 leaf updates-not-sent { 1991 type empty; 1992 description 1993 "This is a flag which indicates that not all data nodes 1994 subscribed to are included with this update. In other words, 1995 the publisher has failed to fulfill its full subscription 1996 obligations. The result is intermittent loss of 1997 synchronization of data at the receiver."; 1998 } 1999 anydata datastore-contents { 2000 description 2001 "This contains the updated data. It constitutes a snapshot 2002 at the time-of-update of the set of data that has been 2003 subscribed to. The format and syntax of the data 2004 corresponds to the format and syntax of data that would be 2005 returned in a corresponding get operation with the same 2006 selection filter parameters applied."; 2007 } 2008 } 2010 notification push-change-update { 2011 if-feature "on-change"; 2012 description 2013 "This notification contains an on-change push update. This 2014 notification shall only be sent to the receivers of a 2015 subscription; it does not constitute a general-purpose 2016 notification."; 2017 leaf subscription-id { 2018 type sn:subscription-id; 2019 description 2020 "This references the subscription which drove the notification 2021 to be sent."; 2022 } 2023 leaf time-of-update { 2024 type yang:date-and-time; 2025 description 2026 "This leaf identifies the generation time of the datastore 2027 changes extract. If a dampening-period was in effect before 2028 the notification was generated, this may not be the time any of 2029 the datastore-changes were actually made."; 2030 } 2031 leaf updates-not-sent { 2032 type empty; 2033 description 2034 "This is a flag which indicates that not all changes which 2035 have occurred since the last update are included with this 2036 update. In other words, the publisher has failed to 2037 fulfill its full subscription obligations, for example in 2038 cases where it was not able to keep up with a change burst."; 2039 } 2040 anydata datastore-changes { 2041 description 2042 "This contains an incremental set of datastore changes needed 2043 to update a remote datastore starting at the time of the 2044 previous update, per the terms of the subscription. Changes 2045 are encoded analogous to the syntax of a corresponding yang- 2046 patch operation, i.e. a yang-patch operation applied to the 2047 YANG datastore implied by the previous update to result in the 2048 current state."; 2049 reference 2050 "RFC 8072 section 2.5, with a delta that it is ok to receive 2051 ability create on an existing node, or receive a delete on a 2052 missing node."; 2053 } 2054 } 2056 augment "/sn:subscription-started" { 2057 description 2058 "This augmentation adds many yang datastore specific objects to 2059 the notification that a subscription has started."; 2060 uses update-policy; 2061 uses update-qos; 2062 } 2063 augment "/sn:subscription-started/sn:target" { 2064 description 2065 "This augmentation allows the datastore to be included as part 2066 of the notification that a subscription has started."; 2067 case datastore { 2068 uses datastore-criteria; 2069 } 2070 } 2071 augment "/sn:filters/sn:filter/sn:filter-type" { 2072 description 2073 "This augmentation allows the datastore to be included as part 2074 of the selection filtering criteria for a subscription."; 2075 case datastore { 2076 uses selection-filter-elements; 2077 } 2078 } 2079 augment "/sn:subscription-modified" { 2080 description 2081 "This augmentation adds many yang datastore specific objects to 2082 the notification that a subscription has been modified."; 2083 uses update-policy; 2084 uses update-qos; 2085 } 2086 augment "/sn:subscription-modified/sn:target" { 2087 description 2088 "This augmentation allows the datastore to be included as part 2089 of the notification that a subscription has been modified."; 2090 case datastore { 2091 uses datastore-criteria; 2092 } 2093 } 2094 augment "/sn:subscription-config/sn:subscription" { 2095 description 2096 "This augmentation adds many yang datastore specific objects 2097 which can be configured as opposed to established via RPC."; 2098 uses update-policy; 2099 uses update-qos; 2100 } 2101 augment "/sn:subscription-config/sn:subscription/sn:target" { 2102 description 2103 "This augmentation adds the datastore to the selection filtering 2104 criteria for a subscription."; 2105 case datastore { 2106 uses datastore-criteria; 2107 } 2108 } 2109 augment "/sn:subscriptions/sn:subscription" { 2110 yp:notifiable-on-change true; 2111 description 2112 "This augmentation adds many datastore specific objects to a 2113 subscription."; 2114 uses update-policy; 2115 uses update-qos; 2116 } 2117 augment "/sn:subscriptions/sn:subscription/sn:target" { 2118 description 2119 "This augmentation allows the datastore to be included as part 2120 of the selection filtering criteria for a subscription."; 2121 case datastore { 2122 uses datastore-criteria; 2123 } 2124 } 2126 /* YANG Parser Pyang crashing on syntax below, due to fixed bug 2127 https://github.com/mbj4668/pyang/issues/300 2129 deviation "/sn:subscriptions/sn:subscription/sn:receivers/" 2130 + "sn:receiver/sn:pushed-notifications" { 2131 deviate add { 2132 yp:notifiable-on-change false; 2133 } 2134 } 2135 deviation "/sn:subscriptions/sn:subscription/sn:receivers/" 2136 + "sn:receiver/sn:excluded-notifications" { 2137 deviate add { 2138 yp:notifiable-on-change false; 2139 } 2140 } 2141 YANG Parser Pyang crashing on syntax above */ 2142 } 2143 2145 6. IANA Considerations 2147 This document registers the following namespace URI in the "IETF XML 2148 Registry" [RFC3688]: 2150 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push 2151 Registrant Contact: The IESG. 2152 XML: N/A; the requested URI is an XML namespace. 2154 This document registers the following YANG module in the "YANG Module 2155 Names" registry [RFC6020]: 2157 Name: ietf-yang-push 2158 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push 2159 Prefix: yp 2160 Reference: draft-ietf-netconf-yang-push-08.txt (RFC form) 2162 7. Security Considerations 2164 All security considerations from [subscribe] are relevant for 2165 datastores. In addition there are specific security considerations 2166 for receivers defined in Section 3.9 2168 If the access control permissions on subscribed YANG nodes change 2169 during the lifecycle of a subscription, a publisher MUST either 2170 transparently conform to the new access control permissions, or must 2171 terminate or restart the subscriptions so that new access control 2172 permissions are re-established. 2174 The NETCONF Authorization Control Model SHOULD be used to restrict 2175 the delivery of YANG nodes for which the receiver has no access. 2177 8. Acknowledgments 2179 For their valuable comments, discussions, and feedback, we wish to 2180 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei 2181 Guo, Michael Scharf, Sharon Chisholm, and Guangying Zheng. 2183 9. References 2185 9.1. Normative References 2187 [revised-datastores] 2188 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2189 and R. Wilton, "Network Management Datastore 2190 Architecture", draft-ietf-netmod-revised-datastores-04 2191 (work in progress), August 2017. 2193 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2194 DOI 10.17487/RFC3688, January 2004, 2195 . 2197 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2198 the Network Configuration Protocol (NETCONF)", RFC 6020, 2199 DOI 10.17487/RFC6020, October 2010, 2200 . 2202 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2203 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 2204 February 2012, . 2206 [RFC6536bis] 2207 Bierman, A. and M. Bjorklund, "Network Configuration 2208 Protocol (NETCONF) Access Control Model", draft-ietf- 2209 netconf-rfc6536bis-05 (work in progress), September 2017. 2211 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 2212 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 2213 . 2215 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2216 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2217 . 2219 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2220 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2221 . 2223 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2224 Media Type", RFC 8072, DOI 10.17487/RFC8072, February 2225 2017, . 2227 [subscribe] 2228 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 2229 and E. Nilsen-Nygaard, "Custom Subscription to Event 2230 Notifications", draft-ietf-netconf-subscribed- 2231 notifications-04 (work in progress), September 2017. 2233 9.2. Informative References 2235 [netconf-notif] 2236 Gonzalez Prieto, A., Clemm, A., Voit, E., Nilsen-Nygaard, 2237 E., and A. Tripathy, "NETCONF Support for Event 2238 Notifications", September 2017. 2240 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2241 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 2242 . 2244 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2245 and A. Bierman, Ed., "Network Configuration Protocol 2246 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2247 . 2249 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 2250 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 2251 . 2253 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2254 for Subscription to YANG Datastores", RFC 7923, 2255 DOI 10.17487/RFC7923, June 2016, 2256 . 2258 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2259 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2260 . 2262 Appendix A. Changes between revisions 2264 (To be removed by RFC editor prior to publication) 2266 v08 - v09 2268 o Minor tweaks cleaning up text, removing appendicies, and making 2269 reference to revised-datastores. 2271 o Subscription-id optional in push updates, except when encoded in 2272 RFC5277, Section 4 one-way notification. 2274 o Finished adding the text descibing the resynch subscription RPC. 2276 o Removed relationships to other drafts and future technology 2277 appendicies as this work is being explored elsewhere. 2279 o Deferred the multi-line card issue to new drafts 2280 o Simplified the NACM interactions. 2282 v07 - v08 2284 o Updated YANG models with minor tweaks to accommodate changes of 2285 ietf-subscribed-notifications. 2287 v06 - v07 2289 o Clarifying text tweaks. 2291 o Clarification that filters act as selectors for subscribed data 2292 nodes; support for value filters not included but possible as a 2293 future extension 2295 o Filters don't have to be matched to existing YANG objects 2297 v05 - v06 2299 o Security considerations updated. 2301 o Base YANG model in [subscribe] updated as part of move to 2302 identities, YANG augmentations in this doc matched up 2304 o Terms refined and text updates throughout 2306 o Appendix talking about relationship to other drafts added. 2308 o Datastore replaces stream 2310 o Definitions of filters improved 2312 v04 to v05 2314 o Referenced based subscription document changed to Subscribed 2315 Notifications from 5277bis. 2317 o Getting operational data from filters 2319 o Extension notifiable-on-change added 2321 o New appendix on potential futures. Moved text into there from 2322 several drafts. 2324 o Subscription configuration section now just includes changed 2325 parameters from Subscribed Notifications 2327 o Subscription monitoring moved into Subscribed Notifications 2328 o New error and hint mechanisms included in text and in the yang 2329 model. 2331 o Updated examples based on the error definitions 2333 o Groupings updated for consistency 2335 o Text updates throughout 2337 v03 to v04 2339 o Updates-not-sent flag added 2341 o Not notifiable extension added 2343 o Dampening period is for whole subscription, not single objects 2345 o Moved start/stop into rfc5277bis 2347 o Client and Server changed to subscriber, publisher, and receiver 2349 o Anchor time for periodic 2351 o Message format for synchronization (i.e. synch-on-start) 2353 o Material moved into 5277bis 2355 o QoS parameters supported, by not allowed to be modified by RPC 2357 o Text updates throughout 2359 Authors' Addresses 2361 Alexander Clemm 2362 Huawei 2364 Email: ludwig@clemm.org 2366 Eric Voit 2367 Cisco Systems 2369 Email: evoit@cisco.com 2370 Alberto Gonzalez Prieto 2371 VMware 2373 Email: agonzalezpri@vmware.com 2375 Ambika Prasad Tripathy 2376 Cisco Systems 2378 Email: ambtripa@cisco.com 2380 Einar Nilsen-Nygaard 2381 Cisco Systems 2383 Email: einarnn@cisco.com 2385 Andy Bierman 2386 YumaWorks 2388 Email: andy@yumaworks.com 2390 Balazs Lengyel 2391 Ericsson 2393 Email: balazs.lengyel@ericsson.com