idnits 2.17.1 draft-clemm-netconf-yang-push-00.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 2 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 342: '... the server SHOULD include in the re...' RFC 2119 keyword, line 469: '...e push, a server MUST support the inte...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 605 has weird spacing: '...-period yan...' == Line 872 has weird spacing: '...n event to...' == Line 902 has weird spacing: '...n event to th...' == 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 (March 9, 2015) is 3329 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-5277' is mentioned on line 277, but not defined == Missing Reference: 'RFC 5277' is mentioned on line 316, 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) Summary: 5 errors (**), 0 flaws (~~), 7 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: September 10, 2015 Cisco Systems 6 March 9, 2015 8 Subscribing to YANG datastore push updates 9 draft-clemm-netconf-yang-push-00.txt 11 Abstract 13 This document defines a subscription and push mechanism for YANG 14 datastores. This mechanism allows client applications to request 15 updates from a YANG datastore, which are then pushed by the server to 16 the client per a subscription policy, without requiring additional 17 client requests. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on September 10, 2015. 36 Copyright Notice 38 Copyright (c) 2015 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 This document may contain material from IETF Documents or IETF 52 Contributions published or made publicly available before November 53 10, 2008. The person(s) controlling the copyright in some of this 54 material may not have granted the IETF Trust the right to allow 55 modifications of such material outside the IETF Standards Process. 56 Without obtaining an adequate license from the person(s) controlling 57 the copyright in such materials, this document may not be modified 58 outside the IETF Standards Process, and derivative works of it may 59 not be created outside the IETF Standards Process, except to format 60 it for publication as an RFC or to translate it into languages other 61 than English. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 66 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 5 67 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 6 68 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 6 69 3.2. Negotiation of Subscription Policies . . . . . . . . . . 8 70 3.3. Custom Datastreams . . . . . . . . . . . . . . . . . . . 8 71 3.4. Push Data Stream and Transport Mapping . . . . . . . . . 9 72 3.5. Subscription operations . . . . . . . . . . . . . . . . . 10 73 3.6. A YANG data model for management of datastore push 74 subscriptions . . . . . . . . . . . . . . . . . . . . . . 13 75 3.7. Other considerations . . . . . . . . . . . . . . . . . . 15 76 3.7.1. Authorization . . . . . . . . . . . . . . . . . . . . 15 77 3.7.2. Additional subscription primitives . . . . . . . . . 15 78 3.7.3. Robustness and reliability considerations . . . . . . 16 79 3.7.4. Implementation considerations . . . . . . . . . . . . 16 80 4. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 16 81 5. Security Considerations . . . . . . . . . . . . . . . . . . . 24 82 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 83 6.1. Normative References . . . . . . . . . . . . . . . . . . 24 84 6.2. Informative References . . . . . . . . . . . . . . . . . 25 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 87 1. Introduction 89 YANG [RFC6020] was originally designed for the Netconf protocol 90 [RFC6241], which originally put most emphasis on configuration. 91 However, YANG is not restricted to configuration data. YANG 92 datastores, i.e. datastores that contain data modeled according using 93 YANG , can contain configuration as well as contain operational data. 94 It is therefore reasonable to expect that data in YANG datastores 95 will increasingly be used to support applications that are not 96 focused on managing configurations but that are, for example, related 97 to service assurance. 99 Service assurance applications typically involve monitoring 100 operational state of networks and devices; of particular interest are 101 changes that this data undergoes over time. Likewise, there are 102 applications in which data and objects from one datastore need to be 103 made available both to applications in other systems and to remote 104 datastores [peermount-req][peermount]. This requires mechanisms that 105 allow remote systems to become quickly aware of any updates to allow 106 to validate and maintain cross-network integrity and consistency. 108 Traditional approaches rely heavily on polling, in which data is 109 periodically explicitly retrieved by a client from a server to stay 110 up-to-date. 112 There are various issues associated with polling-based management: 114 o It introduces additional load on network and devices. Each 115 polling cycle requires a separate yet arguably redundant request 116 that results in an interrupt, requires parsing, consumes 117 bandwidth. 119 o It lacks robustness. Polling cycles may be missed, requests may 120 be delayed or get lost, often particularly in cases when the 121 network is under stress and hence exactly when the need for the 122 data is the greatest. 124 o Data may be difficult to calibrate and compare. Polling requests 125 may undergo slight fluctuations, resulting in intervals of 126 different lengths which makes data hard to compare. Likewise, 127 pollers may have difficulty issuing requests that reach all 128 devices at the same time, resulting in offset polling intervals 129 which again make data hard to compare. 131 More effective is an alternative in which an application can request 132 to be automatically updated of current content of the datastore (such 133 as a subtree, or data in a subtree that meets a certain filter 134 condition), and in which the server that maintains the datastore 135 subsequently pushes those updates. However, such a solution does not 136 currently exist. 138 The need to perform polling-based management is typically considered 139 an important shortcoming of management applications that rely on MIBs 140 polled using SNMP [RFC1157]. However, without a provision to support 141 a push-based alternative, there is no reason to believe that 142 management applications that operate on YANG datastores using 143 protocols such as NETCONF [RFC6241] or RESTconf [restconf] will be 144 any more effective, as they would follow the same request/response 145 pattern. 147 While YANG allows the definition of notifications, such notifications 148 are generally intended to indicate the occurrence of certain well- 149 specified event conditions, such as a the onset of an alarm condition 150 or the occurrence of an error. A capability to subscribe to and 151 deliver event notifications has been defined in [RFC5277]. In 152 addition, configuration change notifications have been defined in 153 [RFC6470]. These change notifications pertain only to configuration 154 information, not to operational state, and convey the root of the 155 subtree to which changes were applied along with the edits, but not 156 the modified data nodes and their values. 158 Accordingly, there is a need for a service that allows client 159 applications to subscribe to updates of a YANG datastore and that 160 allows the server to push those updates. The requirements for such a 161 service are documented in [pub-sub-reqs]. This document proposes a 162 solution that addresses those requirements. The solution features 163 the following: 165 o A mechanism that allows clients to subscribe to automatic 166 datastore updates, and the means to manage those subscription. 167 The subscription allows clients to specify which data they are 168 interested in, and to provide optional filters with criteria that 169 data must meet for updates to be sent. Furthemore, subscription 170 can specify a policy that directs when updates are provided. For 171 example, a client may request to be updated periodically in 172 certain intervals, or whenever data changes occur. 174 o The ability to negotiate subscription parameters. Because not 175 every server may support every requested interval for every piece 176 of data, it is necessary for a server to be able to indicate 177 whether or not it is capable of supporting a requested 178 subscription, and possibly allow to negotiate subscription 179 parameters. 181 o A mechanism is to communicate the updates themselves. For this, 182 the proposal leverages and extends existing YANG/Netconf/Restconf 183 mechanisms, defining special notifications that carry updates. 185 This document specifies a YANG data model to manage subscriptions to 186 data in YANG datastores, and to configure associated filters and data 187 streams. It defines extensions to RPCs defined in [RFC5277] that 188 allow to extend notification subscriptions to subscriptions for 189 datastore updates. It also defines a notification that can be used 190 to carry data updates and thus serve as push mechanism. 192 2. Definitions and Acronyms 194 Data node: An instance of management information in a YANG datastore. 196 Data record: A record containing a set of one or more data node 197 instances and their associated values. 199 Datastore: A conceptual store of instantiated management information, 200 with individual data items represented by data nodes which are 201 arranged in hierarchical manner. 203 Datastream: A continuous stream of data records, each including a set 204 of updates, i.e. data node instances and their associated values. 206 Data subtree: An instantiated data node and the data nodes that are 207 hierarchically contained within it. 209 NACM: NETCONF Access Control Model 211 NETCONF: Network Configuration Protocol 213 Push-update stream: A conceptual data stream of a datastore that 214 streams the entire datastore contents continuously and perpetually. 216 RPC: Remote Procedure Call 218 SNMP: Simple Network Management Protocol 220 Subscription: A contract between a client ("subscriber") and a server 221 ("publisher"), stipulating which information the client wishes to 222 receive from the server (and which information the server has to 223 provide to the client) without the need for further solicitation. 225 Subscription filter: A filter that contains evaluation criteria which 226 are evaluated against YANG objects of a subscription. An update is 227 only published if the object meets the specified filter criteria. 229 Subscription policy: A policy that specifies under what circumstances 230 to push an update, e.g. whether updates are to be provided 231 periodically or only whenever changes occur. 233 Update: A data item containing the current value of a data node. 235 Update trigger: A trigger, as specified by a subscription policy, 236 that causes an update to be sent, respectively a data record to be 237 generated. An example of a trigger is a change trigger, invoked when 238 the value of a data node changes or a data node is created or 239 deleted, or a time trigger, invoked after the laps of a periodic time 240 interval. 242 URI: Uniform Resource Identifier 244 YANG: A data definition language for NETCONF 246 3. Solution Overview 248 This document specifies a solution that allows clients to subscribe 249 to information updates in a YANG datastore, which are subsequently 250 pushed from the server to the client. 252 Subscriptions are initiated by clients. Servers respond to a 253 subscription request explicitly positively or negatively. Negative 254 responses include information about why the subscription was not 255 accepted, in order to facilitate converging on an accepable set of 256 subscription parameters. Once a subscription has been established, 257 datastore push updates are pushed from the server to the subscribing 258 client until the subscription ends. 260 Accordingly, the solution encompasses several components: 262 o The subscription model for configuration and management of the 263 subscriptions, with a set of associated services. 265 o The ability to negotiate subscription parameters, in cases where a 266 subscription desired by a client cannot currently be served. 268 o The stream of datastore push updates. 270 In addition, there are a number of additional considerations, such as 271 the tie-in of the mechanisms with security mechanisms. Each of those 272 aspects will be discussed in the following subsections. 274 3.1. Subscription Model 276 Yang-push subscriptions are defined using a data model. This model 277 is based on the subscriptions defined in [RFC-5277], which is also 278 reused in RESTconf. The model is extended with several parameters, 279 including a subscription type and a subscription ID. 281 A subscription refers to a datastream. The subscription model 282 assumes the presence of a conceptual perpetual datastream "push- 283 update" of continuous datastore updates of infinite time resolution. 284 A subscription refers to this datastream and specifies filters that 285 are to be applied to, it for example, to provide only those subsets 286 of the information that match a filter criteria. In addition, a 287 subscription specifies a subscription policy that defines the trigger 288 when data records should be sent, for example at periodic intervals 289 or whenever underlying data items change. 291 The complete set of subscription parameters is as follows: 293 o The name of the stream to subscribe to. The subscription model 294 always assumes the presence of a perpetual and continuous stream 295 of updates. The stream is called "push-update". However, as 296 mentioned, it is possible to subscribe to other datastreams, such 297 as custom datastreams which are separately configured. 299 o Optional filter(s), describing the subset of data items in the 300 stream's data records that are of interest to the subscriber. The 301 server should only send to the subscriber the data items that 302 match the filter(s), when present. The absence of a filter 303 indicates that all data items from the stream are of interest to 304 the subscriber and all data records must be sent in their entirety 305 to the subscriber. Two filtering mechanisms are provided: subtree 306 filtering and Xpath filtering, with the semantics described in 307 [RFC 5277 Section 3.6]. (Additional filter types can be added 308 through extensions.) 310 o An identifier for the subscription. 312 o An optional start time. Used to trigger replays starting at the 313 provided time. Its semantics are those in [RFC 5277]. 315 o An optional stop time. Used to limit temporarily the events of 316 interest. Its semantics are those in [RFC 5277]. 318 o For subscriptions to "push-update", a subscription policy 319 definition regarding the update trigger to send new updates. The 320 trigger can be periodic or based on change. For periodic 321 subscriptions, the trigger is defines by the interval with which 322 to push updates. For on-change subscriptions, the trigger is 323 defined using the dampening interval with which to push repeated 324 changes, an indicator for the magnitude of changes, etc. 326 It is conceivable that additional subscription parameters might be 327 added in the future. For example, a parameter might be introduced 328 that allows to specify which encoding method for updates to use. The 329 list could accordingly be extended and augmented in the future. 331 3.2. Negotiation of Subscription Policies 333 A subscription rejection can be caused by the inability of the server 334 to provide a stream with the requested semantics. Providing "on- 335 change" updates for operational data can be computationally expensive 336 and an agent may decide not to support them or supporting them for a 337 small number of subscribers or for a limited set of data nodes. 339 Yang-push supports a simple negotiation between clients and servers 340 for subscription parameters. The negotiation is limited to a single 341 pair of subscription request and response. For negative responses, 342 the server SHOULD include in the returned error what subscription 343 parameters would have been accepted for the request. The returned 344 acceptable parameters are no guarantee for subsequent requests for 345 this client or others. 347 3.3. Custom Datastreams 349 Optionally, it is possible to introduce other datastreams (beyond the 350 datastore-push datastream) with custom semantics. Some datastreams 351 can be custom configured. The support of this is tied to a separate 352 feature. The configuration of a custom datastream specifies the 353 trigger conditions under which new data records for the stream are 354 generated, and which updates the corresponding data records contain. 355 For example, the configuration of a datastream can specify which 356 subsets of data nodes in a datastore the datastream should contain, 357 which filter criteria the updates need to meet, and under what 358 conditions to create updates - for example, periodically or whenever 359 a data item changes. 361 A subscription that refers to a custom datastream can specify a set 362 of filters, like for the "push-update" datastream. However, the 363 policy as to when updates are triggered (periodically or on change) 364 needs to be the same as the policy of the datastream and cannot be 365 modified. It is not possible, for example, to define a custom 366 datastream which creates on-change updates, yet subscribe to that 367 datastream with periodic updates. 369 While conceptually similar, the choice between subscribing to 370 datastream "push-update" or configuring and subscribing to a custom 371 datastream can be thought of as analogous to the choice between 372 operating a nozzle that is connected to a hose, or controlling the 373 faucet (custom datastream). Operating the nozzle is for most uses 374 simpler; however, the option to operate the faucet instead can 375 provide additional flexibility in some scenarios. 377 3.4. Push Data Stream and Transport Mapping 379 Pushing data based on a subscription could be considered analogous to 380 a response to a data retrieval request, e.g. a "get" request. 381 However, contrary to such a request, multiple responses to the same 382 request may get sent over a longer period of time. 384 A more suitable mechanism is therefore that of a notification. 385 Contrary to notifications associated with alarms and unexpected event 386 occurrences, push updates are solicited, i.e. tied tied to a 387 particular subscription which triggered the notification. (An 388 alternative conceptual model would consider a subscription an "opt- 389 in" filter on a continuous stream of updates.) 391 The notification contains several parameters: 393 o A subscription correlator, referencing the name of the 394 subscription on whose behalf the notification is sent. 396 o A data node that contains a representation of the datastore 397 subtree containing the updates. The subtree is filtered per 398 access control rules to contain only data that the subscriber is 399 authorized to see. Also, depending on the subscription type, 400 i.e., specifically for on-change subscriptions, the subtree 401 contains only the data nodes that contain actual changes. (This 402 can be simply a node of type string or, for XML-based encoding, 403 anyxml.) 405 Notifications are sent using elements as defined in 406 [RFC5277]. Alternative transports are conceivable but outside the 407 scope of this specification. 409 The solution specified in this document uses notifications to 410 communicate datastore updates. The contents of the notification 411 includes a set of explicitly defined data nodes. For this purpose, a 412 new generic notification is introduced, "push-update" notification. 413 This notification is used to carry a data record with updates of 414 datastore contents as specified by a subscription. 416 The update record consists of a data snippet that contains an 417 instantiated datastore subtree with the subscribed contents. Data 418 nodes that do not match filter criteria are removed. Likewise, in 419 the case of a subscription with "on-change" subscription policy, data 420 nodes that have not undergone change are omitted. The contents of 421 the update record is equivalent to the contents that would be 422 obtained had the same data been explicitly retrieved using e.g. a 423 Netconf "get"-operation, with the same filters applied. 425 The contents of the notification conceptually represents the union of 426 all data nodes in the yang modules supported by the server, excluding 427 the following statements: "mandatory", "must", "min-elements", "max- 428 elements", "when", and "default". However, in a YANG data model, it 429 is not practical to model the precise data contained in the updates 430 as part of the notification, because the specific data nodes 431 supported depends on the implementing system and may even vary 432 dynamically. Therefore, to capture this data, a single parameter 433 that can represent any datastore contents is used, not parameters 434 that represent data nodes one at a time. 436 The following is an example of push notification. It contains an 437 update for subscription my-sub, including a subtree with root foo 438 that contains a leaf, bar: 440 441 442 444 my-sub 445 446 2015-03-09T19:14:56Z 447 449 450 some_string 451 452 453 455 Figure 1: Push example 457 3.5. Subscription operations 459 There are several operations associated with subscriptions. At the 460 most basic level, clients need to be able to create subscriptions, as 461 well as delete subscriptions when they are no longer needed. 463 RFC 5277 specifies an operation to create subscriptions for event 464 streams, . This operation is leveraged and 465 extended to create datastore-push subscriptions. Specifically, an 466 additional parameter is added to allow for the specification of 467 trigger policy. 469 To support datastore push, a server MUST support the interleave 470 capability specified in [RFC5277]. This is required to allow for 471 modification of what data is being subscribed to without needing to 472 establish a separate Netconf session. 474 The example below illustrates a subscription for a periodic push of 475 all data under a container called foo. 477 479 481 push-update 482 484 my-sub 485 486 489 490 500 491 492 493 495 Figure 2: Subscription example 497 The example below illustrates a subscription response, where an agent 498 does not support frequent periodic updates, and suggests a different 499 sampling rate to the client. 501 502 503 application 504 operation-not-supported 505 error 506 507 509 3000 510 511 512 513 515 Figure 3: Subscription negotiation example 517 RFC 5277 does not specify operations to delete subscriptions. 518 Instead, it assumes that an event subscription is associated with its 519 own Netconf session. When the session is torn down, the subscription 520 is implicitly deleted. Likewise, there is no operation to modify a 521 subscription. Modifying a subscription requires tearing down a 522 Netconf session, starting a new one, and creating a new subscription. 523 Furthermore, each session only supports a single subscription. 524 Establishing multiple subscriptions requires multiple concurrent 525 Netconf sessions. 527 To facilitate datastore-push subscriptions, an additional RPC is 528 introduced, . 530 The operation takes as parameter a subscription 531 ID. As a result of the operation, the subscription is removed and no 532 more data records will be sent. 534 536 538 540 my-sub 541 542 543 545 Figure 4: Subscription deletion 547 Finally, a separate operation to modify a subscription is introduced, 548 . This operation takes the same parameters as 549 , but refers to an existing subscription. Of 550 course, a subscription could also be deleted and another be created. 551 However, modify operation avoids issues regarding the synchronization 552 of creation and deletion operations, such as potential loss or 553 duplication of updates. Also, a modify operation allows to simply 554 extend an existing subscription beyond the initial subscription end 555 time. 557 559 561 push-update 562 564 my-sub 565 566 569 571 3000 572 573 574 576 Figure 5: Modify subscription 578 3.6. A YANG data model for management of datastore push subscriptions 580 Subscriptions as well as datastreams can be subjected to management 581 themselves. For example, it is possible that a server may no longer 582 be able to serve a subscription that it had previously accepted. 583 Perhaps it has run out of resources, or internal errors may have 584 occurred. When this is the case, a server needs to be able to 585 temporarily suspend the subscription, or even to terminate it. More 586 generally, the server should provide a means by which the status of 587 subscriptions can be monitored. When custom datastreams are 588 supported, those datastreams need to be configured and monitored as 589 well. 591 For this purpose, a YANG data model is introduced, which is depicted 592 in the following figure. 594 module: ietf-datastore-push 595 +--rw streams {custom-streams}? 596 | +--rw stream* [stream-name] 597 | +--rw stream-name string 598 | +--ro stream-status? identityref 599 | +--rw subtree-filter? subtree-filter 600 | +--rw xpath-filter? yang:xpath1.0 601 | +--rw (update-trigger)? 602 | +--:(periodic) 603 | | +--rw period? yang:timeticks 604 | +--:(on-change) 605 | +--rw dampening-period yang:timeticks 606 | +--rw (change-policy)? 607 | +--:(delta-policy) 608 | +--rw delta? uint32 609 +--rw subscriptions 610 +--ro datastore-push-subscription* [subscription-id] 611 +--ro subscription-id subscription-identifier 612 +--ro subscription-status? identityref 613 +--ro stream? string 614 +--ro start-time? yang:date-and-time 615 +--ro stop-time? yang:date-and-time 616 +--ro subtree-filter? subtree-filter 617 +--ro xpath-filter? yang:xpath1.0 618 +--ro (update-trigger)? 619 +--:(periodic) 620 | +--ro period? yang:timeticks 621 +--:(on-change) 622 +--ro dampening-period yang:timeticks 623 +--ro (change-policy)? 624 +--:(delta-policy) 625 +--ro delta? uint32 627 Figure 6: Model structure 629 Each subscription is represented as a list element "datastore-push- 630 subscription". The associated information includes an identifier for 631 the subscription, a subscription status, as well as the various 632 subscription paramters. The subscription status indicates whether 633 the subscription is currently active and healthy, or if it is 634 degraded in some form. Subscriptions are automatically removed from 635 the list once they expire or are terminated. Because subscriptions 636 are managed using their own set of operation primitives, they are 637 read-only. 639 An optional feature, custom-streams, is introduced to allow for the 640 configuration of custom datastreams. Custom datastreams are 641 represented through a separate list, consisting of information used 642 to configure those datastreams. This information consititutes mostly 643 configuration information, with the exception of parameters used to 644 indicate the status and health of the datastream. 646 In addition, a server needs to indicate any changes in status to the 647 subscriber through a notification. Specifically, subscribers need to 648 be informed of the following: 650 o A subscription has been temporarily suspended(including the 651 reason) 653 o A subscription (that had been suspended earlier) is once again 654 operational 656 o A subscription has been abnormally terminated (including the 657 reason) 659 o A subscription has been modified (including the current set of 660 subscription parameters in effect) 662 Finally, a server might provide additional information about 663 subscriptions, such as statistics about the number of data updates 664 that were sent. However, such information is currently outside the 665 scope of this specification. 667 3.7. Other considerations 669 3.7.1. Authorization 671 A client may only receive updates to data that the client has proper 672 authorization for. Normal authorization rules apply. Data that is 673 being pushed therefore needs to be subjected to a filter that applies 674 the corresponding rules, removing any non-authorized data as 675 applicable. 677 The authorization model for data in YANG datastores is described in 678 the Netconf Access Control Model [RFC6536]. 680 3.7.2. Additional subscription primitives 682 Other possible operations include the ability to suspend and resume 683 subscriptions. However, those operations are not viewed as 684 essential, as it is always possible to alternatively simply remove a 685 subscription and recreate it when needed. 687 3.7.3. Robustness and reliability considerations 689 Particularly in the case of on-change push updates, it is important 690 that push updates do not get lost. However, datastore-push uses a 691 secure and reliable transport. Notifations are not getting 692 reordered, and in addition contain a time stamp. For those reasons, 693 we believe that additional reliability mechanisms at the application 694 level, such as sequence numbers for push updates, are not required. 696 3.7.4. Implementation considerations 698 Implementation specifics are outside the scope of this specification. 699 That said,it should be noted that monitoring of operational state 700 changes inside a system can be associated with significant 701 implementation challenges. 703 Even periodic retrieval of operational state alone, to be able to 704 push it, can consume considerable system resources. Configuration 705 data may in many cases be persisted in an actual database or a 706 configuration file, where retrieval of the database content or the 707 file itself is reasonably straightforward and computationally 708 inexpensive. However, retrieval of operational data may, depending 709 on the implementation, require invocation of APIs, possibly on an 710 object-by-object basis, possibly involving additional internal 711 interrupts, etc. 713 For those reasons, if is important for an implementation to 714 understand what subscriptions it can or cannot support. It is far 715 preferrable to decline a subscription request, than to accept it only 716 to result in subsequent failure later. 718 Whether or not a subscription can be supported will in general be 719 determined by a combination of several factors, including the 720 subscription policy (on-change or periodic, with on-change in general 721 being the more challenging of the two), the period in which to report 722 changes (1 second periods will consume more resources than 1 hour 723 periods), the amount of data in the subtree that is being subscribed 724 to, and the number and combination of other subscriptions that are 725 concurrently being serviced. 727 4. YANG module 729 730 file "ietf-datastore-push@2014-03-09.yang" 732 module ietf-datastore-push { 733 namespace "urn:XXXX:params:xml:ns:yang:ietf-datastore-push"; 734 prefix datastore-push; 735 import ietf-yang-types { 736 prefix yang; 737 } 739 organization "IETF"; 740 contact 741 "Editor: Alexander Clemm 742 744 Editor: Alberto Gonzalez Prieto 745 747 Editor: Eric Voit 748 "; 749 description 750 "This module contains conceptual YANG specifications 751 for datastore push."; 753 revision 2014-03-09 { 754 description 755 "Initial revision."; 756 reference "Datastore push."; 757 } 759 feature custom-streams { 760 description 761 "This feature allows users to configure datastore update 762 streams in addition to the stream provided by default, 763 datastore-push."; 764 } 766 identity subscription-stream-status { 767 description 768 "Base identity for the status of subscriptions and 769 datastreams."; 770 } 772 identity active { 773 base subscription-stream-status; 774 description 775 "Status is active and healthy."; 776 } 778 identity inactive { 779 base subscription-stream-status; 780 description 781 "Status is inactive, for example outside the 782 interval between start time and stop time."; 784 } 786 identity in-error { 787 base subscription-stream-status; 788 description 789 "The status is in error or degraded, meaning that 790 stream and/or subscription are currently unable to provide 791 the negotiated updates."; 792 } 794 identity subscription-errors { 795 description 796 "Base identity for subscription errors."; 797 } 799 identity internal-error { 800 base subscription-errors; 801 description 802 "Subscription failures caused by server internal error."; 803 } 805 identity no-resources { 806 base subscription-errors; 807 description 808 "Lack of resources, e.g. CPU, memory, bandwidth"; 809 } 811 identity other { 812 base subscription-errors; 813 description 814 "Fallback reason - any other reason"; 815 } 817 typedef datastore-contents { 818 type string; 819 description 820 "This type is be used to represent datastore contents, 821 including a filtered datastore subtree per a set of 822 subscription parameters. "; 823 } 825 typedef subtree-filter { 826 type string; 827 description 828 "This type is used to define a subtree filter. 829 Its precise syntax is TBD."; 830 } 831 typedef subscription-identifier { 832 type string { 833 length "1 .. max"; 834 } 835 description 836 "A client-provided identifier for the subscription."; 837 } 839 typedef subscription-term-reason { 840 type identityref { 841 base subscription-errors; 842 } 843 description 844 "Reason for a server to terminate a subscription."; 845 } 847 typedef subscription-susp-reason { 848 type identityref { 849 base subscription-errors; 850 } 851 description 852 "Reason for a server to suspend a subscription."; 853 } 855 grouping subscription-stream-policy { 856 description 857 "This grouping contains the parameters which describe 858 the policy which data is pushed as part of a 859 subscription or a data stream."; 860 leaf subtree-filter { 861 description 862 "Datastore subtree of interest."; 863 type subtree-filter; 864 } 865 leaf xpath-filter { 866 type yang:xpath1.0; 867 description 868 "Xpath defining the data items of interest."; 869 } 870 choice update-trigger { 871 description 872 "Defines necessary conditions for sending an event to 873 the subscriber."; 874 case periodic { 875 description 876 "The agent is requested to notify periodically the 877 current values of the datastore or the subset 878 defined by the filter."; 880 leaf period { 881 type yang:timeticks; 882 description 883 "Elapsed time between notifications."; 884 } 885 } 886 case on-change { 887 description 888 "The agent is requested to notify changes in 889 values in the datastore or a subset of it defined 890 by a filter."; 891 leaf dampening-period { 892 type yang:timeticks; 893 mandatory true; 894 description 895 "Minimum amount of time that needs to have 896 passed since the last time an update was 897 provided."; 898 } 899 choice change-policy { 900 description 901 "Policy describing necessary conditions for 902 sending an event to the subscriber."; 903 case delta-policy { 904 leaf delta { 905 type uint32; 906 description 907 "For integer, minimum difference 908 between current and last reports 909 values that can trigger an update."; 910 } 911 } 912 } 913 } 914 } 915 } 917 grouping subscription-info { 918 description 919 "This grouping describes basic information concerning a 920 subscription, without the subscription policy which is 921 defined separately to be shareable with the definition 922 of a datastream."; 923 leaf stream { 924 type string; 925 description 926 "The name of the stream subscribed to."; 927 } 928 leaf start-time { 929 type yang:date-and-time; 930 description 931 "Starting time for replays."; 932 reference "RFC 5277, Section 2.1.1"; 933 } 934 leaf stop-time { 935 type yang:date-and-time; 936 description 937 "Time limit for events of interest."; 938 reference "RFC 5277, Section 2.1.1"; 939 } 940 } 942 notification push-update { 943 description 944 "This notification contains an update from a datastore"; 945 leaf subscription-id { 946 type subscription-identifier; 947 mandatory true; 948 description 949 "This references the subscription because of which the 950 notification is sent."; 951 } 952 leaf datastore-contents { 953 type datastore-contents; 954 description 955 "This contains datastore contents 956 per the subscription."; 957 } 958 } 959 notification subscription-suspended { 960 description 961 "This notification indicates that a suspension of the 962 subscription by the server has occurred. No further 963 datastore updates will be sent until subscription 964 resumes."; 965 leaf subscription-id { 966 type subscription-identifier; 967 mandatory true; 968 description 969 "This references the affected subscription."; 970 } 971 leaf reason { 972 type subscription-susp-reason; 973 description 974 "Provides a reason for why the subscription was 975 suspended."; 977 } 978 } 979 notification subscription-resumed { 980 description 981 "This notification indicates that a subscription that had 982 previously been suspended has resumed. Datastore updates 983 will once again be sent."; 984 leaf subscription-id { 985 type subscription-identifier; 986 mandatory true; 987 description 988 "This references the affected subscription."; 989 } 990 } 991 notification subscription-modified { 992 description 993 "This notification indicates that a subscription has 994 been modified. Datastore updates sent from this point 995 on will conform to the modified terms of the 996 subscription."; 997 leaf subscription-id { 998 type subscription-identifier; 999 mandatory true; 1000 description 1001 "This references the affected subscription."; 1002 } 1003 uses subscription-info; 1004 uses subscription-stream-policy; 1005 } 1006 notification subscription-terminated { 1007 description 1008 "This notification indicates that a subscription has been 1009 terminated."; 1010 leaf subscription-id { 1011 type subscription-identifier; 1012 mandatory true; 1013 description 1014 "This references the affected subscription."; 1015 } 1016 leaf reason { 1017 type subscription-term-reason; 1018 description 1019 "Provides a reason for why the subscription was 1020 terminated."; 1021 } 1022 } 1023 container streams { 1024 if-feature custom-streams; 1025 list stream { 1026 key "stream-name"; 1027 description 1028 "A user-definable stream."; 1029 leaf stream-name { 1030 type string; 1031 mandatory true; 1032 description 1033 "The name assigned to the stream."; 1034 } 1035 leaf stream-status { 1036 type identityref { 1037 base subscription-stream-status; 1038 } 1039 config false; 1040 } 1041 uses subscription-stream-policy; 1042 } 1043 } 1044 container subscriptions { 1045 list datastore-push-subscription { 1046 description 1047 "Content of a yang-push subscription. 1048 Subscriptions are created using a dedicated RPC, hence 1049 they do not constitute configuration information."; 1050 config false; 1051 key "subscription-id"; 1052 leaf subscription-id { 1053 type subscription-identifier; 1054 description 1055 "Identifier to use for this subscription."; 1056 } 1057 leaf subscription-status { 1058 type identityref { 1059 base subscription-stream-status; 1060 } 1061 description 1062 "The status of the subscription."; 1063 } 1064 uses subscription-info; 1065 uses subscription-stream-policy; 1066 } 1067 } 1068 } 1070 1072 5. Security Considerations 1074 Subscriptions could be used to attempt to overload servers of YANG 1075 datastores. For this reason, it is important that the server has the 1076 ability to decline a subscription request if it would deplete its 1077 resources. In addition, a server needs to be able to suspend an 1078 existing subscription when needed. When this occur, the subscription 1079 status is updated accordingly and the clients are notified. 1080 Likewise, requests for subscriptions need to be properly authorized. 1082 A subscription could be used to retrieve data in subtrees that a 1083 client has not authorized access to. Therefore it is important that 1084 data pushed based on subscriptions is authorized in the same way that 1085 regular data retrieval operations are. Data being pushed to a client 1086 needs therefore to be filtered accordingly, just like if the data 1087 were being retrieved on-demand. The Netconf Authorization Control 1088 Model applies. 1090 6. References 1092 6.1. Normative References 1094 [RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin, 1095 "Simple Network Management Protocol (SNMP)", STD 15, RFC 1096 1157, May 1990. 1098 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1099 Notifications", RFC 5277, July 2008. 1101 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1102 Network Configuration Protocol (NETCONF)", RFC 6020, 1103 October 2010. 1105 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1106 Bierman, "Network Configuration Protocol (NETCONF)", RFC 1107 6241, June 2011. 1109 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 1110 Base Notifications", RFC 5277, February 2012. 1112 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1113 Protocol (NETCONF) Access Control Model", RFC 6536, March 1114 2012. 1116 6.2. Informative References 1118 [peermount] 1119 Clemm, A., Medved, J., and E. Voit, "Mounting YANG-defined 1120 information from remote datastores", draft-clemm-netmod- 1121 mount-02 (work in progress), October 2014. 1123 [peermount-req] 1124 Voit, E., Clemm, A., Bansal, S., Tripathy, A., and P. 1125 Yellai, "Requirements for Peer Mounting of YANG subtrees 1126 from Remote Datastores", draft-voit-netmod-peer-mount- 1127 requirements-00 (work in progress), September 2014. 1129 [pub-sub-reqs] 1130 Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 1131 for Subscription to YANG Datastores", draft-ietf-i2rs-pub- 1132 sub-requirements-00 (work in progress), March 2015. 1134 [restconf] 1135 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1136 Protocol", I-D draft-ietf-netconf-restconf-03, October 1137 2014. 1139 Authors' Addresses 1141 Alexander Clemm 1142 Cisco Systems 1144 EMail: alex@cisco.com 1146 Alberto Gonzalez Prieto 1147 Cisco Systems 1149 EMail: albertgo@cisco.com 1151 Eric Voit 1152 Cisco Systems 1154 EMail: evoit@cisco.com