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