idnits 2.17.1 draft-lengyel-netconf-notification-capabilities-02.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 206 has weird spacing: '...on-sent boo...' -- The document date (July 2, 2018) is 2124 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-17 == Outdated reference: A later version (-05) exists of draft-lengyel-netmod-yang-instance-data-02 Summary: 0 errors (**), 0 flaws (~~), 4 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: January 3, 2019 Huawei USA 6 July 2, 2018 8 YangPush Notification Capabilities 9 draft-lengyel-netconf-notification-capabilities-02 11 Abstract 13 This document proposes a YANG module that allows a YANG server to 14 specify for which data nodes it will send "YANG Datastore 15 Subscription" on-change notifications. It also proposes to use YANG 16 Instance Data to document this information 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 January 3, 2019. 35 Copyright Notice 37 Copyright (c) 2018 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. On-change Notification Capability Model . . . . . . . . . . . 4 55 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 5 56 3.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 5 57 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 58 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 59 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 8 60 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 8 61 6. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 64 7.2. Informative References . . . . . . . . . . . . . . . . . 9 65 Appendix A. Changes between revisions . . . . . . . . . . . . . 9 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 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 On-change Notification Capability: The capability of the YANG server 77 to send on-change notifications on the change of the value for a 78 specific data node. 80 Implementation-time information: Information about the YANG server's 81 behavior that is made available during the implementation of the 82 server, available from a source other then a running Yang server. 84 Rutime-information: Information about the YANG server's behavior that 85 is available from the running YANG server via a protocol like 86 NETCONF, RESTCONF or HTTPS. 88 2. Introduction 90 As defined in [I-D.ietf-netconf-yang-push] a YANG server may allow 91 clients to subscribe to updates from a datastore and subsequently 92 push such update notifications to the client. Notifications may be 93 sent periodically or on-change (more or less immendiately after each 94 change). 96 In some cases, a publisher supporting on-change notifications will 97 not be able to push updates for some object types on-change. Reasons 98 for this might be that the value of the datastore node changes 99 frequently (e.g. in-octets counter), that small object changes are 100 frequent and meaningless (e.g., a temperature gauge changing 0.1 101 degrees), or that the implementation is not capable of on-change 102 notification for a particular object. In those cases, it will be 103 important for client applications to have a way to identify for which 104 objects on-change notifications are supported and for which ones are 105 not supported. 107 Faced with the reality that support for on-change notification does 108 not mean that such notifications will be sent for any specific data 109 node, client/management applications can not rely on the on-change 110 functionality unless the client has some means to identify for which 111 objects on-change notifications are supported and for which ones are 112 not supported. YANG models are meant to be used as an interface 113 contract. Without identification of data nodes supporting on-change, 114 this contract would only state the YANG server may (or may not) send 115 on-change notifications for a data node specified in a YANG module. 117 This document proposes a YANG module that allows a client to identify 118 which data nodes support on-change notification, removing the 119 uncertainty for on-change notifications. 121 On-change Notification Capability information will be needed both in 122 implementation-time and run-time. 124 Run-time information is needed 126 o for any "purely model driven" client, e.g. a Netconf-browser. As 127 long as it has a valid model, it does not care which data nodes 128 send notification, it will just handle whats available. 130 o to check that early implementation time information about the 131 capability is indeed what the server supports 133 o in case the capability might change during run-time e.g. due to 134 licensing, HW constraints etc. 136 Implementation time information is needed by Network Management 137 System (NMS) implementers. During NMS implementation for any 138 functionality that depends on the notifications the information about 139 on change notification capability is needed. If the information is 140 not available early in some document, but only as instance data from 141 the network node, the NMS implementation will be delayed, because it 142 has to wait for the network node to be ready. Also assuming that all 143 NMS implementers will have a correctly configured network node 144 available to retrieve data from, is an expensive proposition. (An 145 NMS may handle dozens of network node types.) Often a fully 146 functional NMS is a requirement for introducing a new network node 147 type into a network, so delaying the NMS effectively delays the 148 availability of the network node as well. 150 Implementation time information is needed by system integrators. 151 System integrators will need information about on change notification 152 capability early. When introducing a network node type into their 153 network operators often need to integrate the node type into their 154 own management system. The NMS may have management functions that 155 depend on on-change notifications. The network operator needs to 156 plan his management practices and NMS implementation before he even 157 decides to buy the specific network node type. Moreover the decision 158 to buy the node type sometimes depends on these management 159 possibilities. 161 3. On-change Notification Capability Model 163 As described above a number of stakeholders need information about 164 the on change notification capability both in implementation and run- 165 time. It is a goal to provide this information in a format that is 167 o vendor independent (standard) 169 o formal (no freeform English text please) 171 o the same both in implementation-time and run-time 173 The YANG module ietf-notification-capabilities is defined to provide 174 information about the on-change notification capabilities. There is 175 a default notification capability separately for config false and 176 config true data nodes. There is also an on-change-notification- 177 capability list containing a potentially different true/false 178 notification capability for any data node in the schema tree. Unless 179 a node is in the list with a specific capability value, it inherits 180 its on-change-notification-capability from its parent in the data 181 tree, or from the relevant default values. 183 The instance information SHALL be provided in two ways both following 184 the ietf-notification-capabilities module: 186 o It SHALL be provided by the implementer as YANG instance data file 187 complying to the [I-D.lengyel-netmod-yang-instance-data]. The 188 file SHALL be available already in implementation time retrievable 189 in a way that does not depend on a live network node. E.g. 190 download from product Website. 192 o It SHALL be available via Netconf or Restconf from the live YANG 193 server during runtime. 195 3.1. Tree Diagram 197 The following tree diagram [RFC8340] provides an overview of the data 198 model. 200 module: ietf-notification-capabilities 201 +--ro on-change-notification-capability 202 +--ro notification-sent-for-config-default? boolean 203 +--ro notification-sent-for-state-default? boolean 204 +--ro on-change-notification-capability* [node-selector] 205 +--ro node-selector nacm:node-instance-identifier 206 +--ro on-change-notification-sent boolean 208 3.2. YANG Module 210 file "ietf-notification-capabilities.yang" 212 module ietf-notification-capabilities { 213 yang-version 1.1; 214 namespace 215 "urn:ietf:params:xml:ns:yang:ietf-notification-capabilities"; 216 prefix inc; 218 import ietf-netconf-acm { prefix nacm; } 220 organization 221 "IETF NETCONF (Network Configuration) Working Group"; 223 contact 224 "WG Web: 225 WG List: 227 WG Chair: Kent Watsen 228 230 WG Chair: Mahesh Jethanandani 231 233 Editor: Balazs Lengyel 234 "; 236 description "This module specifies for which data nodes will the 237 YANG server send on-change notifications. 239 On-change notification capability is marked as true or false. 240 This marking is inherited from the parent down the data tree 241 unless explicitly marked otherwise. 243 On-change notifications SHALL be sent for a config=true 244 data node if one of the following is true: 245 - it is specified in the on-change-notification-capability 246 list and has a on-change-notification-sent value true or 247 - notifications are sent for its parent data node and it is 248 not specified in the on-change-notification-capability list or 249 - if it is a top level data-node and is not specified in the 250 on-change-notification-capability list and the 251 notification-sent-for-config-default is true. 253 On-change notifications SHALL be sent for a config=false 254 data node if one of the following is true: 255 - it is specified in the on-change-notification-capability 256 list and has an on-change-notification-sent value true or 257 - notifications are sent for its parent data node 258 which is also config=false and it is 259 not specified in the on-change-notification-capability list or 260 - if it is a top level data-node or has a config=true parent 261 data node and is not specified in the 262 on-change-notification-capability list and the 263 notification-sent-for-state-default is true. 264 "; 266 reference "RFC XXXX Yang-Push"; 268 revision 2018-07-02 { 269 description "Initial version"; 270 reference 271 "RFC XXX: YangPush Notification Capabilities"; 272 } 274 container on-change-notification-capability { 275 config false; 276 description "Contains default values for the 277 on-change-notifiction-capability and a list of data nodes that 278 have the on-change-notification-capability specifically defined."; 280 leaf notification-sent-for-config-default { 281 type boolean; 282 default true; 283 description "Specifies the default value for 284 top level configuration data nodes for the 285 on-change-notification-sent capability."; 286 } 288 leaf notification-sent-for-state-default { 289 type boolean; 290 default false; 291 description "Specifies the default value 292 top level state data nodes for the 293 on-change-notification-sent capability."; 294 } 296 list on-change-notification-capability { 297 key node-selector ; 298 description "A list of data nodes that have the 299 on-change-notification-capability specifically defined. 301 Should be used when specific data nodes support 302 on-change notification in a module/subtree that 303 generally does not support it or when some data nodes 304 do not support the notification in a module/subtree 305 that generally supports on-change notifications."; 307 leaf node-selector { 308 type nacm:node-instance-identifier; 309 } 311 leaf on-change-notification-sent { 312 type boolean; 313 mandatory true; 314 description "Specifies whether the YANG server will 315 send on-change notifications for the selected 316 data nodes."; 317 } 318 } 319 } 320 } 322 324 4. Security Considerations 326 The YANG module defined in this document is designed to be accessed 327 via YANG based management protocols, such as NETCONF and RESTCONF. 328 Both of these protocols have mandatory-to- implement secure transport 329 layers (e.g., SSH, TLS) with mutual authentication. 331 The NETCONF access control model (NACM) provides the means to 332 restrict access for particular users to a pre-configured subset of 333 all available protocol operations and content. 335 5. IANA Considerations 337 5.1. The IETF XML Registry 339 This document registers one URI in the IETF XML registry [RFC3688]. 340 Following the format in [RFC3688], the following registrations are 341 requested: 343 URI: urn:ietf:params:xml:ns:yang:ietf-notification-capabilities 344 Registrant Contact: The NETCONF WG of the IETF. 345 XML: N/A, the requested URI is an XML namespace. 347 5.2. The YANG Module Names Registry 349 This document registers one YANG module in the YANG Module Names 350 registry [RFC7950]. Following the format in [RFC7950], the the 351 following registrations are requested: 353 name: ietf-notification-capabilities 354 namespace: urn:ietf:params:xml:ns:yang:ietf-notification-capabilities 355 prefix: inc 356 reference: RFC XXXX 358 6. Open Issues 360 Do we need separate defaults/individual lists for every datastore? 361 Proposal: no, it would be an overkill. 363 Should type nacm:node-instance-identifier be moved to yang-types? 364 It is useful for more then just nacm. 366 7. References 368 7.1. Normative References 370 [I-D.ietf-netconf-yang-push] 371 Clemm, A., Voit, E., Prieto, A., Tripathy, A., Nilsen- 372 Nygaard, E., Bierman, A., and B. Lengyel, "YANG Datastore 373 Subscription", draft-ietf-netconf-yang-push-17 (work in 374 progress), July 2018. 376 [I-D.lengyel-netmod-yang-instance-data] 377 Lengyel, B. and B. Claise, "YANG Instance Data Files and 378 their use for Documenting Server Capabilities", draft- 379 lengyel-netmod-yang-instance-data-02 (work in progress), 380 July 2018. 382 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 383 RFC 7950, DOI 10.17487/RFC7950, August 2016, 384 . 386 7.2. Informative References 388 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 389 Requirement Levels", BCP 14, RFC 2119, 390 DOI 10.17487/RFC2119, March 1997, 391 . 393 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 394 DOI 10.17487/RFC3688, January 2004, 395 . 397 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 398 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 399 May 2017, . 401 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 402 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 403 . 405 Appendix A. Changes between revisions 407 v01 - v02 409 o Instead of augmenting ietf-yang-library a more simple standalone 410 model is proposed. 412 v00 - v01 414 o Corrections 416 o Augment only the new yanglib 418 o Correct the condtions for notifying state data 420 Authors' Addresses 422 Balazs Lengyel 423 Ericsson 424 Magyar Tudosok korutja 11 425 1117 Budapest 426 Hungary 428 Email: balazs.lengyel@ericsson.com 429 Alexander Clemm 430 Huawei USA 431 2330 Central Expressway 432 Santa Clara, CA 95050 433 USA 435 Email: ludwig@clemm.org