idnits 2.17.1 draft-ietf-netconf-yang-push-01.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 5 instances of too long lines in the document, the longest one being 4 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 464: '... the server SHOULD include in the re...' RFC 2119 keyword, line 492: '...cription request MUST be rejected. As...' RFC 2119 keyword, line 528: '... MUST support XML encoding and MAY s...' RFC 2119 keyword, line 806: '...rnative subscription parameters MAY be...' RFC 2119 keyword, line 868: '...ations. Servers SHOULD reject attempt...' (6 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 (February 23, 2016) is 2982 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 423, but not defined == Missing Reference: 'RFC 5277' is mentioned on line 424, 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-03 == Outdated reference: A later version (-09) exists of draft-ietf-i2rs-pub-sub-requirements-05 == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-09 == Outdated reference: A later version (-14) exists of draft-ietf-netconf-yang-patch-07 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-yang-json-07 Summary: 5 errors (**), 0 flaws (~~), 9 warnings (==), 2 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: August 26, 2016 A. Tripathy 6 E. Nilsen-Nygaard 7 Cisco Systems 8 February 23, 2016 10 Subscribing to YANG datastore push updates 11 draft-ietf-netconf-yang-push-01.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 August 26, 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 . . . . . . . . . . . . . . . . . . 5 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 . . . . . . . . . . . . . . . 12 76 3.5. Subscription Filters . . . . . . . . . . . . . . . . . . 13 77 3.6. Push Data Stream and Transport Mapping . . . . . . . . . 13 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 . . . . . . 21 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 4. A YANG data model for management of datastore push 89 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 23 90 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 23 91 4.2. Update streams . . . . . . . . . . . . . . . . . . . . . 25 92 4.3. Filters . . . . . . . . . . . . . . . . . . . . . . . . . 26 93 4.4. Subscription configuration . . . . . . . . . . . . . . . 26 94 4.5. Subscription monitoring . . . . . . . . . . . . . . . . . 28 95 4.6. Notifications . . . . . . . . . . . . . . . . . . . . . . 28 96 4.7. RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . 29 97 4.7.1. Create-subscription RPC . . . . . . . . . . . . . . . 29 98 4.7.2. Modify-subscription RPC . . . . . . . . . . . . . . . 31 99 4.7.3. Delete-subscription RPC . . . . . . . . . . . . . . . 33 100 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 33 101 6. Security Considerations . . . . . . . . . . . . . . . . . . . 55 102 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 56 103 7.1. Normative References . . . . . . . . . . . . . . . . . . 56 104 7.2. Informative References . . . . . . . . . . . . . . . . . 56 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57 107 1. Introduction 109 YANG [RFC6020] was originally designed for the Netconf protocol 110 [RFC6241], which originally put most emphasis on configuration. 111 However, YANG is not restricted to configuration data. YANG 112 datastores, i.e. datastores that contain data modeled according using 113 YANG, can contain configuration as well as operational data. It is 114 therefore reasonable to expect that data in YANG datastores will 115 increasingly be used to support applications that are not focused on 116 managing configurations but that are, for example, related to service 117 assurance. 119 Service assurance applications typically involve monitoring 120 operational state of networks and devices; of particular interest are 121 changes that this data undergoes over time. Likewise, there are 122 applications in which data and objects from one datastore need to be 123 made available both to applications in other systems and to remote 124 datastores [I-D.voit-netmod-peer-mount-requirements] 125 [I-D.clemm-netmod-mount]. This requires mechanisms that allow remote 126 systems to become quickly aware of any updates to allow to validate 127 and maintain cross-network integrity and consistency. 129 Traditional approaches to remote network state visibility rely 130 heavily on polling. With polling, data is periodically explicitly 131 retrieved by a client from a server to stay up-to-date. 133 There are various issues associated with polling-based management: 135 o It introduces additional load on network, devices, and 136 applications. Each polling cycle requires a separate yet arguably 137 redundant request that results in an interrupt, requires parsing, 138 consumes bandwidth. 140 o It lacks robustness. Polling cycles may be missed, requests may 141 be delayed or get lost, often particularly in cases when the 142 network is under stress and hence exactly when the need for the 143 data is the greatest. 145 o Data may be difficult to calibrate and compare. Polling requests 146 may undergo slight fluctuations, resulting in intervals of 147 different lengths which makes data hard to compare. Likewise, 148 pollers may have difficulty issuing requests that reach all 149 devices at the same time, resulting in offset polling intervals 150 which again make data hard to compare. 152 A more effective alternative is when an application can request to be 153 automatically updated as necessary of current content of the 154 datastore (such as a subtree, or data in a subtree that meets a 155 certain filter condition), and in which the server that maintains the 156 datastore subsequently pushes those updates. However, such a 157 solution does not currently exist. 159 The need to perform polling-based management is typically considered 160 an important shortcoming of management applications that rely on MIBs 161 polled using SNMP [RFC1157]. However, without a provision to support 162 a push-based alternative, there is no reason to believe that 163 management applications that operate on YANG datastores using 164 protocols such as NETCONF or Restconf [I-D.ietf-netconf-restconf] 165 will be any more effective, as they would follow the same request/ 166 response pattern. 168 While YANG allows the definition of notifications, such notifications 169 are generally intended to indicate the occurrence of certain well- 170 specified event conditions, such as a the onset of an alarm condition 171 or the occurrence of an error. A capability to subscribe to and 172 deliver event notifications has been defined in [RFC5277]. In 173 addition, configuration change notifications have been defined in 174 [RFC6470]. These change notifications pertain only to configuration 175 information, not to operational state, and convey the root of the 176 subtree to which changes were applied along with the edits, but not 177 the modified data nodes and their values. 179 Accordingly, there is a need for a service that allows client 180 applications to dynamically subscribe to updates of a YANG datastore 181 and that allows the server to push those updates. Additionally, 182 support for static subscriptions configured directly on the server 183 are also useful when dynamic signaling is undesirable or unsupported. 184 The requirements for such a service are documented in 185 [I-D.i2rs-pub-sub-requirements]. This document proposes a solution 186 that features the following capabilities: 188 o A mechanism that allows clients to dynamically subscribe to 189 automatic datastore updates, and the means to manage those 190 subscription. The subscription allows clients to specify which 191 data they are interested in, and to provide optional filters with 192 criteria that data must meet for updates to be sent. Furthermore, 193 subscription can specify a policy that directs when updates are 194 provided. For example, a client may request to be updated 195 periodically in certain intervals, or whenever data changes occur. 197 o An alternative mechanism that allows for the static configuration 198 of subscriptions to automatic data store updates as part of a 199 device configuration. In addition to the aspects that are 200 configurable for a dynamic subscription (filter criteria, update 201 policy), static configuration of subscriptions allows for the 202 definition of additional aspects such as intended receivers and 203 alternative transport options. 205 o The ability for a server to push back on requested subscription 206 parameters. Because not every server may support every requested 207 interval for every piece of data, it is necessary for a server to 208 be able to indicate whether or not it is capable of supporting a 209 requested subscription, and possibly allow to negotiate 210 subscription parameters. 212 o A mechanism to communicate the updates themselves. For this, the 213 proposal leverages and extends existing YANG/Netconf/Restconf 214 mechanisms, defining special notifications that carry updates. 216 This document specifies a YANG data model to manage subscriptions to 217 data in YANG datastores, and to configure associated filters and data 218 streams. It defines extensions to RPCs defined in [RFC5277] that 219 allow to extend notification subscriptions to subscriptions for 220 datastore updates. It also defines a notification that can be used 221 to carry data updates and thus serve as push mechanism. 223 2. Definitions and Acronyms 225 Data node: An instance of management information in a YANG datastore. 227 Data record: A record containing a set of one or more data node 228 instances and their associated values. 230 Datastore: A conceptual store of instantiated management information, 231 with individual data items represented by data nodes which are 232 arranged in hierarchical manner. 234 Datastream: A continuous stream of data records, each including a set 235 of updates, i.e. data node instances and their associated values. 237 Data subtree: An instantiated data node and the data nodes that are 238 hierarchically contained within it. 240 Dynamic subscription: A subscription negotiated between subscriber 241 and publisher via create, modify, and delete RPCs respectively 242 control plane signaling messages that are part of an existing 243 management association between and publisher. Subscriber and 244 receiver are the same system. 246 NACM: NETCONF Access Control Model 248 NETCONF: Network Configuration Protocol 250 Publisher: A server that sends push updates to a receiver according 251 to the terms of a subscription. In general, the publisher is also 252 the "owner" of the subscription. 254 Push-update stream: A conceptual data stream of a datastore that 255 streams the entire datastore contents continuously and perpetually. 257 Receiver: The target of push updates of a subscription. In case of a 258 dynamic subscription, receiver and subscriber are the same system. 259 However, in the case of a static subscription, the receiver may be a 260 different system than the one that configured the subscription. 262 RPC: Remote Procedure Call 264 SNMP: Simple Network Management Protocol 266 Static subscription: A subscription installed as part of a 267 configuration datastore via a configuration interface. 269 Subscriber: A client that negotiates a subscription with a server 270 ("publisher"). A client that creates a static subscription is also 271 considered a subscriber, even if it is not necessarily the receiver 272 of a subscription. 274 Subscription: A contract between a client ("subscriber") and a server 275 ("publisher"), stipulating which information the client wishes to 276 receive from the server (and which information the server has to 277 provide to the client) without the need for further solicitation. 279 Subscription filter: A filter that contains evaluation criteria which 280 are evaluated against YANG objects of a subscription. An update is 281 only published if the object meets the specified filter criteria. 283 Subscription policy: A policy that specifies under what circumstances 284 to push an update, e.g. whether updates are to be provided 285 periodically or only whenever changes occur. 287 Update: A data item containing the current value of a data node. 289 Update trigger: A trigger, as specified by a subscription policy, 290 that causes an update to be sent, respectively a data record to be 291 generated. An example of a trigger is a change trigger, invoked when 292 the value of a data node changes or a data node is created or 293 deleted, or a time trigger, invoked after the laps of a periodic time 294 interval. 296 URI: Uniform Resource Identifier 298 YANG: A data definition language for NETCONF 300 Yang-push: The subscription and push mechanism for YANG datastores 301 that is specified in this document. 303 3. Solution Overview 305 This document specifies a solution for a subscription service, which 306 supports the dynamic as well as static creation of subscriptions to 307 information updates of operational or configuration YANG data which 308 are subsequently pushed from the server to the client. 310 Dynamic subscriptions are initiated by clients who want to receive 311 push updates. Servers respond to requests for the creation of 312 subscriptions positively or negatively. Negative responses include 313 information about why the subscription was not accepted, in order to 314 facilitate converging on an acceptable set of subscription 315 parameters. Similarly, static subscriptions are configured as part 316 of a device's configuration. Once a subscription has been 317 established, datastore push updates are pushed from the server to the 318 receiver until the subscription ends. 320 Accordingly, the solution encompasses several components: 322 o The subscription model for configuration and management of the 323 subscriptions, with a set of associated services. 325 o The ability to provide hints for acceptable subscription 326 parameters, in cases where a subscription desired by a client 327 cannot currently be served. 329 o The stream of datastore push updates. 331 In addition, there are a number of additional considerations, such as 332 the tie-in of the mechanisms with security mechanisms. Each of those 333 aspects will be discussed in the following subsections. 335 3.1. Subscription Model 337 Yang-push subscriptions are defined using a data model that is itself 338 defined in YANG. This model is based on the subscriptions defined in 339 [RFC5277], which are also reused in Restconf. The model is extended 340 with several parameters, including a subscription type and a 341 subscription ID. 343 The subscription model assumes the presence of a conceptual perpetual 344 datastream "push-update" of continuous datastore updates that can be 345 subscribed to, although other datastreams may be supported as well. 346 A subscription refers to a datastream and specifies filters that are 347 to be applied to, it for example, to provide only those subsets of 348 the information that match a filter criteria. In addition, a 349 subscription specifies a set of subscription parameters that define 350 the trigger when data records should be sent, for example at periodic 351 intervals or whenever underlying data items change. 353 The complete set of subscription parameters for both dynamic and 354 static subscriptions is as follows: 356 o The stream being subscribed to. The subscription model assumes 357 the presence of perpetual and continuous streams of updates. The 358 stream "push-update" is always available and covers the entire set 359 of YANG data in the server, but a system may provide other streams 360 to choose from. 362 o The datastore to target. By default, the datastore will always be 363 "running". However, it is conceivable that implementations want 364 to also support subscriptions to updates to other datastores. 366 o An encoding for the data updates. By default, updates are encoded 367 using XML, but JSON can be requested as an option and other 368 encodings may be supported in the future. 370 o An optional start time for the subscription. If the specified 371 start time is in the past, the subscription goes into effect 372 immediately. The start time also serves as anchor time for 373 periodic subscriptions, from which intervals at which to send 374 updates are calculated (see also below). 376 o An optional stop time for the subscription. Once the stop time is 377 reached, the subscription is automatically terminated. 379 o A subscription policy definition regarding the update trigger when 380 to send new updates. The trigger can be periodic or based on 381 change. 383 * For periodic subscriptions, the trigger is defined by a 384 parameter that defines the interval with which updates are to 385 be pushed. The start time of the subscription serves as anchor 386 time, defining one specific point in time at which an update 387 needs to be sent. Update intervals always fall on the points 388 in time that are a multiple of a period after the start time. 390 * For on-change subscriptions, the trigger occurs whenever a 391 change in the subscribed information is detected. On-change 392 subscriptions have more complex semantics that can be guided by 393 additional parameters. Please refer also to Section 3.3. 395 + One parameter is needed to specify the dampening period, 396 i.e. the interval that must pass before a successive update 397 for the same data node is sent. The first time a change is 398 detected, the update is sent immediately. If a subsequent 399 change is detected, another update is only sent once the 400 dampening period has passed, containing the value of the 401 data node that is then valid. 403 + Another parameter allows to restrict the types of changes 404 for which updates are sent (changes to object values, object 405 creation or deletion events). It is conceivable to augment 406 the data model with additional parameters in the future to 407 specify even more refined policies, such as parameters that 408 specify the magnitude of a change that must occur before an 409 update is triggered. 411 + A third parameter specifies whether or not a complete update 412 with all the subscribed data should be sent at the beginning 413 of a subscription. 415 o Optionally, a filter, or set of filters, describing the subset of 416 data items in the stream's data records that are of interest to 417 the subscriber. The server should only send to the subscriber the 418 data items that match the filter(s), when present. The absence of 419 a filter indicates that all data items from the stream are of 420 interest to the subscriber and all data records must be sent in 421 their entirety to the subscriber. Three types of filters are 422 supported: subtree filters, with the same semantics as defined in 423 [RFC 6241], XPath filters, and RFC 5277 filter, with the same 424 semantics as defined in [RFC 5277]. Additional filter types can 425 be added through augmentations. Filters can be specified "inline" 426 as part of the subscription, or can be configured separately and 427 referenced by a subscription, in order to facilitate reuse of 428 complex filters. 430 In addition, for the configuration of static subscriptions, the 431 following parameters are supported: 433 o One or more receiver IP addresses (and corresponding ports) 434 intended as the destination for push updates for each 435 subscription. In addition the transport protocol for each 436 destination may be defined. 438 o Optional parameters to identify an egress interface or IP address 439 / VRF where a subscription updates should be pushed from the 440 publisher. 442 The subscription data model is specified as part of the YANG data 443 model described later in this specification. Specifically, the 444 subscription parameters are defined in the "subscription-info" and 445 "update-policy" groupings. Receiver information is defined in the 446 "receiver-info" grouping. Information about the source address is 447 defined in the "push-source-info" grouping. It is conceivable that 448 additional subscription parameters might be added in the future. 449 This can be accomplished through augmentation of the subscription 450 data model. 452 3.2. Negotiation of Subscription Policies 454 A subscription rejection can be caused by the inability of the server 455 to provide a stream with the requested semantics. For example, a 456 server may not be able to support "on-change" updates for operational 457 data, or only support them for a limited set of data nodes. 458 Likewise, a server may not be able to support a requested updated 459 frequency, or a requested encoding. 461 Yang-push supports a simple negotiation between clients and servers 462 for subscription parameters. The negotiation is limited to a single 463 pair of subscription request and response. For negative responses, 464 the server SHOULD include in the returned error what subscription 465 parameters would have been accepted for the request. The returned 466 acceptable parameters constitute suggestions that, when followed, 467 increase the likelihood of success for subsequent requests. However, 468 they are no guarantee that subsequent requests for this client or 469 others will in fact be accepted. 471 In case a subscriber requests an encoding other than XML, and this 472 encoding is not supported by the server, the server simply indicates 473 in the response that the encoding is not supported. 475 3.3. On-Change Considerations 477 On-change subscriptions allow clients to subscribe to updates 478 whenever changes to objects occur. As such, on-change subscriptions 479 are of particular interest for data that changes relatively 480 infrequently, yet that require applications to be notified with 481 minimal delay when changes do occur. 483 On-change subscriptions tend to be more difficult to implement than 484 periodic subscriptions. Specifically, on-change subscriptions may 485 involve a notion of state to see if a change occurred between past 486 and current state, or the ability to tap into changes as they occur 487 in the underlying system. Accordingly, on-change subscriptions may 488 not be supported by all implementations or for every object. 490 When an on-change subscription is requested for a datastream with a 491 given subtree filter, where not all objects support on-change update 492 triggers, the subscription request MUST be rejected. As a result, 493 on-change subscription requests will tend to be directed at very 494 specific, targeted subtrees with only few objects. 496 Any updates for an on-change subscription will include only objects 497 for which a change was detected. To avoid flooding clients with 498 repeated updates for fast-changing objects, or objects with 499 oscillating values, an on-change subscription allows for the 500 definition of a dampening period. Once an update for a given object 501 is sent, no other updates for this particular object are sent until 502 the end of the dampening period. Values sent at the end of the 503 dampening period are the values current when that dampening period 504 expires. In addition, updates include information about objects that 505 were deleted and ones that were newly created. 507 On-change subscriptions can be refined to let users subscribe only to 508 certain types of changes, for example, only to object creations and 509 deletions, but not to modifications of object values. 511 Additional refinements are conceivable. For example, in order to 512 avoid sending updates on objects whose values undergo only a 513 negligible change, additional parameters might be added to an on- 514 change subscription specifying a policy that states how large or 515 "significant" a change has to be before an update is sent. A simple 516 policy is a "delta-policy" that states, for integer-valued data 517 nodes, the minimum difference between the current value and the value 518 that was last reported that triggers an update. Also more 519 sophisticated policies are conceivable, such as policies specified in 520 percentage terms or policies that take into account the rate of 521 change. While not specified as part of this draft, such policies can 522 be accommodated by augmenting the subscription data model 523 accordingly. 525 3.4. Data Encodings 527 Subscribed data is encoded in either XML or JSON format. A server 528 MUST support XML encoding and MAY support JSON encoding. 530 It is conceivable that additional encodings may be supported as 531 options in the future. This can be accomplished by augmenting the 532 subscription data model with additional identity statements used to 533 refer to requested encodings. 535 3.4.1. Periodic Subscriptions 537 In a periodic subscription, the data included as part of an update 538 corresponds to data that could have been simply retrieved using a get 539 operation and is encoded in the same way. XML encoding rules for 540 data nodes are defined in [RFC6020]. JSON encoding rules are defined 541 in [I-D.ietf-netmod-yang-json]. This encoding is valid JSON, but 542 also has special encoding rules to identify module namespaces and 543 provide consistent type processing of YANG data. 545 3.4.2. On-Change Subscriptions 547 In an on-change subscription, updates need to allow to differentiate 548 between data nodes that were newly created since the last update, 549 data nodes that were deleted, and data nodes whose value changed. 551 XML encoding rules correspond to how data would be encoded in input 552 to Netconf edit-config operations as specified in [RFC6241] section 553 7.2, adding "operation" attributes to elements in the data subtree. 554 Specifically, the following values will be utilized: 556 o create: The data identified by the element has been added since 557 the last update. 559 o delete: The data identified by the element has been deleted since 560 the last update. 562 o merge: The data identified by the element has been changed since 563 the last update. 565 o replace: The data identified by the element has been replaced with 566 the update contents since the last update. 568 The remove value will not be utilized. 570 Contrary to edit-config operations, the data is sent from the server 571 to the client, not from the client to the server, and will not be 572 restricted to configuration data. 574 JSON encoding rules are roughly analogous to how data would be 575 encoded in input to a YANG-patch operation, as specified in 576 [I-D.ietf-netconf-yang-patch] section 2.2. However, no edit-ids will 577 be needed. Specifically, changes will be grouped under respective 578 "operation" containers for creations, deletions, and modifications. 580 3.5. Subscription Filters 582 Subscriptions can specify filters for subscribed data. The following 583 filters are supported: 585 o subtree-filter: A subtree filter specifies a subtree that the 586 subscription refers to. When specified, updates will only concern 587 data nodes from this subtree. Syntax and semantics correspond to 588 that specified for [RFC6241] section 6. 590 o xpath-filter: An XPath filter specifies an XPath expression 591 applied to the data in an update, assuming XML-encoded data. 593 o RFC5277 filter: A filter that allows for matching of update 594 notification records per RFC 5277. 596 Only a single filter can be applied to a subscription at a time. 598 It is conceivable for implementations to support other filters. For 599 example, an on-change filter might specify that changes in values 600 should be sent only when the magnitude of the change since previous 601 updates exceeds a certain threshold. It is possible to augment the 602 subscription data model with additional filter types. 604 3.6. Push Data Stream and Transport Mapping 606 Pushing data based on a subscription could be considered analogous to 607 a response to a data retrieval request, e.g. a "get" request. 608 However, contrary to such a request, multiple responses to the same 609 request may get sent over a longer period of time. 611 A more suitable mechanism to consider is therefore that of a 612 notification. There are however some specifics that need to be 613 considered. Contrary to other notifications that are associated with 614 alarms and unexpected event occurrences, push updates are solicited, 615 i.e. tied to a particular subscription which triggered the 616 notification, and arguably only of interest to the subscriber, 617 respectively the intended receiver of the subscription. A 618 subscription therefore needs to be able to distinguish between 619 streams that underlie push updates and streams of other 620 notifications. By the same token, notifications associated with 621 updates and subscriptions to updates need to be distinguished from 622 other notifications, in that they enter a datastream of push updates, 623 not a stream of other event notifications. 625 A push update notification contains several parameters: 627 o A subscription correlator, referencing the name of the 628 subscription on whose behalf the notification is sent. 630 o A data node that contains a representation of the datastore 631 subtree containing the updates. The subtree is filtered per 632 access control rules to contain only data that the subscriber is 633 authorized to see. Also, depending on the subscription type, 634 i.e., specifically for on-change subscriptions, the subtree 635 contains only the data nodes that contain actual changes. (This 636 can be simply a node of type string or, for XML-based encoding, 637 anyxml.) 639 Notifications are sent using elements as defined in 640 [RFC5277]. Alternative transports are conceivable but outside the 641 scope of this specification. 643 The solution specified in this document uses notifications to define 644 datastore updates. The contents of the notification includes a set 645 of explicitly defined data nodes. For this purpose, two new generic 646 notifications are introduced, "push-update" and "push-change-update". 647 Those notifications define how mechanisms that carry YANG 648 notifications (e.g. Netconf notifications and Restconf) can be used 649 to carry data records with updates of datastore contents as specified 650 by a subscription. It is possible also map notifications to other 651 transports and encodings and use the same subscription model; 652 however, the definition of such mappings is outside the scope of this 653 document. 655 Push-update notification defines updates for a periodic subscription, 656 as well as for the initial update of an on-change subscription used 657 to synchronize the receiver at the start of a new subscription. The 658 update record contains a data snippet that contains an instantiated 659 subtree with the subscribed contents. The content of the update 660 record is equivalent to the contents that would be obtained had the 661 same data been explicitly retrieved using e.g. a Netconf "get"- 662 operation, with the same filters applied. 664 The contents of the notification conceptually represents the union of 665 all data nodes in the yang modules supported by the server. However, 666 in a YANG data model, it is not practical to model the precise data 667 contained in the updates as part of the notification. This is 668 because the specific data nodes supported depend on the implementing 669 system and may even vary dynamically. Therefore, to capture this 670 data, a single parameter that can represent any datastore contents is 671 used, not parameters that represent data nodes one at a time. 673 Push-change-update notification defines updates for on-change 674 subscriptions. The update record here contains a data snippet that 675 indicates the changes that data nodes have undergone, i.e. that 676 indicates which data nodes have been created, deleted, or had changes 677 to their values. The format follows the same format that operations 678 that apply changes to a data tree would apply, indicating the 679 creates, deletes, and modifications of data nodes. 681 The following is an example of push notification. It contains an 682 update for subscription 1011, including a subtree with root foo that 683 contains a leaf, bar: 685 687 2015-03-09T19:14:56Z 688 689 1011 690 2015-03-09T19:14:56Z 691 692 693 some_string 694 695 696 697 699 Figure 1: Push example 701 The following is an example of an on-change notification. It 702 contains an update for subscription 89, including a new value for a 703 leaf called beta, which is a child of a top-level container called 704 alpha: 706 708 2015-03-09T19:14:56Z 709 711 89 712 2015-03-09T19:14:56Z 713 714 715 1500 716 717 718 719 721 Figure 2: Push example for on change 723 The equivalent update when requesting json encoding: 725 727 2015-03-09T19:14:56Z 728 730 89 731 2015-03-09T19:14:56Z 732 733 { 734 "ietf-yang-patch:yang-patch": { 735 "patch-id": [ 736 null 737 ], 738 "edit": [ 739 { 740 "edit-id": "edit1", 741 "operation": "merge", 742 "target": "/alpha/beta", 743 "value": { 744 "beta": 1500 745 } 746 } 747 ] 748 } 749 } 750 751 752 754 Figure 3: Push example for on change with JSON 756 When the beta leaf is deleted, the server may send 757 759 2015-03-09T19:14:56Z 760 762 89 763 2015-03-09T19:14:56Z 764 765 766 768 769 770 771 773 Figure 4: 2nd push example for on change update 775 3.7. Subscription management 777 There are two ways in which subscriptions can be managed: RPC-based 778 and configuration based. Any given subscription is either RPC-based 779 or configuration-based. There is no mixing-and-matching of RPC and 780 configuration operations. Specifically, a configured subscription 781 cannot be modified or deleted using RPC. Likewise, a subscription 782 created via RPC cannot be through configuration operations. 784 3.7.1. Subscription management by RPC 786 RPC-based subscription allows a subscriber to create a subscription 787 via an RPC call. The subscriber and the receiver are the same 788 entity, i.e. a subscriber cannot subscribe or in other ways interfere 789 with a subscription on another receiver's behalf. The lifecycle of 790 the subscription is dependent on the lifecyle of the transport 791 session over which the subscription was requested. For example, when 792 a Netconf session over which a subscription was created is torn down, 793 the subscription is automatically terminated (and needs to be re- 794 initiated when a new session is established). Alternatively, a 795 subscriber can also decide to delete a subscription via another RPC. 797 When a create-subscription request is successful, the subscription 798 identifier of the freshly created subscription is returned. 800 A subscription can be rejected for multiple reasons, including the 801 lack of authorization to create a subscription, the lack of read 802 authorization on the requested data node, or the inability of the 803 server to provide a stream with the requested semantics. In such 804 cases, no subscription is created. Instead, the subscription-result 805 with the failure reason is returned as part of the RPC response. In 806 addition, a set of alternative subscription parameters MAY be 807 returned that would likely have resulted in acceptance of the 808 subscription request, which the subscriber may try for a future 809 subscription attempt. 811 It should be noted that a rejected subscription does not result in 812 the generation of an rpc-reply with an rpc-error element, as neither 813 the specification of YANG-push specific errors nor the specification 814 of additional data parameters to be returned in an error case are 815 supported as part of a YANG data model. 817 For instance, for the following request: 819 821 823 push-update 824 827 500 828 encode-xml 829 830 832 Figure 5: Create-Subscription example 834 the server might return: 836 838 840 error-insufficient-resources 841 842 2000 843 845 Figure 6: Error response example 847 A subscriber that creates a subscription using RPC can modify or 848 delete the subscription using other RPCs. When the session between 849 subscriber and publisher is terminated, the subscription is 850 implicitly deleted. 852 3.7.2. Subscription management by configuration 854 Configuration-based subscription allows a subscription to be 855 established as part of a server's configuration. This allows to 856 persist subscriptions. Persisted subscriptions allow for a number of 857 additional options than RPC-based subscriptions. As part of a 858 configured subscription, a receiver needs to be specified. It is 859 thus possible to have a different system acting as subscriber (the 860 client creating the subscription) and as receiver (the client 861 receiving the updates). In addition, a configured subscription 862 allows to specify which transport protocol should be used, as well as 863 the sender source (for example, a particular interface or an address 864 of a specific VRF) from which updates are to be pushed. 866 Configuration-based subscriptions cannot be modified or deleted using 867 RPCs. Instead, configured subscriptions are deleted as part of 868 regular configuration operations. Servers SHOULD reject attempts to 869 modify configurations of active subscriptions. This way, race 870 conditions in which a receiver may not be aware of changed 871 subscription policies are avoided. 873 3.8. Other considerations 875 3.8.1. Authorization 877 A receiver of subscription data may only be sent updates for which 878 they have proper authorization. Data that is being pushed therefore 879 needs to be subjected to a filter that applies all corresponding 880 rules applicable at the time of a specific pushed update, removing 881 any non-authorized data as applicable. 883 The authorization model for data in YANG datastores is described in 884 the Netconf Access Control Model [RFC6536]. However, some 885 clarifications to that RFC are needed so that the desired access 886 control behavior is applied to pushed updates. 888 One of these clarifications is that a subscription may only be 889 established if the Receiver has read access to the target data node. 891 +-------------+ +-------------+ 892 subscription | protocol | | target | 893 request --> | operation | -------------> | data node | 894 | allowed? | datastore | access | 895 +-------------+ or state | allowed? | 896 data access +-------------+ 898 Figure 7: Access control for subscription 900 Likewise if a receiver no longer has read access permission to a 901 target data node, the subscription must be abnormally terminated 902 (with loss of access permission as the reason provided). 904 Another clarification to [RFC6536] is that each of the individual 905 nodes in a pushed update must also go through access control 906 filtering. This includes new nodes added since the last push update, 907 as well as existing nodes. For each of these read access must be 908 verified. The methods of doing this efficiently are left to 909 implementation. 911 +-------------+ +-------------------+ 912 subscription | data node | yes | | 913 update --> | access | ---> | add data node | 914 | allowed? | | to update message | 915 +-------------+ +-------------------+ 917 Figure 8: Access control for push updates 919 If there are read access control changes applied under the target 920 node, no notifications indicating the fact that this has occurred 921 need to be provided. 923 3.8.2. Additional subscription primitives 925 Other possible operations include the ability for a Subscriber to 926 request the suspension/resumption of a Subscription with a Publisher. 927 However, subscriber driven suspension is not viewed as essential at 928 this time, as a simpler alternative is to remove a subscription and 929 recreate it when needed. 931 It should be noted that this does not affect the ability of the 932 Publisher to suspend a subscription. This can occur in cases the 933 server is not able to serve the subscription for a certain period of 934 time, and indicated by a corresponding notification. 936 3.8.3. Robustness and reliability considerations 938 Particularly in the case of on-change push updates, it is important 939 that push updates do not get lost. 941 Yang-push uses a secure and reliable transport. Notifications are 942 not getting reordered, and in addition contain a time stamp. For 943 those reasons, for the transport of push-updates, we believe that 944 additional reliability mechanisms at the application level, such as 945 sequence numbers for push updates, are not required. 947 At the same time, it is conceivable that under certain circumstances, 948 a push server is not able to generate the update notifications that 949 it had committed to when accepting a subcription. In those 950 circumstances, the server needs to inform the receiver of the 951 situation. For this purpose, notifications are defined that a push 952 server can use to inform subscribers/ receivers when a subscription 953 is (temporarily) suspended, when a suspended subscription is resumed, 954 and when a a subscription is terminated. This way, receivers will be 955 able to rely on a subscription, knowing that they will be informed of 956 any situations in which updates might be missed. 958 3.8.4. Update size and fragmentation considerations 960 Depending on the subscription, the volume of updates can become quite 961 large. There is no inherent limitation to the amount of data that 962 can be included in a notification. That said, it may not always be 963 practical to send the entire update in a single chunk. 964 Implementations MAY therefore choose, at their discretion, to "chunk" 965 updates and break them out into several update notifications. 967 3.8.5. Push data streams 969 There are several conceptual data streams introduced in this 970 specification: 972 o yang-push includes the entirety of YANG data, including both 973 configuration and operational data. 975 o operational-push includes all operational (read-only) YANG data 977 o config-push includes all YANG configuration data. 979 It is conceivable to introduce other data streams with more limited 980 scope, for example: 982 o operdata-nocounts-push, a datastream containing all operational 983 (read-only) data with the exception of counters 985 o other custom datastreams 987 Those data streams make particular sense for use cases involving 988 service assurance (not relying on operational data), and for use 989 cases requiring on-change update triggers which make no sense to 990 support in conjunction with fast-changing counters. While it is 991 possible to specify subtree filters on yang-push to the same effect, 992 having those data streams greatly simplifies articulating 993 subscriptions in such scenarios. 995 3.8.6. Implementation considerations 997 Implementation specifics are outside the scope of this specification. 998 That said,it should be noted that monitoring of operational state 999 changes inside a system can be associated with significant 1000 implementation challenges. 1002 Even periodic retrieval of operational state alone, to be able to 1003 push it, can consume considerable system resources. Configuration 1004 data may in many cases be persisted in an actual database or a 1005 configuration file, where retrieval of the database content or the 1006 file itself is reasonably straightforward and computationally 1007 inexpensive. However, retrieval of operational data may, depending 1008 on the implementation, require invocation of APIs, possibly on an 1009 object-by-object basis, possibly involving additional internal 1010 interrupts, etc. 1012 For those reasons, if is important for an implementation to 1013 understand what subscriptions it can or cannot support. It is far 1014 preferrable to decline a subscription request, than to accept it only 1015 to result in subsequent failure later. 1017 Whether or not a subscription can be supported will in general be 1018 determined by a combination of several factors, including the 1019 subscription policy (on-change or periodic, with on-change in general 1020 being the more challenging of the two), the period in which to report 1021 changes (1 second periods will consume more resources than 1 hour 1022 periods), the amount of data in the subtree that is being subscribed 1023 to, and the number and combination of other subscriptions that are 1024 concurrently being serviced. 1026 When providing access control to every node in a pushed update, it is 1027 possible to make and update efficient access control filters for an 1028 update. These filters can be set upon subscription and applied 1029 against a stream of updates. These filters need only be updated when 1030 (a) there is a new node added/removed from the subscribed tree with 1031 different permissions than its parent, or (b) read access permissions 1032 have been changed on nodes under the target node for the subscriber. 1034 4. A YANG data model for management of datastore push subscriptions 1036 4.1. Overview 1038 The YANG data model for datastore push subscriptions is depicted in 1039 the following figure. 1041 module: ietf-datastore-push 1042 +--ro update-streams 1043 | +--ro update-stream* update-stream 1044 +--rw filters 1045 | +--rw filter* [filter-id] 1046 | +--rw filter-id filter-id 1047 | +--rw (filter-type)? 1048 | +--:(subtree) 1049 | | +--rw subtree-filter 1050 | +--:(xpath) 1051 | | +--rw xpath-filter? yang:xpath1.0 1052 | +--:(rfc5277) 1053 | +--rw filter 1054 +--rw subscription-config {configured-subscriptions}? 1055 | +--rw datastore-push-subscription* [subscription-id] 1056 | +--rw subscription-id subscription-id 1057 | +--rw stream? update-stream 1058 | +--rw encoding? encoding 1059 | +--rw subscription-start-time? yang:date-and-time 1060 | +--rw subscription-stop-time? yang:date-and-time 1061 | +--rw (filterspec)? 1062 | | +--:(inline) 1063 | | | +--rw (filter-type)? 1064 | | | +--:(subtree) 1065 | | | | +--rw subtree-filter 1066 | | | +--:(xpath) 1067 | | | | +--rw xpath-filter? yang:xpath1.0 1068 | | | +--:(rfc5277) 1069 | | | +--rw filter 1070 | | +--:(by-reference) 1071 | | +--rw filter-ref? filter-ref 1072 | +--rw (update-trigger)? 1073 | | +--:(periodic) 1074 | | | +--rw period yang:timeticks 1075 | | +--:(on-change) {on-change}? 1076 | | +--rw no-synch-on-start? empty 1077 | | +--rw dampening-period yang:timeticks 1078 | | +--rw excluded-change* change-type 1079 | +--rw receiver* [address] 1080 | | +--rw address inet:host 1081 | | +--rw port? inet:port-number 1082 | | +--rw protocol? transport-protocol 1083 | +--rw (push-source)? 1084 | +--:(interface-originated) 1085 | | +--rw source-interface? if:interface-ref 1086 | +--:(address-originated) 1087 | +--rw source-vrf? uint32 1088 | +--rw source-address inet:ip-address-no-zone 1089 +--ro subscriptions 1090 +--ro datastore-push-subscription* [subscription-id] 1091 +--ro subscription-id subscription-id 1092 +--ro configured-subscription? empty {configured-subscriptions}? 1093 +--ro subscription-status? identityref 1094 +--ro stream? update-stream 1095 +--ro encoding? encoding 1096 +--ro subscription-start-time? yang:date-and-time 1097 +--ro subscription-stop-time? yang:date-and-time 1098 +--ro (filterspec)? 1099 | +--:(inline) 1100 | | +--ro (filter-type)? 1101 | | +--:(subtree) 1102 | | | +--ro subtree-filter 1103 | | +--:(xpath) 1104 | | | +--ro xpath-filter? yang:xpath1.0 1105 | | +--:(rfc5277) 1106 | | +--ro filter 1107 | +--:(by-reference) 1108 | +--ro filter-ref? filter-ref 1109 +--ro (update-trigger)? 1110 | +--:(periodic) 1111 | | +--ro period yang:timeticks 1112 | +--:(on-change) {on-change}? 1113 | +--ro no-synch-on-start? empty 1114 | +--ro dampening-period yang:timeticks 1115 | +--ro excluded-change* change-type 1116 +--ro receiver* [address] 1117 | +--ro address inet:host 1118 | +--ro port? inet:port-number 1119 | +--ro protocol? transport-protocol 1120 +--ro (push-source)? 1121 +--:(interface-originated) 1122 | +--ro source-interface? if:interface-ref 1123 +--:(address-originated) 1124 +--ro source-vrf? uint32 1125 +--ro source-address inet:ip-address-no-zone 1127 Figure 9: Model structure 1129 The components of the model are described in the following 1130 subsections. 1132 4.2. Update streams 1134 Container "update-streams" is used to indicate which data streams are 1135 provided by the system and can be subscribed to. For this purpose, 1136 it contains a leaf list of data nodes identifying the supported 1137 streams. 1139 4.3. Filters 1141 Container "filters" contains a list of configurable data filters, 1142 each specified in its own list element. This allows users to 1143 configure filters separately from an actual subscription, which can 1144 then be referenced from a subscription. This facilitates the reuse 1145 of filter definitions, which can be important in case of complex 1146 filter conditions. 1148 One of three types of filters can be specified as part of a filter 1149 list element. Subtree filters follow syntax and semantics of RFC 1150 6241 and allow to specify which subtree(s) to subscribe to. In 1151 addition, XPath filters can be specified for more complex filter 1152 conditions. Finally, filters can be specified using syntax and 1153 semantics of RFC5277. 1155 It is conceivable to introduce other types of filters; in that case, 1156 the data model needs to be augmented accordingly. 1158 4.4. Subscription configuration 1160 As an optional feature, configured-subscriptions, allows for the 1161 static configuration of subscriptions, i.e. for subscriptions that 1162 are created via configuration as opposed to RPC. Subscriptions 1163 configurations are represented by list subscription-config. Each 1164 subscription is represented through its own list element and includes 1165 the following components: 1167 o "subscription-id" is an identifier used to refer to the 1168 subscription. 1170 o "stream" refers to the stream being subscribed to. The 1171 subscription model assumes the presence of perpetual and 1172 continuous streams of updates. Various streams are defined: 1173 "push-update" covers the entire set of YANG data in the server. 1174 "operational-push" covers all operational data, while "config- 1175 push" covers all configuration data. Other streams could be 1176 introduced in augmentations to the model by introducing additional 1177 identities. 1179 o "encoding" refers to the encoding requested for the data updates. 1180 By default, updates are encoded using XML. However, JSON can be 1181 requested as an option if the json-enconding feature is supported. 1182 Other encodings may be supported in the future. 1184 o "subscription-start-time" specifies when the subscription is 1185 supposed to start. The start time also serves as anchor time for 1186 periodic subscriptions (see below). 1188 o "subscription-stop-time" specifies a stop time for the 1189 subscription. Once the stop time is reached, the subscription is 1190 automatically terminated. However, even when terminated, the 1191 subscription entry remains part of the configuration unless 1192 explicity deleted from the configuration. It is possible to 1193 effectively "resume" a stopped subscription by reconfiguring the 1194 stop time. 1196 o Filters for a subscription can be specified using a choice, 1197 allowing to either reference a filter that has been separately 1198 configured or entering its definition inline. 1200 o A choice of subscription policies allows to define when to send 1201 new updates - periodic or on change. 1203 * For periodic subscriptions, the trigger is defined by a 1204 "period", a parameter that defines the interval with which 1205 updates are to be pushed. The start time of the subscription 1206 serves as anchor time, defining one specific point in time at 1207 which an update needs to be sent. Update intervals always fall 1208 on the points in time that are a multiple of a period after the 1209 start time. 1211 * For on-change subscriptions, the trigger occurs whenever a 1212 change in the subscribed information is detected. On-change 1213 subscriptions have more complex semantics that is guided by 1214 additional parameters. "dampening-period" specifies the 1215 interval that must pass before a successive update for the same 1216 data node is sent. The first time a change is detected, the 1217 update is sent immediately. If a subsequent change is 1218 detected, another update is only sent once the dampening period 1219 has passed, containing the value of the data node that is then 1220 valid. "excluded-change" allows to restrict the types of 1221 changes for which updates are sent (changes to object values, 1222 object creation or deletion events). "no-synch-on-start" is a 1223 flag that allows to specify whether or not a complete update 1224 with all the subscribed data should be sent at the beginning of 1225 a subscription; if the flag is omitted, a complete update is 1226 sent to facilitate synchronization. It is conceivable to 1227 augment the data model with additional parameters in the future 1228 to specify even more refined policies, such as parameters that 1229 specify the magnitude of a change that must occur before an 1230 update is triggered. 1232 o This is followed with a list of receivers for the subscription, 1233 indicating for each receiver the transport that should be used for 1234 push updates (if options other than Netconf are supported). It 1235 should be noted that the receiver does not have to be the same 1236 system that configures the subscription. 1238 o Finally, "push-source" can be used to specify the source of push 1239 updates, either a specific interface or server address. 1241 A subscription created through configuration cannot be deleted using 1242 an RPC. Likewise, subscriptions created through RPC cannot be 1243 deleted through configuration. 1245 The deletion of a subscription, whether through RPC or configuration, 1246 results in immediate termination of the subsciption. 1248 4.5. Subscription monitoring 1250 Subscriptions can be subjected to management themselves. For 1251 example, it is possible that a server may no longer be able to serve 1252 a subscription that it had previously accepted. Perhaps it has run 1253 out of resources, or internal errors may have occurred. When this is 1254 the case, a server needs to be able to temporarily suspend the 1255 subscription, or even to terminate it. More generally, the server 1256 should provide a means by which the status of subscriptions can be 1257 monitored. 1259 Container "subscriptions" contains the state of all subscriptions 1260 that are currently active. This includes subscriptions that were 1261 created (and have not yet been deleted) using RPCs, as well as 1262 subscriptions that have been configured as part of configuration. 1264 Each subscription is represented as a list element "datastore-push- 1265 subscription". The associated information includes an identifier for 1266 the subscription, a subscription status, as well as the various 1267 subscription parameters that are in effect. The subscription status 1268 indicates whether the subscription is currently active and healthy, 1269 or if it is degraded in some form. Leaf "configured-subscription" 1270 indicates whether the subscription came into being via configuration 1271 or via RPC. 1273 Subscriptions that were created by RPC are removed from the list once 1274 they expire (reaching stop-time )or when they are terminated. 1275 Subscriptions that were created by configuration need to be deleted 1276 from the configuration by a configuration editing operation. 1278 4.6. Notifications 1280 A server needs to indicate any changes in status of a subscription to 1281 the receiver through a notification. Specifically, subscribers need 1282 to be informed of the following: 1284 o A subscription has been temporarily suspended (including the 1285 reason) 1287 o A subscription (that had been suspended earlier) is once again 1288 operational 1290 o A subscription has been terminated (including the reason) 1292 o A subscription has been modified (including the current set of 1293 subscription parameters in effect) 1295 Finally, a server might provide additional information about 1296 subscriptions, such as statistics about the number of data updates 1297 that were sent. However, such information is currently outside the 1298 scope of this specification. 1300 4.7. RPCs 1302 Yang-push subscriptions are created, modified, and deleted using 1303 three RPCs. 1305 4.7.1. Create-subscription RPC 1307 The subscriber sends a create-subscription RPC with the parameters in 1308 section 3.1. For instance 1310 1312 1314 push-update 1315 1318 500 1319 encode-xml 1320 1321 1323 Figure 10: Create-subscription RPC 1325 The server must respond explicitly positively (i.e., subscription 1326 accepted) or negatively (i.e., subscription rejected) to the request. 1327 Positive responses include the subscription-id of the accepted 1328 subscription. In that case a server may respond: 1330 1332 1334 ok 1335 1336 1337 52 1338 1339 1341 Figure 11: Create-subscription positive RPC response 1343 A subscription can be rejected for multiple reasons, including the 1344 lack of authorization to create a subscription, the lack of read 1345 authorization on the requested data node, or the inability of the 1346 server to provide a stream with the requested semantics. . 1348 When the requester is not authorized to read the requested data node, 1349 the returned indicates an authorization error and the 1350 requested node. For instance, if the above request was unauthorized 1351 to read node "ex:foo" the server may return: 1353 1355 1357 error-data-not-authorized 1358 1359 1361 Figure 12: Create-subscription access denied response 1363 If a request is rejected because the server is not able to serve it, 1364 the server SHOULD include in the returned error what subscription 1365 parameters would have been accepted for the request. However, they 1366 are no guarantee that subsequent requests for this client or others 1367 will in fact be accepted. 1369 For example, for the following request: 1371 1373 1375 push-update 1376 1379 10 1380 encode-xml 1381 1382 1384 Figure 13: Create-subscription request example 2 1386 A server that cannot serve on-change updates but periodic updates 1387 might return the following: 1389 1391 1393 error-no-such-option 1394 1395 100 1396 1398 Figure 14: Create-subscription error response example 2 1400 4.7.2. Modify-subscription RPC 1402 The subscriber may send a modify-subscription PRC for a subscription 1403 previously created using RPC The subscriber may change any 1404 subscription parameters by including the new values in the modify- 1405 subscription RPC. Parameters not included in the rpc should remain 1406 unmodified. For illustration purposes we include an exchange example 1407 where a subscriber modifies the period of the subscription. 1409 1411 1413 push-update 1414 1415 1011 1416 1417 1420 250 1421 encode-xml 1422 1423 1425 Figure 15: Modify subscription request 1427 The server must respond explicitly positively (i.e., subscription 1428 accepted) or negatively (i.e., subscription rejected) to the request. 1429 Positive responses include the subscription-id of the accepted 1430 subscription. In that case a server may respond: 1432 1434 1436 ok 1437 1438 1439 1011 1440 1441 1443 Figure 16: Modify subscription response 1445 If the subscription modification is rejected, the server must send a 1446 response like it does for a create-subscription and maintain the 1447 subscription as it was before the modification request. A 1448 subscription may be modified multiple times. 1450 A configured subscription cannot be modified using modify- 1451 subscription RPC. Instead, the configuration needs to be edited as 1452 needed. 1454 4.7.3. Delete-subscription RPC 1456 To stop receiving updates from a subscription and effectively delete 1457 a subscription that had previously been created using a create- 1458 subscription RPC, a subscriber can send a delete-subscription RPC, 1459 which takes as only input the subscription-id. For example 1461 1463 1465 1466 1011 1467 1468 1469 1471 1473 1474 1476 Figure 17: Delete subscription 1478 Configured subscriptions cannot be deleted via RPC, but have to be 1479 removed from the configuration. 1481 5. YANG module 1483 1484 file "ietf-yang-push@2016-02-23.yang" 1486 module ietf-yang-push { 1487 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1488 prefix yp; 1490 import ietf-inet-types { 1491 prefix inet; 1492 } 1493 import ietf-yang-types { 1494 prefix yang; 1495 } 1496 import ietf-interfaces { 1497 prefix if; 1498 } 1500 organization "IETF"; 1501 contact 1502 "WG Web: 1503 WG List: 1505 WG Chair: Mahesh Jethanandani 1506 1508 WG Chair: Mehmet Ersue 1509 1511 Editor: Alexander Clemm 1512 1514 Editor: Eric Voit 1515 1517 Editor: Alberto Gonzalez Prieto 1518 1520 Editor: Ambika Prasad Tripathy 1521 1523 Editor: Einar Nilsen-Nygaard 1524 "; 1526 description 1527 "This module contains conceptual YANG specifications 1528 for YANG push."; 1530 revision 2016-02-23 { 1531 description 1532 "Changes to grouping structure, RPC definitions, filter 1533 definitions, origin interface and receiver definitions."; 1534 reference "YANG Datastore Push, draft-ietf-netconf-yang-push-01"; 1535 } 1537 feature on-change { 1538 description 1539 "This feature indicates that on-change updates are 1540 supported."; 1541 } 1543 feature json { 1544 description 1545 "This feature indicates that JSON encoding of push updates 1546 is supported."; 1547 } 1548 feature configured-subscriptions { 1549 description 1550 "This feature indicates that management plane configuration 1551 of subscription is supported."; 1552 } 1554 identity subscription-result { 1555 description 1556 "Base identity for RPC responses to requests surrounding 1557 management (e.g. creation, modification) of 1558 subscriptions."; 1559 } 1561 identity ok { 1562 base subscription-result; 1563 description 1564 "OK - RPC was successful and was performed as requested."; 1565 } 1567 identity error { 1568 base subscription-result; 1569 description 1570 "RPC was not successful. 1571 Base identity for error return codes."; 1572 } 1574 identity error-no-such-subscription { 1575 base error; 1576 description 1577 "A subscription with the requested subscription ID 1578 does not exist."; 1579 } 1581 identity error-no-such-option { 1582 base error; 1583 description 1584 "A requested parameter setting is not supported."; 1585 } 1587 identity error-insufficient-resources { 1588 base error; 1589 description 1590 "The server has insufficient resources to support the 1591 subscription as requested."; 1592 } 1594 identity error-configured-subscription { 1595 base error; 1596 description 1597 "Cannot apply RPC to a configured subscription, i.e. 1598 to a subscription that was not created via RPC."; 1599 } 1601 identity error-data-not-authorized { 1602 base error; 1603 description 1604 "No read authorization for a requested data node."; 1605 } 1607 identity error-other { 1608 base error; 1609 description 1610 "An unspecified error has occurred (catch all)."; 1611 } 1613 identity subscription-stream-status { 1614 description 1615 "Base identity for the status of subscriptions and 1616 datastreams."; 1617 } 1619 identity active { 1620 base subscription-stream-status; 1621 description 1622 "Status is active and healthy."; 1623 } 1625 identity inactive { 1626 base subscription-stream-status; 1627 description 1628 "Status is inactive, for example outside the 1629 interval between start time and stop time."; 1630 } 1632 identity in-error { 1633 base subscription-stream-status; 1634 description 1635 "The status is in error or degraded, meaning that 1636 stream and/or subscription is currently unable to provide 1637 the negotiated updates."; 1638 } 1640 identity subscription-errors { 1641 description 1642 "Base identity for subscription error status. 1643 This identity is not to be confused with error return 1644 codes for RPCs"; 1645 } 1647 identity internal-error { 1648 base subscription-errors; 1649 description 1650 "Subscription failures caused by server internal error."; 1651 } 1653 identity no-resources { 1654 base subscription-errors; 1655 description 1656 "Lack of resources, e.g. CPU, memory, bandwidth"; 1657 } 1659 identity subscription-deleted { 1660 base subscription-errors; 1661 description 1662 "The subscription was terminated because the subscription 1663 was deleted."; 1664 } 1666 identity other { 1667 base subscription-errors; 1668 description 1669 "Fallback reason - any other reason"; 1670 } 1672 identity event-stream { 1673 description 1674 "Base identity to represent a generic stream of event 1675 notifications."; 1676 } 1678 identity update-stream { 1679 base event-stream; 1680 description 1681 "Base identity to represent a conceptual system-provided 1682 datastream of datastore updates with predefined semantics."; 1683 } 1685 identity yang-push { 1686 base update-stream; 1687 description 1688 "A conceptual datastream consisting of all datastore 1689 updates, including operational and configuration data."; 1690 } 1691 identity operational-push { 1692 base update-stream; 1693 description 1694 "A conceptual datastream consisting of updates of all 1695 operational data."; 1696 } 1698 identity config-push { 1699 base update-stream; 1700 description 1701 "A conceptual datastream consisting of updates of all 1702 configuration data."; 1703 } 1705 identity custom-stream { 1706 base update-stream; 1707 description 1708 "A category of customizable datastream for datastore 1709 updates with contents that have defined by a user."; 1710 } 1712 identity netconf-stream { 1713 base event-stream; 1714 description 1715 "Default notification stream"; 1716 } 1718 identity encodings { 1719 description 1720 "Base identity to represent data encodings"; 1721 } 1723 identity encode-xml { 1724 base encodings; 1725 description 1726 "Encode data using XML"; 1727 } 1729 identity encode-json { 1730 base encodings; 1731 description 1732 "Encode data using JSON"; 1733 } 1735 identity transport { 1736 description 1737 "An identity that represents a transport protocol for event updates"; 1738 } 1739 identity netconf { 1740 base transport; 1741 description 1742 "Netconf notifications as a transport"; 1743 } 1745 identity restconf { 1746 base transport; 1747 description 1748 "Restconf notifications as a transport"; 1749 } 1751 typedef datastore-contents-xml { 1752 type string; 1753 description 1754 "This type is be used to represent datastore contents, 1755 i.e. a set of data nodes with their values, in XML. 1756 The syntax corresponds to the syntax of the data payload 1757 returned in a corresponding Netconf get operation with the 1758 same filter parameters applied."; 1759 reference "RFC 6241 section 7.7"; 1760 } 1762 typedef datastore-changes-xml { 1763 type string; 1764 description 1765 "This type is used to represent a set of changes in a 1766 datastore encoded in XML, indicating for datanodes whether 1767 they have been created, deleted, or updated. The syntax 1768 corresponds to the syntax used to when editing a 1769 datastore using the edit-config operation in Netconf."; 1770 reference "RFC 6241 section 7.2"; 1771 } 1773 typedef datastore-contents-json { 1774 type string; 1775 description 1776 "This type is be used to represent datastore contents, 1777 i.e. a set of data nodes with their values, in JSON. 1778 The syntax corresponds to the syntax of the data 1779 payload returned in a corresponding RESTCONF get 1780 operation with the same filter parameters applied."; 1781 reference "RESTCONF Protocol"; 1782 } 1784 typedef datastore-changes-json { 1785 type string; 1786 description 1787 "This type is used to represent a set of changes in a 1788 datastore encoded in JSON, indicating for datanodes whether 1789 they have been created, deleted, or updated. The syntax 1790 corresponds to the syntax used to patch a datastore 1791 using the yang-patch operation with Restconf."; 1792 reference "draft-ietf-netconf-yang-patch"; 1793 } 1795 typedef subscription-id { 1796 type uint32; 1797 description 1798 "A type for subscription identifiers."; 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 subscription-result; 1811 } 1812 description 1813 "The result of a subscription operation"; 1814 } 1816 typedef subscription-term-reason { 1817 type identityref { 1818 base 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 subscription-errors; 1827 } 1828 description 1829 "Reason for a server to suspend a subscription."; 1830 } 1832 typedef encoding { 1833 type identityref { 1834 base encodings; 1836 } 1837 description 1838 "Specifies a data encoding, e.g. for a data subscription."; 1839 } 1841 typedef change-type { 1842 type enumeration { 1843 enum "create" { 1844 description 1845 "A new data node was created"; 1846 } 1847 enum "delete" { 1848 description 1849 "A data node was deleted"; 1850 } 1851 enum "modify" { 1852 description 1853 "The value of a data node has changed"; 1854 } 1855 } 1856 description 1857 "Specifies different types of changes that may occur 1858 to a datastore."; 1859 } 1861 typedef transport-protocol { 1862 type identityref { 1863 base transport; 1864 } 1865 description 1866 "Specifies transport protocol used to send updates to a 1867 receiver."; 1868 } 1870 typedef push-source { 1871 type enumeration { 1872 enum "interface-originated" { 1873 description 1874 "Pushes will be sent from a specific interface on a 1875 Publisher"; 1876 } 1877 enum "address-originated" { 1878 description 1879 "Pushes will be sent from a specific address on a 1880 Publisher"; 1881 } 1882 } 1883 description 1884 "Specifies from where objects will be sourced when being pushed 1885 off a publisher."; 1886 } 1888 typedef update-stream { 1889 type identityref { 1890 base update-stream; 1891 } 1892 description 1893 "Specifies a system-provided datastream."; 1894 } 1896 typedef filter-ref { 1897 type leafref { 1898 path "/yp:filters/yp:filter/yp:filter-id"; 1899 } 1900 description 1901 "This type is used to reference a yang push filter."; 1902 } 1904 grouping datatree-filter { 1905 description 1906 "This grouping defines filters for a datastore tree."; 1907 choice filter-type { 1908 description 1909 "A filter needs to be a single filter of a given type. 1910 Mixing and matching of multiple filters does not occur 1911 at the level of this grouping."; 1912 case subtree { 1913 description 1914 "Subtree filter."; 1915 anyxml subtree-filter { 1916 description 1917 "Subtree-filter used to specify the data nodes targeted 1918 for subscription within a subtree, or subtrees, of a 1919 conceptual YANG datastore. 1920 It may include additional criteria, 1921 allowing users to receive only updates of a limited 1922 set of data nodes that match those filter criteria. 1923 This will be used to define what 1924 updates to include in a stream of update events, i.e. 1925 to specify for which data nodes update events should be 1926 generated and specific match expressions that objects 1927 need to meet. The syntax follows the subtree filter 1928 syntax specified in RFC 6241, section 6."; 1929 reference "RFC 6241 section 6"; 1930 } 1931 } 1932 case xpath { 1933 description 1934 "XPath filter"; 1935 leaf xpath-filter { 1936 type yang:xpath1.0; 1937 description 1938 "Xpath defining the data items of interest."; 1939 } 1940 } 1941 case rfc5277 { 1942 anyxml filter { 1943 description 1944 "Subtree filter per RFC 5277"; 1945 } 1946 } 1947 } 1948 } 1950 grouping update-policy { 1951 description 1952 "This grouping describes the conditions under which an 1953 update will be sent as part of an update stream."; 1954 choice update-trigger { 1955 description 1956 "Defines necessary conditions for sending an event to 1957 the subscriber."; 1958 case periodic { 1959 description 1960 "The agent is requested to notify periodically the 1961 current values of the datastore or the subset 1962 defined by the filter."; 1963 leaf period { 1964 type yang:timeticks; 1965 mandatory true; 1966 description 1967 "Duraton of time which should occur between periodic 1968 push updates. Where the anchor of a start-time is 1969 available, the push will include the objects and their 1970 values which exist at an exact multiple of timeticks 1971 aligning to this start-time anchor."; 1972 } 1973 } 1974 case on-change { 1975 if-feature "on-change"; 1976 description 1977 "The agent is requested to notify changes in 1978 values in the datastore or a subset of it defined 1979 by a filter."; 1981 leaf no-synch-on-start { 1982 type empty; 1983 description 1984 "This leaf acts as a flag that determines behavior at the 1985 start of the subscription. When present, 1986 synchronization of state at the beginning of the 1987 subscription is outside the scope of the subscription. 1988 Only updates about changes that are observed from the 1989 start time, i.e. only push-change-update notifications 1990 are sent. 1991 When absent (default behavior), in order to facilitate 1992 a receiver's synchronization, a full update is sent 1993 when the subscription starts using a push-update 1994 notification, just like in the case of a periodic 1995 subscription. After that, push-change-update 1996 notifications are sent."; 1997 } 1998 leaf dampening-period { 1999 type yang:timeticks; 2000 mandatory true; 2001 description 2002 "Minimum amount of time that needs to have 2003 passed since the last time an update was 2004 provided."; 2005 } 2006 leaf-list excluded-change { 2007 type change-type; 2008 description 2009 "Use to restrict which changes trigger an update. 2010 For example, if modify is excluded, only creation and 2011 deletion of objects is reported."; 2012 } 2013 } 2014 } 2015 } 2017 grouping subscription-info { 2018 description 2019 "This grouping describes basic information concerning a 2020 subscription."; 2021 leaf stream { 2022 type update-stream; 2023 description 2024 "The stream being subscribed to."; 2025 } 2026 leaf encoding { 2027 type encoding; 2028 default "encode-xml"; 2029 description 2030 "The type of encoding for the subscribed data. 2031 Default is XML"; 2032 } 2033 leaf subscription-start-time { 2034 type yang:date-and-time; 2035 description 2036 "Designates the time at which a subscription is supposed 2037 to start, or immediately, in case the start-time is in 2038 the past. For periodic subscription, the start time also 2039 serves as anchor time from which the time of the next 2040 update is computed. The next update will take place at the 2041 next period interval from the anchor time. 2042 For example, for an anchor time at the top of a minute 2043 and a period interval of a minute, the next update will 2044 be sent at the top of the next minute."; 2045 } 2046 leaf subscription-stop-time { 2047 type yang:date-and-time; 2048 description 2049 "Designates the time at which a subscription will end. 2050 When a subscription reaches its stop time, it will be 2051 automatically deleted. No final push is required unless there 2052 is exact alignment with the end of a periodic subscription 2053 period."; 2054 } 2055 choice filterspec { 2056 description 2057 "The filter to be applied to the stream as part of the 2058 subscription. The filter defines which updates of the 2059 data stream are of interest to a subscriber. 2060 The filter can be specified in-line 2061 or configured separately and referenced here. 2062 If no filter is specified, the entire datatree 2063 is of interest."; 2064 case inline { 2065 description 2066 "Filter is defined as part of the subscription."; 2067 uses datatree-filter; 2068 } 2069 case by-reference { 2070 description 2071 "Incorporate a filter that has been configured 2072 separately."; 2073 leaf filter-ref { 2074 type filter-ref; 2075 description 2076 "References filter which is associated with the 2077 subscription."; 2078 } 2079 } 2080 } 2081 } 2083 grouping push-source-info { 2084 description 2085 "Defines the sender source from which push updates 2086 for a configured subscription are pushed."; 2087 choice push-source { 2088 description 2089 "Identifies the egress interface on the Publisher from 2090 which pushed updates will or are being sent."; 2091 case interface-originated { 2092 description 2093 "When the push source is out of an interface on the 2094 Publisher established via static configuration."; 2095 leaf source-interface { 2096 type if:interface-ref; 2097 description 2098 "References the interface for pushed updates."; 2099 } 2100 } 2101 case address-originated { 2102 description 2103 "When the push source is out of an IP address on the 2104 Publisher established via static configuration."; 2105 leaf source-vrf { 2106 type uint32 { 2107 range "16..1048574"; 2108 } 2109 description 2110 "Label of the vrf."; 2111 } 2112 leaf source-address { 2113 type inet:ip-address-no-zone; 2114 mandatory true; 2115 description 2116 "The source address for the pushed objects."; 2117 } 2118 } 2119 } 2120 } 2122 grouping receiver-info { 2123 description 2124 "Defines where and how to deliver push updates for a 2125 configured subscription. This includes 2126 specifying the receiver, as well as defining 2127 any network and transport aspects when pushing of 2128 updates occurs outside of Netconf or Restconf."; 2129 list receiver { 2130 key "address"; 2131 description 2132 "A single host or multipoint address intended as a target 2133 for the pushed updates for a subscription."; 2134 leaf address { 2135 type inet:host; 2136 description 2137 "Specifies the address for the traffic to reach a 2138 remote host. One of the following must be 2139 specified: an ipv4 address, an ipv6 address, 2140 or a host name."; 2141 } 2142 leaf port { 2143 type inet:port-number; 2144 description 2145 "This leaf specifies the port number to use for messages 2146 destined for a receiver."; 2147 } 2148 leaf protocol { 2149 type transport-protocol; 2150 default "netconf"; 2151 description 2152 "This leaf specifies the transport protocol used 2153 to deliver messages destined for the receiver."; 2154 } 2155 } 2156 } 2158 rpc create-subscription { 2159 description 2160 "This RPC allows a subscriber to create a subscription 2161 on its own behalf. If successful, the subscription 2162 remains in effect for the duration of the subscriber's 2163 association with the publisher, or until the subscription 2164 is terminated by virtue of a delete-subscription request. 2165 In case an error (as indicated by subscription-result) 2166 is returned, the subscription is 2167 not created. In that case, the RPC output 2168 MAY include suggested parameter settings 2169 that would have a high likelihood of succeeding in a 2170 subsequent create-subscription request."; 2171 input { 2172 uses subscription-info; 2173 uses update-policy; 2174 } 2175 output { 2176 leaf subscription-result { 2177 type subscription-result; 2178 mandatory true; 2179 description 2180 "Indicates whether subscription is operational, 2181 or if a problem was encountered."; 2182 } 2183 choice result { 2184 description 2185 "Depending on the subscription result, different 2186 data is returned."; 2187 case success { 2188 description 2189 "This case is used when the subscription request 2190 was successful and a subscription was created as 2191 a result"; 2192 leaf subscription-id { 2193 type subscription-id; 2194 mandatory true; 2195 description 2196 "Identifier used for this subscription."; 2197 } 2198 } 2199 case no-success { 2200 description 2201 "This case applies when a subscription request 2202 was not successful and no subscription was 2203 created as a result. In this case, 2204 information MAY be returned that indicates 2205 suggested parameter settings that would have a 2206 high likelihood of succeeding in a subsequent 2207 create-subscription request."; 2208 uses subscription-info; 2209 uses update-policy; 2210 } 2211 } 2212 } 2213 } 2214 rpc modify-subscription { 2215 description 2216 "This RPC allows a subscriber to modify a subscription 2217 that was previously created using create-subscription. 2218 If successful, the subscription 2219 remains in effect for the duration of the subscriber's 2220 association with the publisher, or until the subscription 2221 is terminated by virtue of a delete-subscription request. 2222 In case an error is returned (as indicated by 2223 subscription-result), the subscription is 2224 not modified and the original subscription parameters 2225 remain in effect. In that case, the rpc error response 2226 MAY include suggested parameter settings 2227 that would have a high likelihood of succeeding in a 2228 subsequent modify-subscription request."; 2229 input { 2230 leaf subscription-id { 2231 type subscription-id; 2232 description 2233 "Identifier to use for this subscription."; 2234 } 2235 } 2236 output { 2237 leaf subscription-result { 2238 type subscription-result; 2239 mandatory true; 2240 description 2241 "Indicates whether subscription was modified 2242 or if a problem was encountered. 2243 In case the subscription-result has a value 2244 other than OK, the original subscription was not 2245 changed."; 2246 } 2247 uses subscription-info; 2248 uses update-policy; 2249 } 2250 } 2251 rpc delete-subscription { 2252 description 2253 "This RPC allows a subscriber to delete a subscription that 2254 was previously created using create-subscription."; 2255 input { 2256 leaf subscription-id { 2257 type subscription-id; 2258 description 2259 "Identifier of the subscription that is to be deleted. 2260 Only subscriptions that were created using 2261 create-subscription can be deleted via this RPC."; 2262 } 2263 } 2264 } 2265 notification push-update { 2266 description 2267 "This notification contains a periodic push update. 2268 This notification shall only be sent to receivers 2269 of a subscription; it does not constitute a general-purpose 2270 notification."; 2271 leaf subscription-id { 2272 type subscription-id; 2273 mandatory true; 2274 description 2275 "This references the subscription because of which the 2276 notification is sent."; 2277 } 2278 leaf time-of-update { 2279 type yang:date-and-time; 2280 description 2281 "This leaf contains the time of the update."; 2282 } 2283 choice encoding { 2284 description 2285 "Distinguish between the proper encoding that was specified 2286 for the subscription"; 2287 case encode-xml { 2288 description 2289 "XML encoding"; 2290 leaf datastore-contents-xml { 2291 type datastore-contents-xml; 2292 description 2293 "This contains data encoded in XML, 2294 per the subscription."; 2295 } 2296 } 2297 case encode-json { 2298 if-feature "json"; 2299 description 2300 "JSON encoding"; 2301 leaf datastore-contents-json { 2302 type datastore-contents-json; 2303 description 2304 "This leaf contains data encoded in JSON, 2305 per the subscription."; 2306 } 2307 } 2308 } 2309 } 2310 notification push-change-update { 2311 if-feature "on-change"; 2312 description 2313 "This notification contains an on-change push update. 2314 This notification shall only be sent to the receivers 2315 of a subscription; it does not constitute a general-purpose 2316 notification."; 2318 leaf subscription-id { 2319 type subscription-id; 2320 mandatory true; 2321 description 2322 "This references the subscription because of which the 2323 notification is sent."; 2324 } 2325 leaf time-of-update { 2326 type yang:date-and-time; 2327 description 2328 "This leaf contains the time of the update, i.e. the 2329 time at which the change was observed."; 2330 } 2331 choice encoding { 2332 description 2333 "Distinguish between the proper encoding that was specified 2334 for the subscription"; 2335 case encode-xml { 2336 description 2337 "XML encoding"; 2338 leaf datastore-changes-xml { 2339 type datastore-changes-xml; 2340 description 2341 "This contains datastore contents that has changed 2342 since the previous update, per the terms of the 2343 subscription. Changes are encoded analogous to 2344 the syntax of a corresponding Netconf edit-config 2345 operation."; 2346 } 2347 } 2348 case encode-json { 2349 if-feature "json"; 2350 description 2351 "JSON encoding"; 2352 leaf datastore-changes-yang { 2353 type datastore-changes-json; 2354 description 2355 "This contains datastore contents that has changed 2356 since the previous update, per the terms of the 2357 subscription. Changes are encoded analogous 2358 to the syntax of a corresponding RESTCONF yang-patch 2359 operation."; 2360 } 2361 } 2362 } 2363 } 2364 notification subscription-started { 2365 description 2366 "This notification indicates that a subscription has 2367 started and data updates are beginning to be sent. 2368 This notification shall only be sent to receivers 2369 of a subscription; it does not constitute a general-purpose 2370 notification."; 2371 leaf subscription-id { 2372 type subscription-id; 2373 mandatory true; 2374 description 2375 "This references the affected subscription."; 2376 } 2377 uses subscription-info; 2378 uses update-policy; 2379 } 2380 notification subscription-suspended { 2381 description 2382 "This notification indicates that a suspension of the 2383 subscription by the server has occurred. No further 2384 datastore updates will be sent until subscription 2385 resumes. 2386 This notification shall only be sent to receivers 2387 of a subscription; it does not constitute a general-purpose 2388 notification."; 2389 leaf subscription-id { 2390 type subscription-id; 2391 mandatory true; 2392 description 2393 "This references the affected subscription."; 2394 } 2395 leaf reason { 2396 type subscription-susp-reason; 2397 description 2398 "Provides a reason for why the subscription was 2399 suspended."; 2400 } 2401 } 2402 notification subscription-resumed { 2403 description 2404 "This notification indicates that a subscription that had 2405 previously been suspended has resumed. Datastore updates 2406 will once again be sent."; 2407 leaf subscription-id { 2408 type subscription-id; 2409 mandatory true; 2410 description 2411 "This references the affected subscription."; 2412 } 2413 } 2414 notification subscription-modified { 2415 description 2416 "This notification indicates that a subscription has 2417 been modified. Datastore updates sent from this point 2418 on will conform to the modified terms of the 2419 subscription."; 2420 leaf subscription-id { 2421 type subscription-id; 2422 mandatory true; 2423 description 2424 "This references the affected subscription."; 2425 } 2426 uses subscription-info; 2427 uses update-policy; 2428 } 2429 notification subscription-terminated { 2430 description 2431 "This notification indicates that a subscription has been 2432 terminated."; 2433 leaf subscription-id { 2434 type subscription-id; 2435 mandatory true; 2436 description 2437 "This references the affected subscription."; 2438 } 2439 leaf reason { 2440 type subscription-term-reason; 2441 description 2442 "Provides a reason for why the subscription was 2443 terminated."; 2444 } 2445 } 2446 container update-streams { 2447 config false; 2448 description 2449 "This container contains a leaf list of built-in 2450 streams that are provided by the system."; 2451 leaf-list update-stream { 2452 type update-stream; 2453 description 2454 "Identifies a built-in stream that is supported by the 2455 system. Streams are associated with their own identities, 2456 each of which carries a special semantics."; 2457 } 2458 } 2459 container filters { 2460 description 2461 "This container contains a list of configurable filters 2462 that can be applied to subscriptions. This facilitates 2463 the reuse of complex filters once defined."; 2464 list filter { 2465 key "filter-id"; 2466 description 2467 "A list of configurable filters that can be applied to 2468 subscriptions."; 2469 leaf filter-id { 2470 type filter-id; 2471 description 2472 "An identifier to differentiate between filters."; 2473 } 2474 uses datatree-filter; 2475 } 2476 } 2477 container subscription-config { 2478 if-feature "configured-subscriptions"; 2479 description 2480 "Contains the list of subscriptions that are configured, 2481 as opposed to established via RPC or other means."; 2482 list yang-push-subscription { 2483 key "subscription-id"; 2484 description 2485 "Content of a yang-push subscription."; 2486 leaf subscription-id { 2487 type subscription-id; 2488 description 2489 "Identifier to use for this subscription."; 2490 } 2491 uses subscription-info; 2492 uses update-policy; 2493 uses receiver-info; 2494 uses push-source-info; 2495 } 2496 } 2497 container subscriptions { 2498 config false; 2499 description 2500 "Contains the list of currently active subscriptions, 2501 i.e. subscriptions that are currently in effect, 2502 used for subscription management and monitoring purposes. 2503 This includes subscriptions that have been setup via RPC 2504 primitives, e.g. create-subscription, delete-subscription, 2505 and modify-subscription, as well as subscriptions that 2506 have been established via configuration."; 2507 list yang-push-subscription { 2508 key "subscription-id"; 2509 config false; 2510 description 2511 "Content of a yang-push subscription. 2512 Subscriptions can be created using a control channel 2513 or RPC, or be established through configuration."; 2514 leaf subscription-id { 2515 type subscription-id; 2516 description 2517 "Identifier of this subscription."; 2518 } 2519 leaf configured-subscription { 2520 if-feature "configured-subscriptions"; 2521 type empty; 2522 description 2523 "The presence of this leaf indicates that the 2524 subscription originated from configuration, not through 2525 a control channel or RPC."; 2526 } 2527 leaf subscription-status { 2528 type identityref { 2529 base subscription-stream-status; 2530 } 2531 description 2532 "The status of the subscription."; 2533 } 2534 uses subscription-info; 2535 uses update-policy; 2536 uses receiver-info; 2537 uses push-source-info; 2538 } 2539 } 2540 } 2542 2544 6. Security Considerations 2546 Subscriptions could be used to attempt to overload servers of YANG 2547 datastores. For this reason, it is important that the server has the 2548 ability to decline a subscription request if it would deplete its 2549 resources. In addition, a server needs to be able to suspend an 2550 existing subscription when needed. When this occur, the subscription 2551 status is updated accordingly and the clients are notified. 2552 Likewise, requests for subscriptions need to be properly authorized. 2554 A subscription could be used to retrieve data in subtrees that a 2555 client has not authorized access to. Therefore it is important that 2556 data pushed based on subscriptions is authorized in the same way that 2557 regular data retrieval operations are. Data being pushed to a client 2558 needs therefore to be filtered accordingly, just like if the data 2559 were being retrieved on-demand. The Netconf Authorization Control 2560 Model applies. 2562 A subscription could be configured on another receiver's behalf, with 2563 the goal of flooding that receiver with updates. One or more 2564 publishers could be used to overwhelm a receiver which doesn't even 2565 support subscriptions. Clients which do not want pushed data need 2566 only terminate or refuse any transport sessions from the publisher. 2567 In addition, the Netconf Authorization Control Model SHOULD be used 2568 to control and restrict authorization of subscription configuration. 2570 7. References 2572 7.1. Normative References 2574 [RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin, 2575 "Simple Network Management Protocol (SNMP)", RFC 1157, 2576 DOI 10.17487/RFC1157, May 1990, 2577 . 2579 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2580 Notifications", RFC 5277, July 2008. 2582 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2583 the Network Configuration Protocol (NETCONF)", RFC 6020, 2584 DOI 10.17487/RFC6020, October 2010, 2585 . 2587 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2588 and A. Bierman, Ed., "Network Configuration Protocol 2589 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2590 . 2592 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2593 Base Notifications", RFC 5277, February 2012. 2595 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2596 Protocol (NETCONF) Access Control Model", RFC 6536, 2597 DOI 10.17487/RFC6536, March 2012, 2598 . 2600 7.2. Informative References 2602 [I-D.clemm-netmod-mount] 2603 Clemm, A., Medved, J., and E. Voit, "Mounting YANG-defined 2604 information from remote datastores", draft-clemm-netmod- 2605 mount-03 (work in progress), April 2015. 2607 [I-D.i2rs-pub-sub-requirements] 2608 Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2609 for Subscription to YANG Datastores", draft-ietf-i2rs-pub- 2610 sub-requirements-05 (work in progress), February 2016. 2612 [I-D.ietf-netconf-restconf] 2613 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2614 Protocol", I-D draft-ietf-netconf-restconf-09, December 2615 2015. 2617 [I-D.ietf-netconf-yang-patch] 2618 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2619 Media Type", draft-ietf-netconf-yang-patch-07 (work in 2620 progress), December 2015. 2622 [I-D.ietf-netmod-yang-json] 2623 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2624 draft-ietf-netmod-yang-json-07 (work in progress), January 2625 2016. 2627 [I-D.voit-netmod-peer-mount-requirements] 2628 Voit, E., Clemm, A., and S. Mertens, "Requirements for 2629 Peer Mounting of YANG subtrees from Remote Datastores", 2630 draft-voit-netmod-peer-mount-requirements-03 (work in 2631 progress), September 2015. 2633 Authors' Addresses 2635 Alexander Clemm 2636 Cisco Systems 2638 EMail: alex@cisco.com 2640 Alberto Gonzalez Prieto 2641 Cisco Systems 2643 EMail: albertgo@cisco.com 2645 Eric Voit 2646 Cisco Systems 2648 EMail: evoit@cisco.com 2649 Ambika Prasad Tripathy 2650 Cisco Systems 2652 EMail: ambtripa@cisco.com 2654 Einar Nilsen-Nygaard 2655 Cisco Systems 2657 EMail: einarnn@cisco.com