idnits 2.17.1 draft-ma-netconf-with-system-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 2 instances of too long lines in the document, the longest one being 7 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o MUST not update with the system configuration. -- The document date (June 22, 2021) is 1038 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: 'RFC3688' is mentioned on line 439, but not defined == Missing Reference: 'RFC6020' is mentioned on line 449, but not defined == Missing Reference: 'RFC8040' is mentioned on line 460, but not defined == Missing Reference: 'RFC6242' is mentioned on line 462, but not defined == Missing Reference: 'RFC8446' is mentioned on line 464, but not defined == Missing Reference: 'RFC8341' is mentioned on line 466, but not defined Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF C. Feng 3 Internet-Draft Q. Ma 4 Intended status: Standards Track Huawei 5 Expires: December 24, 2021 C. Xie 6 China Telecom 7 June 22, 2021 9 System Configuration Data Handling Behavior 10 draft-ma-netconf-with-system-02 12 Abstract 14 This document defines an optional "system" datastore to allow clients 15 populate the system configuration into running datastore in the 16 device. It also defines a capability-based extension to the NETCONF 17 protocol that helps the NETCONF client identify how system 18 configuration are processed by the server. 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 December 24, 2021. 37 Copyright Notice 39 Copyright (c) 2021 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 . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 4 57 2. System Configuration Datastore . . . . . . . . . . . . . . . 4 58 2.1. Life Cycle of the system configuration management . . . . 4 59 2.2. "Factory-Reset" RPC Impact on System Configuration 60 Datastore . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3. System Configuration data handling Basic Modes . . . . . . . 5 62 3.1. 'auto-populate' Initialization During Reboot . . . . . . 6 63 3.2. 'auto-populate' Behavior towards 6 64 3.3. 'no-populate' Behavior towards . 7 65 4. Retrieval of System Configuration Data . . . . . . . . . . . 7 66 5. With System Capability . . . . . . . . . . . . . . . . . . . 7 67 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 7 68 5.2. Capability Identifier . . . . . . . . . . . . . . . . . . 8 69 5.3. Modifications to Existing Operations . . . . . . . . . . 8 70 5.3.1. Operations . . . . . . . . . . . . . . . . 8 71 5.3.2. Operation . . . . . . . . . . . . . . . 8 72 6. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 75 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 76 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 77 10.1. Normative References . . . . . . . . . . . . . . . . . . 11 78 10.2. Informative References . . . . . . . . . . . . . . . . . 11 79 Appendix A. Changes between Revisions . . . . . . . . . . . . . 12 80 Appendix B. Open Issues tracking . . . . . . . . . . . . . . . . 12 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 83 1. Introduction 85 The NETCONF protocol [RFC6241] defines ways to read configuration and 86 state data from a NETCONF server. 88 In some cases, a client-configured data item refers to a system 89 generated data item (e.g., the auto-created interfaces "eth1"), which 90 is only present in the datastore [RFC8342]. In order 91 for it being referenced, the duplicated system configured data item 92 needs to be retrieved from and overridden by the 93 client. 95 In some other cases, a system generated configured data item is in 96 the when/must statement, the similar operation should also be 97 performed to make sure a successful validation, which is cumbersome. 99 Furthmore, when the system generated data item gets updated, there is 100 no way to synchronize the update into and the client can't 101 detect the update automatically. 103 This document defines a "system" datastore to hold all the 104 configurations provided by the system itself. It also defines a 105 capability-based extension to the NETCONF protocol that allows the 106 configuration synchronization between and both 107 automatically and explicitly. 109 1.1. Terminology 111 This document assumes that the reader is familiar with the contents 112 of [RFC6241], [RFC7950], [RFC8342], [RFC8407], and [RFC8525] and uses 113 terminologies from those documents. 115 The following terms are defined in this document as follows: 117 System configuration: Configuration that is provided by the system 118 itself [RFC8342]. 120 System configuration datastore: A configuration datastore holding 121 the complete configuration provided by the system iteself. This 122 datastore is referred to as "". 124 physical resource independent system configuration: When the device 125 is powered on, the pre-provisioned configuration will be activated 126 and provided, irrespective of physical resource present or not, 127 sometimes the pre-provisioned configuration will be provided 128 without must/when statement constraint (e.g., loop back interface 129 activation), sometimes not, e.g., only provided when a special 130 functionality is enabled. 132 Physical resource dependent system configuration: When the device is 133 powered on and the physical resource is present (e.g., insert 134 interface card), the system will automatically detect it and load 135 pre-provisioned configuration; when the physical resource is not 136 present( remove interface card), the system configuration will be 137 automatically cleared. 139 1.2. Requirements Language 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 143 "OPTIONAL" in this document are to be interpreted as described in BCP 144 14 [RFC2119] [RFC8174] when, and only when, they appear in all 145 capitals, as shown here. 147 2. System Configuration Datastore 149 Following guidelines for defining Datastores in the appendix A of 150 [RFC8342], this document introduces a new datastore resource named 151 'system' that represents the system configuration. 153 o Name: "system" 155 o YANG modules: all 157 o YANG nodes: all "config true" data nodes 159 o Management operations: The content of the datastore is set by the 160 server in an implementation dependent manner. The content can not 161 be changed by management operations via NETCONF, RESTCONF,the CLI, 162 etc unless specialized, dedicated operations are provided. The 163 datastore can be read using the standard NETCONF/RESTCONF protocol 164 operations. 166 o Origin: This document does not define any new origin identity when 167 it interacts with datastore. The system origin 168 Metadata Annotation is used to indicate the origin of a data item. 170 o Protocols: RESTCONF, NETCONF and other management protocol. 172 o Defining YANG module: "ietf-netconf-with-system". 174 The datastore content is usually defined by the device vendor. It is 175 static at most of time and MAY change e.g., depending on external 176 factors like HW available or during device upgrade. does not 177 persist across reboots. It will be automatically loaded when the 178 device is powered on or the physical resource is present. 180 2.1. Life Cycle of the system configuration management 182 When the device is powered on, physical resource independent system 183 configuration will be created in automatically by the system 184 if there is no when/must statement constraint associated with system 185 configuration data or provided only when a special functionality is 186 enabled. 188 When the device is powered on and the physical resource is inserted 189 into the device, physical resource dependent system configuration 190 will be automatically loaded into ; 192 When the physical resource is removed from the device, the physical 193 resource dependent system configuration will be automatically removed 194 from ; 196 2.2. "Factory-Reset" RPC Impact on System Configuration Datastore 198 [RFC8808]defines a "factory-reset" RPC to allow clients to reset a 199 server back to its factory-default condition. Upon receiving the 200 RPC, all supported conventional read-write configuration 201 datastore(i.e.,, and ) are reset to the 202 contents of . should also immediately reset 203 to its factory default state. That's to say, any system 204 configurations generated due to system upgrading or client-enabled 205 functionality should be discarded. System configuration which is 206 generated at the first time when it boots after being shipped from 207 factory should be retained. 209 3. System Configuration data handling Basic Modes 211 Not all server implementations treat system configuration data in the 212 same way. Instead of forcing a single implementation strategy, this 213 document allows a server advertise a particular style of system 214 configuration data handling, and the client can adjust behavior 215 accordingly. 217 This document specifies two standard system configuration handling 218 basic modes that a server implementor may choose from: 220 o auto-populate 222 o no-populate 224 A server that uses the 'auto-populate' basic mode MUST automatically 226 o Update with the system configuration change, after the 227 "system" configuration has been altered as a consequence of a plug 228 and play operation or device powering on operation. However the 229 configurations in can not be removed automatically when 230 configuration data nodes in is deleted since those 231 configurations in are likely to have already been 232 modified or referenced. 234 o The system configuration doesn't need to be explicitly set by the 235 client first before the system configuration needs to be updated 236 with client set configuration or referenced by client set 237 configuration. 239 A server that uses the 'no-populate' basic mode 241 o MUST not update with the system configuration. 243 o The system configuration MUST be explicitly set by the client 244 first before the system configuration needs to be updated with 245 client set configuration or referenced by client set 246 configuration. 248 3.1. 'auto-populate' Initialization During Reboot 250 The contents of don't have to be persist across reboots, 251 even in the presence of non-volatile storage. 253 For the NETCONF server which implements the 254 datastore [RFC8808], it may load at the first time 255 when it boots after being shipped from factory or reset to its 256 factory default condition. Then it's just like each normal boot 257 time, the device generates system configurations and saves into 258 . Then the device loads the saved startup configuration(if 259 exists) into . Lastly, the device loads 260 into . If there exists any conflict, the configuration in 261 the should succeed. 263 3.2. 'auto-populate' Behavior towards 265 For a data node that is loaded from automatically, the 266 server MUST consider it to exist. 268 o A valid 'create' operation attribute for a data node that is 269 loaded from and set by the server MUST fail with a 'data- 270 exists' error-tag; 272 o A valid 'delete' operation attribute for a data node that is 273 loaded from and set by the server MUST succeed. The 274 deleted system configuration MUST be reloaded into 275 immediately if the system configuration is still present in the 276 ; 278 o A valid 'merge' operation attribute for a data node that is loaded 279 from and set by the server MUST succeed. 281 3.3. 'no-populate' Behavior towards 283 The server MUST NOT consider any system configuration data node to 284 exist in configuration datastore, except those explicitly 285 set by the client. 287 o A valid 'create' operation attribute for a data node that is set 288 by the server MUST succeed since the system configuration data is 289 not present in the configuration datastore. 291 o A valid 'merge' operation attribute for a data node that is set by 292 the server MUST succeed even though the name of data node in 293 is same as name of data node explicitly set by the 294 client. 296 o A valid 'delete' operation attribute for a data node that is set 297 by the client MUST succeed even though the name of data node in 298 is same as name of data node explicitly set by the 299 client. A valid 'delete' operation attribute for a data node that 300 is not explicitly set by the client MUST fail since system 301 configuration is not loaded into . 303 4. Retrieval of System Configuration Data 305 TBD 307 5. With System Capability 309 5.1. Overview 311 The :with-system capability indicates which system-data-handling 312 basic mode is supported by the server. These basic modes allow a 313 NETCONF client to control whether system configuration data is 314 returned by the server. Sending of system configuration data is 315 controlled for each individual operation separately. 317 A NETCONF server implementing the :with-system capability: 319 o MUST indicate its basic mode behavior by including the 'basic- 320 mode' parameter in the capability URI; 322 o MUST support the YANG module defined in Section 6 for the system 323 configuration data handling mode indicated by the 'basic-mode' 324 parameter. 326 5.2. Capability Identifier 328 urn:ietf:params:netconf:capability:with-system:1.0 330 The identifier MUST have a parameter: "basic-mode". This indicates 331 how the server will treat system configuration data, as defined in 332 Section 3. The allowed values of this parameter are 'auto-populate', 333 and 'no-populate', as defined in Section 3. 335 urn:ietf:params:netconf:capability:with-system:1.0?basic-mode=no- 336 populate 338 5.3. Modifications to Existing Operations 340 5.3.1. Operations 342 As defined in Section 6, retrieval of system configuration in 343 can be used through operation with the 344 "datastore" parameter set to "system". 346 5.3.2. Operation 348 The operation has several editing modes. The 'create', 349 and 'delete' editing operations are affected by the system 350 configuration data handling basic mode. The other enumeration values 351 for the NETCONF operation attribute are not affected. 353 If the operation attribute contains the value 'create', and the data 354 node already exists in the target configuration datastore, then the 355 server MUST return an response with a 'invalid-value' 356 error-tag. 358 If the client sets a data node that is explicitly set by the server, 359 the server MUST accept the request if it is valid. The server MUST 360 keep or discard the new value based on its system configuration data 361 handling basic mode. 363 6. YANG Module 365 This YANG module uses the "datastore" identity [RFC8342]. Every 366 NETCONF server which supports :with-system capability MUST implement 367 this YANG module. 369 file="ietf-netconf-with-system@2021-05-14.yang" 370 module ietf-netconf-with-system { 371 yang-version 1.1; 372 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-with-system"; 373 prefix ncws; 374 import ietf-datastores { 375 prefix ds; 376 reference 377 "RFC 8342: Network Management Datastore Architecture(NMDA)"; 378 } 380 organization 381 "IETF NETCONF (Network Configuration Protocol) Working Group"; 383 contact 384 "WG Web: 385 WG List: 386 WG Chair: 387 Editor: 388 "; 389 description 390 "This module defines an extension to the NETCONF protocol 391 that allows the NETCONF client to control how system configuration 392 data are handled by the server in particular NETCONF operations. 394 Copyright (c) 2010 IETF Trust and the persons identified as 395 the document authors. All rights reserved. 397 Redistribution and use in source and binary forms, with or 398 without modification, is permitted pursuant to, and subject 399 to the license terms contained in, the Simplified BSD License 400 set forth in Section 4.c of the IETF Trust's Legal Provisions 401 Relating to IETF Documents 402 (http://trustee.ietf.org/license-info). 404 This version of this YANG module is part of RFC XXXX; see 405 the RFC itself for full legal notices."; 406 // RFC Ed.: replace XXXX with actual RFC number and remove this note 408 revision 2021-05-14 { 409 description 410 "Initial version."; 411 reference 412 "RFC XXXX: With-system capability for NETCONF"; 413 } 415 feature system-datastore { 416 description 417 "Indicates that the system configuration is available as a datastore."; 418 } 420 identity system { 421 if-feature "system-datastore"; 422 base ds:datastore; 423 description 424 "This read-only datastore contains the system configuration for the 425 device that will be loaded into automatically in the 426 "auto-populate" basic mode."; 427 } 428 } 429 431 7. IANA Considerations 433 This document registers the following capability identifier URN in 434 the 'Network Configuration Protocol Capability URNs registry': 436 urn:ietf:params:netconf:capability:with-system:1.0 438 This document registers two XML namespace URNs in the 'IETF XML 439 registry', following the format defined in [RFC3688]. 441 URI: urn:ietf:params:xml:ns:netconf:system:1.0 442 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-with-system 444 Registrant Contact: The NETCONF WG of the IETF. 446 XML: N/A, the requested URIs are XML namespaces. 448 This document registers one module name in the 'YANG Module Names' 449 registry, defined in [RFC6020] . 451 name: ietf-netconf-with-system 452 prefix: ncws 453 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-system 454 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 456 8. Security Considerations 458 The YANG module specified in this document defines a schema for data 459 that is designed to be accessed via network management protocols such 460 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 461 is the secure transport layer, and the mandatory-to-implement secure 462 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 463 is HTTPS, and the mandatory-to-implement secure transport is TLS 464 [RFC8446]. 466 The Network Configuration Access Control Model (NACM) [RFC8341] 467 provides the means to restrict access for particular NETCONF or 468 RESTCONF users to a preconfigured subset of all available NETCONF or 469 RESTCONF protocol operations and content. 471 9. Acknowledgements 473 Thanks to Robert Wilton, Kent Watsen, Balazs Lengyel, Timothy Carey 474 for reviewing, and providing important input to, this document. 476 10. References 478 10.1. Normative References 480 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 481 Requirement Levels", BCP 14, RFC 2119, 482 DOI 10.17487/RFC2119, March 1997, 483 . 485 10.2. Informative References 487 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 488 and A. Bierman, Ed., "Network Configuration Protocol 489 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 490 . 492 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 493 RFC 7950, DOI 10.17487/RFC7950, August 2016, 494 . 496 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 497 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 498 May 2017, . 500 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 501 and R. Wilton, "Network Management Datastore Architecture 502 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 503 . 505 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 506 Documents Containing YANG Data Models", BCP 216, RFC 8407, 507 DOI 10.17487/RFC8407, October 2018, 508 . 510 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 511 and R. Wilton, "YANG Library", RFC 8525, 512 DOI 10.17487/RFC8525, March 2019, 513 . 515 [RFC8808] Wu, Q., Lengyel, B., and Y. Niu, "A YANG Data Model for 516 Factory Default Settings", RFC 8808, DOI 10.17487/RFC8808, 517 August 2020, . 519 Appendix A. Changes between Revisions 521 v01 - v02 523 o Remove System configuration data retrieval behavior in the 524 mainbody and examples in the appendix. 526 o Remove operation and operation extension from 527 the YANG data model. 529 o Change basic mode values into auto-populate, no-populate. 531 o Consider to work together with . 533 Appendix B. Open Issues tracking 535 o Do we need to define RPC to allow the server loads 536 configuration data into ? 538 o Can we introduce better terminology? 540 o Should we define a standard operation of system configuration 541 retrieval? 543 Authors' Addresses 545 Feng Chong 546 Huawei 547 101 Software Avenue, Yuhua District 548 Nanjing, Jiangsu 210012 549 China 551 Email: frank.fengchong@huawei.com 553 Qiufang Ma 554 Huawei 555 101 Software Avenue, Yuhua District 556 Nanjing, Jiangsu 210012 557 China 559 Email: maqiufang1@huawei.com 560 Chongfeng Xie 561 China Telecom 562 Beijing 563 China 565 Email: xiechf@chinatelecom.cn