idnits 2.17.1 draft-ietf-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 -- The document date (July 5, 2019) is 1757 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC8341' is mentioned on line 473, but not defined == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-02 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: January 6, 2020 Futurewei 6 B. Claise 7 Cisco Systems, Inc. 8 July 5, 2019 10 Yang-Push Notification Capabilities 11 draft-ietf-netconf-notification-capabilities-02 13 Abstract 15 This document proposes a YANG module that allows a server to specify 16 server capabilities related to "Subscription to YANG Datastores" 17 (Yang-Push). It proposes to use YANG Instance Data to document this 18 information and make it already available at implementation time, but 19 also allow it to be reported at runtime. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 6, 2020. 38 Copyright Notice 40 Copyright (c) 2019 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. Notification Capability Model . . . . . . . . . . . . . . . . 4 58 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 5 59 3.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 6 60 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 62 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 11 63 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 11 64 6. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 66 7.1. Normative References . . . . . . . . . . . . . . . . . . 11 67 7.2. Informative References . . . . . . . . . . . . . . . . . 12 68 Appendix A. Instance data examples . . . . . . . . . . . . . . . 13 69 Appendix B. Changes between revisions . . . . . . . . . . . . . 16 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 72 1. Terminology 74 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 75 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 76 "OPTIONAL" in this document are to be interpreted as described in BCP 77 14 [RFC2119] [RFC8174] when, and only when, they appear in all 78 capitals, as shown here. 80 The terms Yang-Push, On-change subscription and Periodic subscription 81 are used as defined in [I-D.ietf-netconf-yang-push] 83 On-change Notification Capability: The capability of the server to 84 support On-change subscriptions. 86 The term Server is used as defined in [RFC8342] 88 Implementation-time information: Information about the server's 89 behavior that is made available during the implementation of the 90 server, available from a source other then a running server. 92 Runtime-information: Information about the server's behavior that is 93 available from the running server via management protocols such as 94 NETCONF [RFC6241] or RESTCONF [RFC8040]. 96 2. Introduction 98 As defined in [I-D.ietf-netconf-yang-push] a server may allow clients 99 to subscribe to updates from a datastore and subsequently push such 100 update notifications to the client. Notifications may be sent 101 periodically or on-change (more or less immediately after each 102 change). 104 A server supporting YANG-Push has a number of capabilities that are 105 determined during the implementation of the server. These include: 107 o Supported (reporting) periods for periodic subscriptions 109 o Maximum number of objects that can be sent in an update 111 If the optional on-change feature is supported, these include: 113 o Supported dampening periods for on-change subscriptions 115 o The set of data nodes for which on-change notification is 116 supported 118 Servers MAY have limitations in how many update notifications and how 119 many datastore node updates they can send out in a certain time- 120 period. 122 In some cases, a publisher supporting on-change notifications will 123 not be able to push updates for some object types on-change. Reasons 124 for this might be that the value of the datastore node changes 125 frequently (e.g. in-octets counter), that small object changes are 126 frequent and meaningless (e.g., a temperature gauge changing 0.1 127 degrees), or that the implementation is not capable of on-change 128 notification for a particular object. In those cases, it will be 129 important for client applications to have a way to identify for which 130 objects on-change notifications are supported and for which ones not. 132 Faced with the reality that support for on-change notification does 133 not mean that such notifications will be sent for any specific data 134 node, client/management applications can not rely on the on-change 135 functionality unless the client has some means to identify for which 136 objects on-change notifications are supported. YANG models are meant 137 to be used as an interface contract. Without identification of the 138 data nodes actually supporting on-change, this contract would be 139 incomplete. 141 This document proposes a YANG module that allows a client to discover 142 YANG-Push related capabilities both at implementation-time and run- 143 time. 145 Implementation time information is needed by Network Management 146 System (NMS) implementers. During NMS implementation for any 147 functionality that depends on the notifications the information about 148 on change notification capability is needed. If the information is 149 not available early in some document, but only as instance data from 150 the network node once it is deployed, the NMS implementation will be 151 delayed, because it has to wait for the network node to be ready. In 152 addition, the assumption that all NMS implementers will have a 153 correctly configured network node available to retrieve data from, is 154 an expensive proposition and may not always hold. (An NMS may need 155 to be able to handle many dozens of network node types.) Often a 156 fully functional NMS is a requirement for introducing a new network 157 node type into a network, so delaying NMS readiness effectively also 158 delays the time at which a new network node type can be introduced 159 into the network. 161 Implementation time information is needed by system integrators. 162 When introducing a network node type into their network, operators 163 often need to integrate the node type into their own management 164 system. The NMS may have management functions that depend on on- 165 change notifications. The network operator needs to plan his 166 management practices and NMS implementation before he even decides to 167 buy the specific network node type. Moreover the decision to buy the 168 node type sometimes depends on these management possibilities. 170 Run-time information is needed: 172 o for any "purely model driven" client, e.g. a NETCONF-browser. As 173 long as it has a valid model to read the capability information, 174 it does not care which data nodes send notification, it will just 175 handle what is available. 177 o in case the capability might change during run-time e.g. due to 178 licensing, HW constraints etc. 180 o to check that early, implementation time capability information 181 about the capabilities is indeed what the server implements (is 182 the supplied documentation correct?) 184 3. Notification Capability Model 186 It is a goal to provide Yang-Push notification capability information 187 in a format that is: 189 o vendor independent 191 o formal 192 o identical for implementation-time and run-time 194 The YANG module ietf-notification-capabilities is defined to provide 195 the information. It contains: 197 a set of capabilities related to the amount of notifications the 198 server can send out 200 a default on-change notification capability separately for config 201 false and config true data nodes 203 an on-change-notification-capability list containing a potentially 204 different true/false notification capability for a few data nodes 205 in the schema tree. Unless a node is in this list with a specific 206 capability value, it inherits its on-change-notification- 207 capability from its parent in the data tree, or from the relevant 208 default values. It is assumed that only a small number of nodes 209 will be included in this list: special cases where the default 210 behavior is not followed. For a detailed description of the usage 211 of this list see the description in the YANG module. 213 The information SHALL be provided in two ways both following the 214 ietf-notification-capabilities module: 216 o It SHALL be provided by the implementer as YANG instance data file 217 complying to [I-D.ietf-netmod-yang-instance-file-format]. The 218 file SHALL be available already in implementation time retrievable 219 in a way that does not depend on a live network node. E.g. 220 download from product Website. 222 o It SHALL be available via NETCONF [RFC6241] or RESTCONF [RFC8040] 223 from the live server during runtime. 225 3.1. Tree Diagram 227 The following tree diagram [RFC8340] provides an overview of the data 228 model. 230 module: ietf-notification-capabilities 231 +--ro datastore-subscription-capabilities 232 +--ro (update-period)? 233 | +--:(minimum-update-period) 234 | | +--ro minimum-update-period? uint32 235 | +--:(supported-update-period) 236 | +--ro supported-update-period* uint32 237 +--ro max-objects-per-update? uint32 238 +--ro minimum-dampening-period? uint32 {yp:on-change}? 239 +--ro on-change-capable-nodes* [datastore] {yp:on-change}? 240 +--ro datastore union 241 +--ro notification-sent-for-config-default? boolean 242 +--ro notification-sent-for-state-default? boolean 243 +--ro on-change-notification-capability* [node-selector] 244 +--ro node-selector nacm:node-instance-identifier 245 +--ro on-change-supported boolean 247 3.2. YANG Module 249 file "ietf-notification-capabilities@2019-07-02.yang" 251 module ietf-notification-capabilities { 252 yang-version 1.1; 253 namespace 254 "urn:ietf:params:xml:ns:yang:ietf-notification-capabilities"; 255 prefix inc; 257 import ietf-netconf-acm { prefix nacm; } 258 import ietf-yang-push { prefix yp; } 259 import ietf-yang-library { 260 prefix yanglib; 261 description 262 "Requires revision 2019-01-04 or a revision derived from it."; 263 } 265 organization 266 "IETF NETCONF (Network Configuration) Working Group"; 267 contact 268 "WG Web: 269 WG List: 271 Editor: Balazs Lengyel 272 "; 273 description 274 "This module specifies YANG-Push related server 275 capabilities. 277 The module contains 278 - capabilities related to the amount of notifications the 279 server can send out. Note that for a specific subscription 280 the server MAY still allow only longer periods or smaller 281 updates depending on e.g. actual load conditions. 282 - default and schema node specific information specifying 283 the set of data nodes for which the server is capable 284 of sending on-change notifications. 286 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 287 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 288 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 289 are to be interpreted as described in BCP 14 (RFC 2119) 290 (RFC 8174) when, and only when, they appear in all 291 capitals, as shown here. 293 Copyright (c) 2019 IETF Trust and the persons identified as 294 authors of the code. All rights reserved. 296 Redistribution and use in source and binary forms, with or 297 without modification, is permitted pursuant to, and subject 298 to the license terms contained in, the Simplified BSD License 299 set forth in Section 4.c of the IETF Trust's Legal Provisions 300 Relating to IETF Documents 301 (http://trustee.ietf.org/license-info). 303 This version of this YANG module is part of RFC XXXX; see 304 the RFC itself for full legal notices."; 306 revision 2019-07-02 { 307 description 308 "Initial version"; 309 reference 310 "RFC XXX: Yang-Push Notification Capabilities"; 311 } 313 container datastore-subscription-capabilities { 314 config false; 315 description 316 "YANG-Push related server capabilities"; 318 choice update-period { 319 description 320 "Supported period values."; 321 leaf minimum-update-period { 322 type uint32; 323 units "centiseconds"; 324 description 325 "Minimum update period supported for a 326 periodic subscription. May be absent if the server is 327 not capable of providing a specific value."; 328 } 330 leaf-list supported-update-period { 331 type uint32; 332 units "centiseconds"; 333 description 334 "Specific supported update period values 335 for a periodic subscription."; 336 } 337 } 339 leaf max-objects-per-update { 340 type uint32 { 341 range "1..max"; 342 } 343 description 344 "Maximum number of objects that can be sent 345 in an update. May be absent if the server is 346 not capable of providing a specific value."; 347 } 349 leaf minimum-dampening-period { 350 if-feature yp:on-change ; 351 type uint32; 352 units "centiseconds"; 353 description 354 "The minimum dampening period supported for on-change 355 subscriptions. May be absent if the server is 356 not capable of providing a specific value."; 357 } 359 list on-change-capable-nodes { 360 if-feature yp:on-change ; 361 key datastore ; 362 description "Specifies per datastore the data nodes for which the 363 server is capable of sending on-change notifications. 364 If a datastore implemented by the server is not specified 365 in this list and there is no list element for 'all' datastores 366 the datastore does not support any on-change notifications. 368 On-change notification capability is marked as true or false. 369 This marking is inherited from the parent down the data tree 370 unless explicitly marked otherwise. 372 On-change notifications SHALL be sent for a config=true 373 data node if one of the following is true: 374 - if it is a top level data-node and is not specified in the 375 on-change-notification-capability list and the 376 notification-sent-for-config-default is true; or 377 - notifications are sent for its parent data node and it is 378 not specified in the on-change-notification-capability list; or 379 - it is specified in the on-change-notification-capability 380 list and has an on-change-supported value true. 382 On-change notifications SHALL be sent for a config=false 383 data node if one of the following is true: 384 - if it is a top level data-node (a config=false data node with 385 a config=true parent SHALL be treated as a top level data node) 386 and is not specified in the on-change-notification-capability 387 list and the notification-sent-for-state-default is true; or 388 - notifications are sent for its parent data node 389 which is also config=false and it is 390 not specified in the on-change-notification-capability list; or 391 - it is specified in the on-change-notification-capability 392 list and has an on-change-supported value true"; 394 leaf datastore { 395 type union { 396 type leafref { 397 path /yanglib:yang-library/yanglib:datastore/yanglib:name ; 398 } 399 type enumeration { 400 enum all ; 401 } 402 } 403 must '. != "all" or count(..) = "1" ' { 404 error-message 405 "If 'all' is present individual datastores cannot be " + 406 "specified."; 407 } 408 description "The datastore for which on-change capable 409 nodes are defined."; 410 } 412 leaf notification-sent-for-config-default { 413 type boolean; 414 default "true"; 415 description 416 "Specifies the default value for 417 top level configuration data nodes for the 418 on-change-supported capability."; 419 } 420 leaf notification-sent-for-state-default { 421 type boolean; 422 default "false"; 423 description 424 "Specifies the default value 425 top level state data nodes for the 426 on-change-supported capability."; 427 } 429 list on-change-notification-capability { 430 key "node-selector"; 431 description 432 "A list of data nodes that have the 433 on-change-notification-capability specifically defined. 435 Should be used only when specific data nodes support 436 on-change notification in a module/subtree that 437 generally does not support it or when some data nodes 438 do not support the notification in a module/subtree 439 that generally supports on-change notifications."; 441 leaf node-selector { 442 type nacm:node-instance-identifier; 443 description 444 "Selects the data nodes for which 445 on-change capability is specified."; 446 } 448 leaf on-change-supported { 449 type boolean; 450 mandatory true; 451 description 452 "Specifies whether the server is capable of 453 sending on-change notifications for the selected 454 data nodes."; 455 } 456 } 457 } 458 } 459 } 461 463 4. Security Considerations 465 The YANG module specified in this document defines a schema for data 466 that is designed to be accessed via network management protocols such 467 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 468 is the secure transport layer, and the mandatory-to-implement secure 469 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 470 is HTTPS, and the mandatory-to-implement secure transport is TLS 471 [RFC8446]. 473 The Network Configuration Access Control Model (NACM) [RFC8341] 474 provides the means to restrict access for particular NETCONF or 475 RESTCONF users to a preconfigured subset of all available NETCONF or 476 RESTCONF protocol operations and content. 478 The data in this module is not security sensitive. 480 5. IANA Considerations 482 5.1. The IETF XML Registry 484 This document registers one URI in the IETF XML registry [RFC3688]. 485 Following the format in [RFC3688], the following registrations are 486 requested: 488 URI: urn:ietf:params:xml:ns:yang:ietf-notification-capabilities 489 Registrant Contact: The NETCONF WG of the IETF. 490 XML: N/A, the requested URI is an XML namespace. 492 5.2. The YANG Module Names Registry 494 This document registers one YANG module in the YANG Module Names 495 registry [RFC7950]. Following the format in [RFC7950], the the 496 following registrations are requested: 498 name: ietf-notification-capabilities 499 namespace: urn:ietf:params:xml:ns:yang:ietf-notification-capabilities 500 prefix: inc 501 reference: RFC XXXX 503 6. Open Issues 505 - 507 7. References 509 7.1. Normative References 511 [I-D.ietf-netconf-yang-push] 512 Clemm, A. and E. Voit, "Subscription to YANG Datastores", 513 draft-ietf-netconf-yang-push-25 (work in progress), May 514 2019. 516 [I-D.ietf-netmod-yang-instance-file-format] 517 Lengyel, B. and B. Claise, "YANG Instance Data File 518 Format", draft-ietf-netmod-yang-instance-file-format-02 519 (work in progress), February 2019. 521 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 522 and A. Bierman, Ed., "Network Configuration Protocol 523 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 524 . 526 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 527 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 528 . 530 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 531 RFC 7950, DOI 10.17487/RFC7950, August 2016, 532 . 534 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 535 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 536 . 538 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 539 and R. Wilton, "Network Management Datastore Architecture 540 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 541 . 543 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 544 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 545 . 547 7.2. Informative References 549 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 550 Requirement Levels", BCP 14, RFC 2119, 551 DOI 10.17487/RFC2119, March 1997, 552 . 554 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 555 DOI 10.17487/RFC3688, January 2004, 556 . 558 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 559 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 560 May 2017, . 562 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 563 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 564 . 566 Appendix A. Instance data examples 568 The following example is instance-data describing the notification 569 capabilities of a hypothetical "acme-switch". The switch implements 570 the running, candidate and operational datastores. Every change can 571 be reported on-change from running, nothing from candidate and all 572 config=false data from operational. 574 575 577 acme-switch-notification-capabilites 578 579 Notification capabilities of acme-switch. 580 Acme-switch implements the running, candidate and operational 581 datastores. Every change can be reported on-change from running, 582 nothing from candidate and all config=false data from operational. 583 584 585 586 500 587 2000 588 100 589 590 591 running 592 593 596 597 599 600 601 operational 602 603 604 false 605 606 607 true 608 609 610 611 612 614 Figure 1: Notification Capabilities with default settings 616 The following is the instance-data describing the notification 617 capabilities of a hypothetical "acme-router". The router implements 618 the running, and operational datastores. Every change can be 619 reported on-change from running, but only config=true nodes and some 620 config=false data from operational. Interface statistics are not 621 reported on-change only 2 important counters. 623 624 626 acme-router-notification-capabilites 627 628 Defines the notification capabilities of an acme-router. 629 The router only has running, and operational datastores. 630 Every change can be reported on-change from running, but 631 only config=true nodes and some config=false data from operational. 632 Statistics are not reported on-change only 2 important counters. 633 634 635 637 500 638 2000 639 100 640 641 642 running 643 644 645 646 647 operational 648 649 650 true 651 652 653 654 /if:interfaces/if:interface/if:statistics 655 false 656 657 658 659 /if:interfaces/if:interface/if:statistics/if:in-octets 660 661 true 662 663 664 665 /if:interfaces/if:interface/if:statistics/if:out-octets 666 667 true 668 669 670 672 673 675 Figure 2: Notification Capabilities with data node specific settings 677 Appendix B. Changes between revisions 679 v01 - v02 681 o Added instance data examples 683 o On-change capability can be defined per datastore 685 o Added "if-feature yp:on-change" where relevant 687 o Unified units used 689 v00 - v01 691 o Add more capabilities: minimum period, supported period max-number 692 of objects, min dampening period, dampening supported 694 Authors' Addresses 696 Balazs Lengyel 697 Ericsson 698 Magyar Tudosok korutja 11 699 1117 Budapest 700 Hungary 702 Email: balazs.lengyel@ericsson.com 704 Alexander Clemm 705 Futurewei 706 2330 Central Expressway 707 Santa Clara, CA 95050 708 USA 710 Email: ludwig@clemm.org 711 Benoit Claise 712 Cisco Systems, Inc. 713 De Kleetlaan 6a b1 714 1831 Diegem 715 Belgium 717 Email: bclaise@cisco.com