idnits 2.17.1 draft-ietf-netconf-yang-push-03.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 an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 4 instances of too long lines in the document, the longest one being 17 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 327: '...or negatively. Negative responses MAY...' RFC 2119 keyword, line 453: '... RFC 5277 filter MAY be used, with the...' RFC 2119 keyword, line 483: '... the server SHOULD include in the re...' RFC 2119 keyword, line 517: '...cription request MUST be rejected. As...' RFC 2119 keyword, line 553: '... MUST support XML encoding and MAY s...' (5 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 15, 2016) is 2871 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) == Missing Reference: 'RFC 6241' is mentioned on line 452, but not defined == Missing Reference: 'RFC 5277' is mentioned on line 454, but not defined ** Downref: Normative reference to an Historic RFC: RFC 1157 -- Duplicate reference: RFC5277, mentioned in 'RFC6470', was also mentioned in 'RFC5277'. ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-06) exists of draft-clemm-netmod-mount-04 == Outdated reference: A later version (-06) exists of draft-clemm-netmod-mount-03 -- Duplicate reference: draft-clemm-netmod-mount, mentioned in 'I-D.gonzalez-netconf-5277bis', was also mentioned in 'I-D.clemm-netmod-mount'. == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-13 == Outdated reference: A later version (-14) exists of draft-ietf-netconf-yang-patch-08 Summary: 5 errors (**), 0 flaws (~~), 8 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Clemm 3 Internet-Draft A. Gonzalez Prieto 4 Intended status: Standards Track E. Voit 5 Expires: December 17, 2016 A. Tripathy 6 E. Nilsen-Nygaard 7 Cisco Systems 8 June 15, 2016 10 Subscribing to YANG datastore push updates 11 draft-ietf-netconf-yang-push-03.txt 13 Abstract 15 This document defines a subscription and push mechanism for YANG 16 datastores. This mechanism allows client applications to request 17 updates from a YANG datastore, which are then pushed by the server to 18 a receiver per a subscription policy, without requiring additional 19 client requests. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on December 17, 2016. 38 Copyright Notice 40 Copyright (c) 2016 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 This document may contain material from IETF Documents or IETF 54 Contributions published or made publicly available before November 55 10, 2008. The person(s) controlling the copyright in some of this 56 material may not have granted the IETF Trust the right to allow 57 modifications of such material outside the IETF Standards Process. 58 Without obtaining an adequate license from the person(s) controlling 59 the copyright in such materials, this document may not be modified 60 outside the IETF Standards Process, and derivative works of it may 61 not be created outside the IETF Standards Process, except to format 62 it for publication as an RFC or to translate it into languages other 63 than English. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 6 69 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 7 70 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 8 71 3.2. Negotiation of Subscription Policies . . . . . . . . . . 10 72 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 11 73 3.4. Data Encodings . . . . . . . . . . . . . . . . . . . . . 12 74 3.4.1. Periodic Subscriptions . . . . . . . . . . . . . . . 12 75 3.4.2. On-Change Subscriptions . . . . . . . . . . . . . . . 13 76 3.5. Subscription Filters . . . . . . . . . . . . . . . . . . 13 77 3.6. Push Data Stream and Transport Mapping . . . . . . . . . 14 78 3.7. Subscription management . . . . . . . . . . . . . . . . . 18 79 3.7.1. Subscription management by RPC . . . . . . . . . . . 18 80 3.7.2. Subscription management by configuration . . . . . . 20 81 3.8. Other considerations . . . . . . . . . . . . . . . . . . 20 82 3.8.1. Authorization . . . . . . . . . . . . . . . . . . . . 20 83 3.8.2. Additional subscription primitives . . . . . . . . . 21 84 3.8.3. Robustness and reliability considerations . . . . . . 22 85 3.8.4. Update size and fragmentation considerations . . . . 22 86 3.8.5. Push data streams . . . . . . . . . . . . . . . . . . 22 87 3.8.6. Implementation considerations . . . . . . . . . . . . 23 88 3.8.7. Alignment with RFC 5277bis . . . . . . . . . . . . . 24 89 4. A YANG data model for management of datastore push 90 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 24 91 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 24 92 4.2. Update streams . . . . . . . . . . . . . . . . . . . . . 28 93 4.3. Filters . . . . . . . . . . . . . . . . . . . . . . . . . 29 94 4.4. Subscription configuration . . . . . . . . . . . . . . . 29 95 4.5. Subscription monitoring . . . . . . . . . . . . . . . . . 31 96 4.6. Notifications . . . . . . . . . . . . . . . . . . . . . . 31 97 4.7. RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . 32 98 4.7.1. Establish-subscription RPC . . . . . . . . . . . . . 32 99 4.7.2. Modify-subscription RPC . . . . . . . . . . . . . . . 34 100 4.7.3. Delete-subscription RPC . . . . . . . . . . . . . . . 36 101 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 36 102 6. Security Considerations . . . . . . . . . . . . . . . . . . . 51 103 7. Issues that are currently being worked and resolved . . . . . 51 104 7.1. Unresolved issues under discussion . . . . . . . . . . . 51 105 7.2. Agreement in principal . . . . . . . . . . . . . . . . . 52 106 7.3. Closed Issues . . . . . . . . . . . . . . . . . . . . . . 52 107 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53 108 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 109 9.1. Normative References . . . . . . . . . . . . . . . . . . 53 110 9.2. Informative References . . . . . . . . . . . . . . . . . 53 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54 113 1. Introduction 115 YANG [RFC6020] was originally designed for the Netconf protocol 116 [RFC6241], which originally put most emphasis on configuration. 117 However, YANG is not restricted to configuration data. YANG 118 datastores, i.e. datastores that contain data modeled according using 119 YANG, can contain configuration as well as operational data. It is 120 therefore reasonable to expect that data in YANG datastores will 121 increasingly be used to support applications that are not focused on 122 managing configurations but that are, for example, related to service 123 assurance. 125 Service assurance applications typically involve monitoring 126 operational state of networks and devices; of particular interest are 127 changes that this data undergoes over time. Likewise, there are 128 applications in which data and objects from one datastore need to be 129 made available both to applications in other systems and to remote 130 datastores [I-D.voit-netmod-yang-mount-requirements] 131 [I-D.clemm-netmod-mount]. This requires mechanisms that allow remote 132 systems to become quickly aware of any updates to allow to validate 133 and maintain cross-network integrity and consistency. 135 Traditional approaches to remote network state visibility rely 136 heavily on polling. With polling, data is periodically explicitly 137 retrieved by a client from a server to stay up-to-date. 139 There are various issues associated with polling-based management: 141 o It introduces additional load on network, devices, and 142 applications. Each polling cycle requires a separate yet arguably 143 redundant request that results in an interrupt, requires parsing, 144 consumes bandwidth. 146 o It lacks robustness. Polling cycles may be missed, requests may 147 be delayed or get lost, often particularly in cases when the 148 network is under stress and hence exactly when the need for the 149 data is the greatest. 151 o Data may be difficult to calibrate and compare. Polling requests 152 may undergo slight fluctuations, resulting in intervals of 153 different lengths which makes data hard to compare. Likewise, 154 pollers may have difficulty issuing requests that reach all 155 devices at the same time, resulting in offset polling intervals 156 which again make data hard to compare. 158 A more effective alternative is when an application can request to be 159 automatically updated as necessary of current content of the 160 datastore (such as a subtree, or data in a subtree that meets a 161 certain filter condition), and in which the server that maintains the 162 datastore subsequently pushes those updates. However, such a 163 solution does not currently exist. 165 The need to perform polling-based management is typically considered 166 an important shortcoming of management applications that rely on MIBs 167 polled using SNMP [RFC1157]. However, without a provision to support 168 a push-based alternative, there is no reason to believe that 169 management applications that operate on YANG datastores using 170 protocols such as NETCONF or Restconf [I-D.ietf-netconf-restconf] 171 will be any more effective, as they would follow the same request/ 172 response pattern. 174 While YANG allows the definition of notifications, such notifications 175 are generally intended to indicate the occurrence of certain well- 176 specified event conditions, such as a the onset of an alarm condition 177 or the occurrence of an error. A capability to subscribe to and 178 deliver event notifications has been defined in [RFC5277]. In 179 addition, configuration change notifications have been defined in 180 [RFC6470]. These change notifications pertain only to configuration 181 information, not to operational state, and convey the root of the 182 subtree to which changes were applied along with the edits, but not 183 the modified data nodes and their values. Furthermore, while 184 delivery of updates using notifications is a viable option, some 185 applications desire the ability to stream updates using other 186 transports. 188 Accordingly, there is a need for a service that allows client 189 applications to dynamically subscribe to updates of a YANG datastore 190 and that allows the server to push those updates, possibly using one 191 of several delivery mechanisms. Additionally, support for 192 subscriptions configured directly on the server are also useful when 193 dynamic signaling is undesirable or unsupported. The requirements 194 for such a service are documented in [I-D.i2rs-pub-sub-requirements]. 196 This document proposes a solution. The solution builds on top of the 197 Netconf Event Model [I-D.gonzalez-netconf-5277bis] which defines a 198 mechanism for the management of event subscriptions. At its core, 199 the solution that is defined here introduces a new set of event 200 streams including datastore push updates that clients can subscribe 201 to, as well as extensions to the event subscription model that allow 202 to manage policies that define what and when updates are trigged. To 203 this end, the document specifies a YANG data model that augments the 204 YANG data model (and RPCs) defined as part of the NETCONF Event 205 Model. 207 Specifically, the solution features the following capabilities: 209 o An extension to event subscription mechanisms allows clients to 210 subscribe to event streams containing automatic datastore updates. 211 The subscription allows clients to specify which data they are 212 interested in, what types of updates (e.g. create, delete, 213 modify), and to provide optional filters with criteria that data 214 must meet for updates to be sent. Furthermore, subscriptions can 215 specify a policy that directs when updates are provided. For 216 example, a client may request to be updated periodically in 217 certain intervals, or whenever data changes occur. 219 o The ability for a server to push back on requested subscription 220 parameters. Because not every server may support every requested 221 update policy for every piece of data, it is necessary for a 222 server to be able to indicate whether or not it is capable of 223 supporting a requested subscription, and possibly allow to 224 negotiate push update subscription parameters. For example, some 225 servers may have a lower limit to the period with which they can 226 send updates, or they may not support on-change updates for every 227 piece of data. 229 o A mechanism to communicate the updates themselves. For this, the 230 proposal leverages and extends existing YANG/Netconf/Restconf 231 mechanisms, defining special notifications that carry updates. In 232 addition, optional subscription parameters allow to specify which 233 transport should be used to stream updates, and to define QoS 234 extensions that allow to address aspects such as how to prioritize 235 between streams of updates. 237 2. Definitions and Acronyms 239 Data node: An instance of management information in a YANG datastore. 241 Data record: A record containing a set of one or more data node 242 instances and their associated values. 244 Datastore: A conceptual store of instantiated management information, 245 with individual data items represented by data nodes which are 246 arranged in hierarchical manner. 248 Datastream: A continuous stream of data records, each including a set 249 of updates, i.e. data node instances and their associated values. 251 Data subtree: An instantiated data node and the data nodes that are 252 hierarchically contained within it. 254 Dynamic subscription: A subscription negotiated between subscriber 255 and publisher vian establish, modify, and delete RPCs respectively 256 control plane signaling messages that are part of an existing 257 management association between and publisher. Subscriber and 258 receiver are the same system. 260 NACM: NETCONF Access Control Model 262 NETCONF: Network Configuration Protocol 264 Publisher: A server that sends push updates to a receiver according 265 to the terms of a subscription. In general, the publisher is also 266 the "owner" of the subscription. 268 Push-update stream: A conceptual data stream of a datastore that 269 streams the entire datastore contents continuously and perpetually. 271 Receiver: The target of push updates of a subscription. In case of a 272 dynamic subscription, receiver and subscriber are the same system. 273 However, in the case of a configured subscription, the receiver may 274 be a different system than the one that configured the subscription. 276 RPC: Remote Procedure Call 278 SNMP: Simple Network Management Protocol 280 Configured subscription: A subscription installed as part of a 281 configuration datastore via a configuration interface. 283 Subscriber: A client that negotiates a subscription with a server 284 ("publisher"). A client that establishes a configured subscription 285 is also considered a subscriber, even if it is not necessarily the 286 receiver of a subscription. 288 Subscription: A contract between a client ("subscriber") and a server 289 ("publisher"), stipulating which information the client wishes to 290 receive from the server (and which information the server has to 291 provide to the client) without the need for further solicitation. 293 Subscription filter: A filter that contains evaluation criteria which 294 are evaluated against YANG objects of a subscription. An update is 295 only published if the object meets the specified filter criteria. 297 Subscription policy: A policy that specifies under what circumstances 298 to push an update, e.g. whether updates are to be provided 299 periodically or only whenever changes occur. 301 Update: A data item containing the current value of a data node. 303 Update trigger: A trigger, as specified by a subscription policy, 304 that causes an update to be sent, respectively a data record to be 305 generated. An example of a trigger is a change trigger, invoked when 306 the value of a data node changes or a data node is created or 307 deleted, or a time trigger, invoked after the laps of a periodic time 308 interval. 310 URI: Uniform Resource Identifier 312 YANG: A data definition language for NETCONF 314 YANG-Push: The subscription and push mechanism for YANG datastores 315 that is specified in this document. 317 3. Solution Overview 319 This document specifies a solution for a push update subscription 320 service, which supports the dynamic as well as static (via 321 configuration) creation of subscriptions to information updates of 322 operational or configuration YANG data which are subsequently pushed 323 from the server to the client. 325 Dynamic subscriptions are initiated by clients who want to receive 326 push updates. Servers respond to requests for the creation of 327 subscriptions positively or negatively. Negative responses MAY 328 include information about why the subscription was not accepted, in 329 order to facilitate converging on an acceptable set of subscription 330 parameters. Similarly, configured subscriptions are configured as 331 part of a device's configuration. Once a subscription has been 332 established, datastore push updates are pushed from the server to the 333 receiver until the subscription ends. 335 Accordingly, the solution encompasses several components: 337 o The subscription model for configuration and management of the 338 subscriptions. 340 o The ability to provide hints for acceptable subscription 341 parameters, in cases where a subscription desired by a client 342 cannot currently be served. 344 o The stream of push updates. 346 In addition, there are a number of additional considerations, such as 347 the tie-in of the mechanisms with security mechanisms. Each of those 348 aspects will be discussed in the following subsections. 350 3.1. Subscription Model 352 YANG-Push subscriptions are defined using a data model that is itself 353 defined in YANG. This model augments the event subscription model 354 defined in [I-D.gonzalez-netconf-5277bis] and introduces several new 355 parameters, for example parameters that allow subscribers to specify 356 what to include in an update, what triggers an update, and how to 357 deliver updates. 359 The subscription model assumes the presence of one or more conceptual 360 perpetual datastreams of continuous updates that can be subscribed 361 to. There are several datastreams with predefined semantics, such as 362 the stream of updates of all operational data or the stream of 363 updates of all config data. In addition, it is possible to define 364 custom streams with customizable semantics. The model includes the 365 list of update datastreams that are supported by a system and 366 available for subscription. 368 The subscription model augments the NETCONF event subscription model 369 with a set of parameters as follows: 371 o An encoding for push updates. By default, updates are encoded 372 using XML, but JSON can be requested as an option and other 373 encodings may be supported in the future. 375 o An optional start time for the subscription. If the specified 376 start time is in the past, the subscription goes into effect 377 immediately. The start time also serves as anchor time for 378 periodic subscriptions, from which intervals at which to send 379 updates are calculated (see also below). 381 o An optional stop time for the subscription. Once the stop time is 382 reached, the subscription is automatically terminated. 384 o A subscription policy definition regarding the update trigger when 385 to send new updates. The trigger can be periodic or based on 386 change. 388 * For periodic subscriptions, the trigger is defined by a 389 parameter that defines the interval with which updates are to 390 be pushed. The start time of the subscription serves as anchor 391 time, defining one specific point in time at which an update 392 needs to be sent. Update intervals always fall on the points 393 in time that are a multiple of a period after the start time. 395 * EDITOR'S NOTE: A possible option to discuss concerns the 396 introduction of an additional parameter "changes-only" for 397 periodic subscription. Including this flag would results in 398 sending at the end of each period an update containing only 399 changes since the last update (i.e. a change-update as in the 400 case of an on-change subscription), not a full snapshot of the 401 subscribed information. Such an option might be interesting in 402 case of data that is largely static and bandwidth-constrained 403 environments. 405 * For on-change subscriptions, the trigger occurs whenever a 406 change in the subscribed information is detected. On-change 407 subscriptions have more complex semantics that can be guided by 408 additional parameters. Please refer also to Section 3.3. 410 + One parameter specifies the dampening period, i.e. the 411 interval that must pass before a successive update for the 412 same data node is sent. The first time a change is 413 detected, the update is sent immediately. If a subsequent 414 change is detected, another update for that object is only 415 sent once the dampening period has passed, containing the 416 value of the data node that is then valid. Note that the 417 dampening period applies to each object, not the set of all 418 objects that are part of the same subscription. This means 419 that on the first change of an object, an update for that 420 object is immediately sent, regardless of whether or not for 421 another object of the same subscription a dampening period 422 is already in effect. 424 + Another parameter allows to restrict the types of changes 425 for which updates are sent (changes to object values, object 426 creation or deletion events). It is conceivable to augment 427 the data model with additional parameters in the future to 428 specify even more refined policies, such as parameters that 429 specify the magnitude of a change that must occur before an 430 update is triggered. 432 + A third parameter specifies whether or not a complete update 433 with all the subscribed data should be sent at the beginning 434 of a subscription to facilitate synchronization and 435 establish the frame of reference for subsequent updates. 437 + EDITOR'S NOTE: Several semantic variations are conceivable. 438 In one variation, an on-change notification is sent 439 immediately, but successive dampening updates are sent at 440 fixed period intervals, grouping all changes of objects for 441 which changes have occurred since the sending of their last 442 update and the current dampening period. 444 o Optionally, a filter, or set of filters, describing the subset of 445 data items in the stream's data records that are of interest to 446 the subscriber. The server should only send to the subscriber the 447 data items that match the filter(s), when present. The absence of 448 a filter indicates that all data items from the stream are of 449 interest to the subscriber and all data records must be sent in 450 their entirety to the subscriber. The following types of filters 451 are introduced: subtree filters, with the same semantics as 452 defined in [RFC 6241],and XPath filters. In addition, as with any 453 subscription, an RFC 5277 filter MAY be used, with the same 454 semantics as defined in [RFC 5277]. Additional filter types can 455 be added through augmentations. Filters can be specified "inline" 456 as part of the subscription, or can be configured separately and 457 referenced by a subscription, in order to facilitate reuse of 458 complex filters. 460 The subscription data model is specified as part of the YANG data 461 model described later in this specification. Specifically, the 462 subscription parameters are defined in the "subscription-info" and 463 "update-policy" groupings. Receiver information is defined in the 464 "receiver-info" grouping. Information about the source address is 465 defined in the "push-source-info" grouping. It is conceivable that 466 additional subscription parameters might be added in the future. 467 This can be accomplished through augmentation of the subscription 468 data model. 470 3.2. Negotiation of Subscription Policies 472 A subscription rejection can be caused by the inability of the server 473 to provide a stream with the requested semantics. For example, a 474 server may not be able to support "on-change" updates for operational 475 data, or only support them for a limited set of data nodes. 477 Likewise, a server may not be able to support a requested update 478 frequency. 480 YANG-Push supports a simple negotiation between clients and servers 481 for subscription parameters. The negotiation is limited to a single 482 pair of subscription request and response. For negative responses, 483 the server SHOULD include in the returned error what subscription 484 parameters would have been accepted for the request. The returned 485 acceptable parameters constitute suggestions that, when followed, 486 increase the likelihood of success for subsequent requests. However, 487 they are no guarantee that subsequent requests for this client or 488 others will in fact be accepted. 490 In case a subscriber requests an encoding other than XML, and this 491 encoding is not supported by the server, the server simply indicates 492 in the response that the encoding is not supported. 494 A subscription negotiation capability has been introduced as part of 495 the NETCON Event Notifications model. However, the ability to 496 negotiate subscriptions is of particular importance in conjunction 497 with push updates, as server implementations may have limitations 498 with regards to what updates can be generated and at what velocity. 500 3.3. On-Change Considerations 502 On-change subscriptions allow clients to subscribe to updates 503 whenever changes to objects occur. As such, on-change subscriptions 504 are of particular interest for data that changes relatively 505 infrequently, yet that require applications to be notified with 506 minimal delay when changes do occur. 508 On-change subscriptions tend to be more difficult to implement than 509 periodic subscriptions. Specifically, on-change subscriptions may 510 involve a notion of state to see if a change occurred between past 511 and current state, or the ability to tap into changes as they occur 512 in the underlying system. Accordingly, on-change subscriptions may 513 not be supported by all implementations or for every object. 515 When an on-change subscription is requested for a datastream with a 516 given subtree filter, where not all objects support on-change update 517 triggers, the subscription request MUST be rejected. As a result, 518 on-change subscription requests will tend to be directed at very 519 specific, targeted subtrees with only few objects. 521 Any updates for an on-change subscription will include only objects 522 for which a change was detected. To avoid flooding clients with 523 repeated updates for fast-changing objects, or objects with 524 oscillating values, an on-change subscription allows for the 525 definition of a dampening period. Once an update for a given object 526 is sent, no other updates for this particular object are sent until 527 the end of the dampening period. Values sent at the end of the 528 dampening period are the values current when that dampening period 529 expires. In addition, updates include information about objects that 530 were deleted and ones that were newly created. 532 On-change subscriptions can be refined to let users subscribe only to 533 certain types of changes, for example, only to object creations and 534 deletions, but not to modifications of object values. 536 Additional refinements are conceivable. For example, in order to 537 avoid sending updates on objects whose values undergo only a 538 negligible change, additional parameters might be added to an on- 539 change subscription specifying a policy that states how large or 540 "significant" a change has to be before an update is sent. A simple 541 policy is a "delta-policy" that states, for integer-valued data 542 nodes, the minimum difference between the current value and the value 543 that was last reported that triggers an update. Also more 544 sophisticated policies are conceivable, such as policies specified in 545 percentage terms or policies that take into account the rate of 546 change. While not specified as part of this draft, such policies can 547 be accommodated by augmenting the subscription data model 548 accordingly. 550 3.4. Data Encodings 552 Subscribed data is encoded in either XML or JSON format. A server 553 MUST support XML encoding and MAY support JSON encoding. 555 It is conceivable that additional encodings may be supported as 556 options in the future. This can be accomplished by augmenting the 557 subscription data model with additional identity statements used to 558 refer to requested encodings. 560 3.4.1. Periodic Subscriptions 562 In a periodic subscription, the data included as part of an update 563 corresponds to data that could have been simply retrieved using a get 564 operation and is encoded in the same way. XML encoding rules for 565 data nodes are defined in [RFC6020]. JSON encoding rules are defined 566 in [I-D.ietf-netmod-yang-json]. This encoding is valid JSON, but 567 also has special encoding rules to identify module namespaces and 568 provide consistent type processing of YANG data. 570 3.4.2. On-Change Subscriptions 572 In an on-change subscription, updates need to allow to differentiate 573 between data nodes that were newly created since the last update, 574 data nodes that were deleted, and data nodes whose value changed. 576 XML encoding rules correspond to how data would be encoded in input 577 to Netconf edit-config operations as specified in [RFC6241] section 578 7.2, adding "operation" attributes to elements in the data subtree. 579 Specifically, the following values will be utilized: 581 o create: The data identified by the element has been added since 582 the last update. 584 o delete: The data identified by the element has been deleted since 585 the last update. 587 o merge: The data identified by the element has been changed since 588 the last update. 590 o replace: The data identified by the element has been replaced with 591 the update contents since the last update. 593 The remove value will not be utilized. 595 Contrary to edit-config operations, the data is sent from the server 596 to the client, not from the client to the server, and will not be 597 restricted to configuration data. 599 JSON encoding rules are roughly analogous to how data would be 600 encoded in input to a YANG-patch operation, as specified in 601 [I-D.ietf-netconf-yang-patch] section 2.2. However, no edit-ids will 602 be needed. Specifically, changes will be grouped under respective 603 "operation" containers for creations, deletions, and modifications. 605 3.5. Subscription Filters 607 Subscriptions can specify filters for subscribed data. The following 608 filters are supported in addition to RFC 5277 filters that apply to 609 any event subscription: 611 o subtree-filter: A subtree filter specifies a subtree that the 612 subscription refers to. When specified, updates will only concern 613 data nodes from this subtree. Syntax and semantics correspond to 614 that specified for [RFC6241] section 6. 616 o xpath-filter: An XPath filter specifies an XPath expression 617 applied to the data in an update, assuming XML-encoded data. 619 Only a single filter can be applied to a subscription at a time. 621 It is conceivable for implementations to support other filters. For 622 example, an on-change filter might specify that changes in values 623 should be sent only when the magnitude of the change since previous 624 updates exceeds a certain threshold. It is possible to augment the 625 subscription data model with additional filter types. 627 3.6. Push Data Stream and Transport Mapping 629 Pushing data based on a subscription could be considered analogous to 630 a response to a data retrieval request, e.g. a "get" request. 631 However, contrary to such a request, multiple responses to the same 632 request may get sent over a longer period of time. 634 A more suitable mechanism to consider is therefore that of a 635 notification. There are however some specifics that need to be 636 considered. Contrary to other notifications that are associated with 637 alarms and unexpected event occurrences, push updates are solicited, 638 i.e. tied to a particular subscription which triggered the 639 notification, and arguably only of interest to the subscriber, 640 respectively the intended receiver of the subscription. A 641 subscription therefore needs to be able to distinguish between 642 streams that underlie push updates and streams of other 643 notifications. By the same token, notifications associated with 644 updates and subscriptions to updates need to be distinguished from 645 other notifications, in that they enter a datastream of push updates, 646 not a stream of other event notifications. 648 A push update notification contains several parameters: 650 o A subscription correlator, referencing the name of the 651 subscription on whose behalf the notification is sent. 653 o A data node that contains a representation of the datastore 654 subtree containing the updates. The subtree is filtered per 655 access control rules to contain only data that the subscriber is 656 authorized to see. Also, depending on the subscription type, 657 i.e., specifically for on-change subscriptions, the subtree 658 contains only the data nodes that contain actual changes. (This 659 can be simply a node of type string or, for XML-based encoding, 660 anyxml.) 662 Notifications are sent using elements as defined in 663 [RFC5277]. Alternative transports are conceivable but outside the 664 scope of this specification. 666 The solution specified in this document uses notifications to define 667 datastore updates. The contents of the notification includes a set 668 of explicitly defined data nodes. For this purpose, two new generic 669 notifications are introduced, "push-update" and "push-change-update". 670 Those notifications define how mechanisms that carry YANG 671 notifications (e.g. Netconf notifications and Restconf) can be used 672 to carry data records with updates of datastore contents as specified 673 by a subscription. It is possible also map notifications to other 674 transports and encodings and use the same subscription model; 675 however, the definition of such mappings is outside the scope of this 676 document. 678 Push-update notification defines updates for a periodic subscription, 679 as well as for the initial update of an on-change subscription used 680 to synchronize the receiver at the start of a new subscription. The 681 update record contains a data snippet that contains an instantiated 682 subtree with the subscribed contents. The content of the update 683 record is equivalent to the contents that would be obtained had the 684 same data been explicitly retrieved using e.g. a Netconf "get"- 685 operation, with the same filters applied. 687 The contents of the notification conceptually represents the union of 688 all data nodes in the yang modules supported by the server. However, 689 in a YANG data model, it is not practical to model the precise data 690 contained in the updates as part of the notification. This is 691 because the specific data nodes supported depend on the implementing 692 system and may even vary dynamically. Therefore, to capture this 693 data, a single parameter that can represent any datastore contents is 694 used, not parameters that represent data nodes one at a time. 696 Push-change-update notification defines updates for on-change 697 subscriptions. The update record here contains a data snippet that 698 indicates the changes that data nodes have undergone, i.e. that 699 indicates which data nodes have been created, deleted, or had changes 700 to their values. The format follows the same format that operations 701 that apply changes to a data tree would apply, indicating the 702 creates, deletes, and modifications of data nodes. 704 The following is an example of push notification. It contains an 705 update for subscription 1011, including a subtree with root foo that 706 contains a leaf, bar: 708 710 2015-03-09T19:14:56Z 711 713 1011 714 2015-03-09T19:14:56Z 715 716 717 some_string 718 719 720 721 723 Figure 1: Push example 725 The following is an example of an on-change notification. It 726 contains an update for subscription 89, including a new value for a 727 leaf called beta, which is a child of a top-level container called 728 alpha: 730 732 2015-03-09T19:14:56Z 733 735 89 736 2015-03-09T19:14:56Z 737 738 739 1500 740 741 742 743 745 Figure 2: Push example for on change 747 The equivalent update when requesting json encoding: 749 751 2015-03-09T19:14:56Z 752 754 89 755 2015-03-09T19:14:56Z 756 757 { 758 "ietf-yang-patch:yang-patch": { 759 "patch-id": [ 760 null 761 ], 762 "edit": [ 763 { 764 "edit-id": "edit1", 765 "operation": "merge", 766 "target": "/alpha/beta", 767 "value": { 768 "beta": 1500 769 } 770 } 771 ] 772 } 773 } 774 775 776 778 Figure 3: Push example for on change with JSON 780 When the beta leaf is deleted, the server may send 781 783 2015-03-09T19:14:56Z 784 786 89 787 2015-03-09T19:14:56Z 788 789 790 792 793 794 795 797 Figure 4: 2nd push example for on change update 799 3.7. Subscription management 801 There are two ways in which subscriptions can be managed, as 802 specified in the NETCONF Event Notifications model: RPC-based and 803 configuration based. Any given subscription is either RPC-based or 804 configuration-based. There is no mixing-and-matching of RPC and 805 configuration operations. Specifically, a configured subscription 806 cannot be modified or deleted using RPC. Likewise, a subscription 807 established via RPC cannot be modified or deleted through 808 configuration operations. 810 The following sections describe how subscription management is 811 applied to YANG Push subscriptions. 813 3.7.1. Subscription management by RPC 815 RPC-based subscription allows a subscriber to establish a 816 subscription via an RPC call. The subscriber and the receiver are 817 the same entity, i.e. a subscriber cannot subscribe or in other ways 818 interfere with a subscription on another receiver's behalf. The 819 lifecycle of the subscription is dependent on the lifecyle of the 820 transport session over which the subscription was requested. For 821 example, when a Netconf session over which a subscription was 822 established is torn down, the subscription is automatically 823 terminated (and needs to be re-initiated when a new session is 824 established). Alternatively, a subscriber can also decide to delete 825 a subscription via another RPC. 827 When an establish-subscription request is successful, the 828 subscription identifier of the freshly established subscription is 829 returned. 831 A subscription can be rejected for multiple reasons, including the 832 lack of authorization to establish a subscription, the lack of read 833 authorization on the requested data node, or the inability of the 834 server to provide a stream with the requested semantics. In such 835 cases, no subscription is established. Instead, the subscription- 836 result with the failure reason is returned as part of the RPC 837 response. In addition, a set of alternative subscription parameters 838 MAY be returned that would likely have resulted in acceptance of the 839 subscription request, which the subscriber may try for a future 840 subscription attempt. 842 It should be noted that a rejected subscription does not result in 843 the generation of an rpc-reply with an rpc-error element, as neither 844 the specification of YANG-push specific errors nor the specification 845 of additional data parameters to be returned in an error case are 846 supported as part of a YANG data model. 848 For instance, for the following request: 850 852 854 push-update 855 858 500 859 encode-xml 860 861 863 Figure 5: Establish-Subscription example 865 the server might return: 867 869 871 error-insufficient-resources 872 873 2000 874 876 Figure 6: Error response example 878 A subscriber that establishes a subscription using RPC can modify or 879 delete the subscription using other RPCs. When the session between 880 subscriber and publisher is terminated, the subscription is 881 implicitly deleted. 883 3.7.2. Subscription management by configuration 885 Configuration-based subscription allows a subscription to be 886 established as part of a server's configuration. This allows to 887 persist subscriptions. Persisted subscriptions allow for a number of 888 additional options than RPC-based subscriptions. As part of a 889 configured subscription, a receiver needs to be specified. It is 890 thus possible to have a different system acting as subscriber (the 891 client creating the subscription) and as receiver (the client 892 receiving the updates). In addition, a configured subscription 893 allows to specify which transport protocol should be used, as well as 894 the sender source (for example, a particular interface or an address 895 of a specific VRF) from which updates are to be pushed. 897 Configuration-based subscriptions cannot be modified or deleted using 898 RPCs. Instead, configured subscriptions are deleted as part of 899 regular configuration operations. Servers SHOULD reject attempts to 900 modify configurations of active subscriptions. This way, race 901 conditions in which a receiver may not be aware of changed 902 subscription policies are avoided. 904 3.8. Other considerations 906 3.8.1. Authorization 908 A receiver of subscription data may only be sent updates for which 909 they have proper authorization. Data that is being pushed therefore 910 needs to be subjected to a filter that applies all corresponding 911 rules applicable at the time of a specific pushed update, removing 912 any non-authorized data as applicable. 914 The authorization model for data in YANG datastores is described in 915 the Netconf Access Control Model [RFC6536]. However, some 916 clarifications to that RFC are needed so that the desired access 917 control behavior is applied to pushed updates. 919 One of these clarifications is that a subscription may only be 920 established if the Receiver has read access to the target data node. 922 +-------------+ +-------------+ 923 subscription | protocol | | target | 924 request --> | operation | -------------> | data node | 925 | allowed? | datastore | access | 926 +-------------+ or state | allowed? | 927 data access +-------------+ 929 Figure 7: Access control for subscription 931 Likewise if a receiver no longer has read access permission to a 932 target data node, the subscription must be abnormally terminated 933 (with loss of access permission as the reason provided). 935 Another clarification to [RFC6536] is that each of the individual 936 nodes in a pushed update must also go through access control 937 filtering. This includes new nodes added since the last push update, 938 as well as existing nodes. For each of these read access must be 939 verified. The methods of doing this efficiently are left to 940 implementation. 942 +-------------+ +-------------------+ 943 subscription | data node | yes | | 944 update --> | access | ---> | add data node | 945 | allowed? | | to update message | 946 +-------------+ +-------------------+ 948 Figure 8: Access control for push updates 950 If there are read access control changes applied under the target 951 node, no notifications indicating the fact that this has occurred 952 need to be provided. 954 3.8.2. Additional subscription primitives 956 Other possible operations include the ability for a Subscriber to 957 request the suspension/resumption of a Subscription with a Publisher. 958 However, subscriber driven suspension is not viewed as essential at 959 this time, as a simpler alternative is to remove a subscription and 960 reestablish it when needed. 962 It should be noted that this does not affect the ability of the 963 Publisher to suspend a subscription. This can occur in cases the 964 server is not able to serve the subscription for a certain period of 965 time, and indicated by a corresponding notification. 967 3.8.3. Robustness and reliability considerations 969 Particularly in the case of on-change push updates, it is important 970 that push updates do not get lost. 972 YANG-Push uses a secure and reliable transport. Notifications are 973 not getting reordered, and in addition contain a time stamp. For 974 those reasons, for the transport of push-updates, we believe that 975 additional reliability mechanisms at the application level, such as 976 sequence numbers for push updates, are not required. 978 At the same time, it is conceivable that under certain circumstances, 979 a push server is not able to generate the update notifications that 980 it had committed to when accepting a subcription. In those 981 circumstances, the server needs to inform the receiver of the 982 situation. For this purpose, notifications are defined that a push 983 server can use to inform subscribers/ receivers when a subscription 984 is (temporarily) suspended, when a suspended subscription is resumed, 985 and when a a subscription is terminated. This way, receivers will be 986 able to rely on a subscription, knowing that they will be informed of 987 any situations in which updates might be missed. 989 3.8.4. Update size and fragmentation considerations 991 Depending on the subscription, the volume of updates can become quite 992 large. There is no inherent limitation to the amount of data that 993 can be included in a notification. That said, it may not always be 994 practical to send the entire update in a single chunk. 995 Implementations MAY therefore choose, at their discretion, to "chunk" 996 updates and break them out into several update notifications. 998 3.8.5. Push data streams 1000 There are several conceptual data streams introduced in this 1001 specification: 1003 o yang-push includes the entirety of YANG data, including both 1004 configuration and operational data. 1006 o operational-push includes all operational (read-only) YANG data 1008 o config-push includes all YANG configuration data. 1010 It is conceivable to introduce other data streams with more limited 1011 scope, for example: 1013 o operdata-nocounts-push, a datastream containing all operational 1014 (read-only) data with the exception of counters 1016 o other custom datastreams 1018 Those data streams make particular sense for use cases involving 1019 service assurance (not relying on operational data), and for use 1020 cases requiring on-change update triggers which make no sense to 1021 support in conjunction with fast-changing counters. While it is 1022 possible to specify subtree filters on yang-push to the same effect, 1023 having those data streams greatly simplifies articulating 1024 subscriptions in such scenarios. 1026 3.8.6. Implementation considerations 1028 Implementation specifics are outside the scope of this specification. 1029 That said,it should be noted that monitoring of operational state 1030 changes inside a system can be associated with significant 1031 implementation challenges. 1033 Even periodic retrieval of operational state alone, to be able to 1034 push it, can consume considerable system resources. Configuration 1035 data may in many cases be persisted in an actual database or a 1036 configuration file, where retrieval of the database content or the 1037 file itself is reasonably straightforward and computationally 1038 inexpensive. However, retrieval of operational data may, depending 1039 on the implementation, require invocation of APIs, possibly on an 1040 object-by-object basis, possibly involving additional internal 1041 interrupts, etc. 1043 For those reasons, if is important for an implementation to 1044 understand what subscriptions it can or cannot support. It is far 1045 preferrable to decline a subscription request, than to accept it only 1046 to result in subsequent failure later. 1048 Whether or not a subscription can be supported will in general be 1049 determined by a combination of several factors, including the 1050 subscription policy (on-change or periodic, with on-change in general 1051 being the more challenging of the two), the period in which to report 1052 changes (1 second periods will consume more resources than 1 hour 1053 periods), the amount of data in the subtree that is being subscribed 1054 to, and the number and combination of other subscriptions that are 1055 concurrently being serviced. 1057 When providing access control to every node in a pushed update, it is 1058 possible to make and update efficient access control filters for an 1059 update. These filters can be set upon subscription and applied 1060 against a stream of updates. These filters need only be updated when 1061 (a) there is a new node added/removed from the subscribed tree with 1062 different permissions than its parent, or (b) read access permissions 1063 have been changed on nodes under the target node for the subscriber. 1065 3.8.7. Alignment with RFC 5277bis 1067 A new draft has been chartered by the Netconf Working Group to 1068 replace the current Netconf Event Model defined in RFC 5277. Future 1069 revisions of this document will leverage RFC 5277bis as applicable. 1070 It is anticipated that portions of the data model and subscription 1071 management that are now defined in this this document and that are 1072 not applicable only to YANG-Push, but to more general event 1073 subscriptions, will move to RFC 5277bis. 1075 4. A YANG data model for management of datastore push subscriptions 1077 4.1. Overview 1079 The YANG data model for datastore push subscriptions is depicted in 1080 the following figure. 1082 module: ietf-yang-push 1083 augment /notif-bis:establish-subscription/notif-bis:input: 1084 +---- subscription-start-time? yang:date-and-time 1085 +---- subscription-stop-time? yang:date-and-time 1086 +---- (update-trigger)? 1087 | +--:(periodic) 1088 | | +---- period yang:timeticks 1089 | +--:(on-change) {on-change}? 1090 | +---- no-synch-on-start? empty 1091 | +---- dampening-period yang:timeticks 1092 | +---- excluded-change* change-type 1093 +---- dscp? inet:dscp 1094 | {notif-bis:configured-subscriptions}? 1095 +---- subscription-priority? uint8 1096 +---- subscription-dependency? string 1097 augment /notif-bis:establish-subscription/notif-bis:input/ 1098 | notif-bis:filter-type: 1099 +--:(update-filter) 1100 +---- (update-filter)? 1101 +--:(subtree) 1102 | +---- subtree-filter 1103 +--:(xpath) 1104 +---- xpath-filter? yang:xpath1.0 1106 augment /notif-bis:establish-subscription/notif-bis:output: 1107 +---- subscription-start-time? yang:date-and-time 1108 +---- subscription-stop-time? yang:date-and-time 1109 +---- (update-trigger)? 1110 | +--:(periodic) 1111 | | +---- period yang:timeticks 1112 | +--:(on-change) {on-change}? 1113 | +---- no-synch-on-start? empty 1114 | +---- dampening-period yang:timeticks 1115 | +---- excluded-change* change-type 1116 +---- dscp? inet:dscp 1117 | {notif-bis:configured-subscriptions}? 1118 +---- subscription-priority? uint8 1119 +---- subscription-dependency? string 1120 augment /notif-bis:establish-subscription/notif-bis:output/ 1121 | notif-bis:result/notif-bis:no-success/notif-bis:filter-type: 1122 +--:(update-filter) 1123 +---- (update-filter)? 1124 +--:(subtree) 1125 | +---- subtree-filter 1126 +--:(xpath) 1127 +---- xpath-filter? yang:xpath1.0 1128 augment /notif-bis:modify-subscription/notif-bis:input: 1129 +---- subscription-start-time? yang:date-and-time 1130 +---- subscription-stop-time? yang:date-and-time 1131 +---- (update-trigger)? 1132 | +--:(periodic) 1133 | | +---- period yang:timeticks 1134 | +--:(on-change) {on-change}? 1135 | +---- no-synch-on-start? empty 1136 | +---- dampening-period yang:timeticks 1137 | +---- excluded-change* change-type 1138 +---- dscp? inet:dscp 1139 | {notif-bis:configured-subscriptions}? 1140 +---- subscription-priority? uint8 1141 +---- subscription-dependency? string 1142 augment /notif-bis:modify-subscription/notif-bis:input/ 1143 | notif-bis:filter-type: 1144 +--:(update-filter) 1145 +---- (update-filter)? 1146 +--:(subtree) 1147 | +---- subtree-filter 1148 +--:(xpath) 1149 +---- xpath-filter? yang:xpath1.0 1150 augment /notif-bis:modify-subscription/notif-bis:output: 1151 +---- subscription-start-time? yang:date-and-time 1152 +---- subscription-stop-time? yang:date-and-time 1153 +---- (update-trigger)? 1154 | +--:(periodic) 1155 | | +---- period yang:timeticks 1156 | +--:(on-change) {on-change}? 1157 | +---- no-synch-on-start? empty 1158 | +---- dampening-period yang:timeticks 1159 | +---- excluded-change* change-type 1160 +---- dscp? inet:dscp 1161 | {notif-bis:configured-subscriptions}? 1162 +---- subscription-priority? uint8 1163 +---- subscription-dependency? string 1164 augment /notif-bis:modify-subscription/notif-bis:output/ 1165 | notif-bis:result/notif-bis:no-success/notif-bis:filter-type: 1166 +--:(update-filter) 1167 +---- (update-filter)? 1168 +--:(subtree) 1169 | +---- subtree-filter 1170 +--:(xpath) 1171 +---- xpath-filter? yang:xpath1.0 1172 augment /notif-bis:subscription-started: 1173 +---- subscription-start-time? yang:date-and-time 1174 +---- subscription-stop-time? yang:date-and-time 1175 +---- (update-trigger)? 1176 | +--:(periodic) 1177 | | +---- period yang:timeticks 1178 | +--:(on-change) {on-change}? 1179 | +---- no-synch-on-start? empty 1180 | +---- dampening-period yang:timeticks 1181 | +---- excluded-change* change-type 1182 +---- dscp? inet:dscp 1183 | {notif-bis:configured-subscriptions}? 1184 +---- subscription-priority? uint8 1185 +---- subscription-dependency? string 1186 augment /notif-bis:subscription-started/notif-bis:filter-type: 1187 +--:(update-filter) 1188 +---- (update-filter)? 1189 +--:(subtree) 1190 | +---- subtree-filter 1191 +--:(xpath) 1192 +---- xpath-filter? yang:xpath1.0 1193 augment /notif-bis:subscription-modified: 1194 +---- subscription-start-time? yang:date-and-time 1195 +---- subscription-stop-time? yang:date-and-time 1196 +---- (update-trigger)? 1197 | +--:(periodic) 1198 | | +---- period yang:timeticks 1199 | +--:(on-change) {on-change}? 1200 | +---- no-synch-on-start? empty 1201 | +---- dampening-period yang:timeticks 1202 | +---- excluded-change* change-type 1203 +---- dscp? inet:dscp 1204 | {notif-bis:configured-subscriptions}? 1205 +---- subscription-priority? uint8 1206 +---- subscription-dependency? string 1207 augment /notif-bis:subscription-modified/notif-bis:filter-type: 1208 +--:(update-filter) 1209 +---- (update-filter)? 1210 +--:(subtree) 1211 | +---- subtree-filter 1212 +--:(xpath) 1213 +---- xpath-filter? yang:xpath1.0 1214 augment /notif-bis:filters/notif-bis:filter/notif-bis:filter-type: 1215 +--:(update-filter) 1216 +--rw (update-filter)? 1217 +--:(subtree) 1218 | +--rw subtree-filter 1219 +--:(xpath) 1220 +--rw xpath-filter? yang:xpath1.0 1221 augment /notif-bis:subscription-config/notif-bis:subscription: 1222 +--rw subscription-start-time? yang:date-and-time 1223 +--rw subscription-stop-time? yang:date-and-time 1224 +--rw (update-trigger)? 1225 | +--:(periodic) 1226 | | +--rw period yang:timeticks 1227 | +--:(on-change) {on-change}? 1228 | +--rw no-synch-on-start? empty 1229 | +--rw dampening-period yang:timeticks 1230 | +--rw excluded-change* change-type 1231 +--rw dscp? inet:dscp 1232 | {notif-bis:configured-subscriptions}? 1233 +--rw subscription-priority? uint8 1234 +--rw subscription-dependency? string 1235 augment /notif-bis:subscription-config/notif-bis:subscription/ 1236 | notif-bis:filter-type: 1237 +--:(update-filter) 1238 +--rw (update-filter)? 1239 +--:(subtree) 1240 | +--rw subtree-filter 1241 +--:(xpath) 1242 +--rw xpath-filter? yang:xpath1.0 1243 augment /notif-bis:subscriptions/notif-bis:subscription: 1244 +--ro subscription-start-time? yang:date-and-time 1245 +--ro subscription-stop-time? yang:date-and-time 1246 +--ro (update-trigger)? 1247 | +--:(periodic) 1248 | | +--ro period yang:timeticks 1249 | +--:(on-change) {on-change}? 1250 | +--ro no-synch-on-start? empty 1251 | +--ro dampening-period yang:timeticks 1252 | +--ro excluded-change* change-type 1253 +--ro dscp? inet:dscp 1254 | {notif-bis:configured-subscriptions}? 1255 +--ro subscription-priority? uint8 1256 +--ro subscription-dependency? string 1257 augment /notif-bis:subscriptions/notif-bis:subscription/ 1258 | notif-bis:filter-type: 1259 +--:(update-filter) 1260 +--ro (update-filter)? 1261 +--:(subtree) 1262 | +--ro subtree-filter 1263 +--:(xpath) 1264 +--ro xpath-filter? yang:xpath1.0 1265 notifications: 1266 +---n push-update 1267 | +--ro subscription-id notif-bis:subscription-id 1268 | +--ro time-of-update? yang:date-and-time 1269 | +--ro (encoding)? 1270 | +--:(encode-xml) 1271 | | +--ro datastore-contents-xml? datastore-contents-xml 1272 | +--:(encode-json) {notif-bis:json}? 1273 | +--ro datastore-contents-json? datastore-contents-json 1274 +---n push-change-update {on-change}? 1275 +--ro subscription-id notif-bis:subscription-id 1276 +--ro time-of-update? yang:date-and-time 1277 +--ro (encoding)? 1278 +--:(encode-xml) 1279 | +--ro datastore-changes-xml? datastore-changes-xml 1280 +--:(encode-json) {notif-bis:json}? 1281 +--ro datastore-changes-yang? datastore-changes-json 1283 Figure 9: Model structure 1285 The components of the model are described in the following 1286 subsections. 1288 4.2. Update streams 1290 Container "update-streams" is used to indicate which data streams are 1291 provided by the system and can be subscribed to. For this purpose, 1292 it contains a leaf list of data nodes identifying the supported 1293 streams. 1295 4.3. Filters 1297 Container "filters" contains a list of configurable data filters, 1298 each specified in its own list element. This allows users to 1299 configure filters separately from an actual subscription, which can 1300 then be referenced from a subscription. This facilitates the reuse 1301 of filter definitions, which can be important in case of complex 1302 filter conditions. 1304 One of three types of filters can be specified as part of a filter 1305 list element. Subtree filters follow syntax and semantics of RFC 1306 6241 and allow to specify which subtree(s) to subscribe to. In 1307 addition, XPath filters can be specified for more complex filter 1308 conditions. Finally, filters can be specified using syntax and 1309 semantics of RFC5277. 1311 It is conceivable to introduce other types of filters; in that case, 1312 the data model needs to be augmented accordingly. 1314 4.4. Subscription configuration 1316 As an optional feature, configured-subscriptions, allows for the 1317 configuration of subscriptions as opposed to RPC. Subscriptions 1318 configurations are represented by list subscription-config. Each 1319 subscription is represented through its own list element and includes 1320 the following components: 1322 o "subscription-id" is an identifier used to refer to the 1323 subscription. 1325 o "stream" refers to the stream being subscribed to. The 1326 subscription model assumes the presence of perpetual and 1327 continuous streams of updates. Various streams are defined: 1328 "push-update" covers the entire set of YANG data in the server. 1329 "operational-push" covers all operational data, while "config- 1330 push" covers all configuration data. Other streams could be 1331 introduced in augmentations to the model by introducing additional 1332 identities. 1334 o "encoding" refers to the encoding requested for the data updates. 1335 By default, updates are encoded using XML. However, JSON can be 1336 requested as an option if the json-enconding feature is supported. 1337 Other encodings may be supported in the future. 1339 o "subscription-start-time" specifies when the subscription is 1340 supposed to start. The start time also serves as anchor time for 1341 periodic subscriptions (see below). 1343 o "subscription-stop-time" specifies a stop time for the 1344 subscription. Once the stop time is reached, the subscription is 1345 automatically terminated. However, even when terminated, the 1346 subscription entry remains part of the configuration unless 1347 explicity deleted from the configuration. It is possible to 1348 effectively "resume" a stopped subscription by reconfiguring the 1349 stop time. 1351 o Filters for a subscription can be specified using a choice, 1352 allowing to either reference a filter that has been separately 1353 configured or entering its definition inline. 1355 o A choice of subscription policies allows to define when to send 1356 new updates - periodic or on change. 1358 * For periodic subscriptions, the trigger is defined by a 1359 "period", a parameter that defines the interval with which 1360 updates are to be pushed. The start time of the subscription 1361 serves as anchor time, defining one specific point in time at 1362 which an update needs to be sent. Update intervals always fall 1363 on the points in time that are a multiple of a period after the 1364 start time. 1366 * For on-change subscriptions, the trigger occurs whenever a 1367 change in the subscribed information is detected. On-change 1368 subscriptions have more complex semantics that is guided by 1369 additional parameters. "dampening-period" specifies the 1370 interval that must pass before a successive update for the same 1371 data node is sent. The first time a change is detected, the 1372 update is sent immediately. If a subsequent change is 1373 detected, another update is only sent once the dampening period 1374 has passed, containing the value of the data node that is then 1375 valid. "excluded-change" allows to restrict the types of 1376 changes for which updates are sent (changes to object values, 1377 object creation or deletion events). "no-synch-on-start" is a 1378 flag that allows to specify whether or not a complete update 1379 with all the subscribed data should be sent at the beginning of 1380 a subscription; if the flag is omitted, a complete update is 1381 sent to facilitate synchronization. It is conceivable to 1382 augment the data model with additional parameters in the future 1383 to specify even more refined policies, such as parameters that 1384 specify the magnitude of a change that must occur before an 1385 update is triggered. 1387 o This is followed with a list of receivers for the subscription, 1388 indicating for each receiver the transport that should be used for 1389 push updates (if options other than Netconf are supported). It 1390 should be noted that the receiver does not have to be the same 1391 system that configures the subscription. 1393 o Finally, "push-source" can be used to specify the source of push 1394 updates, either a specific interface or server address. 1396 A subscription established through configuration cannot be deleted 1397 using an RPC. Likewise, subscriptions established through RPC cannot 1398 be deleted through configuration. 1400 The deletion of a subscription, whether through RPC or configuration, 1401 results in immediate termination of the subsciption. 1403 4.5. Subscription monitoring 1405 Subscriptions can be subjected to management themselves. For 1406 example, it is possible that a server may no longer be able to serve 1407 a subscription that it had previously accepted. Perhaps it has run 1408 out of resources, or internal errors may have occurred. When this is 1409 the case, a server needs to be able to temporarily suspend the 1410 subscription, or even to terminate it. More generally, the server 1411 should provide a means by which the status of subscriptions can be 1412 monitored. 1414 Container "subscriptions" contains the state of all subscriptions 1415 that are currently active. This includes subscriptions that were 1416 established (and have not yet been deleted) using RPCs, as well as 1417 subscriptions that have been configured as part of configuration. 1419 Each subscription is represented as a list element "datastore-push- 1420 subscription". The associated information includes an identifier for 1421 the subscription, a subscription status, as well as the various 1422 subscription parameters that are in effect. The subscription status 1423 indicates whether the subscription is currently active and healthy, 1424 or if it is degraded in some form. Leaf "configured-subscription" 1425 indicates whether the subscription came into being via configuration 1426 or via RPC. 1428 Subscriptions that were established by RPC are removed from the list 1429 once they expire (reaching stop-time )or when they are terminated. 1430 Subscriptions that were established by configuration need to be 1431 deleted from the configuration by a configuration editing operation. 1433 4.6. Notifications 1435 A server needs to indicate any changes in status of a subscription to 1436 the receiver through a notification. Specifically, subscribers need 1437 to be informed of the following: 1439 o A subscription has been temporarily suspended (including the 1440 reason) 1442 o A subscription (that had been suspended earlier) is once again 1443 operational 1445 o A subscription has been terminated (including the reason) 1447 o A subscription has been modified (including the current set of 1448 subscription parameters in effect) 1450 Finally, a server might provide additional information about 1451 subscriptions, such as statistics about the number of data updates 1452 that were sent. However, such information is currently outside the 1453 scope of this specification. 1455 4.7. RPCs 1457 YANG-Push subscriptions are established, modified, and deleted using 1458 three RPCs. 1460 4.7.1. Establish-subscription RPC 1462 The subscriber sends an establish-subscription RPC with the 1463 parameters in section 3.1. For instance 1465 1467 1469 push-update 1470 1473 500 1474 encode-xml 1475 1476 1478 Figure 10: Establish-subscription RPC 1480 The server must respond explicitly positively (i.e., subscription 1481 accepted) or negatively (i.e., subscription rejected) to the request. 1482 Positive responses include the subscription-id of the accepted 1483 subscription. In that case a server may respond: 1485 1487 1489 ok 1490 1491 1493 52 1494 1495 1497 Figure 11: Establish-subscription positive RPC response 1499 A subscription can be rejected for multiple reasons, including the 1500 lack of authorization to establish a subscription, the lack of read 1501 authorization on the requested data node, or the inability of the 1502 server to provide a stream with the requested semantics. . 1504 When the requester is not authorized to read the requested data node, 1505 the returned indicates an authorization error and the 1506 requested node. For instance, if the above request was unauthorized 1507 to read node "ex:foo" the server may return: 1509 1511 1513 error-data-not-authorized 1514 1515 1517 Figure 12: Establish-subscription access denied response 1519 If a request is rejected because the server is not able to serve it, 1520 the server SHOULD include in the returned error what subscription 1521 parameters would have been accepted for the request. However, they 1522 are no guarantee that subsequent requests for this client or others 1523 will in fact be accepted. 1525 For example, for the following request: 1527 1529 1531 push-update 1532 1535 10 1536 encode-xml 1537 1538 1540 Figure 13: Establish-subscription request example 2 1542 A server that cannot serve on-change updates but periodic updates 1543 might return the following: 1545 1547 1549 error-no-such-option 1550 1551 100 1552 1554 Figure 14: Establish-subscription error response example 2 1556 4.7.2. Modify-subscription RPC 1558 The subscriber may send a modify-subscription PRC for a subscription 1559 previously established using RPC The subscriber may change any 1560 subscription parameters by including the new values in the modify- 1561 subscription RPC. Parameters not included in the rpc should remain 1562 unmodified. For illustration purposes we include an exchange example 1563 where a subscriber modifies the period of the subscription. 1565 1567 1569 push-update 1570 1571 1011 1572 1573 1576 250 1577 encode-xml 1578 1579 1581 Figure 15: Modify subscription request 1583 The server must respond explicitly positively (i.e., subscription 1584 accepted) or negatively (i.e., subscription rejected) to the request. 1585 Positive responses include the subscription-id of the accepted 1586 subscription. In that case a server may respond: 1588 1590 1592 ok 1593 1594 1596 1011 1597 1598 1600 Figure 16: Modify subscription response 1602 If the subscription modification is rejected, the server must send a 1603 response like it does for an establish-subscription and maintain the 1604 subscription as it was before the modification request. A 1605 subscription may be modified multiple times. 1607 A configured subscription cannot be modified using modify- 1608 subscription RPC. Instead, the configuration needs to be edited as 1609 needed. 1611 4.7.3. Delete-subscription RPC 1613 To stop receiving updates from a subscription and effectively delete 1614 a subscription that had previously been established using an 1615 establish-subscription RPC, a subscriber can send a delete- 1616 subscription RPC, which takes as only input the subscription-id. For 1617 example 1619 1621 1623 1624 1011 1625 1626 1627 1629 1631 1632 1634 Figure 17: Delete subscription 1636 Configured subscriptions cannot be deleted via RPC, but have to be 1637 removed from the configuration. 1639 5. YANG module 1641 file "ietf-yang-push@2016-06-15.yang" 1642 module ietf-yang-push { 1643 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1644 prefix yp; 1646 import ietf-inet-types { 1647 prefix inet; 1648 } 1649 import ietf-yang-types { 1650 prefix yang; 1651 } 1652 import ietf-event-notifications { 1653 prefix notif-bis; 1654 } 1655 import ietf-5277-netconf { 1656 prefix notif; 1657 } 1658 organization "IETF"; 1659 contact 1660 "WG Web: 1661 WG List: 1663 WG Chair: Mahesh Jethanandani 1664 1666 WG Chair: Mehmet Ersue 1667 1669 Editor: Alexander Clemm 1670 1672 Editor: Eric Voit 1673 1675 Editor: Alberto Gonzalez Prieto 1676 1678 Editor: Ambika Prasad Tripathy 1679 1681 Editor: Einar Nilsen-Nygaard 1682 "; 1683 description 1684 "This module contains conceptual YANG specifications 1685 for YANG push."; 1687 revision 2016-06-15 { 1688 description 1689 "First revision to incorporate RFC 5277-bis."; 1690 reference "YANG Datastore Push, draft-ietf-netconf-yang-push-03"; 1691 } 1693 feature on-change { 1694 description 1695 "This feature indicates that on-change updates are 1696 supported."; 1697 } 1699 /* 1700 * IDENTITIES 1701 */ 1703 /* Additional errors for subscription operations */ 1704 identity error-data-not-authorized { 1705 base notif-bis:error; 1706 description 1707 "No read authorization for a requested data node."; 1708 } 1710 /* Additional types of streams */ 1711 identity update-stream { 1712 base notif:stream; 1713 description 1714 "Base identity to represent a conceptual system-provided 1715 datastream of datastore updates with predefined semantics."; 1716 } 1718 identity yang-push { 1719 base update-stream; 1720 description 1721 "A conceptual datastream consisting of all datastore 1722 updates, including operational and configuration data."; 1723 } 1725 identity operational-push { 1726 base update-stream; 1727 description 1728 "A conceptual datastream consisting of updates of all 1729 operational data."; 1730 } 1732 identity config-push { 1733 base update-stream; 1734 description 1735 "A conceptual datastream consisting of updates of all 1736 configuration data."; 1737 } 1739 identity custom-stream { 1740 base update-stream; 1741 description 1742 "A conceptual datastream for datastore 1743 updates with custom updates as defined by a user."; 1744 } 1746 /* Additional transport option */ 1747 identity restconf { 1748 base notif-bis:transport; 1749 description 1750 "Restconf notifications as a transport"; 1751 } 1753 /* 1754 * TYPE DEFINITIONS 1755 */ 1757 typedef datastore-contents-xml { 1758 type string; 1759 description 1760 "This type is be used to represent datastore contents, 1761 i.e. a set of data nodes with their values, in XML. 1762 The syntax corresponds to the syntax of the data payload 1763 returned in a corresponding Netconf get operation with the 1764 same filter parameters applied."; 1765 reference "RFC 6241 section 7.7"; 1766 } 1768 typedef datastore-changes-xml { 1769 type string; 1770 description 1771 "This type is used to represent a set of changes in a 1772 datastore encoded in XML, indicating for datanodes whether 1773 they have been created, deleted, or updated. The syntax 1774 corresponds to the syntax used to when editing a 1775 datastore using the edit-config operation in Netconf."; 1776 reference "RFC 6241 section 7.2"; 1777 } 1779 typedef datastore-contents-json { 1780 type string; 1781 description 1782 "This type is be used to represent datastore contents, 1783 i.e. a set of data nodes with their values, in JSON. 1784 The syntax corresponds to the syntax of the data 1785 payload returned in a corresponding RESTCONF get 1786 operation with the same filter parameters applied."; 1787 reference "RESTCONF Protocol"; 1788 } 1790 typedef datastore-changes-json { 1791 type string; 1792 description 1793 "This type is used to represent a set of changes in a 1794 datastore encoded in JSON, indicating for datanodes whether 1795 they have been created, deleted, or updated. The syntax 1796 corresponds to the syntax used to patch a datastore 1797 using the yang-patch operation with Restconf."; 1798 reference "draft-ietf-netconf-yang-patch"; 1799 } 1801 typedef filter-id { 1802 type uint32; 1803 description 1804 "A type to identify filters which can be associated with a 1805 subscription."; 1806 } 1808 typedef subscription-result { 1809 type identityref { 1810 base notif-bis:subscription-result; 1811 } 1812 description 1813 "The result of a subscription operation"; 1814 } 1816 typedef subscription-term-reason { 1817 type identityref { 1818 base notif-bis:subscription-errors; 1819 } 1820 description 1821 "Reason for a server to terminate a subscription."; 1822 } 1824 typedef subscription-susp-reason { 1825 type identityref { 1826 base notif-bis:subscription-errors; 1827 } 1828 description 1829 "Reason for a server to suspend a subscription."; 1830 } 1832 typedef encoding { 1833 type identityref { 1834 base notif-bis:encodings; 1835 } 1836 description 1837 "Specifies a data encoding, e.g. for a data subscription."; 1838 } 1840 typedef change-type { 1841 type enumeration { 1842 enum "create" { 1843 description 1844 "A new data node was created"; 1845 } 1846 enum "delete" { 1847 description 1848 "A data node was deleted"; 1849 } 1850 enum "modify" { 1851 description 1852 "The value of a data node has changed"; 1853 } 1854 } 1855 description 1856 "Specifies different types of changes that may occur 1857 to a datastore."; 1858 } 1860 typedef transport-protocol { 1861 type identityref { 1862 base notif-bis:transport; 1863 } 1864 description 1865 "Specifies transport protocol used to send updates to a 1866 receiver."; 1867 } 1869 typedef push-source { 1870 type enumeration { 1871 enum "interface-originated" { 1872 description 1873 "Pushes will be sent from a specific interface on a 1874 Publisher"; 1875 } 1876 enum "address-originated" { 1877 description 1878 "Pushes will be sent from a specific address on a 1879 Publisher"; 1880 } 1881 } 1882 description 1883 "Specifies from where objects will be sourced when being pushed 1884 off a publisher."; 1885 } 1887 typedef update-stream { 1888 type identityref { 1889 base update-stream; 1890 } 1891 description 1892 "Specifies a system-provided datastream."; 1893 } 1895 grouping update-filter { 1896 description 1897 "This groupings defines filters for push updates for a datastore 1898 tree. The filters define which updates are of interest in a 1899 push update subscription. 1900 Mixing and matching of multiple filters does not occur 1901 at the level of this grouping. 1902 When a push-update subscription is created, the filter can 1903 be a regular subscription filter, or one of the additional 1904 filters that are defined in this grouping."; 1905 choice update-filter { 1906 description 1907 "Define filters regarding which data nodes to include 1908 in push updates"; 1909 case subtree { 1910 description 1911 "Subtree filter."; 1912 anyxml subtree-filter { 1913 description 1914 "Subtree-filter used to specify the data nodes targeted 1915 for subscription within a subtree, or subtrees, of a 1916 conceptual YANG datastore. 1917 It may include additional criteria, 1918 allowing users to receive only updates of a limited 1919 set of data nodes that match those filter criteria. 1920 This will be used to define what 1921 updates to include in a stream of update events, i.e. 1922 to specify for which data nodes update events should be 1923 generated and specific match expressions that objects 1924 need to meet. The syntax follows the subtree filter 1925 syntax specified in RFC 6241, section 6."; 1926 reference "RFC 6241 section 6"; 1927 } 1928 } 1929 case xpath { 1930 description 1931 "XPath filter"; 1932 leaf xpath-filter { 1933 type yang:xpath1.0; 1934 description 1935 "Xpath defining the data items of interest."; 1936 } 1937 } 1938 } 1939 } 1941 grouping update-policy { 1942 description 1943 "This grouping describes the conditions under which an 1944 update will be sent as part of an update stream."; 1945 choice update-trigger { 1946 description 1947 "Defines necessary conditions for sending an event to 1948 the subscriber."; 1949 case periodic { 1950 description 1951 "The agent is requested to notify periodically the 1952 current values of the datastore or the subset 1953 defined by the filter."; 1954 leaf period { 1955 type yang:timeticks; 1956 mandatory true; 1957 description 1958 "Duraton of time which should occur between periodic 1959 push updates. Where the anchor of a start-time is 1960 available, the push will include the objects and their 1961 values which exist at an exact multiple of timeticks 1962 aligning to this start-time anchor."; 1963 } 1964 } 1965 case on-change { 1966 if-feature "on-change"; 1967 description 1968 "The agent is requested to notify changes in 1969 values in the datastore or a subset of it defined 1970 by a filter."; 1971 leaf no-synch-on-start { 1972 type empty; 1973 description 1974 "This leaf acts as a flag that determines behavior at the 1975 start of the subscription. When present, 1976 synchronization of state at the beginning of the 1977 subscription is outside the scope of the subscription. 1978 Only updates about changes that are observed from the 1979 start time, i.e. only push-change-update notifications 1980 are sent. 1981 When absent (default behavior), in order to facilitate 1982 a receiver's synchronization, a full update is sent 1983 when the subscription starts using a push-update 1984 notification, just like in the case of a periodic 1985 subscription. After that, push-change-update 1986 notifications are sent."; 1987 } 1988 leaf dampening-period { 1989 type yang:timeticks; 1990 mandatory true; 1991 description 1992 "Minimum amount of time that needs to have 1993 passed since the last time an update was 1994 provided."; 1995 } 1996 leaf-list excluded-change { 1997 type change-type; 1998 description 1999 "Use to restrict which changes trigger an update. 2000 For example, if modify is excluded, only creation and 2001 deletion of objects is reported."; 2002 } 2003 } 2004 } 2005 } 2007 grouping push-subscription-info { 2008 description 2009 "This grouping describes information concerning a 2010 push subscription that is need in addition to information 2011 already included in notif-bis:subscription-info."; 2012 leaf subscription-start-time { 2013 type yang:date-and-time; 2014 description 2015 "Designates the time at which a subscription is supposed 2016 to start, or immediately, in case the start-time is in 2017 the past. For periodic subscription, the start time also 2018 serves as anchor time from which the time of the next 2019 update is computed. The next update will take place at the 2020 next period interval from the anchor time. 2021 For example, for an anchor time at the top of a minute 2022 and a period interval of a minute, the next update will 2023 be sent at the top of the next minute."; 2024 } 2025 leaf subscription-stop-time { 2026 type yang:date-and-time; 2027 description 2028 "Designates the time at which a subscription will end. 2029 When a subscription reaches its stop time, it will be 2030 automatically deleted. No final push is required unless there 2031 is exact alignment with the end of a periodic subscription 2032 period."; 2033 } 2034 } 2036 grouping subscription-qos { 2037 description 2038 "This grouping describes Quality of Service information 2039 concerning a subscription. This information is passed to lower 2040 layers for transport priortization and treatment"; 2041 leaf dscp { 2042 if-feature "notif-bis:configured-subscriptions"; 2043 type inet:dscp; 2044 default "0"; 2045 description 2046 "The push update's IP packet transport priority. 2047 This is made visible across network hops to receiver. 2048 The transport priority is shared for all receivers of 2049 a given subscription."; 2050 } 2051 leaf subscription-priority { 2052 type uint8; 2053 description 2054 "Relative priority for a subscription. Allows an underlying 2055 transport layer perform informed load balance allocations 2056 between various subscriptions"; 2057 } 2058 leaf subscription-dependency { 2059 type string; 2060 description 2061 "Provides the Subscription ID of a parent subscription 2062 without which this subscription should not exist. In 2063 other words, there is no reason to stream these objects 2064 if another subscription is missing."; 2065 } 2066 } 2068 augment "/notif-bis:establish-subscription/notif-bis:input" { 2069 description 2070 "Define additional subscription parameters that apply 2071 specifically to push updates"; 2072 uses push-subscription-info; 2073 uses update-policy; 2074 uses subscription-qos; 2075 } 2076 augment "/notif-bis:establish-subscription/notif-bis:input/notif-bis:filter-type" { 2077 description 2078 "Add push filters to selection of filter types."; 2079 case update-filter { 2080 description 2081 "Additional filter options for push subscription."; 2082 uses update-filter; 2083 } 2084 } 2085 augment "/notif-bis:establish-subscription/notif-bis:output" { 2086 description 2087 "Allow to return additional subscription parameters that apply 2088 specifically to push updates."; 2089 uses push-subscription-info; 2090 uses update-policy; 2091 uses subscription-qos; 2092 } 2093 augment "/notif-bis:establish-subscription/notif-bis:output/"+ 2094 "notif-bis:result/notif-bis:no-success/notif-bis:filter-type" { 2095 description 2096 "Add push filters to selection of filter types."; 2097 case update-filter { 2098 description 2099 "Additional filter options for push subscription."; 2100 uses update-filter; 2101 } 2102 } 2103 augment "/notif-bis:modify-subscription/notif-bis:input" { 2104 description 2105 "Define additional subscription parameters that apply 2106 specifically to push updates."; 2107 uses push-subscription-info; 2108 uses update-policy; 2109 uses subscription-qos; 2110 } 2111 augment "/notif-bis:modify-subscription/notif-bis:input/notif-bis:filter-type" { 2112 description 2113 "Add push filters to selection of filter types."; 2114 case update-filter { 2115 description 2116 "Additional filter options for push subscription."; 2117 uses update-filter; 2118 } 2119 } 2120 augment "/notif-bis:modify-subscription/notif-bis:output" { 2121 description 2122 "Allow to retun additional subscription parameters that apply 2123 specifically to push updates."; 2124 uses push-subscription-info; 2125 uses update-policy; 2126 uses subscription-qos; 2127 } 2128 augment "/notif-bis:modify-subscription/notif-bis:output/"+ 2129 "notif-bis:result/notif-bis:no-success/notif-bis:filter-type" { 2130 description 2131 "Add push filters to selection of filter types."; 2132 case update-filter { 2133 description 2134 "Additional filter options for push subscription."; 2135 uses update-filter; 2136 } 2137 } 2138 notification push-update { 2139 description 2140 "This notification contains a periodic push update. 2141 This notification shall only be sent to receivers 2142 of a subscription; it does not constitute a general-purpose 2143 notification."; 2144 leaf subscription-id { 2145 type notif-bis:subscription-id; 2146 mandatory true; 2147 description 2148 "This references the subscription because of which the 2149 notification is sent."; 2150 } 2151 leaf time-of-update { 2152 type yang:date-and-time; 2153 description 2154 "This leaf contains the time of the update."; 2155 } 2156 choice encoding { 2157 description 2158 "Distinguish between the proper encoding that was specified 2159 for the subscription"; 2160 case encode-xml { 2161 description 2162 "XML encoding"; 2163 leaf datastore-contents-xml { 2164 type datastore-contents-xml; 2165 description 2166 "This contains data encoded in XML, 2167 per the subscription."; 2168 } 2169 } 2170 case encode-json { 2171 if-feature "notif-bis:json"; 2172 description 2173 "JSON encoding"; 2174 leaf datastore-contents-json { 2175 type datastore-contents-json; 2176 description 2177 "This leaf contains data encoded in JSON, 2178 per the subscription."; 2179 } 2180 } 2181 } 2182 } 2183 notification push-change-update { 2184 if-feature "on-change"; 2185 description 2186 "This notification contains an on-change push update. 2187 This notification shall only be sent to the receivers 2188 of a subscription; it does not constitute a general-purpose 2189 notification."; 2190 leaf subscription-id { 2191 type notif-bis:subscription-id; 2192 mandatory true; 2193 description 2194 "This references the subscription because of which the 2195 notification is sent."; 2196 } 2197 leaf time-of-update { 2198 type yang:date-and-time; 2199 description 2200 "This leaf contains the time of the update, i.e. the 2201 time at which the change was observed."; 2202 } 2203 choice encoding { 2204 description 2205 "Distinguish between the proper encoding that was specified 2206 for the subscription"; 2207 case encode-xml { 2208 description 2209 "XML encoding"; 2210 leaf datastore-changes-xml { 2211 type datastore-changes-xml; 2212 description 2213 "This contains datastore contents that has changed 2214 since the previous update, per the terms of the 2215 subscription. Changes are encoded analogous to 2216 the syntax of a corresponding Netconf edit-config 2217 operation."; 2218 } 2219 } 2220 case encode-json { 2221 if-feature "notif-bis:json"; 2222 description 2223 "JSON encoding"; 2224 leaf datastore-changes-yang { 2225 type datastore-changes-json; 2226 description 2227 "This contains datastore contents that has changed 2228 since the previous update, per the terms of the 2229 subscription. Changes are encoded analogous 2230 to the syntax of a corresponding RESTCONF yang-patch 2231 operation."; 2232 } 2233 } 2235 } 2236 } 2237 augment "/notif-bis:subscription-started" { 2238 description 2239 "This augmentation adds push subscription parameters 2240 to the notification that a subscription has 2241 started and data updates are beginning to be sent. 2242 This notification shall only be sent to receivers 2243 of a subscription; it does not constitute a general-purpose 2244 notification."; 2245 uses push-subscription-info; 2246 uses update-policy; 2247 uses subscription-qos; 2248 } 2249 augment "/notif-bis:subscription-started/notif-bis:filter-type" { 2250 description 2251 "This augmentation allows to include additional update filters 2252 options to be included as part of the notification that a 2253 subscription has started."; 2254 case update-filter { 2255 description 2256 "Additional filter options for push subscription."; 2257 uses update-filter; 2258 } 2259 } 2260 augment "/notif-bis:subscription-modified" { 2261 description 2262 "This augmentation adds push subscription parameters 2263 to the notification that a subscription has 2264 been modified. 2265 This notification shall only be sent to receivers 2266 of a subscription; it does not constitute a general-purpose 2267 notification."; 2268 uses push-subscription-info; 2269 uses update-policy; 2270 uses subscription-qos; 2271 } 2272 augment "/notif-bis:subscription-modified/notif-bis:filter-type" { 2273 description 2274 "This augmentation allows to include additional update filters 2275 options to be included as part of the notification that a 2276 subscription has been modified."; 2277 case update-filter { 2278 description 2279 "Additional filter options for push subscription."; 2280 uses update-filter; 2281 } 2282 } 2283 augment "/notif-bis:filters/notif-bis:filter/notif-bis:filter-type" { 2284 description 2285 "This container adds additional update filter options 2286 to the list of configurable filters 2287 that can be applied to subscriptions. This facilitates 2288 the reuse of complex filters once defined."; 2289 case update-filter { 2290 uses update-filter; 2291 } 2292 } 2293 augment "/notif-bis:subscription-config/notif-bis:subscription" { 2294 description 2295 "Contains the list of subscriptions that are configured, 2296 as opposed to established via RPC or other means."; 2297 uses push-subscription-info; 2298 uses update-policy; 2299 uses subscription-qos; 2300 } 2301 augment "/notif-bis:subscription-config/notif-bis:subscription/notif-bis:filter-type" { 2302 description 2303 "Add push filters to selection of filter types."; 2304 case update-filter { 2305 uses update-filter; 2306 } 2307 } 2308 augment "/notif-bis:subscriptions/notif-bis:subscription" { 2309 description 2310 "Contains the list of currently active subscriptions, 2311 i.e. subscriptions that are currently in effect, 2312 used for subscription management and monitoring purposes. 2313 This includes subscriptions that have been setup via RPC 2314 primitives, e.g. establish-subscription, delete-subscription, 2315 and modify-subscription, as well as subscriptions that 2316 have been established via configuration."; 2317 uses push-subscription-info; 2318 uses update-policy; 2319 uses subscription-qos; 2320 } 2321 augment "/notif-bis:subscriptions/notif-bis:subscription/notif-bis:filter-type" { 2322 description 2323 "Add push filters to selection of filter types."; 2324 case update-filter { 2325 description 2326 "Additional filter options for push subscription."; 2327 uses update-filter; 2328 } 2329 } 2330 } 2331 2333 6. Security Considerations 2335 Subscriptions could be used to attempt to overload servers of YANG 2336 datastores. For this reason, it is important that the server has the 2337 ability to decline a subscription request if it would deplete its 2338 resources. In addition, a server needs to be able to suspend an 2339 existing subscription when needed. When this occur, the subscription 2340 status is updated accordingly and the clients are notified. 2341 Likewise, requests for subscriptions need to be properly authorized. 2343 A subscription could be used to retrieve data in subtrees that a 2344 client has not authorized access to. Therefore it is important that 2345 data pushed based on subscriptions is authorized in the same way that 2346 regular data retrieval operations are. Data being pushed to a client 2347 needs therefore to be filtered accordingly, just like if the data 2348 were being retrieved on-demand. The Netconf Authorization Control 2349 Model applies. 2351 A subscription could be configured on another receiver's behalf, with 2352 the goal of flooding that receiver with updates. One or more 2353 publishers could be used to overwhelm a receiver which doesn't even 2354 support subscriptions. Clients which do not want pushed data need 2355 only terminate or refuse any transport sessions from the publisher. 2356 In addition, the Netconf Authorization Control Model SHOULD be used 2357 to control and restrict authorization of subscription configuration. 2359 7. Issues that are currently being worked and resolved 2361 7.1. Unresolved issues under discussion 2363 o Which stream types to introduce. Current list includes streams 2364 for all operational and for all config data. Consider adding 2365 stream for operational data minus counters. Also: assess 2366 implications of opstate implications on required data streams. 2368 o In addition to identifying which items go to which streams, 2369 identifying and calling out which items (such as counters) should 2370 not be "on-change subscribable" may be useful. Consider 2371 introducing a Yang extension to define if an object: is-a-counter 2372 and/or not-notifiable. 2374 o What QoS parameters should be supported for subscriptions. Note: 2375 QoS parameters are applicable to buffering as well as temporarily 2376 loss of transport connectivity. 2378 o Implications of ephemeral requirements from I2RS 2379 o Filters: YANG 1.1 allows filters to be defined in multiple places. 2380 How do they intersect each other in a deterministic way. 2382 o On-change subscription: consider providing publisher with 2383 capability to initiate a refresh of contents rather than send 2384 deltas. Current proposal allows for a "synch-on-start" option; 2385 such an option might be useful also e.g. on resumption of a 2386 subscription that had been suspended. 2388 o Do we need an extension for NACM to support filter out datastore 2389 nodes for which the receiver has no read access? (And how does 2390 this differ from existing GET, which must do the same filtering?) 2391 In 5277, such filtering is done at the notification level. Yang- 2392 push includes notification-content filtering. This may be very 2393 expensive in terms of processing. Andy suggestion: only accept 2394 Yang-push subscriptions for subtrees the user has rights for all 2395 the nodes in the subtree. Changes to those rights trigger a 2396 subscription termination. Should we codify this, or let vendors 2397 determine when per subtree filtering might be applied? 2399 7.2. Agreement in principal 2401 Still need to agree on draft text 2403 o Multiple receivers per configured subscription is ok. 2405 o Proper behavior for on-change, including detecting and indicating 2406 changes within a dampening period. 2408 o Still some details to work through, e.g., do we add a counter for 2409 the number of object changes during a dampening period? 2411 o Negotiate vs. auto-adjust. Cases where negotiate is needed exists 2412 for domain synchronization. Error messages can be used to 2413 transport information back as hints. Alternative is dedicated RPC 2414 responses. In either case specific contents of these negotiation 2415 messages must still be defined. 2417 o Message format for synchronization (i.e. synch-on-start) still 2418 needs to be defined. 2420 7.3. Closed Issues 2422 Some editorial updates needed to reflect these 2424 o Periodic interval goes to seconds from timeticks 2426 o Balancing Augment vs. Parallel Model structures (maximize augment) 2427 o Moving from separate start/stop to Anchor time for Periodic 2429 8. Acknowledgments 2431 For their valuable comments, discussions, and feedback, we wish to 2432 acknowledge Andy Bierman, Yang Geng, Peipei Guo, Susan Hares, Tim 2433 Jenkins, Balazs Lengyel, Kent Watsen, and Guangying Zheng. 2435 9. References 2437 9.1. Normative References 2439 [RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin, 2440 "Simple Network Management Protocol (SNMP)", RFC 1157, 2441 DOI 10.17487/RFC1157, May 1990, 2442 . 2444 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2445 Notifications", RFC 5277, July 2008. 2447 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2448 the Network Configuration Protocol (NETCONF)", RFC 6020, 2449 DOI 10.17487/RFC6020, October 2010, 2450 . 2452 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2453 and A. Bierman, Ed., "Network Configuration Protocol 2454 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2455 . 2457 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2458 Base Notifications", RFC 5277, February 2012. 2460 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2461 Protocol (NETCONF) Access Control Model", RFC 6536, 2462 DOI 10.17487/RFC6536, March 2012, 2463 . 2465 9.2. Informative References 2467 [I-D.clemm-netmod-mount] 2468 Clemm, A., Medved, J., and E. Voit, "Mounting YANG-defined 2469 information from remote datastores", draft-clemm-netmod- 2470 mount-04 (work in progress), March 2016. 2472 [I-D.gonzalez-netconf-5277bis] 2473 Gonzalez Prieto, A., Clemm, A., Voit, E., Tripathy, A., 2474 Nilsen-Nygaard, E., Chisholm, S., and H. Trevino, 2475 "Subscribing to YANG-Defined Event Notifications", draft- 2476 clemm-netmod-mount-03 (work in progress), June 2016. 2478 [I-D.i2rs-pub-sub-requirements] 2479 Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2480 for Subscription to YANG Datastores", draft-ietf-i2rs-pub- 2481 sub-requirements-09 (work in progress), May 2016. 2483 [I-D.ietf-netconf-restconf] 2484 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2485 Protocol", I-D draft-ietf-netconf-restconf-13, April 2016. 2487 [I-D.ietf-netconf-yang-patch] 2488 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2489 Media Type", draft-ietf-netconf-yang-patch-08 (work in 2490 progress), March 2016. 2492 [I-D.ietf-netmod-yang-json] 2493 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2494 draft-ietf-netmod-yang-json-10 (work in progress), March 2495 2016. 2497 [I-D.voit-netmod-yang-mount-requirements] 2498 Voit, E., Clemm, A., and S. Mertens, "Requirements for 2499 Peer Mounting of YANG subtrees from Remote Datastores", 2500 draft-voit-netmod-yang-mount-requirements-00 (work in 2501 progress), March 2016. 2503 Authors' Addresses 2505 Alexander Clemm 2506 Cisco Systems 2508 EMail: alex@cisco.com 2510 Alberto Gonzalez Prieto 2511 Cisco Systems 2513 EMail: albertgo@cisco.com 2514 Eric Voit 2515 Cisco Systems 2517 EMail: evoit@cisco.com 2519 Ambika Prasad Tripathy 2520 Cisco Systems 2522 EMail: ambtripa@cisco.com 2524 Einar Nilsen-Nygaard 2525 Cisco Systems 2527 EMail: einarnn@cisco.com