idnits 2.17.1 draft-ma-netconf-with-system-01.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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The abstract seems to contain references ([RFC6241]), 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 == 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: MUST not update with the system configuration, -- The document date (November 2, 2020) is 1242 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: 'RFC6020' is mentioned on line 625, but not defined == Missing Reference: 'RFC3688' is mentioned on line 615, but not defined Summary: 2 errors (**), 0 flaws (~~), 4 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: May 6, 2021 November 2, 2020 7 With System Capability for NETCONF 8 draft-ma-netconf-with-system-01 10 Abstract 12 The NETCONF protocol [RFC6241] defines ways to read configuration and 13 state data from a NETCONF server. In some cases, a client-configured 14 data item refers to a non-existent system generated data item 15 (e.g.,the auto-create interfaces ("eth1") is not yet present). In 16 many situations, the system configured data item doesn't need to be 17 know to the client and client-configured data item will automatically 18 be removed from the operational state datastore and thus only appear 19 in the intended datastore if client-configured data item doesn't 20 exist. In other situations system configured data item needs to be 21 known and overriden by the client. Not all server implementations 22 treat the system configuration data in the same way. This document 23 defines a capability-based extension to the NETCONF protocol that 24 allows the NETCONF client to identify how system configuration are 25 processed by the server, and also defines a new mechanism for client 26 control of server processing of system configuration data. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on May 6, 2021. 45 Copyright Notice 47 Copyright (c) 2020 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 4 65 1.3. System Configuration Data Handling . . . . . . . . . . . 4 66 2. System Configuration Datastore . . . . . . . . . . . . . . . 4 67 2.1. Life Cycle of the system configuration . . . . . . . . . 5 68 3. System Configuration data handling Basic Modes . . . . . . . 5 69 3.1. 'report-all' Initialization During Reboot . . . . . . . . 6 70 3.2. 'report-all' Behavior . . . . . . . . . . . 7 71 3.3. 'explicit' Behavior . . . . . . . . . . . . 7 72 4. Retrieval of System Configuration Data . . . . . . . . . . . 8 73 5. With System Capability . . . . . . . . . . . . . . . . . . . 8 74 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 8 75 5.2. Capability Identifier . . . . . . . . . . . . . . . . . . 9 76 5.3. Modifications to Existing Operations . . . . . . . . . . 9 77 5.3.1. and Operations . . . . . . . . . . 9 78 5.3.2. Operation . . . . . . . . . . . . . . . 10 79 6. YANG Module for the Parameter . . . . . . . . . 10 80 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 81 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 82 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 83 9.1. Normative References . . . . . . . . . . . . . . . . . . 14 84 9.2. Informative References . . . . . . . . . . . . . . . . . 14 85 Appendix A. Usage Examples . . . . . . . . . . . . . . . . . . . 15 86 A.1. Example YANG Module . . . . . . . . . . . . . . . . . . . 15 87 A.2. Example Data Set . . . . . . . . . . . . . . . . . . . . 15 88 A.3. Protocol Operation Examples . . . . . . . . . . . . . . . 16 89 A.3.1. = 'report-all' . . . . . . . . . . . . 17 90 A.3.2. = 'report-all-tagged' . . . . . . . . . 18 91 A.3.3. = 'explicit' . . . . . . . . . . . . . 20 92 A.3.4. = 'trim' . . . . . . . . . . . . . . . 21 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 96 1. Introduction 98 The NETCONF protocol [RFC6241] defines ways to read configuration and 99 state data from a NETCONF server. 101 In some cases, a client-configured data item refers to a nonexistent 102 system generated data item (e.g.,the auto-create interfaces ("eth1") 103 is not yet present). 105 o In many situations, the system configured data item doesn't need 106 to be known to the client and client-configured data item will 107 automatically be removed from the operational state datastore and 108 thus only appear in the intended datastore if client-configured 109 data item doesn't exist. 111 o In other situations system configured data item needs to be known 112 and overriden by the client. Without system configuration 113 datastore, the duplicated system configured data item in the 114 system configuration need to be created and overriden by the 115 client each time there is a system configured data item being 116 referenced. 118 Therefore not all server implementations treat the system 119 configuration data in the same way. 121 This document defines a capability-based extension to the NETCONF 122 protocol that allows the NETCONF client to identify how system 123 configuration are processed by the server, and also defines new 124 mechanism for client control of server processing of system 125 configuration data. 127 1.1. Terminology 129 This document assumes that the reader is familiar with the contents 130 of [RFC6241], [RFC7950], [RFC8342], [RFC8407], and [RFC8525] and uses 131 terminologies from those documents. 133 The following terms are defined in this document as follows: 135 System configuration: Configuration that is supplied by the device 136 itself [RFC8342]. 138 Logical resource dependent system configuration: When the device is 139 powered on, the pre-provisioned configuration will be activated 140 and provided, irrespective of physical resource present or not, 141 sometimes the pre-provisioned configuration will be provided 142 unconditionally(e.g., loop back interface activation), sometimes 143 not, e.g., only provided when a special functionality is enabled. 145 Physical resource dependent system configuration: When the device is 146 powered on and the physical resource is present (e.g., insert 147 interface card), the system will automatically detect it and load 148 pre-provisioned configuration; when the physical resource is not 149 present( remove interface card), the system configuration will be 150 automatically cleared. 152 System configuration datastore: A configuration datastore holding 153 the complete system configuration of the device. This datastore 154 is referred to as "". 156 1.2. Requirements Language 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 160 "OPTIONAL" in this document are to be interpreted as described in BCP 161 14 [RFC2119] [RFC8174] when, and only when, they appear in all 162 capitals, as shown here. 164 1.3. System Configuration Data Handling 166 The system configuration data handling behavior used by a server will 167 impact NETCONF protocol operations in two ways: 169 o Data retrieval: A server is normally allowed to exclude data nodes 170 which it considers to contain the system configuration data. The 171 actual nodes omitted depends on the system configuration data 172 handling behavior used by the server. 174 o Create and delete operations: The 'operation' 175 attribute can be used to create and/or delete specific data nodes. 176 These operations depend on whether the target node currently 177 exists or not. The server's system configuration data handling 178 behavior will determine whether the requested node currently 179 exists in the configuration datastore or not. 181 2. System Configuration Datastore 183 Following guidelines for defining Datastores in the appendix A of 184 [RFC8342], this document introduces a new datastore resource named 185 'system' that represents the pre-provisioned configuration or 186 physical resource dependent configuration. 188 o Name: "system" 190 o YANG modules: all 192 o YANG nodes: all "config true" data nodes 194 o Management operations: The content of the datastore is set by the 195 server in an implementation dependent manner. The content can not 196 be changed by management operations via NETCONF, RESTCONF,the CLI 197 etc unless specialized, dedicated operations are provided. The 198 datastore can be read using the standard NETCONF/RESTCONF protocol 199 operations. 201 o Origin: This document does not define any new origin identity when 202 it interacts with datastore. The system origin 203 Metadata Annotation is used to indicate the origin of a data item. 205 o Protocols: RESTCONF, NETCONF and other management protocol. 207 o Defining YANG module: "ietf-netconf-with-system". 209 The datastore content is usually defined by the device vendor. It is 210 static at most of time and MAY change e.g., depending on external 211 factors like HW available or during device upgrade. does not 212 persist across reboots. It will be automatically loaded when the 213 device is powered on or the physical resource is present. 215 2.1. Life Cycle of the system configuration 217 When the device is powered on, unconditional logical resource 218 dependent system configuration will be generated and loaded into 219 automatically by the device operating system. Conditional 220 logical resource dependent system configuration is only provided when 221 a special functionality is enabled. 223 When the device is powered on and the physical resource is inserted 224 into the device, physical resource dependent system configuration 225 will be automatically loaded into ; 227 When the physical resource is removed from the device, the physical 228 resource dependent system configuration will be automatically removed 229 from ; 231 3. System Configuration data handling Basic Modes 233 Not all server implementations treat system configuration data in the 234 same way. Instead of forcing a single implementation strategy, this 235 document allows a server to advertise a particular style of system 236 configuration data handling, and the client can adjust accordingly. 238 NETCONF servers report system configuration data in different ways. 239 This document specifies two standard defaults handling basic modes 240 that a server implementor may choose from: 242 o report-all 244 o explicit 246 A server that uses the 'report-all' basic mode MUST automatically 248 o Update with the system configuration, after the "system" 249 configuration has been altered as a consequence of a plug and play 250 operation or device powering on operation. However the 251 configurations in can not be removed automatically when 252 configuration data nodes in is deleted since those 253 configurations in are likely to have already been 254 modified or referenced. 256 o The system configuration doesn't need to be explicitly set by the 257 client first before the system configuration needs to be updated 258 with client set configuration or referenced by client set 259 configuration. 261 A server that uses the 'explicit' basic mode 263 MUST not update with the system configuration, 265 The system configuration MUST be explicitly set by the client 266 first before the system configuration needs to be updated with 267 client set configuration or referenced by client set 268 configuration. 270 3.1. 'report-all' Initialization During Reboot 272 At boot time, the device loads the saved system configuration into 273 together with saved startup configuration via 'merge' 274 protocol operation. To save a new system configuration, data is 275 copied to via either implicit or explicit protocol 276 operations. 278 The contents of don't have to be persist across reboots. At 279 each boot time, the device generates system configurations (e.g., 280 unconditional logical resource dependent system configuration and 281 physical resource dependent system configuration) and saves into 282 . Then the device loads the saved startup configuration into 283 . The device may generate conditional logical resource 284 dependent system configuration at the time of loading . 285 Lastly, the device loads into . If there exists 286 any conflict, the configuration in the should succeed. 288 3.2. 'report-all' Behavior 290 The server MUST consider every data node to exist, even those set by 291 the server. 293 o A valid 'create' operation attribute for a data node that is 294 loaded from and explicitly set by the server MUST fail 295 with a 'data-exists' error-tag; 297 o A valid 'delete' operation attribute for a data node that is 298 loaded from and explicitly set by the server MUST 299 succeed. The deleted system configuration MUST be reloaded into 300 immediately if the system configuration is still present 301 in the ; 303 o A valid 'merge' operation attribute for a data node that is loaded 304 from and explicitly set by the server MUST succeed. 306 3.3. 'explicit' Behavior 308 The server considers any data node that is explicitly set data to 309 exist. 311 o A valid 'create' operation attribute for a data node that is 312 explicitly set by the server MUST succeed since the system 313 configuration data is not present in the configuration 314 datastore. 316 o A valid 'merge' operation attribute for a data node that is 317 explicitly set by the server MUST succeed even though the name of 318 data node in is same as name of data node explicitly set 319 by the client. 321 o A valid 'delete' operation attribute for a data node that is 322 explicitly set by the client MUST succeed even though the name of 323 data node in is same as name of data node explicitly set 324 by the client. A valid 'delete' operation attribute for a data 325 node that is not explicitly set by the client MUST fail since 326 system configuration is not loaded into . 328 4. Retrieval of System Configuration Data 330 When data is retrieved from a server using the 'report-all' basic 331 mode, and the parameter is not present, all data nodes 332 MUST be reported including data nodes considered to be system 333 configuration data by the server. 335 If the 'report-all' basic mode is used by the server and the parameter supported by the server is set to a value equal to 337 'report-all', all data nodes MUST be reported, including any data 338 nodes considered to be system configuration data by the server. 340 If the 'report-all' basic mode is used by the server and the parameter supported by the server is set to a value equal to 342 'report-all-tagged', all data nodes MUST be reported, including any 343 data nodes considered to be system configuration data by the server. 344 Explicitly set data by the server will be tagged if the system 345 configuration is applied. 347 When data is retrieved from a server using the 'explicit' basic mode, 348 and the parameter is not present, data nodes modified 349 explicitly by the client MUST be reported. 351 If the 'explicit' basic mode is used by the server and the parameter supported by the server is set to a value equal to 353 'explicit', data nodes MUST also be reported if explicitly modified 354 by the client. 356 When data is retrieved from a server using the 357 parameter with a value equal to 'trim' , data nodes MUST be reported 358 if considered to be not consistent with system configuration data by 359 the server. Data node MUST NOT be reported if explicitly modified by 360 the client. 362 5. With System Capability 364 5.1. Overview 366 The :with-system capability indicates which system-data-handling 367 basic mode is supported by the server. These basic modes allow a 368 NETCONF client to control whether system configuration data is 369 returned by the server. Sending of system configuration data is 370 controlled for each individual operation separately. 372 A NETCONF server implementing the :with-system capability: 374 o MUST indicate its basic mode behavior by including the 'basic- 375 mode' parameter in the capability URI; 377 o MUST support the YANG module defined in Section 6 for the system 378 configuration data handling mode indicated by the 'basic-mode' 379 parameter. 381 o SHOULD support the YANG module in Section 6 for the system 382 configuration data handling mode identified by the 'report-all' or 383 'report-all-tagged' enumeration value. 385 o If the 'report-all-tagged' system data handling mode is supported, 386 then the 'origin' metadata attribute MUST be supported. 388 o MAY support the YANG module in Section 6 for additional system 389 data handling modes. 391 5.2. Capability Identifier 393 urn:ietf:params:netconf:capability:with-system:1.0 395 The identifier MUST have a parameter: "basic-mode". This indicates 396 how the server will treat system configuration data, as defined in 397 Section 3. The allowed values of this parameter are 'report-all', 398 and 'explicit', as defined in Section 3. 400 The identifier MAY have another parameter: "also-supported". This 401 parameter indicates which additional enumeration values (besides the 402 basic-mode enumeration), the server will accept for the 403 parameter in Section 3. The value of the parameter is a comma 404 separated list of one or more modes that are supported beside the 405 mode indicated in the 'basic-mode' parameter. Possible modes are 406 'report-all', 'report-all-tagged','trim' and 'explicit', as defined 407 in Section 3. 409 urn:ietf:params:netconf:capability:with-system:1.0?basic- 410 mode=explicit&also-supported=report-all,report-all-tagged 412 5.3. Modifications to Existing Operations 414 5.3.1. and Operations 416 A new XML element is added to the input for the , 417 and operations. If the 418 element is present, it controls the reporting of system configuration 419 data. The server MUST return system configuration data in the 420 NETCONF messages according to the value of this element, 421 if the server supports the specified retrieval mode (i.e.,report-all/ 422 report-all-tagged). 424 This parameter only controls these specified retrieval operations, 425 and does not impact any other operations or the non-volatile storage 426 of configuration data. 428 The element is defined in the XML namespace for the 429 ietf-netconf-with-system.yang module in Section 6, not the XML 430 namespace for the , and operations. 432 If the element is not present, the server MUST follow 433 its basic mode behavior as indicated by the :with-system capability 434 identifier's 'basic-mode' parameter, defined in Section 5.2. 436 The and operations support a separate filtering 437 mechanism, using the parameter. The system configuration 438 data filtering is conceptually done before the parameter is 439 processed. For example, if the parameter is equal to 440 'report-all', then the parameter is conceptually applied to 441 all data nodes and all system configuration data. 443 5.3.2. Operation 445 The operation has several editing modes. The 'create', 446 and 'delete' editing operations are affected by the system 447 configuration data handling basic mode. The other enumeration values 448 for the NETCONF operation attribute are not affected. 450 If the operation attribute contains the value 'create', and the data 451 node already exists in the target configuration datastore, then the 452 server MUST return an response with a 'invalid-value' 453 error-tag. 455 If the client sets a data node that is explicitly set by the server, 456 the server MUST accept the request if it is valid. The server MUST 457 keep or discard the new value based on its system configuration data 458 handling basic mode. 460 6. YANG Module for the Parameter 462 The following YANG module defines the addition of the with-system 463 element to the , , and operations. 464 The YANG language is defined in [RFC6020]. The above operations are 465 defined in YANG in [RFC6241]. Every NETCONF server which supports 466 the :with-system capability MUST implement this YANG module. 468 file="ietf-netconf-with-system@2019-12-31.yang" 469 module ietf-netconf-with-system { 470 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-with-system"; 471 prefix ncws; 472 import ietf-netconf { prefix nc; } 474 organization 475 "IETF NETCONF (Network Configuration Protocol) Working Group"; 477 contact 478 "WG Web: 479 WG List: 480 WG Chair: 481 Editor: 482 "; 483 description 484 "This module defines an extension to the NETCONF protocol 485 that allows the NETCONF client to control how system configuration 486 data are handled by the server in particular NETCONF operations. 488 Copyright (c) 2010 IETF Trust and the persons identified as 489 the document authors. All rights reserved. 491 Redistribution and use in source and binary forms, with or 492 without modification, is permitted pursuant to, and subject 493 to the license terms contained in, the Simplified BSD License 494 set forth in Section 4.c of the IETF Trust's Legal Provisions 495 Relating to IETF Documents 496 (http://trustee.ietf.org/license-info). 498 This version of this YANG module is part of RFC XXXX; see 499 the RFC itself for full legal notices."; 500 // RFC Ed.: replace XXXX with actual RFC number and remove this note 502 revision 2019-12-31 { 503 description 504 "Initial version."; 505 reference 506 "RFC XXXX: With-system capability for NETCONF"; 507 } 509 typedef with-system-mode { 510 description 511 "Possible modes to report system configuration data."; 512 reference 513 "RFC XXXX; section 3."; 514 // RFC Ed.: replace XXXX with actual 515 // RFC number and remove this note 517 type enumeration { 518 enum report-all { 519 description 520 "All system configuration data is reported."; 521 reference 522 "RFC XXXX; section 3.1"; 523 // RFC Ed.: replace XXXX with actual 524 // RFC number and remove this note 526 } 527 enum report-all-tagged { 528 description 529 "All system configuration data is reported. 530 Any nodes considered to be system configuration 531 data will contain a 'origin' XML attribute, 532 set to 'system'."; 533 reference 534 "RFC XXXX; section 3.4"; 535 // RFC Ed.: replace XXXX with actual 536 // RFC number and remove this note 537 } 538 enum trim { 539 description 540 "Values are not reported if they contain the system 541 configuration data."; 542 reference 543 "RFC XXXX; section 3.2"; 544 // RFC Ed.: replace XXXX with actual 545 // RFC number and remove this note 547 } 548 enum explicit { 549 description 550 "Report values that contain the definition of 551 explicitly set data."; 552 reference 553 "RFC XXXX; section 3.3"; 554 // RFC Ed.: replace XXXX with actual 555 // RFC number and remove this note 556 } 557 } 558 } 560 grouping with-system-parameters { 561 description 562 "Contains the parameter for control 563 of system configuration data in NETCONF retrieval 564 operations."; 566 leaf with-system { 567 description 568 "The explicit system configuration data processing 569 mode requested."; 570 reference 571 "RFC XXXX; section 4.6.1"; 572 // RFC Ed.: replace XXXX with actual 573 // RFC number and remove this note 575 type with-system-mode; 576 } 577 } 579 // extending the get-config operation 580 augment /nc:get-config/nc:input { 581 description 582 "Adds the parameter to the 583 input of the NETCONF operation."; 584 reference 585 "RFC XXXX; section 4.6.1"; 586 // RFC Ed.: replace XXXX with actual 587 // RFC number and remove this note 589 uses with-system-parameters; 590 } 592 // extending the get operation 593 augment /nc:get/nc:input { 594 description 595 "Adds the parameter to 596 the input of the NETCONF operation."; 597 reference 598 "RFC XXXX; section 4.6.1"; 599 // RFC Ed.: replace XXXX with actual 600 // RFC number and remove this note 602 uses with-system-parameters; 603 } 604 } 605 607 7. IANA Considerations 609 This document registers the following capability identifier URN in 610 the 'Network Configuration Protocol Capability URNs registry': 612 urn:ietf:params:netconf:capability:with-system:1.0 614 This document registers two XML namespace URNs in the 'IETF XML 615 registry', following the format defined in [RFC3688]. 617 URI: urn:ietf:params:xml:ns:netconf:system:1.0 618 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-with-system 620 Registrant Contact: The NETCONF WG of the IETF. 622 XML: N/A, the requested URIs are XML namespaces. 624 This document registers one module name in the 'YANG Module Names' 625 registry, defined in [RFC6020] . 627 name: ietf-netconf-with-system 628 prefix: ncws 629 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-system 630 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 632 8. Acknowledgements 634 9. References 636 9.1. Normative References 638 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 639 Requirement Levels", BCP 14, RFC 2119, 640 DOI 10.17487/RFC2119, March 1997, 641 . 643 9.2. Informative References 645 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 646 and A. Bierman, Ed., "Network Configuration Protocol 647 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 648 . 650 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 651 RFC 7950, DOI 10.17487/RFC7950, August 2016, 652 . 654 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 655 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 656 May 2017, . 658 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 659 and R. Wilton, "Network Management Datastore Architecture 660 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 661 . 663 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 664 Documents Containing YANG Data Models", BCP 216, RFC 8407, 665 DOI 10.17487/RFC8407, October 2018, 666 . 668 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 669 and R. Wilton, "YANG Library", RFC 8525, 670 DOI 10.17487/RFC8525, March 2019, 671 . 673 Appendix A. Usage Examples 675 A.1. Example YANG Module 677 The following YANG module defines an example interfaces table to 678 demonstrate how the parameter behaves for a specific 679 data model. 681 container interfaces { 682 list interface { 683 key name; 684 leaf name { 685 type string; 686 } 687 leaf description { 688 type string; 689 } 690 leaf-list ip-address { 691 type inet:ip-address; 692 } 693 } 694 } 696 A.2. Example Data Set 698 The following data element shows the conceptual contents of the 699 example server for the protocol operation examples in the next 700 section. This includes all the configuration data nodes and system 701 configuration leafs. 703 704 705 706 lo0 707 127.0.0.1 708 ::1 709 710 711 lo1 712 loopback 713 127.0.0.1 714 ::2 715 716 717 lo2 718 loopback 719 127.0.0.1 720 ::3 721 722 723 lo3 724 127.0.0.1 725 ::1 726 727 728 730 In this example, the 'ip-address' field for each interface entry is 731 set in the following manner: 733 +---------+----------+-------+ 734 | name |ip-address| set by| 735 +---------+----------+-------+ 736 | lo0 |127.0.0.1 | server| 737 | lo0 | ::1 | server| 738 | lo1 |127.0.0.1 | server| 739 | lo1 | ::2 | client| 740 | lo2 |127.0.0.1 | server| 741 | lo2 | ::3 | client| 742 | lo3 |127.0.0.1 | server| 743 | lo3 | ::1 | server| 744 +---------+----------+-------+ 746 A.3. Protocol Operation Examples 748 The following examples show some operations using the 'with- 749 system' element. The data model used for these examples is defined 750 in Appendix A.1. 752 The client is retrieving all the data nodes within the 'interfaces' 753 object, filtered with the parameter. 755 A.3.1. = 'report-all' 757 The behavior of the parameter handling for the value 758 'report-all' is demonstrated in this example. 760 762 763 764 765 766 768 report-all 769 770 771 773 775 776 777 778 lo0 779 127.0.0.1 780 ::1 781 782 783 lo1 784 loopback 785 127.0.0.1 786 ::2 787 788 789 lo2 790 loopback 791 127.0.0.1 792 ::3 793 794 795 lo3 796 127.0.0.1 797 ::1 798 799 800 801 803 A.3.2. = 'report-all-tagged' 805 The behavior of the parameter handling for the value 806 'report-all-tagged' is demonstrated in this example. A 'tagged' data 807 node is an element that contains the 'origin' XML attribute, set to 808 'system'. 810 The actual data nodes tagged by the server depend on the system 811 configuration data handling basic mode used by the server. Only the 812 data nodes that are considered to be system configuration data will 813 be tagged. 815 In this example, the server's basic mode is 'explicit', then only 816 data nodes that are not explicitly set data are tagged. If the 817 server's basic mode is 'report-all', then no data nodes are tagged. 819 821 822 823 824 825 827 report-all-tagged 828 829 830 831 833 xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"> 834 835 836 837 lo0 838 127.0.0.1 839 ::1 840 841 842 lo1 843 loopback 844 127.0.0.1 845 ::2 846 847 848 lo2 849 loopback 850 127.0.0.1 851 ::3 852 853 854 lo3 855 127.0.0.1 856 ::1 857 858 859 860 862 A.3.3. = 'explicit' 864 The behavior of the parameter handling for the value 865 'explicit' is demonstrated in this example. 867 869 870 871 872 873 875 explicit 876 877 878 879 881 882 883 884 lo0 885 886 887 lo1 888 loopback 889 ::2 890 891 892 lo2 893 loopback 894 ::3 895 896 897 lo3 898 899 900 901 903 A.3.4. = 'trim' 905 The behavior of the parameter handling for the value 906 'trim' is demonstrated in this example. 908 910 911 912 913 914 916 trim 917 918 919 921 923 924 925 926 lo0 927 127.0.0.1 928 ::1 929 930 931 lo1 932 loopback 933 127.0.0.1 934 935 936 lo2 937 loopback 938 127.0.0.1 939 940 941 lo3 942 127.0.0.1 943 ::1 944 945 946 947 949 Authors' Addresses 950 Feng Chong 951 Huawei 952 101 Software Avenue, Yuhua District 953 Nanjing, Jiangsu 210012 954 China 956 Email: frank.fengchong@huawei.com 958 Qiufang Ma 959 Huawei 960 101 Software Avenue, Yuhua District 961 Nanjing, Jiangsu 210012 962 China 964 Email: maqiufang1@huawei.com