idnits 2.17.1 draft-ietf-netconf-notification-capabilities-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 237 has weird spacing: '...on-sent boo...' -- The document date (March 1, 2019) is 1876 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-25) exists of draft-ietf-netconf-yang-push-22 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Netconf B. Lengyel 3 Internet-Draft Ericsson 4 Intended status: Standards Track A. Clemm 5 Expires: September 2, 2019 Huawei USA 6 March 1, 2019 8 YangPush Notification Capabilities 9 draft-ietf-netconf-notification-capabilities-01 11 Abstract 13 This document proposes a YANG module that allows a YANG server to 14 specify server capabilities related to "Subscription to YANG 15 Datastores" (YangPush). It proposes to use YANG Instance Data to 16 document this information already in implementation time. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on September 2, 2019. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 3. Notification Capability Model . . . . . . . . . . . . . . . . 4 55 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 5 56 3.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 6 57 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 58 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 59 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 9 60 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 9 61 6. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 9 62 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 63 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 64 7.2. Informative References . . . . . . . . . . . . . . . . . 10 65 Appendix A. Changes between revisions . . . . . . . . . . . . . 10 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 68 1. Terminology 70 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 71 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 72 "OPTIONAL" in this document are to be interpreted as described in BCP 73 14 [RFC2119] [RFC8174] when, and only when, they appear in all 74 capitals, as shown here. 76 The terms Yang-Push, On-change subscription and Periodic subscription 77 are used as defined in [I-D.ietf-netconf-yang-push] 79 On-change Notification Capability: The capability of the YANG server 80 to support On-change subscriptions. 82 Implementation-time information: Information about the YANG server's 83 behavior that is made available during the implementation of the 84 server, available from a source other then a running Yang server. 86 Rutime-information: Information about the YANG server's behavior that 87 is available from the running YANG server via a protocol like 88 NETCONF, RESTCONF or HTTPS. 90 2. Introduction 92 As defined in [I-D.ietf-netconf-yang-push] a YANG server may allow 93 clients to subscribe to updates from a datastore and subsequently 94 push such update notifications to the client. Notifications may be 95 sent periodically or on-change (more or less immediately after each 96 change). 98 A YANG server supporting YANG-Push has a number of capabilities that 99 are determined during the implementation of the server. These 100 include: 102 o Supported dampening periods for on-change subscriptions 104 o Supported (reporting) periods for periodic subscriptions 106 o Maximum number of objects that can be sent in an update 108 o The set of data nodes for which on-change notification is 109 supported 111 Servers MAY have limitations in how many update notifications and how 112 many datastore node updates they can send out in a certain time- 113 period. 115 In some cases, a publisher supporting on-change notifications will 116 not be able to push updates for some object types on-change. Reasons 117 for this might be that the value of the datastore node changes 118 frequently (e.g. in-octets counter), that small object changes are 119 frequent and meaningless (e.g., a temperature gauge changing 0.1 120 degrees), or that the implementation is not capable of on-change 121 notification for a particular object. In those cases, it will be 122 important for client applications to have a way to identify for which 123 objects on-change notifications are supported and for which ones not. 125 Faced with the reality that support for on-change notification does 126 not mean that such notifications will be sent for any specific data 127 node, client/management applications can not rely on the on-change 128 functionality unless the client has some means to identify for which 129 objects on-change notifications are supported. YANG models are meant 130 to be used as an interface contract. Without identification of data 131 nodes supporting on-change, this contract would only state the YANG 132 server may (or may not) send on-change notifications for a data node 133 specified in a YANG module. 135 This document proposes a YANG module that allows a client to discover 136 YANG-Push related capabilities. 138 YANG-Push related capability information will be needed both in 139 implementation-time and run-time. 141 Implementation time information is needed by Network Management 142 System (NMS) implementers. During NMS implementation for any 143 functionality that depends on the notifications the information about 144 on change notification capability is needed. If the information is 145 not available early in some document, but only as instance data from 146 the network node, the NMS implementation will be delayed, because it 147 has to wait for the network node to be ready. Also assuming that all 148 NMS implementers will have a correctly configured network node 149 available to retrieve data from, is an expensive proposition. (An 150 NMS may handle dozens of network node types.) Often a fully 151 functional NMS is a requirement for introducing a new network node 152 type into a network, so delaying the NMS effectively delays the 153 availability of the network node as well. 155 Implementation time information is needed by system integrators. 156 When introducing a network node type into their network, operators 157 often need to integrate the node type into their own management 158 system. The NMS may have management functions that depend on on- 159 change notifications. The network operator needs to plan his 160 management practices and NMS implementation before he even decides to 161 buy the specific network node type. Moreover the decision to buy the 162 node type sometimes depends on these management possibilities. 164 Run-time information is needed 166 o for any "purely model driven" client, e.g. a NETCONF-browser. As 167 long as it has a valid model to read the capability information, 168 it does not care which data nodes send notification, it will just 169 handle what is available. 171 o in case the capability might change during run-time e.g. due to 172 licensing, HW constraints etc. 174 o to check that early, implementation time capability information 175 about the capabilities is indeed what the server implements (is 176 the supplied documentation correct?) 178 3. Notification Capability Model 180 It is a goal to provide YangPush notification capability information 181 in a format that is 183 o vendor independent (standard) 185 o formal (no freeform English text please) 187 o the same both in implementation-time and run-time 189 The YANG module ietf-notification-capabilities is defined to provide 190 the information. It contains 192 a set of capabilities related to the amount of notifications the 193 server can send out 194 a default on-change notification capability separately for config 195 false and config true data nodes 197 an on-change-notification-capability list containing a potentially 198 different true/false notification capability for a few data nodes 199 in the schema tree. Unless a node is in this list with a specific 200 capability value, it inherits its on-change-notification- 201 capability from its parent in the data tree, or from the relevant 202 default values. It is assumed that only a small number of nodes 203 will be included in this list: special cases where the default 204 behavior is not followed. For a detailed description of the usage 205 of this list see the description in the YANG module. 207 The information SHALL be provided in two ways both following the 208 ietf-notification-capabilities module: 210 o It SHALL be provided by the implementer as YANG instance data file 211 complying to the [I-D.lengyel-netmod-yang-instance-data]. The 212 file SHALL be available already in implementation time retrievable 213 in a way that does not depend on a live network node. E.g. 214 download from product Website. 216 o It SHALL be available via NETCONF or RESTCONF from the live YANG 217 server during runtime. 219 3.1. Tree Diagram 221 The following tree diagram [RFC8340] provides an overview of the data 222 model. 224 module: ietf-notification-capabilities 225 +--ro yangpush-notification-capabilities 226 +--ro minimum-dampening-period? uint32 227 +--ro (update-period)? 228 | +--:(minimum-update-period) 229 | | +--ro minimum-update-period? uint32 230 | +--:(supported-update-period) 231 | +--ro supported-update-period* uint32 232 +--ro max-objects-per-update? uint32 233 +--ro notification-sent-for-config-default? boolean 234 +--ro notification-sent-for-state-default? boolean 235 +--ro on-change-notification-capability* [node-selector] 236 +--ro node-selector nacm:node-instance-identifier 237 +--ro on-change-notification-sent boolean 239 3.2. YANG Module 241 file "ietf-notification-capabilities.yang" 243 module ietf-notification-capabilities { 244 yang-version 1.1; 245 namespace 246 "urn:ietf:params:xml:ns:yang:ietf-notification-capabilities"; 247 prefix inc; 249 import ietf-netconf-acm { prefix nacm; } 251 organization 252 "IETF NETCONF (Network Configuration) Working Group"; 254 contact 255 "WG Web: 256 WG List: 258 WG Chair: Kent Watsen 259 261 WG Chair: Mahesh Jethanandani 262 264 Editor: Balazs Lengyel 265 "; 267 description "This module specifies YANG-Push related server 268 capabilities. It contains 269 - capabilities related to the amount of notifications the 270 server can send out 271 - default and schema node specific information specifying 272 the set of data nodes for which the YANG server is capable 273 of sending on-change notifications. 275 On-change notification capability is marked as true or false. 276 This marking is inherited from the parent down the data tree 277 unless explicitly marked otherwise. 279 On-change notifications SHALL be sent for a config=true 280 data node if one of the following is true: 281 - if it is a top level data-node and is not specified in the 282 on-change-notification-capability list and the 283 notification-sent-for-config-default is true; or 284 - notifications are sent for its parent data node and it is 285 not specified in the on-change-notification-capability list; or 286 - it is specified in the on-change-notification-capability 287 list and has a on-change-notification-sent value true. 289 On-change notifications SHALL be sent for a config=false 290 data node if one of the following is true: 291 - if it is a top level data-node or has a config=true parent 292 data node and is not specified in the 293 on-change-notification-capability list and the 294 notification-sent-for-state-default is true; or 295 - notifications are sent for its parent data node 296 which is also config=false and it is 297 not specified in the on-change-notification-capability list; or 298 - it is specified in the on-change-notification-capability 299 list and has an on-change-notification-sent value true or 300 "; 302 revision 2019-02-28 { 303 description "Initial version"; 304 reference 305 "RFC XXX: YangPush Notification Capabilities"; 306 } 308 container yangpush-notification-capabilities { 309 config false; 310 description "YANG-Push related server capabilities"; 312 leaf minimum-dampening-period { 313 type uint32; 314 units msec; 315 description "The minimum dampening period supported for on-change 316 subscriptions."; 317 } 319 choice update-period { 320 description "Supported period values."; 321 leaf minimum-update-period { 322 type uint32; 323 units centiseconds; 324 description "Minimum update period supported for a 325 periodic subscription."; 326 } 328 leaf-list supported-update-period { 329 type uint32; 330 units centiseconds; 331 description "Specific supported update period values 332 for a periodic subscription"; 333 } 335 } 337 leaf max-objects-per-update { 338 type uint32; 339 description "Maximum number of objects that can be sent 340 in an update"; 341 } 343 leaf notification-sent-for-config-default { 344 type boolean; 345 default true; 346 description "Specifies the default value for 347 top level configuration data nodes for the 348 on-change-notification-sent capability."; 349 } 351 leaf notification-sent-for-state-default { 352 type boolean; 353 default false; 354 description "Specifies the default value 355 top level state data nodes for the 356 on-change-notification-sent capability."; 357 } 359 list on-change-notification-capability { 360 key node-selector ; 361 description "A list of data nodes that have the 362 on-change-notification-capability specifically defined. 364 Should be used when specific data nodes support 365 on-change notification in a module/subtree that 366 generally does not support it or when some data nodes 367 do not support the notification in a module/subtree 368 that generally supports on-change notifications."; 370 leaf node-selector { 371 type nacm:node-instance-identifier; 372 description "Selects the data nodes for which 373 on-change capability is specified."; 374 } 376 leaf on-change-notification-sent { 377 type boolean; 378 mandatory true; 379 description "Specifies whether the YANG server will 380 send on-change notifications for the selected 381 data nodes."; 382 } 384 } 385 } 386 } 388 390 4. Security Considerations 392 The YANG module defined in this document is designed to be accessed 393 via YANG based management protocols, such as NETCONF and RESTCONF. 394 Both of these protocols have mandatory-to- implement secure transport 395 layers (e.g., SSH, TLS) with mutual authentication. 397 The NETCONF access control model (NACM) provides the means to 398 restrict access for particular users to a pre-configured subset of 399 all available protocol operations and content. 401 The data in this module is not security sensitive. 403 5. IANA Considerations 405 5.1. The IETF XML Registry 407 This document registers one URI in the IETF XML registry [RFC3688]. 408 Following the format in [RFC3688], the following registrations are 409 requested: 411 URI: urn:ietf:params:xml:ns:yang:ietf-notification-capabilities 412 Registrant Contact: The NETCONF WG of the IETF. 413 XML: N/A, the requested URI is an XML namespace. 415 5.2. The YANG Module Names Registry 417 This document registers one YANG module in the YANG Module Names 418 registry [RFC7950]. Following the format in [RFC7950], the the 419 following registrations are requested: 421 name: ietf-notification-capabilities 422 namespace: urn:ietf:params:xml:ns:yang:ietf-notification-capabilities 423 prefix: inc 424 reference: RFC XXXX 426 6. Open Issues 428 Do we need separate defaults/individual lists for every datastore? 429 Proposal: no, it would be an overkill. 431 Should type nacm:node-instance-identifier be moved to yang-types? 432 It is useful for more then just nacm. 434 7. References 436 7.1. Normative References 438 [I-D.ietf-netconf-yang-push] 439 Clemm, A., Voit, E., Prieto, A., Tripathy, A., Nilsen- 440 Nygaard, E., Bierman, A., and B. Lengyel, "Subscription to 441 YANG Datastores", draft-ietf-netconf-yang-push-22 (work in 442 progress), February 2019. 444 [I-D.lengyel-netmod-yang-instance-data] 445 Lengyel, B. and B. Claise, "YANG Based Instance Data Files 446 Format", draft-lengyel-netmod-yang-instance-data-05 (work 447 in progress), October 2018. 449 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 450 RFC 7950, DOI 10.17487/RFC7950, August 2016, 451 . 453 7.2. Informative References 455 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 456 Requirement Levels", BCP 14, RFC 2119, 457 DOI 10.17487/RFC2119, March 1997, 458 . 460 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 461 DOI 10.17487/RFC3688, January 2004, 462 . 464 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 465 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 466 May 2017, . 468 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 469 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 470 . 472 Appendix A. Changes between revisions 474 v00 - v01 476 o Add more capabilities: minimum period, supported period max-number 477 of objects, min dampening period, dampening supported 479 Authors' Addresses 481 Balazs Lengyel 482 Ericsson 483 Magyar Tudosok korutja 11 484 1117 Budapest 485 Hungary 487 Email: balazs.lengyel@ericsson.com 489 Alexander Clemm 490 Huawei USA 491 2330 Central Expressway 492 Santa Clara, CA 95050 493 USA 495 Email: ludwig@clemm.org