idnits 2.17.1 draft-ietf-netconf-yang-push-04.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.) ** 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 368: '... SHOULD include in the returned erro...' RFC 2119 keyword, line 407: '...cription request MUST be rejected. As...' RFC 2119 keyword, line 443: '... MUST support XML encoding and MAY s...' RFC 2119 keyword, line 677: '... MAY be returned that would likely h...' RFC 2119 keyword, line 805: '... Implementations MAY therefore choose,...' (6 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 909 has weird spacing: '...lter-id fil...' == Line 943 has weird spacing: '...-period yan...' == Line 955 has weird spacing: '...address ine...' == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 28, 2016) is 2730 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) -- No information found for draft-ietf-netconf-5277bis - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-netconf-5277bis' == Outdated reference: A later version (-14) exists of draft-ietf-netconf-yang-patch-12 ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-17 Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group A. Clemm 2 Internet-Draft Sympotech 3 Intended status: Standards Track E. Voit 4 Expires: May 1, 2017 A. Gonzalez Prieto 5 A. Tripathy 6 E. Nilsen-Nygaard 7 Pre-release version Cisco Systems 8 A. Bierman 9 YumaWorks 10 B. Lengyel 11 Ericsson 12 October 28, 2016 14 Subscribing to YANG datastore push updates 15 draft-ietf-netconf-yang-push-04 17 Abstract 19 This document defines a subscription and push mechanism for YANG 20 datastores. This mechanism allows subscriber applications to request 21 updates from a YANG datastore, which are then pushed by the publisher 22 to a receiver per a subscription policy, without requiring additional 23 subscriber requests. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on May 1, 2017. 42 Copyright Notice 44 Copyright (c) 2016 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 This document may contain material from IETF Documents or IETF 58 Contributions published or made publicly available before November 59 10, 2008. The person(s) controlling the copyright in some of this 60 material may not have granted the IETF Trust the right to allow 61 modifications of such material outside the IETF Standards Process. 62 Without obtaining an adequate license from the person(s) controlling 63 the copyright in such materials, this document may not be modified 64 outside the IETF Standards Process, and derivative works of it may 65 not be created outside the IETF Standards Process, except to format 66 it for publication as an RFC or to translate it into languages other 67 than English. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 72 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 5 73 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 6 74 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 6 75 3.2. Negotiation of Subscription Policies . . . . . . . . . . 8 76 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 9 77 3.4. Data Encodings . . . . . . . . . . . . . . . . . . . . . 10 78 3.5. YANG object filters . . . . . . . . . . . . . . . . . . . 11 79 3.6. Push Data Stream and Transport Mapping . . . . . . . . . 11 80 3.7. Subscription management . . . . . . . . . . . . . . . . . 15 81 3.8. Other considerations . . . . . . . . . . . . . . . . . . 16 82 4. A YANG data model for management of datastore push 83 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 20 84 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 20 85 4.2. Update streams . . . . . . . . . . . . . . . . . . . . . 26 86 4.3. Filters . . . . . . . . . . . . . . . . . . . . . . . . . 27 87 4.4. Subscription configuration . . . . . . . . . . . . . . . 27 88 4.5. Subscription monitoring . . . . . . . . . . . . . . . . . 29 89 4.6. Notifications . . . . . . . . . . . . . . . . . . . . . . 29 90 4.7. RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . 31 91 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 35 92 6. Security Considerations . . . . . . . . . . . . . . . . . . . 47 93 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48 94 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 48 95 8.1. Normative References . . . . . . . . . . . . . . . . . . 48 96 8.2. Informative References . . . . . . . . . . . . . . . . . 48 97 Appendix A. Issues that are currently being worked and resolved 49 98 A.1. Unresolved and yet-to-be addressed issues . . . . . . . . 49 99 A.2. Agreement in principal . . . . . . . . . . . . . . . . . 49 100 Appendix B. Changes between revisions . . . . . . . . . . . . . 50 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 103 1. Introduction 105 YANG [RFC7950] was originally designed for the Netconf protocol 106 [RFC6241] which focused on configuration data. However, YANG can be 107 used to model both configuration and operational data. It is 108 therefore reasonable to expect YANG datastores will increasingly be 109 used to support applications that care about about both. 111 For example, service assurance applications will need to be aware of 112 any remote updates to configuration and operational objects. Rapid 113 awareness of object changes will enable such things as validating and 114 maintaining cross-network integrity and consistency, or monitoring 115 state and key performance indicators of remote devices. 117 Traditional approaches to remote visibility have been built on 118 polling. With polling, data is periodically explicitly retrieved by 119 a client from a server to stay up-to-date. However, there are issues 120 associated with polling-based management: 122 o It introduces additional load on network, devices, and 123 applications. Each polling cycle requires a separate yet arguably 124 redundant request that results in an interrupt, requires parsing, 125 consumes bandwidth. 127 o It lacks robustness. Polling cycles may be missed, requests may 128 be delayed or get lost, often particularly in cases when the 129 network is under stress and hence exactly when the need for the 130 data is the greatest. 132 o Data may be difficult to calibrate and compare. Polling requests 133 may undergo slight fluctuations, resulting in intervals of 134 different lengths which makes data hard to compare. Likewise, 135 pollers may have difficulty issuing requests that reach all 136 devices at the same time, resulting in offset polling intervals 137 which again make data hard to compare. 139 A more effective alternative to polling is when an application can 140 request to be automatically updated on current relevant content of a 141 datastore. If such a request is accepted, interesting updates will 142 subsequently be pushed from that datastore. 144 Dependence on polling-based management is typically considered an 145 important shortcoming of applications that rely on MIBs polled using 146 SNMP [RFC1157]. However, without a provision to support a push-based 147 alternative, there is no reason to believe that management 148 applications that operate on YANG datastores will be any more 149 effective, as they would follow the same request/response pattern. 151 While YANG allows the definition of push notifications, such 152 notifications generally indicate the occurrence of certain well- 153 specified event conditions, such as the onset of an alarm condition 154 or the occurrence of an error. A capability to subscribe to and 155 deliver such pre-defined event notifications has been defined in 156 [RFC5277]. In addition, configuration change notifications have been 157 defined in [RFC6470]. These change notifications pertain only to 158 configuration information, not to operational state, and convey the 159 root of the subtree to which changes were applied along with the 160 edits, but not the modified data nodes and their values. 161 Furthermore, while delivery of updates using notifications is a 162 viable option, some applications desire the ability to stream updates 163 using other transports. 165 Accordingly, there is a need for a service that allows applications 166 to dynamically subscribe to updates of a YANG datastore and that 167 allows the publisher to push those updates, possibly using one of 168 several delivery mechanisms. Additionally, support for subscriptions 169 configured directly on the publisher are also useful when dynamic 170 signaling is undesirable or unsupported. The requirements for such a 171 service are documented in [RFC7923]. 173 This document proposes a solution. The solution builds on top of the 174 Netconf Event Model [I-D.ietf-netconf-5277bis] which defines a 175 mechanism for the management of event subscriptions. At its core, 176 the solution defined here introduces a new set of event streams which 177 maybe subscribed, introduces datastore push update mechanisms, and 178 provides extensions to the event subscription model. The document 179 also includes YANG data model augmentations which extend the model 180 and RPCs defined within [I-D.ietf-netconf-5277bis]. 182 Key capabilities worth highlighting include: 184 o An extension to event subscription mechanisms allowing clients to 185 subscribe to event streams containing automatic datastore updates. 186 The subscription allows clients to specify which data they are 187 interested in, what types of updates (e.g. create, delete, 188 modify), and to provide optional filters with criteria that data 189 must meet for updates to be sent. Furthermore, subscriptions can 190 specify a policy that directs when updates are provided. For 191 example, a client may request to be updated periodically in 192 certain intervals, or whenever data changes occur. 194 o Format and contents of the YANG push updates themselves. 196 o The ability for a publisher to push back on requested subscription 197 parameters. Because not every publisher may support every 198 requested update policy for every piece of data, it is necessary 199 for a publisher to be able to indicate whether or not it is 200 capable of supporting a requested subscription, and possibly allow 201 to negotiate push update subscription parameters. For example, 202 some publishers may have a lower limit to the period with which 203 they can send updates, or they may not support on-change updates 204 for every piece of data. 206 o Subscription parameters which allow the specification of QoS 207 extensions to address prioritization between independent streams 208 of updates. 210 2. Definitions and Acronyms 212 Many of the terms in this document are defined in 213 [I-D.ietf-netconf-5277bis]. Please see that document for these 214 definitions. 216 Data node: An instance of management information in a YANG datastore. 218 Data node update: A data item containing the current value/property 219 of a Data node at the time the data node update was created. 221 Data record: A record containing a set of one or more data node 222 instances and their associated values. 224 Datastore: A conceptual store of instantiated management information, 225 with individual data items represented by data nodes which are 226 arranged in hierarchical manner. 228 Datastream: A continuous stream of data records, each including a set 229 of updates, i.e. data node instances and their associated values. 231 Data subtree: An instantiated data node and the data nodes that are 232 hierarchically contained within it. 234 Push-update stream: A conceptual data stream of a datastore that 235 streams the entire datastore contents continuously and perpetually. 237 Update: A data item containing the current value of a data node. 239 Update notification: An Event Notification including those data node 240 update(s) to be pushed in order to meet the obligations of a single 241 Subscription. All included data node updates must reflect the state 242 of a Datastore at a snapshot in time. 244 Update record: A representation of a data node update as a data 245 record. An update record can be included as part of an update 246 stream. It can also be logged for retrieval. In general, an update 247 record will include the value/property of a data node. It may also 248 include information about the type of data node update, i.e. whether 249 the data node was modified/updated, or newly created, or deleted. 251 Update trigger: A mechanism, as specified by a Subscription Policy, 252 that determines when a data node update is to be communicated. (e.g., 253 a change trigger, invoked when the value of a data node changes or a 254 data node is created or deleted, or a time trigger, invoked after the 255 laps of a periodic time interval.) 257 YANG object filter: A filter that contains evaluation criteria which 258 are evaluated against YANG objects of a subscription. An update is 259 only published if the object meets the specified filter criteria. 261 YANG-Push: The subscription and push mechanism for YANG datastores 262 that is specified in this document. 264 3. Solution Overview 266 This document specifies a solution for a push update subscription 267 service. This solution supports the dynamic as well as configured 268 subscriptions to information updates from YANG datastores. A 269 subscription might target exposed operational and/or configuration 270 YANG objects on a device. YANG objects are subsequently pushed from 271 the publisher to the receiver per the terms of the subscription. 273 3.1. Subscription Model 275 YANG-push subscriptions are defined using a data model that is itself 276 defined in YANG. This model augments the event subscription model 277 defined in [I-D.ietf-netconf-5277bis] and introduces several new 278 parameters that allow subscribers to specify what to include in an 279 update notification and what triggers such an update notification. 281 The subscription model assumes the presence of one or more conceptual 282 perpetual datastreams of continuous subscribable YANG updates. There 283 are several datastreams with predefined semantics, such as the stream 284 of updates of all operational data or the stream of updates of all 285 config data. In addition, it is possible to define custom streams 286 with customizable semantics. The model includes the list of update 287 datastreams that are supported by a system and available for 288 subscription. 290 The subscription model augments the [I-D.ietf-netconf-5277bis] 291 subscription model with a set of parameters: 293 o Anydata encoding for periodic and on-change push updates. 295 o A subscription policy definition regarding the update trigger when 296 to send new update notifications. 298 * For periodic subscriptions, the trigger is defined by two 299 parameters that defines the interval with which updates are to 300 be pushed. These parameters are the period/interval of 301 reporting duration, and an anchor time which can be used to 302 calculate at which times updates needs to be assembled and 303 sent. 305 * EDITOR'S NOTE: A possible option to discuss concerns the 306 introduction of an additional parameter "changes-only" for 307 periodic subscription. Including this flag would results in 308 sending at the end of each period an update containing only 309 changes since the last update (i.e. a change-update as in the 310 case of an on-change subscription), not a full snapshot of the 311 subscribed information. Such an option might be interesting in 312 case of data that is largely static and bandwidth-constrained 313 environments. 315 * For on-change subscriptions, the trigger occurs whenever a 316 change in the subscribed information is detected. On-change 317 subscriptions have more complex semantics that can be guided by 318 additional parameters. Please refer also to Section 3.3. 320 + One parameter specifies the dampening period, i.e. the 321 interval that must pass before a successive update 322 notification for the same Subscription is sent. Note that 323 the dampening period applies to the set of all data nodes 324 within a single subscription. This means that on the first 325 change of an object, an update notification containing that 326 object is sent either immediately or at the end of a 327 dampening period already in effect. 329 + Another parameter allows to restrict the types of changes 330 for which updates are sent (changes to object values, object 331 creation or deletion events). It is conceivable to augment 332 the data model with additional parameters in the future to 333 specify even more refined policies, such as parameters that 334 specify the magnitude of a change that must occur before an 335 update is triggered. 337 + A third parameter specifies whether or not a complete update 338 with all the subscribed data should be sent at the beginning 339 of a subscription to facilitate synchronization and 340 establish the frame of reference for subsequent updates. 342 o Optionally, a filter, or set of filters, describing the subset of 343 data node updates that are of interest to the subscriber. The 344 publisher must only send to the subscriber those data node updates 345 that can traverse applied filter(s). The absence of a filter 346 indicates that all data items from the stream are of interest to 347 the subscriber and all data records must be sent in their entirety 348 to the subscriber. The following types of filters are supported: 349 subtree filters, with the same semantics as defined in 350 [RFC6241][RFC6241], and XPath filters. Additional filter types 351 can be added through augmentations. Filters can be specified 352 "inline" as part of the subscription, or can be configured 353 separately and referenced by a subscription, in order to 354 facilitate reuse of complex filters. 356 The subscription data model is specified as part of the YANG data 357 model described later in this specification. It is conceivable that 358 additional subscription parameters might be added in the future. 359 This can be accomplished through augmentation of the subscription 360 data model. 362 3.2. Negotiation of Subscription Policies 364 Dynamic subscriptions must support a simple negotiation between 365 subscribers and publishers for subscription parameters. This 366 negotiation is limited to a single pair of subscription request and 367 response messages. For negative response messages, the publisher 368 SHOULD include in the returned error what subscription parameters 369 would have been accepted for the request. The returned acceptable 370 parameters constitute suggestions that, when followed, increase the 371 likelihood of success for subsequent requests. However, there are no 372 guarantee that subsequent requests for this subscriber will in fact 373 be accepted. 375 A subscription request might be declined based on publisher's 376 assessment that it may be unable to provide a filtered update 377 notification stream that would meet the terms of the establish- 378 subscription request. 380 In case a subscriber requests an encoding other than XML, and this 381 encoding is not supported by the publisher, the publisher simply 382 indicates in the response that the encoding is not supported. 384 A subscription negotiation capability has been introduced as part of 385 the NETCONF Event Notifications model. However, the ability to 386 negotiate subscriptions is of particular importance in conjunction 387 with push updates, as publisher implementations may have limitations 388 with regards to what updates can be generated and at what velocity. 390 3.3. On-Change Considerations 392 On-change subscriptions allow subscribers to subscribe to updates 393 whenever changes to objects occur. As such, on-change subscriptions 394 are of particular interest for data that changes relatively 395 infrequently, yet that require applications to be notified with 396 minimal delay when changes do occur. 398 On-change subscriptions tend to be more difficult to implement than 399 periodic subscriptions. Specifically, on-change subscriptions may 400 involve a notion of state to see if a change occurred between past 401 and current state, or the ability to tap into changes as they occur 402 in the underlying system. Accordingly, on-change subscriptions may 403 not be supported by all implementations or for every object. 405 When an on-change subscription is requested for a datastream with a 406 given subtree filter, where not all objects support on-change update 407 triggers, the subscription request MUST be rejected. As a result, 408 on-change subscription requests will tend to be directed at very 409 specific, targeted subtrees with only few objects. 411 Any updates for an on-change subscription will include only objects 412 for which a change was detected. To avoid flooding receivers with 413 repeated updates for fast-changing objects, or objects with 414 oscillating values, an on-change subscription allows for the 415 definition of a dampening period. Once an update for a given object 416 is sent, no other updates for this particular object are sent until 417 the end of the dampening period. Values sent at the end of the 418 dampening period are the values current when that dampening period 419 expires. In addition, updates include information about objects that 420 were deleted and ones that were newly created. 422 On-change subscriptions can be refined to let users subscribe only to 423 certain types of changes, for example, only to object creations and 424 deletions, but not to modifications of object values. 426 Additional refinements are conceivable. For example, in order to 427 avoid sending updates on objects whose values undergo only a 428 negligible change, additional parameters might be added to an on- 429 change subscription specifying a YANG object filter that states how 430 large or "significant" a change has to be before an update is sent. 431 A simple policy is a "delta-policy" that states, for integer-valued 432 data nodes, the minimum difference between the current value and the 433 value that was last reported that triggers an update. Also more 434 sophisticated policies are conceivable, such as policies specified in 435 percentage terms or policies that take into account the rate of 436 change. While not specified as part of this draft, such policies can 437 be accommodated by augmenting the subscription data model 438 accordingly. 440 3.4. Data Encodings 442 Subscribed data is encoded in either XML or JSON format. A publisher 443 MUST support XML encoding and MAY support JSON encoding. 445 It is conceivable that additional encodings may be supported as 446 options in the future. This can be accomplished by augmenting the 447 subscription data model with additional identity statements used to 448 refer to requested encodings. 450 3.4.1. Periodic Subscriptions 452 In a periodic subscription, the data included as part of an update 453 corresponds to data that could have been simply retrieved using a get 454 operation and is encoded in the same way. XML encoding rules for 455 data nodes are defined in [RFC7950]. JSON encoding rules are defined 456 in [RFC7951]. This encoding is valid JSON, but also has special 457 encoding rules to identify module namespaces and provide consistent 458 type processing of YANG data. 460 3.4.2. On-Change Subscriptions 462 In an on-change subscription, updates need to indicate not only 463 values of changed data nodes but also the types of changes that 464 occurred since the last update, such as whether data nodes were newly 465 created since the last update or whether they were merely modified, 466 as well as which data nodes were deleted. 468 Encoding rules for data in on-change updates correspond to how data 469 would be encoded in a YANG-patch operation as specified in 470 [I-D.ietf-netconf-yang-patch]. The "YANG-patch" would in this case 471 be applied to the earlier state reported by the preceding update, to 472 result in the now-current state of YANG data. Of course, contrary to 473 a YANG-patch operation, the data is sent from the publisher to the 474 receiver and is not restricted to configuration data. 476 3.5. YANG object filters 478 Subscriptions can specify filters for subscribed data. The following 479 filters are supported: 481 o subtree-filter: A subtree filter specifies a subtree that the 482 subscription refers to. When specified, updates will only concern 483 data nodes from this subtree. Syntax and semantics correspond to 484 that specified for [RFC6241] section 6. 486 o xpath-filter: An XPath filter specifies an XPath expression 487 applied to the data in an update, assuming XML-encoded data. 489 Only a single filter can be applied to a subscription at a time. 491 It is conceivable for implementations to support other filters. For 492 example, an on-change filter might specify that changes in values 493 should be sent only when the magnitude of the change since previous 494 updates exceeds a certain threshold. It is possible to augment the 495 subscription data model with additional filter types. 497 3.6. Push Data Stream and Transport Mapping 499 Pushing data based on a subscription could be considered analogous to 500 a response to a data retrieval request, e.g. a "get" request. 501 However, contrary to such a request, multiple responses to the same 502 request may get sent over a longer period of time. 504 An applicable mechanism is that of a notification. There are however 505 some specifics that need to be considered. Contrary to other 506 notifications that are associated with alarms and unexpected event 507 occurrences, update notifications are solicited, i.e. tied to a 508 particular subscription which triggered the notification. 510 A push update notification contains several parameters: 512 o A subscription correlator, referencing the name of the 513 subscription on whose behalf the notification is sent. 515 o Data nodes containing a representation of the datastore subtree(s) 516 containing the updates. In all cases, the subtree(s) are filtered 517 per access control rules to contain only data that the subscriber 518 is authorized to see. For on-change subscriptions, the subtree 519 may only contain the data nodes which have changed since the start 520 of the previous dampening interval. 522 This document introduces two generic notifications: "push-update" and 523 "push-change-update". Those notifications may be encapsulated on a 524 transport (e.g. Netconf notifications and HTTP) to carry data 525 records with updates of datastore contents as specified by a 526 subscription. It is possible also map notifications to other 527 transports and encodings and use the same subscription model; 528 however, the definition of such mappings is outside the scope of this 529 document. 531 A push-update notification defines a complete update of the datastore 532 per the terms of a subscription. This type of notification is used 533 for continuous updates of periodic subscriptions. A push-update 534 notification can also used be for the on-change subscriptions in two 535 cases. First it will be used as the initial push-update if there is 536 a need to synchronize the receiver at the start of a new 537 subscription. It also may be sent if the publisher later chooses to 538 resynch a previously synched on-change subscription. The push-update 539 record contains a data snippet that contains an instantiated subtree 540 with the subscribed contents. The content of the update notification 541 is equivalent to the contents that would be obtained had the same 542 data been explicitly retrieved using e.g. a Netconf "get"-operation, 543 with the same filters applied. 545 The contents of the notification conceptually represents the union of 546 all data nodes in the yang modules supported by the publisher. 547 However, in a YANG data model, it is not practical to model the 548 precise data contained in the updates as part of the notification. 549 This is because the specific data nodes supported depend on the 550 implementing system and may even vary dynamically. Therefore, to 551 capture this data, a single parameter that can represent any 552 datastore contents is used, not parameters that represent data nodes 553 one at a time. 555 A push-change-update notification is the most common type of update 556 for on-change subscriptions. It is not used for periodic 557 subscriptions. The update record in this case contains a data 558 snippet that indicates the full set of changes that data nodes have 559 undergone since the last notification of YANG objects. In other 560 words, this indicates which data nodes have been created, deleted, or 561 have had changes to their values. The format of the data snippet 562 follows YANG-patch [I-D.ietf-netconf-yang-patch], i.e. the same 563 format that would be used with a YANG-patch operation to apply 564 changes to a data tree, indicating the creates, deletes, and 565 modifications of data nodes. Please note that as the update can 566 include a mix of configuration and operational data 568 The following is an example of push notification. It contains an 569 update for subscription 1011, including a subtree with root foo that 570 contains a leaf, bar: 572 574 2015-03-09T19:14:56Z 575 577 1011 578 2015-03-09T19:14:56.233Z 579 580 581 some_string 582 583 584 585 587 Figure 1: Push example 589 The following is an example of an on-change notification. It 590 contains an update for subscription 89, including a new value for a 591 leaf called beta, which is a child of a top-level container called 592 alpha: 594 596 2015-03-09T19:14:56Z 597 599 89 600 2015-03-09T19:14:56.233Z 601 602 603 1500 604 605 606 607 609 Figure 2: Push example for on change 611 The equivalent update when requesting json encoding: 613 615 2015-03-09T19:14:56Z 616 618 89 619 2015-03-09T19:14:56.233Z 620 621 { 622 "ietf-yang-patch:yang-patch": { 623 "patch-id": [ 624 null 625 ], 626 "edit": [ 627 { 628 "edit-id": "edit1", 629 "operation": "merge", 630 "target": "/alpha/beta", 631 "value": { 632 "beta": 1500 633 } 634 } 635 ] 636 } 637 } 638 639 640 642 Figure 3: Push example for on change with JSON 644 When the beta leaf is deleted, the publisher may send 645 647 2015-03-09T19:14:56Z 648 650 89 651 2015-03-09T19:14:56.233Z 652 653 654 656 657 658 659 661 Figure 4: 2nd push example for on change update 663 3.7. Subscription management 665 A [[I-D.ietf-netconf-5277bis] subscription needs enhancment to 666 support YANG Push subscription negotiation. Specifically, these 667 enhancements are needed to signal to the subscriber why an attempt 668 has failed. 670 A subscription can be rejected for multiple reasons, including the 671 lack of authorization to establish a subscription, the lack of read 672 authorization on the requested data node, or the inability of the 673 publisher to provide a stream with the requested semantics. In such 674 cases, no subscription is established. Instead, the subscription- 675 result with the failure reason is returned as part of the RPC 676 response. In addition, a set of alternative subscription parameters 677 MAY be returned that would likely have resulted in acceptance of the 678 subscription request, which the subscriber may try for a future 679 subscription attempt. 681 It should be noted that a rejected subscription does not result in 682 the generation of an rpc-reply with an rpc-error element, as neither 683 the specification of YANG-push specific errors nor the specification 684 of additional data parameters to be returned in an error case are 685 supported as part of a YANG data model. 687 For instance, for the following request: 689 691 693 push-update 694 697 500 698 encode-xml 699 700 702 Figure 5: Establish-Subscription example 704 the publisher might return: 706 708 710 error-insufficient-resources 711 712 2000 713 715 Figure 6: Error response example 717 3.8. Other considerations 719 3.8.1. Authorization 721 A receiver of subscription data may only be sent updates for which 722 they have proper authorization. Data that is being pushed therefore 723 needs to be subjected to a filter that applies all corresponding 724 rules applicable at the time of a specific pushed update, silently 725 removing any non-authorized data from subtrees. 727 The authorization model for data in YANG datastores is described in 728 the Netconf Access Control Model [RFC6536]. However, some 729 clarifications to that RFC are needed so that the desired access 730 control behavior is applied to pushed updates. 732 One of these clarifications is that a subscription may only be 733 established if the receiver has read access to the target data node. 735 +-------------+ +-------------+ 736 subscription | protocol | | target | 737 request --> | operation | -------------> | data node | 738 | allowed? | datastore | access | 739 +-------------+ or state | allowed? | 740 data access +-------------+ 742 Figure 7: Access control for subscription 744 Likewise if a receiver no longer has read access permission to a 745 target data node, the subscription must be abnormally terminated 746 (with loss of access permission as the reason provided). 748 Another clarification to [RFC6536] is that each of the individual 749 nodes in a pushed update must also go through access control 750 filtering. This includes new nodes added since the last update 751 notification, as well as existing nodes. For each of these read 752 access must be verified. The methods of doing this efficiently are 753 left to implementation. 755 +-------------+ +-------------------+ 756 subscription | data node | yes | | 757 update --> | access | ---> | add data node | 758 | allowed? | | to update message | 759 +-------------+ +-------------------+ 761 Figure 8: Access control for push updates 763 If there are read access control changes applied under the target 764 node, no notifications indicating the fact that this has occurred 765 should be provided. 767 3.8.2. Robustness and reliability considerations 769 Particularly in the case of on-change push updates, it is important 770 that push updates do not get lost. 772 Update notifications will typically traverse a secure and reliable 773 transport. Notifications will not be reordered, and will also 774 contain a time stamp. Despite these protections for on-change, it is 775 possible that complete update notifications get lost. For this 776 reason, patch-ids may be included in a subscription so that an 777 application can determine if an update has been lost. 779 At the same time, it is conceivable that under certain circumstances, 780 a publisher will recognize that it is unable to include within an 781 update notification the full set of objects desired per the terms of 782 a subscription. In this case, the publisher must take one or more of 783 the following actions. 785 o A publisher must set the updates-not-sent flag on any update 786 notification which is known to be missing information. 788 o It may choose to suspend and resume a subscription as per 789 [I-D.ietf-netconf-5277bis]. 791 o When resuming an on-change subscription, the publisher should 792 generate a complete patch from the previous update notification. 793 If this is not possible and the synch-on-start option is 794 configured, then the full datastore contents may be sent instead 795 (effectively replacing the previous contents). If neither of 796 these are possible, then an updates-not-sent flag must be included 797 on the next push-change-update. 799 3.8.3. Update size and fragmentation considerations 801 Depending on the subscription, the volume of updates can become quite 802 large. There is no inherent limitation to the amount of data that 803 can be included in a notification. That said, it may not always be 804 practical to send the entire update in a single chunk. 805 Implementations MAY therefore choose, at their discretion, to "chunk" 806 updates and break them out into several update notifications. 808 3.8.4. Push data streams 810 There are several conceptual data streams introduced in this 811 specification: 813 o yang-push includes the entirety of YANG data, including both 814 configuration and operational data. 816 o operational-push includes all operational (read-only) YANG data 818 o config-push includes all YANG configuration data. 820 It is conceivable to introduce other data streams with more limited 821 scope, for example: 823 o operdata-nocounts-push, a datastream containing all operational 824 (read-only) data with the exception of counters 826 o other custom datastreams 828 Those data streams make particular sense for use cases involving 829 service assurance (not relying on operational data), and for use 830 cases requiring on-change update triggers which make no sense to 831 support in conjunction with fast-changing counters. While it is 832 possible to specify subtree filters on yang-push to the same effect, 833 having those data streams greatly simplifies articulating 834 subscriptions in such scenarios. 836 3.8.5. Implementation considerations 838 Implementation specifics are outside the scope of this specification. 839 That said,it should be noted that monitoring of operational state 840 changes inside a system can be associated with significant 841 implementation challenges. 843 Even periodic retrieval and push of operational counters may consume 844 considerable system resources. In addition the on-change push of 845 small amounts of configuration data may, depending on the 846 implementation, require invocation of APIs, possibly on an object-by- 847 object basis, possibly involving additional internal interrupts, etc. 849 For those reasons, it is important for an implementation to 850 understand what subscriptions it can or cannot support. It is far 851 preferable to decline a subscription request then to accept such a 852 request when it cannot be met. 854 Whether or not a subscription can be supported will in general be 855 determined by a combination of several factors, including the 856 subscription policy (on-change or periodic, with on-change in general 857 being the more challenging of the two), the period in which to report 858 changes (1 second periods will consume more resources than 1 hour 859 periods), the amount of data in the subtree that is being subscribed 860 to, and the number and combination of other subscriptions that are 861 concurrently being serviced. 863 When providing access control to every node in a pushed update, it is 864 possible to make and update efficient access control filters for an 865 update. These filters can be set upon subscription and applied 866 against a stream of updates. These filters need only be updated when 867 (a) there is a new node added/removed from the subscribed tree with 868 different permissions than its parent, or (b) read access permissions 869 have been changed on nodes under the target node for the subscriber. 871 3.8.6. Not Notifiable YANG Objects 873 In some cases, a publisher supporting "on-change" notifications may 874 not be able to push updates for some object types "on-change". 875 Reasons for this might be that the value of the data node changes 876 frequently (e.g., a received-octets-counter), that small object 877 changes are frequent and meaningless (e.g., a temperature gauge 878 changing 0.1 degrees), or that the implementation is not capable of 879 on-change notification of an object type. 881 The default assumption is that changes on all data nodes will be 882 reported on-change. However if a certain data node cannot do this, 883 it SHOULD be marked with the YANG extension not-notifiable-on-change. 885 4. A YANG data model for management of datastore push subscriptions 887 4.1. Overview 889 The YANG data model for datastore push subscriptions is depicted in 890 the following figure. Following Yang tree convention in the 891 depiction, brackets enclose list keys, "rw" means configuration, "ro" 892 operational state data, "?" designates optional nodes, "*" designates 893 nodes that can have multiple instances. Parantheses with a name in 894 the middle enclose choice and case nodes. A "+" at the end of a line 895 indicates that the line is to be concatenated with the subsequent 896 line. New YANG tree notation is the i] which indicates that the node 897 in that line has been brought in / imported from another model, and 898 an (a) which indicates this is the specific imported node augmented. 899 In the figure below, all have been imported from 5277bis. The model 900 consists mostly of augmentations to RPCs and notifications defined in 901 the data model for subscriptions for event notifications of 902 [I-D.ietf-netconf-5277bis]. 904 module: ietf-yang-push 905 i] +--ro streams 906 i] | +--ro stream* stream 907 i] +--rw filters 908 i] | +--rw filter* [filter-id] 909 i] | +--rw filter-id filter-id 910 i] | +--rw (filter-type)? 911 i] | +--:(rfc5277) 912 i] | | +--rw filter? 913 | +--:(update-filter) 914 | +--rw (update-filter)? 915 | +--:(subtree) 916 | | +--rw subtree-filter? 917 | +--:(xpath) 918 | +--rw xpath-filter? yang:xpath1.0 919 i] +--rw subscription-config {configured-subscriptions}? 920 i] | +--rw subscription* [subscription-id] 921 i] | +--rw subscription-id subscription-id 922 i] | +--rw stream? stream 923 i] | +--rw encoding? encoding 924 (a) | +--rw (filter-type)? 925 i] | | +--:(rfc5277) 926 i] | | | +--rw filter? 927 | | +--:(update-filter) 928 | | | +--rw (update-filter)? 929 | | | +--:(subtree) 930 | | | | +--ro subtree-filter? 931 | | | +--:(xpath) 932 | | | +--rw xpath-filter? yang:xpath1.0 933 i] | | +--:(by-reference) 934 i] | | +--rw filter-ref? filter-ref 935 i] | +--rw startTime? yang:date-and-time 936 i] | +--rw stopTime? yang:date-and-time 937 | +--rw (update-trigger)? 938 | | +--:(periodic) 939 | | | +--rw period yang:timeticks 940 | | | +--rw anchor-time? yang:date-and-time 941 | | +--:(on-change) {on-change}? 942 | | +--rw no-synch-on-start? empty 943 | | +--rw dampening-period yang:timeticks 944 | | +--rw excluded-change* change-type 945 i] | +--rw receivers 946 i] | | +--rw receiver* [address] 947 i] | | +--rw address inet:host 948 i] | | +--rw port inet:port-number 949 i] | | +--rw protocol? transport-protocol 950 i] | +--rw (push-source)? 951 i] | | +--:(interface-originated) 952 i] | | | +--rw source-interface? if:interface-ref 953 i] | | +--:(address-originated) 954 i] | | +--rw source-vrf? uint32 955 i] | | +--rw source-address inet:ip-address-no-zone 956 | +--rw dscp? inet:dscp 957 | +--rw subscription-priority? uint8 958 | +--rw subscription-dependency? string 959 (a) +--ro subscriptions 960 i] +--ro subscription* 961 i] +--ro subscription-id 962 i] +--ro configured-subscription? 963 i] +--ro subscription-status? 964 i] +--ro stream? 965 i] +--ro encoding? 966 (a) +--ro (filter-type)? 967 i] | +--:(rfc5277) 968 i] | | +--ro filter? 969 | +--:(update-filter) 970 | | +--ro (update-filter)? 971 | | +--:(subtree) 972 | | | +--ro subtree-filter? 973 | | +--:(xpath) 974 | | +--ro xpath-filter? 975 i] | +--:(by-reference) 976 i] | +--ro filter-ref? 977 i] +--ro startTime? 978 i] +--ro stopTime? 979 +--ro (update-trigger)? 980 | +--:(periodic) 981 | | +--ro period 982 | | +--ro anchor-time? 983 | +--:(on-change) {on-change}? 984 | +--ro no-synch-on-start? 985 | +--ro dampening-period 986 | +--ro excluded-change* 987 i] +--ro receivers 988 i] | +--ro receiver* 989 i] | +--ro address 990 i] | +--ro port 991 i] | +--ro protocol? 992 i] +--ro (push-source)? 993 i] | +--:(interface-originated) 994 i] | | +--ro source-interface? 995 i] | +--:(address-originated) 996 i] | +--ro source-vrf? 997 i] | +--ro source-address 998 +--ro dscp? 999 +--ro subscription-priority? 1000 +--ro subscription-dependency? 1001 i] rpcs: 1002 i] +---x establish-subscription 1003 (a) | +---w input 1004 i] | | +---w stream? 1005 i] | | +---w encoding? 1006 (a) | | +---w (filter-type)? 1007 i] | | | +--:(rfc5277) 1008 i] | | | | +---w filter? 1009 | | | +--:(update-filter) 1010 | | | | +---w (update-filter)? 1011 | | | | +--:(subtree) 1012 | | | | | +---w subtree-filter? 1013 | | | | +--:(xpath) 1014 | | | | +---w xpath-filter? 1015 i] | | | +--:(by-reference) 1016 i] | | | +---w filter-ref? 1017 i] | | +---w startTime? 1018 i] | | +---w stopTime? 1019 | | +---w (update-trigger)? 1020 | | | +--:(periodic) 1021 | | | | +---w period 1022 | | | | +---w anchor-time? 1023 | | | +--:(on-change) {on-change}? 1024 | | | +---w no-synch-on-start? 1025 | | | +---w dampening-period 1026 | | | +---w excluded-change* 1027 | | +---w dscp? 1028 | | +---w subscription-priority? 1029 | | +---w subscription-dependency? 1030 i] | +--ro output 1031 i] | +--ro subscription-result 1032 i] | +--ro (result)? 1033 i] | +--:(success) 1034 i] | | +--ro subscription-id 1035 (a) | +--:(no-success) 1036 i] | +--ro stream? 1037 i] | +--ro encoding? 1038 (a) | +--ro (filter-type)? 1039 i] | | +--:(rfc5277) 1040 i] | | | +--ro filter? 1041 | | +--:(update-filter) 1042 | | | +---w (update-filter)? 1043 | | | +--:(subtree) 1044 | | | | +---w subtree-filter? 1045 | | | +--:(xpath) 1046 | | | +---w xpath-filter? 1047 i] | | +--:(by-reference) 1048 i] | | +--ro filter-ref? 1049 i] | +--ro startTime? 1050 i] | +--ro stopTime? 1051 | +--ro (update-trigger)? 1052 | | +--:(periodic) 1053 | | | +--ro period 1054 | | | +--ro anchor-time? 1055 | | +--:(on-change) {on-change}? 1056 | | +--ro no-synch-on-start? 1057 | | +--ro dampening-period 1058 | | +--ro excluded-change* 1059 | +--ro dscp? 1060 | +--ro subscription-priority? 1061 | +--ro subscription-dependency? 1062 i] +---x modify-subscription 1063 i] | +---w input 1064 i] | | +---w subscription-id? 1065 i] | | +---w (filter-type)? 1066 i] | | | +--:(rfc5277) 1067 i] | | | | +---w filter? 1068 | | | +--:(update-filter) 1069 | | | | +---w (update-filter)? 1070 | | | | +--:(subtree) 1071 | | | | | +---w subtree-filter? 1072 | | | | +--:(xpath) 1073 | | | | +---w xpath-filter? 1074 i] | | | +--:(by-reference) 1075 i] | | | +---w filter-ref? 1076 i] | | +---w startTime? 1077 i] | | +---w stopTime? 1078 | | +---w (update-trigger)? 1079 | | +--:(periodic) 1080 | | | +---w period 1081 | | | +---w anchor-time? 1082 | | +--:(on-change) {on-change}? 1083 | | +---w dampening-period 1084 | | +---w excluded-change* 1085 i] | +--ro output 1086 i] | +--ro subscription-result 1087 i] | +--ro (result)? 1088 i] | +--:(success) 1089 i] | | +--ro subscription-id 1090 i] | +--:(no-success) 1091 i] | +--ro stream? 1092 i] | +--ro encoding? 1093 i] | +--ro (filter-type)? 1094 i] | | +--:(rfc5277) 1095 i] | | | +--ro filter? 1096 | | +--:(update-filter) 1097 | | | +---w (update-filter)? 1098 | | | +--:(subtree) 1099 | | | | +---w subtree-filter? 1100 | | | +--:(xpath) 1101 | | | +---w xpath-filter? 1102 i] | | +--:(by-reference) 1103 i] | | +--ro filter-ref? 1104 i] | +--ro startTime? 1105 i] | +--ro stopTime? 1106 | +--ro (update-trigger)? 1107 | | +--:(periodic) 1108 | | | +--ro period 1109 | | | +--ro anchor-time? 1110 | | +--:(on-change) {on-change}? 1111 | | +--ro no-synch-on-start? 1112 | | +--ro dampening-period 1113 | | +--ro excluded-change* 1114 | +--ro dscp? 1115 | +--ro subscription-priority? 1116 | +--ro subscription-dependency? 1117 i] +---x delete-subscription 1118 i] +---w input 1119 i] | +---w subscription-id 1120 i] +--ro output 1121 i] +--ro subscription-result 1123 (a) notifications 1124 (a) +---n subscription-started 1125 i] | +--ro subscription-id 1126 i] | +--ro stream? 1127 i] | +--ro encoding? 1128 (a) | +--ro (filter-type)? 1129 i] | | +--:(rfc5277) 1130 i] | | | +--ro filter? 1131 | | +--:(update-filter) 1132 | | | +--rw (update-filter)? 1133 | | | +--:(subtree) 1134 | | | | +--ro subtree-filter? 1135 | | | +--:(xpath) 1136 | | | +--rw xpath-filter? 1137 i] | | +--:(by-reference) 1138 i] | | +--ro filter-ref? 1139 i] | +--ro startTime? 1140 i] | +--ro stopTime? 1141 | +--ro (update-trigger)? 1142 | | +--:(periodic) 1143 | | | +--ro period 1144 | | | +--ro anchor-time? 1145 | | +--:(on-change) {on-change}? 1146 | | +--ro no-synch-on-start? 1147 | | +--ro dampening-period 1148 | | +--ro excluded-change* 1149 | +--ro dscp? 1150 | +--ro subscription-priority? 1151 | +--ro subscription-dependency? 1152 (a) +---n subscription-modified 1153 i] | +--ro subscription-id 1154 i] | +--ro stream? 1155 i] | +--ro encoding? 1156 (a) | +--ro (filter-type)? 1157 i] | | +--:(rfc5277) 1158 i] | | | +--ro filter? 1159 | | +--:(update-filter) 1160 | | | +--rw (update-filter)? 1161 | | | +--:(subtree) 1162 | | | | +--ro subtree-filter? 1163 | | | +--:(xpath) 1164 | | | +--rw xpath-filter? 1165 i] | | +--:(by-reference) 1166 i] | | +--ro filter-ref? 1167 i] | +--ro startTime? 1168 i] | +--ro stopTime? 1169 | +--ro (update-trigger)? 1170 | | +--:(periodic) 1171 | | | +--ro period 1172 | | | +--ro anchor-time? 1173 | | +--:(on-change) {on-change}? 1174 | | +--ro no-synch-on-start? 1175 | | +--ro dampening-period 1176 | | +--ro excluded-change* 1177 | +--ro dscp? 1178 | +--ro subscription-priority? 1179 | +--ro subscription-dependency? 1180 i] +---n subscription-terminated 1181 i] | +--ro subscription-id 1182 i] | +--ro reason? 1183 i] +---n subscription-suspended 1184 i] | +--ro subscription-id 1185 i] | +--ro reason? 1186 i] +---n subscription-resumed 1187 i] | +--ro subscription-id 1188 i] +---n replay-complete 1189 i] | +--ro subscription-id 1190 i] +---n notification-complete 1191 i] | +--ro subscription-id 1192 +---n push-update 1193 | +--ro subscription-id 1194 | +--ro time-of-update? 1195 | +--ro updates-not-sent? 1196 | +--ro datastore-contents? 1197 +---n push-change-update {on-change}? 1198 +--ro subscription-id 1199 +--ro time-of-update? 1200 +--ro updates-not-sent? 1201 +--ro datastore-changes? 1203 Figure 9: Model structure 1205 The components of the model are described in the following 1206 subsections. 1208 4.2. Update streams 1210 Container "update-streams" is used to indicate which data streams are 1211 provided by the system and can be subscribed to. For this purpose, 1212 it contains a leaf list of data nodes identifying the supported 1213 streams. 1215 4.3. Filters 1217 Container "filters" contains a list of configurable data filters, 1218 each specified in its own list element. This allows users to 1219 configure filters separately from an actual subscription, which can 1220 then be referenced from a subscription. This facilitates the reuse 1221 of filter definitions, which can be important in case of complex 1222 filter conditions. 1224 One of three types of filters can be specified as part of a filter 1225 list element. Subtree filters follow syntax and semantics of RFC 1226 6241 and allow to specify which subtree(s) to subscribe to. In 1227 addition, XPath filters can be specified for more complex filter 1228 conditions. Finally, filters can be specified using syntax and 1229 semantics of RFC5277. 1231 It is conceivable to introduce other types of filters; in that case, 1232 the data model needs to be augmented accordingly. 1234 4.4. Subscription configuration 1236 As an optional feature, configured-subscriptions, allows for the 1237 configuration of subscriptions as opposed to RPC. Subscriptions 1238 configurations are represented by list subscription-config. Each 1239 subscription is represented through its own list element and includes 1240 the following components: 1242 o "subscription-id" is an identifier used to refer to the 1243 subscription. 1245 o "stream" refers to the stream being subscribed to. The 1246 subscription model assumes the presence of perpetual and 1247 continuous streams of updates. Various streams are defined: 1248 "push-update" covers the entire set of YANG data in the publisher. 1249 "operational-push" covers all operational data, while "config- 1250 push" covers all configuration data. Other streams could be 1251 introduced in augmentations to the model by introducing additional 1252 identities. 1254 o "encoding" refers to the encoding requested for the data updates. 1255 By default, updates are encoded using XML. However, JSON can be 1256 requested as an option if the json-enconding feature is supported. 1257 Other encodings may be supported in the future. 1259 o "anchor-time" is a timestamp. When used in conjunction with 1260 period, the boundaries of periodic update periods may be 1261 calculated. 1263 o Filters for a subscription can be specified using a choice, 1264 allowing to either reference a filter that has been separately 1265 configured or entering its definition inline. 1267 o A choice of subscription policies allows to define when to send 1268 new updates - periodic or on change. 1270 * For periodic subscriptions, the trigger is defined by a 1271 "period", a parameter that defines the interval with which 1272 updates are to be pushed. The start time of the subscription 1273 serves as anchor time, defining one specific point in time at 1274 which an update needs to be sent. Update intervals always fall 1275 on the points in time that are a multiple of a period after the 1276 start time. 1278 * For on-change subscriptions, the trigger occurs whenever a 1279 change in the subscribed information is detected. On-change 1280 subscriptions have more complex semantics that is guided by 1281 additional parameters. "dampening-period" specifies the 1282 interval that must pass before a successive update for the same 1283 data node is sent. The first time a change is detected, the 1284 update is sent immediately. If a subsequent change is 1285 detected, another update is only sent once the dampening period 1286 has passed, containing the value of the data node that is then 1287 valid. "excluded-change" allows to restrict the types of 1288 changes for which updates are sent (changes to object values, 1289 object creation or deletion events). "no-synch-on-start" is a 1290 flag that allows to specify whether or not a complete update 1291 with all the subscribed data should be sent at the beginning of 1292 a subscription; if the flag is omitted, a complete update is 1293 sent to facilitate synchronization. It is conceivable to 1294 augment the data model with additional parameters in the future 1295 to specify even more refined policies, such as parameters that 1296 specify the magnitude of a change that must occur before an 1297 update is triggered. 1299 o This is followed with a list of receivers for the subscription, 1300 indicating for each receiver the transport that should be used for 1301 push updates (if options other than Netconf are supported). It 1302 should be noted that the receiver does not have to be the same 1303 system that configures the subscription. 1305 o Finally, "push-source" can be used to specify the source of push 1306 updates, either a specific interface or publisher address. 1308 A subscription established through configuration cannot be deleted 1309 using an RPC. Likewise, subscriptions established through RPC cannot 1310 be deleted through configuration. 1312 The deletion of a subscription, whether through RPC or configuration, 1313 results in immediate termination of the subsciption. 1315 4.5. Subscription monitoring 1317 Subscriptions can be subjected to management themselves. For 1318 example, it is possible that a publisher may no longer be able to 1319 serve a subscription that it had previously accepted. Perhaps it has 1320 run out of resources, or internal errors may have occurred. When 1321 this is the case, a publisher needs to be able to temporarily suspend 1322 the subscription, or even to terminate it. More generally, the 1323 publisher should provide a means by which the status of subscriptions 1324 can be monitored. 1326 Container "subscriptions" contains the state of all subscriptions 1327 that are currently active. This includes subscriptions that were 1328 established (and have not yet been deleted) using RPCs, as well as 1329 subscriptions that have been configured as part of configuration. 1331 Each subscription is represented as a list element "datastore-push- 1332 subscription". The associated information includes an identifier for 1333 the subscription, a subscription status, as well as the various 1334 subscription parameters that are in effect. The subscription status 1335 indicates whether the subscription is currently active and healthy, 1336 or if it is degraded in some form. Leaf "configured-subscription" 1337 indicates whether the subscription came into being via configuration 1338 or via RPC. 1340 Subscriptions that were established by RPC are removed from the list 1341 once they expire (reaching stop-time )or when they are terminated. 1342 Subscriptions that were established by configuration need to be 1343 deleted from the configuration by a configuration editing operation. 1345 4.6. Notifications 1347 4.6.1. Monitoring and OAM Notifications 1349 OAM notifications are reused from [I-D.ietf-netconf-5277bis]. Some 1350 have augmentations to include new objects defined in this draft. 1352 Still to be investigated is whether a publisher might also provide 1353 additional information about subscriptions, such as statistics about 1354 the number of data updates that were sent. However, such information 1355 is currently outside the scope of this specification. 1357 4.6.2. Update Notifications 1359 The data model introduces two YANG notifications for the actual 1360 updates themselves. 1362 Notification "push-update" is used to send a complete snapshot of the 1363 data that has been subscribed to, with all YANG object filters 1364 applied. The notification is used for periodic subscription updates 1365 in a periodic subscription. 1367 The notification can also be used in an on-change subscription for 1368 the purposes of allowing a receiver to "synch". Specifically, it is 1369 used at the start of an on-change subscription, unless no-synch-on- 1370 start is specified for the subscription. In addition, it MAY be used 1371 during the subscription, for example if change updates were not sent 1372 as indicated by the "updates-not-sent" flag (see below), or for synch 1373 updates at longer period intervals (such as once per day) to mitigate 1374 the possibility of any application-dependent synchronization drift. 1375 The trigger for sending a push-update notification in conjunction 1376 with on-change subscriptions are at this point outside the scope of 1377 the specification. 1379 The format and syntax of the contained data corresponds to the format 1380 and syntax of data that would be returned in a corresponding get 1381 operation with the same filter parameters applied. 1383 Notification "push-change-update" is used to send data updates for 1384 changes that have occurred in the subscribed data. This notification 1385 is used only in conjunction with on-change subscriptions. 1387 The data updates are encoded analogous to the syntax of a 1388 corresponding yang-patch operation. It corresponds to the data that 1389 would be contained in a yang-patch operation applied to the YANG 1390 datastore at the previous update, to result in the current state (and 1391 applying it also to operational data). 1393 In rare circumstances, the notification can include a flag "updates- 1394 not-sent". This is a flag which indicates that not all changes which 1395 have occurred since the last update are actually included with this 1396 update. In other words, the publisher has failed to fulfill its full 1397 subscription obligations, for example in cases where it was not able 1398 to keep up with a change burst. To facilitate synchronization, a 1399 publisher MAY subsequently send a push-update containing a full 1400 snapshot of subscribed data. Such a push-update might also be 1401 triggered by a subscriber requesting an on-demand synchronization. 1403 4.7. RPCs 1405 YANG-Push subscriptions are established, modified, and deleted using 1406 three RPCs. 1408 4.7.1. Establish-subscription RPC 1410 The subscriber sends an establish-subscription RPC with the 1411 parameters in section 3.1. For instance 1413 1415 1417 push-update 1418 1421 500 1422 encode-xml 1423 1424 1426 Figure 10: Establish-subscription RPC 1428 The publisher must respond explicitly positively (i.e., subscription 1429 accepted) or negatively (i.e., subscription rejected) to the request. 1430 Positive responses include the subscription-id of the accepted 1431 subscription. In that case a publisher may respond: 1433 1435 1437 ok 1438 1439 1441 52 1442 1443 1445 Figure 11: Establish-subscription positive RPC response 1447 A subscription can be rejected for multiple reasons, including the 1448 lack of authorization to establish a subscription, the lack of read 1449 authorization on the requested data node, or the inability of the 1450 publisher to provide a stream with the requested semantics. 1452 When the requester is not authorized to read the requested data node, 1453 the returned "error-info"; indicates an authorization error and the 1454 requested node. For instance, if the above request was unauthorized 1455 to read node "ex:foo" the publisher may return: 1457 1459 1461 error-data-not-authorized 1462 1463 1465 Figure 12: Establish-subscription access denied response 1467 If a request is rejected because the publisher is not able to serve 1468 it, the publisher SHOULD include in the returned error what 1469 subscription parameters would have been accepted for the request. 1470 However, there are no guarantee that subsequent requests for this 1471 subscriber or others will in fact be accepted. 1473 For example, for the following request: 1475 1477 1479 push-update 1480 1483 10 1484 encode-xml 1485 1486 1488 Figure 13: Establish-subscription request example 2 1490 A publisher that cannot serve on-change updates but periodic updates 1491 might return the following: 1493 1495 1497 error-no-such-option 1498 1499 100 1500 1502 Figure 14: Establish-subscription error response example 2 1504 4.7.2. Modify-subscription RPC 1506 The subscriber may send a modify-subscription PRC for a subscription 1507 previously established using RPC The subscriber may change any 1508 subscription parameters by including the new values in the modify- 1509 subscription RPC. Parameters not included in the rpc should remain 1510 unmodified. For illustration purposes we include an exchange example 1511 where a subscriber modifies the period of the subscription. 1513 1515 1517 push-update 1518 1519 1011 1520 1521 1524 250 1525 encode-xml 1526 1527 1529 Figure 15: Modify subscription request 1531 The publisher must respond explicitly positively (i.e., subscription 1532 accepted) or negatively (i.e., subscription rejected) to the request. 1533 Positive responses include the subscription-id of the accepted 1534 subscription. In that case a publisher may respond: 1536 1538 1540 ok 1541 1542 1544 1011 1545 1546 1548 Figure 16: Modify subscription response 1550 If the subscription modification is rejected, the publisher must send 1551 a response like it does for an establish-subscription and maintain 1552 the subscription as it was before the modification request. A 1553 subscription may be modified multiple times. 1555 A configured subscription cannot be modified using modify- 1556 subscription RPC. Instead, the configuration needs to be edited as 1557 needed. 1559 4.7.3. Delete-subscription RPC 1561 To stop receiving updates from a subscription and effectively delete 1562 a subscription that had previously been established using an 1563 establish-subscription RPC, a subscriber can send a delete- 1564 subscription RPC, which takes as only input the subscription-id. For 1565 example: 1567 1569 1571 1572 1011 1573 1574 1575 1577 1579 1580 1582 Figure 17: Delete subscription 1584 Configured subscriptions cannot be deleted via RPC, but have to be 1585 removed from the configuration. 1587 4.7.4. YANG Module Synchronization 1589 In order to fully support datastore replication, the receiver needs 1590 to know the YANG module library that is in use by server that is 1591 being replicated. The YANG 1.0 module library information is sent by 1592 a NETCONF server in the NETCONF 'hello' message. For YANG 1.1 1593 modules and all modules used with the RESTCONF 1594 [I-D.ietf-netconf-restconf] protocol, this information is provided by 1595 the YANG Library module (ietf-yang-library.yang from [RFC7895]. The 1596 YANG library information is important for the receiver to reproduce 1597 the set of object definitions used by the replicated datastore. 1599 The YANG library includes a module list with the name, revision, 1600 enabled features, and applied deviations for each YANG YANG module 1601 implemented by the server. The receiver is expected to know the YANG 1602 library information before starting a subscription. The "/modules- 1603 state/module-set-id" leaf in the "ietf-yang-library" module can be 1604 used to cache the YANG library information. [ED. NOTE: Should 1605 "module-set-id" be added to establish-subscription response?] 1607 The set of modules, revisions, features, and deviations can change at 1608 run-time (if supported by the server implementation). In this case, 1609 the receiver needs to be informed of module changes before data nodes 1610 from changed modules can be processed correctly. The YANG library 1611 provides a simple "yang-library-change" notification that informs the 1612 client that the library has changed somehow. The receiver then needs 1613 to re-read the entire YANG library data for the replicated server in 1614 order to detect the specific YANG library changes. The "ietf- 1615 netconf-notifications" module defined in [RFC6470] contains a 1616 "netconf-capability-change" notification that can identify specific 1617 module changes. For example, the module URI capability of a newly 1618 loaded module will be listed in the "added-capability" leaf-list, and 1619 the module URI capability of an removed module will be listed in the 1620 "deleted-capability" leaf-list. 1622 5. YANG module 1624 file "ietf-yang-push@2016-10-28.yang" 1625 module ietf-yang-push { 1626 yang-version 1.1; 1627 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; 1628 prefix yp; 1630 import ietf-inet-types { 1631 prefix inet; 1633 } 1634 import ietf-yang-types { 1635 prefix yang; 1636 } 1637 import ietf-event-notifications { 1638 prefix notif-bis; 1639 } 1641 organization "IETF"; 1642 contact 1643 "WG Web: 1644 WG List: 1646 WG Chair: Mahesh Jethanandani 1647 1649 WG Chair: Mehmet Ersue 1650 1652 Editor: Alexander Clemm 1653 1655 Editor: Eric Voit 1656 1658 Editor: Alberto Gonzalez Prieto 1659 1661 Editor: Ambika Prasad Tripathy 1662 1664 Editor: Einar Nilsen-Nygaard 1665 1667 Editor: Andy Bierman 1668 1670 Editor: Balazs Lengyel 1671 "; 1673 description 1674 "This module contains conceptual YANG specifications 1675 for YANG push."; 1677 revision 2016-10-28 { 1678 description 1679 "Updates to simplify modify-subscription, add anchor-time"; 1680 reference "YANG Datastore Push, draft-ietf-netconf-yang-push-04"; 1682 } 1684 feature on-change { 1685 description 1686 "This feature indicates that on-change updates are 1687 supported."; 1688 } 1690 /* 1691 * IDENTITIES 1692 */ 1694 /* Additional errors for subscription operations */ 1695 identity error-data-not-authorized { 1696 base notif-bis:error; 1697 description 1698 "No read authorization for a requested data node."; 1699 } 1701 /* Additional types of streams */ 1702 identity update-stream { 1703 description 1704 "Base identity to represent a conceptual system-provided 1705 datastream of datastore updates with predefined semantics."; 1706 } 1708 identity yang-push { 1709 base update-stream; 1710 description 1711 "A conceptual datastream consisting of all datastore 1712 updates, including operational and configuration data."; 1713 } 1715 identity operational-push { 1716 base update-stream; 1717 description 1718 "A conceptual datastream consisting of updates of all 1719 operational data."; 1720 } 1722 identity config-push { 1723 base update-stream; 1724 description 1725 "A conceptual datastream consisting of updates of all 1726 configuration data."; 1727 } 1728 identity custom-stream { 1729 base update-stream; 1730 description 1731 "A conceptual datastream for datastore 1732 updates with custom updates as defined by a user."; 1733 } 1735 /* Additional transport option */ 1736 identity http2 { 1737 base notif-bis:transport; 1738 description 1739 "HTTP2 notifications as a transport"; 1740 } 1742 /* 1743 * TYPE DEFINITIONS 1744 */ 1746 typedef filter-id { 1747 type uint32; 1748 description 1749 "A type to identify filters which can be associated with a 1750 subscription."; 1751 } 1753 typedef change-type { 1754 type enumeration { 1755 enum "create" { 1756 description 1757 "A new data node was created"; 1758 } 1759 enum "delete" { 1760 description 1761 "A data node was deleted"; 1762 } 1763 enum "modify" { 1764 description 1765 "The value of a data node has changed"; 1766 } 1767 } 1768 description 1769 "Specifies different types of changes that may occur 1770 to a datastore."; 1771 } 1773 typedef update-stream { 1774 type identityref { 1775 base update-stream; 1777 } 1778 description 1779 "Specifies a system-provided datastream."; 1780 } 1782 grouping update-filter { 1783 description 1784 "This groupings defines filters for push updates for a 1785 datastore tree. The filters define which updates are of 1786 interest in a push update subscription. Mixing and matching 1787 of multiple filters does not occur at the level of this 1788 grouping. When a push-update subscription is created, the 1789 filter can be a regular subscription filter, or one of the 1790 additional filters that are defined in this grouping."; 1791 choice update-filter { 1792 description 1793 "Define filters regarding which data nodes to include 1794 in push updates"; 1795 case subtree { 1796 description 1797 "Subtree filter."; 1798 anyxml subtree-filter { 1799 description 1800 "Subtree-filter used to specify the data nodes targeted 1801 for subscription within a subtree, or subtrees, of a 1802 conceptual YANG datastore. Objects matching the filter 1803 criteria will traverse the filter. The syntax follows 1804 the subtree filter syntax specified in RFC 6241, 1805 section 6."; 1806 reference "RFC 6241 section 6"; 1807 } 1808 } 1809 case xpath { 1810 description 1811 "XPath filter"; 1812 leaf xpath-filter { 1813 type yang:xpath1.0; 1814 description 1815 "Xpath defining the data items of interest."; 1816 } 1817 } 1818 } 1819 } 1821 grouping update-policy { 1822 description 1823 "This grouping describes the conditions under which an 1824 update will be sent as part of an update stream."; 1826 choice update-trigger { 1827 description 1828 "Defines necessary conditions for sending an event to 1829 the subscriber."; 1830 case periodic { 1831 description 1832 "The agent is requested to notify periodically the 1833 current values of the datastore or the subset 1834 defined by the filter."; 1835 leaf period { 1836 type yang:timeticks; 1837 mandatory true; 1838 description 1839 "Duration of time which should occur between periodic 1840 push updates. Where the anchor of a start-time is 1841 available, the push will include the objects and their 1842 values which exist at an exact multiple of timeticks 1843 aligning to this start-time anchor."; 1844 } 1845 leaf anchor-time { 1846 type yang:date-and-time; 1847 description 1848 "Designates a timestamp from which the series of 1849 periodic push updates are computed. The next update 1850 will take place at the next period interval from the 1851 anchor time. For example, for an anchor time at the 1852 top of a minute and a period interval of a minute, 1853 the next update will be sent at the top of the next 1854 minute."; 1855 } 1856 } 1857 case on-change { 1858 if-feature "on-change"; 1859 description 1860 "The agent is requested to notify changes in 1861 values in the datastore or a subset of it defined 1862 by a filter."; 1863 leaf no-synch-on-start { 1864 type empty; 1865 description 1866 "This leaf acts as a flag that determines behavior at the 1867 start of the subscription. When present, 1868 synchronization of state at the beginning of the 1869 subscription is outside the scope of the subscription. 1870 Only updates about changes that are observed from the 1871 start time, i.e. only push-change-update notifications 1872 are sent. 1873 When absent (default behavior), in order to facilitate 1874 a receiver's synchronization, a full update is sent 1875 when the subscription starts using a push-update 1876 notification, just like in the case of a periodic 1877 subscription. After that, push-change-update 1878 notifications only are sent unless the Publisher chooses 1879 to resynch the subscription again."; 1880 } 1881 leaf dampening-period { 1882 type yang:timeticks; 1883 mandatory true; 1884 description 1885 "Minimum amount of time that needs to have 1886 passed since the last time an update was 1887 provided."; 1888 } 1889 leaf-list excluded-change { 1890 type change-type; 1891 description 1892 "Use to restrict which changes trigger an update. 1893 For example, if modify is excluded, only creation and 1894 deletion of objects is reported."; 1895 } 1896 } 1897 } 1898 } 1900 grouping subscription-qos { 1901 description 1902 "This grouping describes Quality of Service information 1903 concerning a subscription. This information is passed to lower 1904 layers for transport priortization and treatment"; 1905 leaf dscp { 1906 if-feature "notif-bis:configured-subscriptions"; 1907 type inet:dscp; 1908 default "0"; 1909 description 1910 "The push update's IP packet transport priority. 1911 This is made visible across network hops to receiver. 1912 The transport priority is shared for all receivers of 1913 a given subscription."; 1914 } 1915 leaf subscription-priority { 1916 type uint8; 1917 description 1918 "Relative priority for a subscription. Allows an 1919 underlying transport layer perform informed load 1920 balance allocations between various subscriptions"; 1921 } 1922 leaf subscription-dependency { 1923 type string; 1924 description 1925 "Provides the Subscription ID of a parent subscription 1926 without which this subscription should not exist. In 1927 other words, there is no reason to stream these objects 1928 if another subscription is missing."; 1929 } 1930 } 1932 augment "/notif-bis:establish-subscription/notif-bis:input" { 1933 description 1934 "Define additional subscription parameters that apply 1935 specifically to push updates"; 1936 uses update-policy; 1937 uses subscription-qos; 1938 } 1939 augment "/notif-bis:establish-subscription/notif-bis:input/"+ 1940 "notif-bis:filter-type" { 1941 description 1942 "Add push filters to selection of filter types."; 1943 case update-filter { 1944 description 1945 "Additional filter options for push subscription."; 1946 uses update-filter; 1947 } 1948 } 1949 augment "/notif-bis:establish-subscription/notif-bis:output" { 1950 description 1951 "Allow to return additional subscription parameters that apply 1952 specifically to push updates."; 1953 uses update-policy; 1954 uses subscription-qos; 1955 } 1956 augment "/notif-bis:establish-subscription/notif-bis:output/"+ 1957 "notif-bis:result/notif-bis:no-success/notif-bis:filter-type" { 1958 description 1959 "Add push filters to selection of filter types."; 1960 case update-filter { 1961 description 1962 "Additional filter options for push subscription."; 1963 uses update-filter; 1964 } 1965 } 1966 augment "/notif-bis:modify-subscription/notif-bis:input" { 1967 description 1968 "Define additional subscription parameters that apply 1969 specifically to push updates."; 1971 uses update-policy; 1972 } 1973 augment "/notif-bis:modify-subscription/notif-bis:input/"+ 1974 "notif-bis:filter-type" { 1975 description 1976 "Add push filters to selection of filter types."; 1977 case update-filter { 1978 description 1979 "Additional filter options for push subscription."; 1980 uses update-filter; 1981 } 1982 } 1983 augment "/notif-bis:modify-subscription/notif-bis:output" { 1984 description 1985 "Allow to retun additional subscription parameters that apply 1986 specifically to push updates."; 1987 uses update-policy; 1988 uses subscription-qos; 1989 } 1990 augment "/notif-bis:modify-subscription/notif-bis:output/"+ 1991 "notif-bis:result/notif-bis:no-success/notif-bis:filter-type" { 1992 description 1993 "Add push filters to selection of filter types."; 1994 case update-filter { 1995 description 1996 "Additional filter options for push subscription."; 1997 uses update-filter; 1998 } 1999 } 2000 notification push-update { 2001 description 2002 "This notification contains a push update, containing 2003 data subscribed to via a subscription. 2004 This notification is sent for periodic updates, for a 2005 periodic subscription. It can also be used for 2006 synchronization updates of an on-change subscription. 2007 This notification shall only be sent to receivers 2008 of a subscription; it does not constitute a general-purpose 2009 notification."; 2010 leaf subscription-id { 2011 type notif-bis:subscription-id; 2012 mandatory true; 2013 description 2014 "This references the subscription because of which the 2015 notification is sent."; 2016 } 2017 leaf time-of-update { 2018 type yang:date-and-time; 2019 description 2020 "This leaf contains the time of the update."; 2021 } 2022 leaf updates-not-sent { 2023 type empty; 2024 description 2025 "This is a flag which indicates that not all data nodes 2026 subscribed to are included included with this 2027 update. In other words, the publisher has failed to 2028 fulfill its full subscription obligations. 2029 This may lead to intermittent loss of synchronization 2030 of data at the client. Synchronization at the client 2031 can occur when the next push-update is received."; 2032 } 2033 anydata datastore-contents { 2034 description 2035 "This contains the updated data. It constitutes a snapshot 2036 at the time-of-update of the set of data that has been 2037 subscribed to. The format and syntax of the data 2038 corresponds to the format and syntax of data that would be 2039 returned in a corresponding get operation with the same 2040 filter parameters applied."; 2041 } 2042 } 2043 notification push-change-update { 2044 if-feature "on-change"; 2045 description 2046 "This notification contains an on-change push update. 2047 This notification shall only be sent to the receivers 2048 of a subscription; it does not constitute a general-purpose 2049 notification."; 2050 leaf subscription-id { 2051 type notif-bis:subscription-id; 2052 mandatory true; 2053 description 2054 "This references the subscription because of which the 2055 notification is sent."; 2056 } 2057 leaf time-of-update { 2058 type yang:date-and-time; 2059 description 2060 "This leaf contains the time of the update, i.e. the 2061 time at which the change was observed."; 2062 } 2063 leaf updates-not-sent { 2064 type empty; 2065 description 2066 "This is a flag which indicates that not all changes which 2067 have occured since the last update are included with this 2068 update. In other words, the publisher has failed to 2069 fulfill its full subscription obligations, for example in 2070 cases where it was not able to keep up with a change burst. 2071 To facilitate synchronization, a publisher MAY subsequently 2072 send a push-update containing a full snapshot of subscribed 2073 data. Such a push-update might also be triggered by a 2074 subscriber requesting an on-demand synchronization."; 2075 } 2076 anydata datastore-changes { 2077 description 2078 "This contains datastore contents that has changed 2079 since the previous update, per the terms of the 2080 subscription. Changes are encoded analogous to 2081 the syntax of a corresponding yang-patch operation, 2082 i.e. a yang-patch operation applied to the YANG datastore 2083 implied by the previous update to result in the current 2084 state (and assuming yang-patch could also be applied to 2085 operational data)."; 2086 } 2087 } 2088 augment "/notif-bis:subscription-started" { 2089 description 2090 "This augmentation adds push subscription parameters 2091 to the notification that a subscription has 2092 started and data updates are beginning to be sent. 2093 This notification shall only be sent to receivers 2094 of a subscription; it does not constitute a general-purpose 2095 notification."; 2096 uses update-policy; 2097 uses subscription-qos; 2098 } 2099 augment "/notif-bis:subscription-started/notif-bis:filter-type" { 2100 description 2101 "This augmentation allows to include additional update filters 2102 options to be included as part of the notification that a 2103 subscription has started."; 2104 case update-filter { 2105 description 2106 "Additional filter options for push subscription."; 2107 uses update-filter; 2108 } 2109 } 2110 augment "/notif-bis:subscription-modified" { 2111 description 2112 "This augmentation adds push subscription parameters 2113 to the notification that a subscription has 2114 been modified. 2116 This notification shall only be sent to receivers 2117 of a subscription; it does not constitute a general-purpose 2118 notification."; 2119 uses update-policy; 2120 uses subscription-qos; 2121 } 2122 augment "/notif-bis:subscription-modified/notif-bis:filter-type" { 2123 description 2124 "This augmentation allows to include additional update 2125 filters options to be included as part of the notification 2126 that a subscription has been modified."; 2127 case update-filter { 2128 description 2129 "Additional filter options for push subscription."; 2130 uses update-filter; 2131 } 2132 } 2133 augment "/notif-bis:filters/notif-bis:filter/"+ 2134 "notif-bis:filter-type" { 2135 description 2136 "This container adds additional update filter options 2137 to the list of configurable filters 2138 that can be applied to subscriptions. This facilitates 2139 the reuse of complex filters once defined."; 2140 case update-filter { 2141 uses update-filter; 2142 } 2143 } 2144 augment "/notif-bis:subscription-config/notif-bis:subscription" { 2145 description 2146 "Contains the list of subscriptions that are configured, 2147 as opposed to established via RPC or other means."; 2148 uses update-policy; 2149 uses subscription-qos; 2150 } 2151 augment "/notif-bis:subscription-config/notif-bis:subscription/"+ 2152 "notif-bis:filter-type" { 2153 description 2154 "Add push filters to selection of filter types."; 2155 case update-filter { 2156 uses update-filter; 2157 } 2158 } 2159 augment "/notif-bis:subscriptions/notif-bis:subscription" { 2160 description 2161 "Contains the list of currently active subscriptions, 2162 i.e. subscriptions that are currently in effect, 2163 used for subscription management and monitoring purposes. 2165 This includes subscriptions that have been setup via RPC 2166 primitives, e.g. establish-subscription, delete-subscription, 2167 and modify-subscription, as well as subscriptions that 2168 have been established via configuration."; 2169 uses update-policy; 2170 uses subscription-qos; 2171 } 2172 augment "/notif-bis:subscriptions/notif-bis:subscription/"+ 2173 "notif-bis:filter-type" { 2174 description 2175 "Add push filters to selection of filter types."; 2176 case update-filter { 2177 description 2178 "Additional filter options for push subscription."; 2179 uses update-filter; 2180 } 2181 } 2182 } 2184 2186 6. Security Considerations 2188 Subscriptions could be used to attempt to overload publishers of YANG 2189 datastores. For this reason, it is important that the publisher has 2190 the ability to decline a subscription request if it would deplete its 2191 resources. In addition, a publisher needs to be able to suspend an 2192 existing subscription when needed. When this occur, the subscription 2193 status is updated accordingly and the receivers are notified. 2194 Likewise, requests for subscriptions need to be properly authorized. 2196 A subscription could be used to retrieve data in subtrees that a 2197 receiver has no authorized access to. Therefore it is important that 2198 data pushed based on subscriptions is authorized in the same way that 2199 regular data retrieval operations are. Data being pushed to a 2200 receiver needs therefore to be filtered accordingly, just like if the 2201 data were being retrieved on-demand. The Netconf Authorization 2202 Control Model applies. 2204 A subscription could be configured on another receiver's behalf, with 2205 the goal of flooding that receiver with updates. One or more 2206 publishers could be used to overwhelm a receiver which doesn't even 2207 support subscriptions. Receivers which do not want pushed data need 2208 only terminate or refuse any transport sessions from the publisher. 2209 In addition, the Netconf Authorization Control Model SHOULD be used 2210 to control and restrict authorization of subscription configuration. 2212 7. Acknowledgments 2214 For their valuable comments, discussions, and feedback, we wish to 2215 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei 2216 Guo, Michael Scharf, Sharon Chisholm, and Guangying Zheng. 2218 8. References 2220 8.1. Normative References 2222 [I-D.ietf-netconf-5277bis] 2223 Clemm, A., Gonzalez Prieto, A., Voit, E., Tripathy, A., 2224 Nilsen-Nygaard, E., Chisholm, S., and H. Trevino, 2225 "Subscribing to YANG-Defined Event Notifications", draft- 2226 ietf-netconf-5277bis-01 (work in progress), October 2016. 2228 [I-D.ietf-netconf-yang-patch] 2229 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch 2230 Media Type", draft-ietf-netconf-yang-patch-12 (work in 2231 progress), September 2016. 2233 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 2234 Base Notifications", RFC 6470, February 2012. 2236 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2237 Protocol (NETCONF) Access Control Model", RFC 6536, March 2238 2012. 2240 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 2241 Library", RFC 7895, June 2016. 2243 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", 2244 RFC 7950, August 2016. 2246 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2247 RFC 7951, August 2016. 2249 8.2. Informative References 2251 [I-D.ietf-netconf-restconf] 2252 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2253 Protocol", I-D draft-ietf-netconf-restconf-17, September 2254 2016. 2256 [RFC1157] Case, J., "A Simple Network Management Protocol (SNMP)", 2257 RFC 1157, May 1990. 2259 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 2260 Notifications", RFC 5277, July 2008. 2262 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 2263 Bierman, "Network Configuration Protocol (NETCONF)", 2264 RFC 6241, June 2011. 2266 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 2267 for Subscription to YANG Datastores", RFC 7923, June 2016. 2269 Appendix A. Issues that are currently being worked and resolved 2271 (To be removed by RFC editor prior to publication) 2273 A.1. Unresolved and yet-to-be addressed issues 2275 Which stream types to introduce, if any based on implications of 2276 opstate. Current list includes streams for all operational and for 2277 all config data. Consider adding stream for operational data minus 2278 counters. 2280 We need a new Metadata filter. But so does traditional GET. This 2281 should be relevant independent of subscriptions. This has 2282 implications of ephemeral requirements from I2RS 2284 Should we allow an interplay of filter types in a single 2285 subscription. Or should we keep them fully independent. 2287 Do we add a counter for the number of object changes during a 2288 dampening period? 2290 A.2. Agreement in principal 2292 Do we need an extension for NACM to support filter out datastore 2293 nodes for which the receiver has no read access? (And how does this 2294 differ from existing GET, which must do the same filtering?) In 2295 5277, such filtering is done at the notification level. Yang-push 2296 includes notification-content filtering. This may be very expensive 2297 in terms of processing. Andy suggestion: only accept Yang-push 2298 subscriptions for subtrees the user has rights for all the nodes in 2299 the subtree. Changes to those rights trigger a subscription 2300 termination. Should we codify this, or let vendors determine when 2301 per subtree filtering might be applied? 2303 Need to add a new RPC to request enabling a resynch for an existing 2304 on-change subscription exposed on publisher 2306 Appendix B. Changes between revisions 2308 (To be removed by RFC editor prior to publication) 2310 v03 to v04 2312 o Updates-not-sent flag added 2314 o Not notifiable extension added 2316 o Dampening period is for whole subscription, not single objects 2318 o Moved start/stop into rfc5277bis 2320 o Client and Server changed to subscriber, publisher, and receiver 2322 o Anchor time for periodic 2324 o Message format for synchronization (i.e. synch-on-start) 2326 o Material moved into 5277bis 2328 o QoS parameters supported, by not allowed to be modified by RPC 2330 o Text updates throughout 2332 Authors' Addresses 2334 Alexander Clemm 2335 Sympotech 2337 Email: alex@sympotech.com 2339 Eric Voit 2340 Cisco Systems 2342 Email: evoit@cisco.com 2344 Alberto Gonzalez Prieto 2345 Cisco Systems 2347 Email: albertgo@cisco.com 2348 Ambika Prasad Tripathy 2349 Cisco Systems 2351 Email: ambtripa@cisco.com 2353 Einar Nilsen-Nygaard 2354 Cisco Systems 2356 Email: einarnn@cisco.com 2358 Andy Bierman 2359 YumaWorks 2361 Email: andy@yumaworks.com 2363 Balazs Lengyel 2364 Ericsson 2366 Email: balazs.lengyel@ericsson.com