idnits 2.17.00 (12 Aug 2021) /tmp/idnits9472/draft-tao-netconf-data-export-capabilities-07.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 9 instances of too long lines in the document, the longest one being 21 characters in excess of 72. ** The abstract seems to contain references ([RFC9196]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (24 February 2022) is 79 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: 'RFC8641' is mentioned on line 87, but not defined == Unused Reference: 'RFC7950' is defined on line 433, but no explicit reference was found in the text == Unused Reference: 'RFC8126' is defined on line 441, but no explicit reference was found in the text == Unused Reference: 'RFC8342' is defined on line 455, but no explicit reference was found in the text == Unused Reference: 'RFC8407' is defined on line 460, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netconf-https-notif' is defined on line 476, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netconf-notification-messages' is defined on line 483, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netconf-udp-notif' is defined on line 491, but no explicit reference was found in the text == Outdated reference: A later version (-05) exists of draft-ietf-netconf-udp-notif-04 Summary: 2 errors (**), 0 flaws (~~), 10 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: 28 August 2022 P. Liu 6 China Mobile 7 W. Wang 8 China Telecom 9 24 February 2022 11 Data Export Notification Capability 12 draft-tao-netconf-data-export-capabilities-07 14 Abstract 16 This document proposes a YANG module for data export notification 17 capabilities which augments "ietf-system-capabilities" YANG module 18 defined in [RFC9196] and provides additional data export attributes 19 associated with system capabilities for transport specific 20 Notification. This YANG module can be used by the client to learn 21 capability information from the server at runtime or at 22 implementation time, by making use of the YANG instance data file 23 format. 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 https://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 28 August 2022. 42 Copyright Notice 44 Copyright (c) 2022 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 (https://trustee.ietf.org/ 49 license-info) in effect on the date of publication of this document. 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. Code Components 52 extracted from this document must include Revised BSD License text as 53 described in Section 4.e of the Trust Legal Provisions and are 54 provided without warranty as described in the Revised BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Data Export Capability . . . . . . . . . . . . . . . . . . . 3 61 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 62 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 64 4.1. Updates to the IETF XML Registry . . . . . . . . . . . . 8 65 4.2. Updates to the YANG Module Names Registry . . . . . . . . 8 66 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 67 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 9 68 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 69 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 70 7.2. Informative References . . . . . . . . . . . . . . . . . 10 71 Appendix A. Usage Example of interaction with UDP Notif and HTTP 72 Notif for Configured Subscription . . . . . . . . . . . . 11 73 Appendix B. Changes between Revisions . . . . . . . . . . . . . 13 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 76 1. Introduction 78 Notification capabilities model defined in [RFC9196] allows a client 79 to discover a set of capabilities supported by the server (e.g., 80 basic system capabilities and YANG-Push related capabilities) both at 81 implementation time and at runtime. These capabilities allow the 82 client to adjust its behavior to take advantage of the features 83 exposed by the server. 85 However the client and the server may still support various different 86 transport specific parameters (e.g., transport protocol, encoding 87 format, encryption). As described in section 3.1 of [RFC8641], a 88 simple negotiation (i.e., inserting hints into error responses to a 89 failed RPC request) between subscribers and publishers for 90 subscription parameters increases the likelihood of success for 91 subsequent RPC requests, but not guaranteed, which may cause 92 unexpected failure or additional message exchange between client and 93 server. 95 This document defines a corresponding solution that is built on top 96 of [RFC9196]. Supplementing that work are YANG data model 97 augmentations for transport specific notification. The module can be 98 used by the client to discover capability information from the server 99 at runtime or at implementation time, by making use of the YANG 100 instance data file format. 102 1.1. Terminology 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 106 "OPTIONAL" in this document are to be interpreted as described in BCP 107 14 [RFC2119] [RFC8174] when, and only when, they appear in all 108 capitals, as shown here. 110 2. Data Export Capability 112 The YANG module "ietf-notification-capabilities" defined in [RFC9196] 113 specifies the following server capabilities related to YANG Push: 115 * Supported (reporting) periods for "periodic" subscriptions 117 * Maximum number of objects that can be sent in an update 119 * The set of datastores or data nodes for which "periodic" or "on- 120 change" notification is supported 122 * Supported dampening periods for "on-change" subscriptions 124 These server capabilities are transport independent, session level 125 capabilities. They can be provided either at the implementation time 126 or reported at runtime. 128 This document augments System Capabilities model and provides 129 additional data export attributes associated with system 130 capabilities: 132 * Specification of transport protocols the client can use to 133 establish a transport connection; 135 * Specification of the encoding selection used (e.g., XML or JSON, 136 Binary) for Data modeled with YANG; 138 * Specification of secure transport mechanisms that are needed by 139 the client to communicate with the server; 141 * Specification of the notification message encapsulation type, 142 either one notification per message or multiple notifications per 143 message [I-D. ietf-netconf-notification-messages]. 145 2.1. Tree Diagram 147 The following tree diagram [RFC8340] provides an overview of the data 148 model. 150 module: ietf-data-export-capabilities 151 augment /sysc:system-capabilities: 152 +--ro data-export-capabilities 153 +--ro data-export-capability* [] 154 +--ro transport-protocol? identityref 155 +--ro encoding-format* identityref 156 +--ro security-protocol? identityref 157 +--ro message-bundling-support? empty 159 3. YANG Module 161 file "ietf-data-export-capabilities.yang" 162 module ietf-data-export-capabilities { 163 yang-version 1.1; 164 namespace "urn:ietf:params:xml:ns:yang:ietf-data-export-capabilities"; 165 prefix dec; 167 import ietf-system-capabilities { 168 prefix sysc; 169 } 170 import ietf-notification-capabilities { 171 prefix inc; 172 } 173 organization 174 "IETF NETCONF (Network Configuration) Working Group"; 175 contact 176 "WG Web: 177 WG List: 178 Editor: Qin Wu 179 Editor: Qiufang Ma 180 Editor: Peng Liu 181 Editor: Wei Wang "; 182 description 183 "This module defines an extension to System Capability and YANG Push 184 Notification Capabilities model and provides additional data export 185 attributes for transport specific notification. 187 Copyright (c) 2019 IETF Trust and the persons identified as 188 authors of the code. All rights reserved. 190 Redistribution and use in source and binary forms, with or 191 without modification, is permitted pursuant to, and subject 192 to the license terms contained in, the Simplified BSD License 193 set forth in Section 4.c of the IETF Trust's Legal Provisions 194 Relating to IETF Documents 195 (http://trustee.ietf.org/license-info). 197 This version of this YANG module is part of RFC XXXX; 198 see the RFC itself for full legal notices."; 200 revision 2020-07-03 { 201 description 202 "Initial revision."; 203 reference 204 "RFC XXXX: Data Export Notification Capability"; 205 } 207 identity transport-protocol { 208 description 209 "Base identity for transport protocol type."; 210 } 212 identity tcp { 213 base transport-protocol; 214 description 215 "Identity for tcp as transport protocol."; 216 } 218 identity udp-notif { 219 base transport-protocol; 220 description 221 "Identity for udp notif as transport protocol."; 222 reference 223 "draft-ietf-netconf-udp-notif:UDP-based Transport 224 for Configured Subscriptions"; 225 } 227 identity http-notif { 228 base transport-protocol; 229 description 230 "Identity for http notif as transport protocol."; 231 reference 232 "draft-ietf-netconf-https-notif: An HTTPS-based 233 Transport for Configured Subscriptions"; 234 } 236 identity grpc { 237 base transport-protocol; 238 description 239 "Identity for grpc as transport protocol."; 240 } 242 identity security-protocol { 243 description 244 "Base identity for security protocol type."; 245 } 247 identity tls { 248 base security-protocol; 249 description 250 "Identity for tls security protocol."; 251 } 253 identity dtls { 254 base security-protocol; 255 description 256 "Identity for dtls security protocol."; 257 } 259 identity ssh { 260 base security-protocol; 261 description 262 "Identity for ssh transport protocol."; 263 } 265 identity encoding-format { 266 description 267 "Base identity for encoding format type."; 268 } 270 identity xml { 271 base encoding-format; 272 description 273 "Identity for xml encoding format."; 274 } 276 identity json { 277 base encoding-format; 278 description 279 "Identity for json encoding format."; 280 } 282 identity binary { 283 base encoding-format; 284 description 285 "Identity for binary encoding format."; 287 } 289 identity cbor { 290 base binary; 291 description 292 "Identity for cbor encoding format."; 293 } 295 augment "/sysc:system-capabilities" { 296 description 297 "Add system level capability."; 298 container data-export-capabilities { 299 description 300 "Capabilities related to data export notification capabilities negotiation."; 301 list data-export-capability { 302 description 303 "Capability list related to data export notification capabilities negotiation."; 304 leaf transport-protocol { 305 type identityref { 306 base transport-protocol; 307 } 308 description 309 "Type of transport protocol."; 310 } 311 leaf-list encoding-format { 312 type identityref { 313 base encoding-format; 314 } 315 description 316 "Type of encoding format."; 317 } 318 leaf security-protocol { 319 type identityref { 320 base security-protocol; 321 } 322 description 323 "Type of secure transport."; 324 } 325 leaf message-bundling-support { 326 type empty; 327 description 328 "Enables message bundling support."; 329 } 330 } 331 } 332 } 333 } 334 336 4. IANA Considerations 338 4.1. Updates to the IETF XML Registry 340 This document registers a URI in the "IETF XML Registry" [RFC3688]. 341 Following the format in [RFC3688], the following registration has 342 been made: 344 URI: 345 urn:ietf:params:xml:ns:yang:ietf-data-export-capabilities 346 Registrant Contact: 347 The IESG. 348 XML: 349 N/A; the requested URI is an XML namespace. 351 4.2. Updates to the YANG Module Names Registry 353 This document registers one YANG module in the "YANG Module Names" 354 registry [RFC6020]. Following the format in [RFC6020], the following 355 registration has been made: 357 name: 358 ietf-data-export-capabilities 359 namespace: 360 urn:ietf:params:xml:ns:yang:ietf-data-export-capabilities 361 prefix: 362 dec 363 reference: 364 RFC XXXX (RFC Ed.: replace XXX with actual RFC number and remove 365 this note.) 367 5. Security Considerations 369 The YANG module specified in this document defines a schema for data 370 that is designed to be accessed via network management protocols such 371 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 372 is the secure transport layer, and the mandatory-to-implement secure 373 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 374 is HTTPS, and the mandatory-to-implement secure transport is TLS 375 [RFC8446]. 377 The NETCONF Configuration Access Control Model (NACM) [RFC8341] 378 provides the means to restrict access for particular NETCONF or 379 RESTCONF users to a preconfigured subset of all available NETCONF or 380 RESTCONF protocol operations and content. 382 All protocol-accessible data nodes are read-only and cannot be 383 modified. The data in these modules is not security sensitive. 384 Access control may be configured, to avoid exposing the read-only 385 data. 387 When this data is in file format, data should be protected against 388 modification or unauthorized access using normal file handling 389 mechanisms. 391 6. Contributors 393 Ran Tao 394 Huawei 395 101 Software Avenue, Yuhua District 396 Nanjing, Jiangsu 210012 397 China 398 Email: taoran20@huawei.com 400 Liang Geng 401 China Mobile 402 32 Xuanwumen West St, Xicheng District 403 Beijing 10053 405 Email: gengliang@chinamobile.com 407 Thomas Graf 408 Swisscom 409 Binzring 17 410 Zuerich 8045 411 Switzerland 413 Email: thomas.graf@swisscom.com 415 7. References 417 7.1. Normative References 419 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 420 Requirement Levels", BCP 14, RFC 2119, 421 DOI 10.17487/RFC2119, March 1997, 422 . 424 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 425 and A. Bierman, Ed., "Network Configuration Protocol 426 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 427 . 429 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 430 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 431 . 433 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 434 RFC 7950, DOI 10.17487/RFC7950, August 2016, 435 . 437 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 438 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 439 . 441 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 442 Writing an IANA Considerations Section in RFCs", BCP 26, 443 RFC 8126, DOI 10.17487/RFC8126, June 2017, 444 . 446 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 447 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 448 May 2017, . 450 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 451 Access Control Model", STD 91, RFC 8341, 452 DOI 10.17487/RFC8341, March 2018, 453 . 455 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 456 and R. Wilton, "Network Management Datastore Architecture 457 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 458 . 460 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 461 Documents Containing YANG Data Models", BCP 216, RFC 8407, 462 DOI 10.17487/RFC8407, October 2018, 463 . 465 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 466 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 467 . 469 [RFC9196] Lengyel, B., Clemm, A., and B. Claise, "YANG Modules 470 Describing Capabilities for Systems and Datastore Update 471 Notifications", RFC 9196, DOI 10.17487/RFC9196, February 472 2022, . 474 7.2. Informative References 476 [I-D.ietf-netconf-https-notif] 477 Jethanandani, M. and K. Watsen, "An HTTPS-based Transport 478 for YANG Notifications", Work in Progress, Internet-Draft, 479 draft-ietf-netconf-https-notif-09, 24 October 2021, 480 . 483 [I-D.ietf-netconf-notification-messages] 484 Voit, E., Jenkins, T., Birkholz, H., Bierman, A., and A. 485 Clemm, "Notification Message Headers and Bundles", Work in 486 Progress, Internet-Draft, draft-ietf-netconf-notification- 487 messages-08, 17 November 2019, 488 . 491 [I-D.ietf-netconf-udp-notif] 492 Zheng, G., Zhou, T., Graf, T., Francois, P., Feng, A. H., 493 and P. Lucente, "UDP-based Transport for Configured 494 Subscriptions", Work in Progress, Internet-Draft, draft- 495 ietf-netconf-udp-notif-04, 21 October 2021, 496 . 499 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 500 DOI 10.17487/RFC3688, January 2004, 501 . 503 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 504 the Network Configuration Protocol (NETCONF)", RFC 6020, 505 DOI 10.17487/RFC6020, October 2010, 506 . 508 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 509 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 510 . 512 Appendix A. Usage Example of interaction with UDP Notif and HTTP Notif 513 for Configured Subscription 515 The following instance-data example describes the Data Export 516 Notification capabilities of a hypothetical "acme-router". 518 519 521 acme-router-notification-capabilities 522 523 ietf-system-capabilities@2020-03-23 524 ietf-notification-capabilities@2020-03-23 525 ietf-data-export-capabilities@2020-03-23 526 527 528 Server Capability Discovery 529 530 534 535 536 http-notif 537 json 538 xml 539 540 541 udp-notif 542 binary 543 544 545 546 547 549 In addition, the client could also query data export capability from 550 the server. For example, the client sends request message to 551 the the server to query data export capability from the server. 553 554 555 556 557 558 559 560 561 563 The server returns server data export capability using as 564 follows: 566 567 568 571 572 573 http-notif 574 json 575 576 577 udp-notif 578 binary 579 580 581 582 583 585 Appendix B. Changes between Revisions 587 v06-v07 589 * Delete the per-node related capability parameters from the 590 Appendix. 592 v05-v06 594 * Revise abstract and introduction sessions so that the scope of 595 this draft is not limited to telemetry but other notification. 597 * Revise the description of module ietf-system-capabilities to align 598 with the latest version of draft-ietf-netconf-notification- 599 capabilities. 601 * Remove compression-mode, timer-event-support and suppress- 602 redundant parameters in the model. 604 * Move per-node related capability parameters to appendix section. 606 * Add a container to wrap data export capabilities to cleanly 607 separate different groups of capabilities. 609 v04 - v05 611 * Change per-node-capabilities related parameters into empty type. 613 * Revise abstract and introduction section to only focus on 614 capability fetching mechanism from the client to the server. 616 * Update Usage Example of interaction with HTTP-Notif and UDP-Notif 617 for Configured Subscription. 619 v03 - v04 621 * Add interface namespace in the Adaptive Subscription usage 622 example. 624 * subtrees and data nodes changes in the security section. 626 * Two compression mode related identities change. 628 * Move message-bundling-support parameer to system capabilities 629 level. 631 * Add an example to discuss report reciever capability from the 632 client per yang instance file format. 634 * Change encoding format from leaf to leaf-list and support multiple 635 encoding formats for the same transport specific notif. 637 v02 - v03 639 * Change 'data-export-capabilities' into list type to support 640 multiple transport protocol, encoding on the server. 642 * Add Usage Example of interaction with UDP based Transport for 643 Configured Subscription. 645 * Add Thomas Graf as a contributor; 647 * Update motivation in the introduction to clarify why this work is 648 needed. 650 * Support udp notif and http notif as two optional transport in the 651 YANG data model. 653 Authors' Addresses 655 Qin Wu 656 Huawei 657 101 Software Avenue, Yuhua District 658 Nanjing 659 Jiangsu, 210012 660 China 661 Email: bill.wu@huawei.com 663 Qiufang Ma 664 Huawei 665 101 Software Avenue, Yuhua District 666 Nanjing 667 Jiangsu, 210012 668 China 669 Email: maqiufang1@huawei.com 671 Peng Liu 672 China Mobile 673 Beiqijia Town, Changping District 674 Beijing 675 Email: liupengyjy@chinamobile.com 677 Wei Wang 678 China Telecom 679 32 Xuanwumen West St, Xicheng District 680 Beijing 681 Email: wangw36@chinatelecom.cn