idnits 2.17.1 draft-tao-netconf-data-export-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 : ---------------------------------------------------------------------------- ** There are 17 instances of too long lines in the document, the longest one being 22 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 166 has weird spacing: '...support boo...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (October 29, 2020) is 1274 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) == Unused Reference: 'RFC7950' is defined on line 519, but no explicit reference was found in the text == Unused Reference: 'RFC8126' is defined on line 527, but no explicit reference was found in the text == Unused Reference: 'RFC8342' is defined on line 541, but no explicit reference was found in the text == Unused Reference: 'RFC8407' is defined on line 546, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group Q. Wu 3 Internet-Draft Q. Ma 4 Intended status: Standards Track Huawei 5 Expires: May 2, 2021 L. Geng 6 P. Liu 7 China Mobile 8 October 29, 2020 10 Telemetry Data Export capability 11 draft-tao-netconf-data-export-capabilities-02 13 Abstract 15 This document proposes a YANG module for telemetry data export 16 capability which augments system Capabilities model and provides 17 additional telemetry data export attributes associated with system 18 capability for transport dependent capability negotiation. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on May 2, 2021. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Data Export capability . . . . . . . . . . . . . . . . . . . 3 57 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 58 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 60 4.1. Updates to the IETF XML Registry . . . . . . . . . . . . 9 61 4.2. Updates to the YANG Module Names Registry . . . . . . . . 10 62 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 63 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 11 64 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 7.1. Normative References . . . . . . . . . . . . . . . . . . 11 66 7.2. Informative References . . . . . . . . . . . . . . . . . 12 67 Appendix A. Usage Example of interaction between telemetry data 68 export capabilities and Adaptive Subscription . . . 13 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 71 1. Introduction 73 Notification capability model defined in [I-D.netconf-notification- 74 capabilities] allows a client to discover a set of capabilities 75 supported by the server (e.g., basic system capability and YANG-Push 76 related capabilities) both at implementation-time and run-time. 77 These "capabilities" permit the client to adjust its behavior to take 78 advantage of the features exposed by the device. 80 However pre-configuration for some transport specific parameters 81 (e.g., transport protocol, encoding format, encryption by the client 82 is still inevitable, which may cause unexpected failure and 83 additional message exchange between client and server. 85 This document proposes a YANG module for telemetry data export 86 capability which augments System Capabilities model and provide 87 additional data export attributes for transport dependent capability 88 negotiation. 90 1.1. Terminology 92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 94 "OPTIONAL" in this document are to be interpreted as described in BCP 95 14 [RFC2119] [RFC8174] when, and only when, they appear in all 96 capitals, as shown here. 98 2. Data Export capability 100 The YANG module ietf-notification-capabilities defined in [I- 101 D.netconf-notification-capabilities] specify the following server 102 capabilities related to YANG Push: 104 o A set of capabilities related to the amount of notifications the 105 server can send out 107 o Specification of which data nodes support on-change notifications. 109 o Capability values can be specified on server level, datastore 110 level or on specific data nodes (and their contained sub-tree) of 111 a specific datastore. Capability values on a smaller, more 112 specific part of the server's data always override more generic 113 values. 115 o On-change capability is not specified on a server level as 116 different datastores usually have different on-change 117 capabilities. On a datastore level on-change capability for 118 configuration and state data can be specified separately. 120 These server capabilities are transport independent and session level 121 capabilities and can be provided either at implementation time or 122 reported at run time. 124 This document augments system Capabilities model and provides 125 additional data export attributes associated with system 126 capabilities: 128 o Specification of transport protocol the client can use to 129 establish transport connection; 131 o Specification of encoding selection(e.g., XML or JSON, to binary) 132 of Data Modeled with YANG; 134 o Specification of secure transport mechanisms that are needed by 135 the client to communicate with the server; 137 o Specification of the type of data compression algorithm (e.g., 138 lossless data compression) the client can use for file compression 139 and decompression 141 o Specification of the notification message encapsulation type, 142 either one notification per message or multiple notifications per 143 message. 145 o Specification of the update trigger type such as adaptive interval 146 trigger, timer event based trigger, count threshold trigger, 147 redundant suppression. 149 2.1. Tree Diagram 151 The following tree diagram [RFC8340] provides an overview of the data 152 model. 154 module: ietf-data-export-capabilities 155 augment /sysc:system-capabilities: 156 +--ro data-export-capabilities 157 +--ro transport-protocol? identityref 158 +--ro encoding-format? identityref 159 +--ro security-protocol? identityref 160 +--ro compression-mode? identityref 161 augment /sysc:system-capabilities/inc:subscription-capabilities: 162 +--ro data-export-capabilities 163 +--ro message-bundling-support? boolean 164 augment /sysc:system-capabilities/sysc:datastore-capabilities/sysc:per-node-capabilities: 165 +--ro data-export-capabilities 166 +--ro adaptive-interval-support boolean 167 +--ro timer-event-support? boolean 168 +--ro counter-threshold-support? boolean 169 +--ro suppress-redundant? boolean 171 3. YANG Module 173 file "ietf-data-export-capabilities.yang" 174 module ietf-data-export-capabilities { 175 yang-version 1.1; 176 namespace "urn:ietf:params:xml:ns:yang:ietf-data-export-capabilities"; 177 prefix dec; 179 import ietf-system-capabilities { 180 prefix sysc; 181 } 182 import ietf-notification-capabilities { 183 prefix inc; 184 } 186 organization 187 "IETF NETCONF (Network Configuration) Working Group"; 188 contact 189 "WG Web: 190 WG List: 191 Editor: Qin Wu 192 426 4. IANA Considerations 428 4.1. Updates to the IETF XML Registry 430 This document registers a URI in the "IETF XML Registry" [RFC3688]. 431 Following the format in [RFC3688], the following registration has 432 been made: 434 URI: 435 urn:ietf:params:xml:ns:yang:ietf-data-export-capabilities 436 Registrant Contact: 437 The IESG. 438 XML: 439 N/A; the requested URI is an XML namespace. 441 4.2. Updates to the YANG Module Names Registry 443 This document registers one YANG module in the "YANG Module Names" 444 registry [RFC6020]. Following the format in [RFC6020], the following 445 registration has been made: 447 name: 448 ietf-data-export-capabilities 449 namespace: 450 urn:ietf:params:xml:ns:yang:ietf-data-export-capabilities 451 prefix: 452 dec 453 reference: 454 RFC XXXX (RFC Ed.: replace XXX with actual RFC number and remove 455 this note.) 457 5. Security Considerations 459 The YANG module specified in this document defines a schema for data 460 that is designed to be accessed via network management protocols such 461 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 462 is the secure transport layer, and the mandatory-to-implement secure 463 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 464 is HTTPS, and the mandatory-to-implement secure transport is TLS 465 [RFC8446]. 467 The NETCONF Configuration Access Control Model (NACM) [RFC8341] 468 provides the means to restrict access for particular NETCONF or 469 RESTCONF users to a preconfigured subset of all available NETCONF or 470 RESTCONF protocol operations and content. 472 There are a number of data nodes defined in this YANG module that are 473 writable/creatable/deletable (i.e., config true, which is the 474 default). These data nodes may be considered sensitive in some 475 network environments. Write operations (e.g., edit-config) to these 476 data nodes without proper protection can have a negative effect on 477 network operations. These are the subtrees and data nodes and their 478 sensitivity/vulnerability: 480 o /sysc:system-capabilities/dec:transport-protocol 481 o /sysc:system-capabilities/dec:encoding-format 483 o /sysc:system-capabilities/dec:secure-transport 485 o /sysc:system-capabilities/dec:compression-mode 487 o /sysc:system-capabilities/inc:subscription-capabilities/ 488 dec:message-bundling-support 490 o /sysc:system-capabilities/inc:subscription-capabilities/ 491 dec:subscription-mode 493 o /sysc:system-capabilities/sysc:datastore-capabilities/sysc:per- 494 node-capabilities/dec:sampling-interval 496 6. Contributors 498 The authors would like to thank Ran Tao for his major contributions 499 to the initial modeling and use cases. 501 7. References 503 7.1. Normative References 505 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 506 Requirement Levels", BCP 14, RFC 2119, 507 DOI 10.17487/RFC2119, March 1997, 508 . 510 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 511 and A. Bierman, Ed., "Network Configuration Protocol 512 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 513 . 515 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 516 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 517 . 519 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 520 RFC 7950, DOI 10.17487/RFC7950, August 2016, 521 . 523 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 524 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 525 . 527 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 528 Writing an IANA Considerations Section in RFCs", BCP 26, 529 RFC 8126, DOI 10.17487/RFC8126, June 2017, 530 . 532 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 533 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 534 May 2017, . 536 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 537 Access Control Model", STD 91, RFC 8341, 538 DOI 10.17487/RFC8341, March 2018, 539 . 541 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 542 and R. Wilton, "Network Management Datastore Architecture 543 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 544 . 546 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 547 Documents Containing YANG Data Models", BCP 216, RFC 8407, 548 DOI 10.17487/RFC8407, October 2018, 549 . 551 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 552 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 553 . 555 7.2. Informative References 557 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 558 DOI 10.17487/RFC3688, January 2004, 559 . 561 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 562 the Network Configuration Protocol (NETCONF)", RFC 6020, 563 DOI 10.17487/RFC6020, October 2010, 564 . 566 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 567 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 568 . 570 Appendix A. Usage Example of interaction between telemetry data export 571 capabilities and Adaptive Subscription 573 The following instance-data example describes the notification 574 capabilities of a hypothetical "acme-router". The router implements 575 the running, and operational datastores. Every change can be 576 reported on-change from running, but only config=true nodes and some 577 config=false data from operational. Interface statistics are 578 reported only when both adaptive-interval-support and count- 579 threshold-support are set to true. 581 file "acme-router-notification-capabilities.xml" 582 ========== NOTE: '\' line wrapping per BCP YYY (RFC YYYY) =========== 584 585 587 acme-router-notification-capabilities 588 589 ietf-system-capabilities@2020-03-23 590 ietf-notification-capabilities@2020-03-23 591 ietf-data-export-capabilities@2020-03-23 592 593 594 Defines the notification capabilities of an acme-router. 595 The router only has running, and operational datastores. 596 Every change can be reported on-change from running, but 597 only config=true nodes and some config=false data from operational. 598 Statistics are not reported based on timer based trigger and counter 599 threshold based trigger. 600 601 602 607 608 ds:operational 609 610 \ 611 /if:interfaces/if:interface/if:statistics\ 612 613 614 5 615 616 \ 617 state-changes\ 619 620 621 622 623 \ 624 /if:interfaces/if:interface/if:statistics/if:out-octets\ 625 626 627 false 628 false 629 630 631 632 633 \ 634 /if:interfaces/if:interface/if:statistics/if:in-errors\ 635 636 637 true 638 true 639 640 641 642 643 644 646 The client configure adaptive subscription parameters on the server. 647 The adaptive subscription configuration parameters require the server 648 to scan all interface of specific type every 5 seconds up to 30 649 seconds if the value of interface in-errors is greater than 1000; If 650 the interface in-errors value is less than 1000, switch to 60 seconds 651 period value, and then scan all client every 60 seconds up to 360 652 seconds. 30 seconds and 360 seconds can be seen as time window. The 653 time window lenght is 6 period values. Irrespective of period value 654 set for adaptive subscription, 6 event records during the time window 655 should be generated for the same subscription and send to the 656 receivers. 658 660 661 662 663 664 665 666 668 ds:running 669 670 672 /if:ietf-interfaces 673 674 676 /if:interfaces/if:interface/if:statistics 677 in-errors 678 679 in-errors < 1000 680 1000 681 5 682 12 683 684 685 in-errors < 1000 686 1000 687 60 688 12 689 690 691 692 693 694 696 Authors' Addresses 698 Qin Wu 699 Huawei 700 101 Software Avenue, Yuhua District 701 Nanjing, Jiangsu 210012 702 China 704 Email: bill.wu@huawei.com 705 Qiufang Ma 706 Huawei 707 101 Software Avenue, Yuhua District 708 Nanjing, Jiangsu 210012 709 China 711 Email: maqiufang1@huawei.com 713 Liang Geng 714 China Mobile 715 32 Xuanwumen West St, Xicheng District 716 Beijing 10053 718 Email: gengliang@chinamobile.com 720 Peng Liu 721 China Mobile 722 32 Xuanwumen West St, Xicheng District 723 Beijing 10053 725 Email: liupengyjy@chinamobile.com