idnits 2.17.1 draft-tao-netconf-data-export-capabilities-06.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 82 characters in excess of 72. ** The abstract seems to contain references ([I-D.netconf-notification-capabilities]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (30 August 2021) is 963 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 == Missing Reference: 'I-D.netconf-notification-capabilities' is mentioned on line 96, but not defined == Unused Reference: 'RFC7950' is defined on line 434, but no explicit reference was found in the text == Unused Reference: 'RFC8126' is defined on line 442, but no explicit reference was found in the text == Unused Reference: 'RFC8342' is defined on line 456, but no explicit reference was found in the text == Unused Reference: 'RFC8407' is defined on line 461, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netconf-https-notif' is defined on line 472, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netconf-notification-capabilities' is defined on line 479, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netconf-notification-messages' is defined on line 487, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netconf-udp-notif' is defined on line 495, but no explicit reference was found in the text == Outdated reference: A later version (-15) exists of draft-ietf-netconf-https-notif-08 == Outdated reference: A later version (-21) exists of draft-ietf-netconf-notification-capabilities-17 == Outdated reference: A later version (-12) exists of draft-ietf-netconf-udp-notif-03 Summary: 2 errors (**), 0 flaws (~~), 15 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: 3 March 2022 P. Liu 6 China Mobile 7 W. Wang 8 China Telecom 9 30 August 2021 11 Data Export Notification Capability 12 draft-tao-netconf-data-export-capabilities-06 14 Abstract 16 This document proposes a YANG module for data export notification 17 capabilities which augments System-Capabilities model defined in [I- 18 D.netconf-notification-capabilities] and provides additional data 19 export attributes associated with system capabilities for transport 20 specific Notification. This YANG module can be used by the client to 21 learn capability information from the server at run-time or 22 implementation-time, per the YANG Instance Data File Format. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on 3 March 2022. 41 Copyright Notice 43 Copyright (c) 2021 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 48 license-info) in effect on the date of publication of this document. 49 Please review these documents carefully, as they describe your rights 50 and restrictions with respect to this document. Code Components 51 extracted from this document must include Simplified BSD License text 52 as described in Section 4.e of the Trust Legal Provisions and are 53 provided without warranty as described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Data Export capability . . . . . . . . . . . . . . . . . . . 3 60 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 61 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 63 4.1. Updates to the IETF XML Registry . . . . . . . . . . . . 8 64 4.2. Updates to the YANG Module Names Registry . . . . . . . . 8 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 66 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 9 67 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 69 7.2. Informative References . . . . . . . . . . . . . . . . . 10 70 Appendix A. Usage Example of interaction with UDP Notif and HTTP 71 Notif for Configured Subscription . . . . . . . . . . . . 11 72 Appendix B. Other Per-node Notification-related Capabilities . . 13 73 Appendix C. Changes between Revisions . . . . . . . . . . . . . 14 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 76 1. Introduction 78 Notification capabilities model defined in [I-D.netconf-notification- 79 capabilities] allows a client to discover a set of capabilities 80 supported by the server (e.g., basic system capabilities and YANG- 81 Push related capabilities) both at implementation-time and run-time. 82 These capabilities allow the client to adjust its behavior to take 83 advantage of the features 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 [I-D.netconf-notification-capabilities]. Supplementing that work 97 are YANG data model augmentations for transport specific 98 notification. The module can be used by the client to discover 99 capability information from the server at run-time or implementation- 100 time, per the YANG 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 [I- 113 D.netconf-notification-capabilities] specify the following server 114 capabilities related to YANG Push: 116 * Supported (reporting) periods for "periodic" subscriptions 118 * Maximum number of objects that can be sent in an update 120 * The set of datastores or data nodes for which "periodic" or "on- 121 change" notification is supported 123 * Supported dampening periods for "on-change" subscriptions 125 These server capabilities are transport independent, session level 126 capabilities. They can be provided either at the implementation time 127 or reported at the run time. 129 This document augments system Capabilities model and provides 130 additional data export attributes associated with system 131 capabilities: 133 * Specification of transport protocol the client can use to 134 establish a transport connection; 136 * Specification of the encoding selection used (e.g., XML or JSON, 137 Binary) for Data modeled with YANG; 139 * Specification of secure transport mechanisms that are needed by 140 the client to communicate with the server; 142 * Specification of the notification message encapsulation type, 143 either one notification per message or multiple notifications per 144 message [I-D. ietf-netconf-notification-messages]. 146 2.1. Tree Diagram 148 The following tree diagram [RFC8340] provides an overview of the data 149 model. 151 module: ietf-data-export-capabilities 152 augment /sysc:system-capabilities: 153 +--ro data-export-capabilities 154 +--ro data-export-capability* [] 155 +--ro transport-protocol? identityref 156 +--ro encoding-format* identityref 157 +--ro security-protocol? identityref 158 +--ro message-bundling-support? empty 160 3. YANG Module 162 file "ietf-data-export-capabilities.yang" 163 module ietf-data-export-capabilities { 164 yang-version 1.1; 165 namespace "urn:ietf:params:xml:ns:yang:ietf-data-export-capabilities"; 166 prefix dec; 168 import ietf-system-capabilities { 169 prefix sysc; 170 } 171 import ietf-notification-capabilities { 172 prefix inc; 173 } 174 organization 175 "IETF NETCONF (Network Configuration) Working Group"; 176 contact 177 "WG Web: 178 WG List: 179 Editor: Qin Wu 180 Editor: Qiufang Ma 181 Editor: Peng Liu 182 Editor: Wei Wang "; 183 description 184 "This module defines an extension to System Capability and YANG Push 185 Notification Capabilities model and provides additional data export 186 attributes for transport specific notification. 188 Copyright (c) 2019 IETF Trust and the persons identified as 189 authors of the code. All rights reserved. 191 Redistribution and use in source and binary forms, with or 192 without modification, is permitted pursuant to, and subject 193 to the license terms contained in, the Simplified BSD License 194 set forth in Section 4.c of the IETF Trust's Legal Provisions 195 Relating to IETF Documents 196 (http://trustee.ietf.org/license-info). 198 This version of this YANG module is part of RFC XXXX; 199 see the RFC itself for full legal notices."; 201 revision 2020-07-03 { 202 description 203 "Initial revision."; 204 reference 205 "RFC XXXX: Telemetry Data Export capability"; 206 } 208 identity transport-protocol { 209 description 210 "Base identity for transport protocol type."; 211 } 213 identity tcp { 214 base transport-protocol; 215 description 216 "Identity for tcp as transport protocol."; 217 } 219 identity udp-notif { 220 base transport-protocol; 221 description 222 "Identity for udp notif as transport protocol."; 223 reference 224 "draft-ietf-netconf-udp-notif:UDP-based Transport 225 for Configured Subscriptions"; 226 } 228 identity http-notif { 229 base transport-protocol; 230 description 231 "Identity for http notif as transport protocol."; 232 reference 233 "draft-ietf-netconf-https-notif: An HTTPS-based 234 Transport for Configured Subscriptions"; 235 } 237 identity grpc { 238 base transport-protocol; 239 description 240 "Identity for grpc as transport protocol."; 241 } 243 identity security-protocol { 244 description 245 "Base identity for security protocol type."; 246 } 248 identity tls { 249 base security-protocol; 250 description 251 "Identity for tls security protocol."; 252 } 254 identity dtls { 255 base security-protocol; 256 description 257 "Identity for dtls security protocol."; 258 } 260 identity ssh { 261 base security-protocol; 262 description 263 "Identity for ssh transport protocol."; 264 } 266 identity encoding-format { 267 description 268 "Base identity for encoding format type."; 269 } 271 identity xml { 272 base encoding-format; 273 description 274 "Identity for xml encoding format."; 275 } 277 identity json { 278 base encoding-format; 279 description 280 "Identity for json encoding format."; 281 } 283 identity binary { 284 base encoding-format; 285 description 286 "Identity for binary encoding format."; 288 } 290 identity cbor { 291 base binary; 292 description 293 "Identity for cbor encoding format."; 294 } 296 augment "/sysc:system-capabilities" { 297 description 298 "Add system level capability."; 299 container data-export-capabilities { 300 description 301 "Capabilities related to data export notification capabilities negotiation."; 302 list data-export-capability { 303 description 304 "Capability list related to data export notification capabilities negotiation."; 305 leaf transport-protocol { 306 type identityref { 307 base transport-protocol; 308 } 309 description 310 "Type of transport protocol."; 311 } 312 leaf-list encoding-format { 313 type identityref { 314 base encoding-format; 315 } 316 description 317 "Type of encoding format."; 318 } 319 leaf security-protocol { 320 type identityref { 321 base security-protocol; 322 } 323 description 324 "Type of secure transport."; 325 } 326 leaf message-bundling-support { 327 type empty; 328 description 329 "Enables message bundling support."; 330 } 331 } 332 } 333 } 334 } 335 337 4. IANA Considerations 339 4.1. Updates to the IETF XML Registry 341 This document registers a URI in the "IETF XML Registry" [RFC3688]. 342 Following the format in [RFC3688], the following registration has 343 been made: 345 URI: 346 urn:ietf:params:xml:ns:yang:ietf-data-export-capabilities 347 Registrant Contact: 348 The IESG. 349 XML: 350 N/A; the requested URI is an XML namespace. 352 4.2. Updates to the YANG Module Names Registry 354 This document registers one YANG module in the "YANG Module Names" 355 registry [RFC6020]. Following the format in [RFC6020], the following 356 registration has been made: 358 name: 359 ietf-data-export-capabilities 360 namespace: 361 urn:ietf:params:xml:ns:yang:ietf-data-export-capabilities 362 prefix: 363 dec 364 reference: 365 RFC XXXX (RFC Ed.: replace XXX with actual RFC number and remove 366 this note.) 368 5. Security Considerations 370 The YANG module specified in this document defines a schema for data 371 that is designed to be accessed via network management protocols such 372 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 373 is the secure transport layer, and the mandatory-to-implement secure 374 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 375 is HTTPS, and the mandatory-to-implement secure transport is TLS 376 [RFC8446]. 378 The NETCONF Configuration Access Control Model (NACM) [RFC8341] 379 provides the means to restrict access for particular NETCONF or 380 RESTCONF users to a preconfigured subset of all available NETCONF or 381 RESTCONF protocol operations and content. 383 All protocol-accessible data nodes are read-only and cannot be 384 modified. The data in these modules is not security sensitive. 385 Access control may be configured, to avoid exposing the read-only 386 data. 388 When this data is in file format, data should be protected against 389 modification or unauthorized access using normal file handling 390 mechanisms. 392 6. Contributors 394 Ran Tao 395 Huawei 396 101 Software Avenue, Yuhua District 397 Nanjing, Jiangsu 210012 398 China 399 Email: taoran20@huawei.com 401 Liang Geng 402 China Mobile 403 32 Xuanwumen West St, Xicheng District 404 Beijing 10053 406 Email: gengliang@chinamobile.com 408 Thomas Graf 409 Swisscom 410 Binzring 17 411 Zuerich 8045 412 Switzerland 414 Email: thomas.graf@swisscom.com 416 7. References 418 7.1. Normative References 420 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 421 Requirement Levels", BCP 14, RFC 2119, 422 DOI 10.17487/RFC2119, March 1997, 423 . 425 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 426 and A. Bierman, Ed., "Network Configuration Protocol 427 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 428 . 430 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 431 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 432 . 434 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 435 RFC 7950, DOI 10.17487/RFC7950, August 2016, 436 . 438 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 439 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 440 . 442 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 443 Writing an IANA Considerations Section in RFCs", BCP 26, 444 RFC 8126, DOI 10.17487/RFC8126, June 2017, 445 . 447 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 448 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 449 May 2017, . 451 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 452 Access Control Model", STD 91, RFC 8341, 453 DOI 10.17487/RFC8341, March 2018, 454 . 456 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 457 and R. Wilton, "Network Management Datastore Architecture 458 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 459 . 461 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 462 Documents Containing YANG Data Models", BCP 216, RFC 8407, 463 DOI 10.17487/RFC8407, October 2018, 464 . 466 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 467 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 468 . 470 7.2. Informative References 472 [I-D.ietf-netconf-https-notif] 473 Jethanandani, M. and K. Watsen, "An HTTPS-based Transport 474 for YANG Notifications", Work in Progress, Internet-Draft, 475 draft-ietf-netconf-https-notif-08, 22 February 2021, 476 . 479 [I-D.ietf-netconf-notification-capabilities] 480 Lengyel, B., Clemm, A., and B. Claise, "YANG Modules 481 describing Capabilities for Systems and Datastore Update 482 Notifications", Work in Progress, Internet-Draft, draft- 483 ietf-netconf-notification-capabilities-17, 5 July 2021, 484 . 487 [I-D.ietf-netconf-notification-messages] 488 Voit, E., Jenkins, T., Birkholz, H., Bierman, A., and A. 489 Clemm, "Notification Message Headers and Bundles", Work in 490 Progress, Internet-Draft, draft-ietf-netconf-notification- 491 messages-08, 17 November 2019, 492 . 495 [I-D.ietf-netconf-udp-notif] 496 Zheng, G., Zhou, T., Graf, T., Francois, P., and P. 497 Lucente, "UDP-based Transport for Configured 498 Subscriptions", Work in Progress, Internet-Draft, draft- 499 ietf-netconf-udp-notif-03, 12 July 2021, 500 . 503 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 504 DOI 10.17487/RFC3688, January 2004, 505 . 507 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 508 the Network Configuration Protocol (NETCONF)", RFC 6020, 509 DOI 10.17487/RFC6020, October 2010, 510 . 512 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 513 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 514 . 516 Appendix A. Usage Example of interaction with UDP Notif and HTTP Notif 517 for Configured Subscription 519 The following instance-data example describes the Data Export 520 Notification capabilities of a hypothetical "acme-router". 522 523 525 acme-router-notification-capabilities 526 527 ietf-system-capabilities@2020-03-23 528 ietf-notification-capabilities@2020-03-23 529 ietf-data-export-capabilities@2020-03-23 530 531 532 Server Capability Discovery 533 534 538 539 540 http-notif 541 json 542 xml 543 544 545 udp-notif 546 binary 547 548 549 550 551 553 In addition, the client could also query data export capability from 554 the server. For example, the client sends request message to 555 the the server to query data export capability from the server. 557 558 559 560 561 562 563 564 565 567 The server returns server data export capability using as 568 follows: 570 571 572 573 574 575 http-notif 576 json 577 578 579 udp-notif 580 binary 581 582 583 584 585 587 Appendix B. Other Per-node Notification-related Capabilities 589 Since there may be a need for a service to configure both clients and 590 servers with multiple different period intervals and corresponding 591 subscription policy which allows servers/publishers automatically 592 switch to different period intervals according to resource usage 593 change without the interaction with the remote client. E.g., in a 594 wireless network performance monitoring scenario when the wireless 595 signal strength falls below a configured low watermark, the 596 subscribed data can be streamed at a higher rate while when the 597 wireless signal strength crosses a configured high watermark, the 598 subscribed data can be streamed at lower rate. 600 Some per-node capability parameters may be useful in this scenario, 601 which augments system capabilities model(e.g., /sysc:system- 602 capabilities/sysc:datastore-capabilities /sysc:per-node-capabilities) 603 to indicate if the server supports to multiple period intervals 604 switching and counter threshold evaluation. These parameters could 605 be: 607 * adaptive-interval-support, which is used to indicate if one event 608 stream supports multiple period intervals and allows period 609 interval switching; 611 * counter-threshold-support, which is used to indicate if the 612 subscription mode supports counter-based trigger (i.e., named 613 counter crosses a specified threshold). 615 The "adaptive-interval-support" parameter can be used to report if a 616 server supports to switch to different period intervals automatically 617 when a trigger condition is satisfied. And the counter threshold 618 evaluation could be used for a specific integer built-in type data 619 node when the "counter-threshold-support" parameter is true or 620 present as an empty type. 622 Appendix C. Changes between Revisions 624 v05-v06 626 * Revise abstract and introduction sessions so that the scope of 627 this draft is not limited to telemetry but other notification. 629 * Revise the description of module ietf-system-capabilities to align 630 with the latest version of draft-ietf-netconf-notification- 631 capabilities. 633 * Remove compression-mode, timer-event-support and suppress- 634 redundant parameters in the model. 636 * Move per-node related capability parameters to appendix section. 638 * Add a container to wrap data export capabilities to cleanly 639 separate different groups of capabilities. 641 v04 - v05 643 * Change per-node-capabilities related parameters into empty type. 645 * Revise abstract and introduction section to only focus on 646 capability fetching mechanism from the client to the server. 648 * Update Usage Example of interaction with HTTP-Notif and UDP-Notif 649 for Configured Subscription. 651 v03 - v04 653 * Add interface namespace in the Adaptive Subscription usage 654 example. 656 * subtrees and data nodes changes in the security section. 658 * Two compression mode related identities change. 660 * Move message-bundling-support parameer to system capabilities 661 level. 663 * Add an example to discuss report reciever capability from the 664 client per yang instance file format. 666 * Change encoding format from leaf to leaf-list and support multiple 667 encoding formats for the same transport specific notif. 669 v02 - v03 671 * Change 'data-export-capabilities' into list type to support 672 multiple transport protocol, encoding on the server. 674 * Add Usage Example of interaction with UDP based Transport for 675 Configured Subscription. 677 * Add Thomas Graf as a contributor; 679 * Update motivation in the introduction to clarify why this work is 680 needed. 682 * Support udp notif and http notif as two optional transport in the 683 YANG data model. 685 Authors' Addresses 687 Qin Wu 688 Huawei 689 101 Software Avenue, Yuhua District 690 Nanjing 691 Jiangsu, 210012 692 China 694 Email: bill.wu@huawei.com 696 Qiufang Ma 697 Huawei 698 101 Software Avenue, Yuhua District 699 Nanjing 700 Jiangsu, 210012 701 China 703 Email: maqiufang1@huawei.com 705 Peng Liu 706 China Mobile 707 Beiqijia Town, Changping District 708 Beijing 710 Email: liupengyjy@chinamobile.com 711 Wei Wang 712 China Telecom 713 32 Xuanwumen West St, Xicheng District 714 Beijing 716 Email: wangw36@chinatelecom.cn