idnits 2.17.1 draft-ma-netconf-with-system-00.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 (October 20, 2020) is 1284 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 610, but not defined == Missing Reference: 'RFC3688' is mentioned on line 600, 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: April 23, 2021 October 20, 2020 7 With System Capability for NETCONF 8 draft-ma-netconf-with-system-00 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 April 23, 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 2. System Configuration Datastore . . . . . . . . . . . . . . . 4 66 2.1. Life Cycle of the system configuration . . . . . . . . . 5 67 3. System Configuration Data Handling . . . . . . . . . . . . . 5 68 4. System Configuration data handling Basic Modes . . . . . . . 5 69 4.1. Initialization During Reboot . . . . . . . . . . . . . . 6 70 4.2. 'report-all' Behavior . . . . . . . . . . . 6 71 4.3. 'explicit' Behavior . . . . . . . . . . . . 7 72 5. Retrieval of System Configuration Data . . . . . . . . . . . 7 73 6. With System Capability . . . . . . . . . . . . . . . . . . . 8 74 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 8 75 6.2. Capability Identifier . . . . . . . . . . . . . . . . . . 9 76 6.3. Modifications to Existing Operations . . . . . . . . . . 9 77 6.3.1. and Operations . . . . . . . . . . 9 78 6.3.2. Operation . . . . . . . . . . . . . . . 10 79 7. YANG Module for the Parameter . . . . . . . . . 10 80 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 81 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 82 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 83 10.1. Normative References . . . . . . . . . . . . . . . . . . 14 84 10.2. Informative References . . . . . . . . . . . . . . . . . 14 85 Appendix A. Usage Examples . . . . . . . . . . . . . . . . . . . 14 86 A.1. Example YANG Module . . . . . . . . . . . . . . . . . . . 14 87 A.2. Example Data Set . . . . . . . . . . . . . . . . . . . . 15 88 A.3. Protocol Operation Examples . . . . . . . . . . . . . . . 16 89 A.3.1. = 'report-all' . . . . . . . . . . . . 16 90 A.3.2. = 'report-all-tagged' . . . . . . . . . 17 91 A.3.3. = 'explicit' . . . . . . . . . . . . . 19 92 A.3.4. = 'trim' . . . . . . . . . . . . . . . 20 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 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 exists. 111 o In other situations system configured data item needs to be known 112 and overriden by the client. 114 Not all server implementations treat the system configuration data in 115 the same way. 117 This document defines a capablity-based extension to the NETCONF 118 protocol that allows the NETCONF client to identify how system 119 configuation are processed by the server, and also defines new 120 mechanism for client control of server processing of system 121 configuration data. 123 1.1. Terminology 125 This document assumes that the reader is familiar with the contents 126 of [RFC6241], [RFC7950], [RFC8342], [RFC8407], and [RFC8525] and uses 127 terminologies from those documents. 129 The following terms are defined in this document as follows: 131 System configuration: Configuration that is supplied by the device 132 itself [RFC8342]. 134 Logical resource dependent system configuration: When the device is 135 powered on, the pre-provisioned configuration will be activated 136 and provided, irrespective of physical resource present or not, 137 sometimes the pre-provisioned configuration will be provided 138 unconditionally(e.g., loop back interface activation), sometimes 139 not, e.g., only provided when a special functionality is enabled. 141 Physical resource dependent system configuration: When the device is 142 powered on and the physical resource is present(e.g., insert 143 interface card), the system will automatically detect it and load 144 pre-provisioned configuration; when the physical resource is not 145 present( remove interface card), the system configuration will be 146 automatically cleared. 148 System configuration datastore: A configuration datastore holding 149 the complete system configuration of the device. This datastore 150 is referred to as "". 152 1.2. Requirements Language 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 156 "OPTIONAL" in this document are to be interpreted as described in BCP 157 14 [RFC2119] [RFC8174] when, and only when, they appear in all 158 capitals, as shown here. 160 2. System Configuration Datastore 162 Following guidelines for defining Datastores in the appendix A of 163 [RFC8342], this document introduces a new datastore resource named 164 'system' that represents the pre-provisioned configuration or 165 physical resource dependent configuration. 167 o Name: "system" 169 o YANG modules: all 171 o YANG nodes: all "config true" data nodes 173 o Management operations: The content of the datastore is set by the 174 server in an implementation dependent manner. The content can not 175 be changed by management operations via NETCONF, RESTCONF,the CLI 176 etc unless specialized, dedicated operations are provided. The 177 datastore can be read using the standard NETCONF/RESTCONF protocol 178 operations. 180 o Origin: This document does not define any new origin identity when 181 it interacts with datastore. The system origin 182 Metadata Annotation is used to indicate the origin of a data item. 184 o Protocols: RESTCONF, NETCONF and other management protocol. 186 o Defining YANG module: "ietf-netconf-with-system". 188 The datastore content is usually defined by the device vendor. It is 189 static at most of time and MAY change e.g., depending on external 190 factors like HW available or during device upgrade. On devices that 191 support non-volatile storage, the contents of configuration 192 datastore need to be persist across reboots. 194 2.1. Life Cycle of the system configuration 196 When the device is powered on and the physical resource is inserted 197 into the device, physical resource dependent system configuration 198 will be automatically loaded into ; 200 When the physical resource is removed from the device, the physical 201 resource dependent system configuration will be automatically removed 202 from ; 204 When the Logical resource dependent system configuration is 205 referenced by another configured data item, it will be automatically 206 loaded into if it doesn't exist in the ; The 207 will keep unchanged if the Logical resource dependent system 208 configuration has already been existed in the . 210 3. System Configuration Data Handling 212 The system configuration data handling behavior used by a server will 213 impact NETCONF protocol operations in two ways: 215 o Data retrieval: A server is normally allowed to exclude data nodes 216 which it considers to contain the system configuration data. The 217 actual nodes omitted depends on the system configuration data 218 handling behavior used by the server. 220 o Create and delete operations: The 'operation' 221 attribute can be used to create and/or delete specific data nodes. 222 These operations depend on whether the target node currently 223 exists or not. The server's system configuration data handling 224 behavior will determine whether the requested node currently 225 exists in the configuration datastore or not. 227 4. System Configuration data handling Basic Modes 229 Not all server implementations treat system configuration data in the 230 same way. Instead of forcing a single implementation strategy, this 231 document allows a server to advertise a particular style of system 232 configuration data handling, and the client can adjust accordingly. 234 NETCONF servers report system configuration data in different ways. 235 This document specifies two standard defaults handling basic modes 236 that a server implementor may choose from: 238 o report-all 240 o explicit 242 A server that uses the 'report-all' basic mode MUST automatically 244 o Update with the system configuration, after the "system" 245 configuration has been altered as a consequence of a plug and play 246 operation or device powering on operation. 248 o The system configuration doesn't need to be explicitly set by the 249 client first before the system configuration needs to be updated 250 with client set configuration or referenced by client set 251 configuration. 253 A server that uses the 'explicit' basic mode 255 MUST not update with the system configuration, 257 The system configuration MUST be explicitly set by the client 258 first before the system configuration needs to be updated with 259 client set configuration or referenced by client set 260 configuration. 262 4.1. Initialization During Reboot 264 On devices that support non-volatile storage, the contents of 265 (e.g.,logical resource dependent system configuration 266 (conditional or unconditional) and physical resource dependent system 267 configuration) will typically persist across reboots via that 268 storage. At boot time, the device loads the saved system 269 configuration into together with saved startup 270 configuration via 'merge' protocol operation. To save a new system 271 configuration, data is copied to via either implicit or 272 explicit protocol operations. 274 4.2. 'report-all' Behavior 276 The server MUST consider every data node to exist, even those 277 explicitly set by the server. 279 o A valid 'create' operation attribute for a data node that is 280 loaded from and explicitly set by the server MUST fail 281 with a 'data-exists' error-tag; 283 o A valid 'delete' operation attribute for a data node that is 284 loaded from and explicitly set by the server MUST 285 succeed. The deleted system configuration MUST be reloaded into 286 immediately if the system configuration is still present 287 in the ; 289 o A valid 'merge' operation attribute for a data node that is loaded 290 from and explicitly set by the server MUST succeed. 292 4.3. 'explicit' Behavior 294 The server considers any data node that is explicitly set data to 295 exist. 297 o A valid 'create' operation attribute for a data node that is 298 explicitly set by the server MUST succeed since the system 299 configuration data is kept in the configuration 300 datastore. 302 o A valid 'merge' operation attribute for a data node that is 303 explicitly set by the server MUST succeed even though the name of 304 data node explicitly set by the server is same as name of data 305 node explicitly set by the client. 307 o A valid 'delete' operation attribute for a data node that is 308 explicitly set by the client MUST succeed even though the name of 309 data node explicitly set by the server is same as name of data 310 node explicitly set by the client. A valid 'delete' operation 311 attribute for a data node that is not explicitly set by the client 312 MUST fail if system configuration is not loaded into . 314 5. Retrieval of System Configuration Data 316 When data is retrieved from a server using the 'explicit' basic mode, 317 and the parameter is not present, data nodes MUST be 318 reported if explicitly modified by the client. 320 If the 'explicit' basic mode is used by the server and the parameter supported by the server is set to a value equal to 322 'explicit', data nodes MUST be reported if explicitly modified by the 323 client. 325 When data is retrieved from a server using the 'report-all' basic 326 mode, and the parameter is not present, all data nodes 327 MUST be reported without data nodes considered to be system 328 configuration data by the server. 330 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 332 'report-all', all data nodes MUST be reported, including any data 333 nodes considered to be system 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-tagged', all data nodes MUST be reported, including any 338 data nodes considered to be system configuration data by the server. 339 Explicitly set data by the server will be tagged with if the 340 system configuration is applied. 342 When data is retrieved from a server using the 343 parameter with a value equal to 'trim' , data nodes MUST be reported 344 if considered to be system configuration data by the server. Data 345 node MUST NOT be reported if explicitly modified by the client. 347 6. With System Capability 349 6.1. Overview 351 The :with-system capability indicates which system-data-handling 352 basic mode is supported by the server. These retrieval modes allow a 353 NETCONF client to control whether system configuration data is 354 returned by the server. Sending of system configuration data is 355 controlled for each individual operation separately. 357 A NETCONF server implementing the :with-system capability: 359 o MUST indicate its basic mode behavior by including the 'basic- 360 mode' parameter in the capability URI; 362 o MUST support the YANG module defined in Section 7 for the system 363 configuration data handling mode indicated by the 'basic-mode' 364 parameter. 366 o SHOULD support the YANG module in Section 7 for the system 367 configuration data handling mode identified by the 'report-all' or 368 'report-all-tagged' enumeration value. 370 o If the 'report-all-tagged' system data handling mode is supported, 371 then the 'origin' metadata attribute MUST be supported. 373 o MAY support the YANG module in Section 7 for additional system 374 data handling modes. 376 6.2. Capability Identifier 378 urn:ietf:params:netconf:capability:with-system:1.0 380 The identifier MUST have a parameter: "basic-mode". This indicates 381 how the server will treat system configuration data, as defined in 382 Section 4. The allowed values of this parameter are 'report-all', 383 and 'explicit', as defined in Section 4. 385 The identifier MAY have another parameter: "also-supported". This 386 parameter indicates which additional enumeration values (besides the 387 basic-mode enumeration), the server will accept for the 388 parameter in Section 4. The value of the parameter is a comma 389 separated list of one or more modes that are supported beside the 390 mode indicated in the 'basic-mode' parameter. Possible modes are 391 'report-all', 'report-all-tagged','trim' and 'explicit', as defined 392 in Section 4. 394 urn:ietf:params:netconf:capability:with-system:1.0?basic- 395 mode=explicit&also-supported=report-all,report-all-tagged 397 6.3. Modifications to Existing Operations 399 6.3.1. and Operations 401 A new XML element is added to the input for the , 402 and operations. If the 403 element is present, it controls the reporting of system configuration 404 data. The server MUST return system configuration data in the 405 NETCONF messages according to the value of this element, 406 if the server supports the specified retrieval mode. 408 This parameter only controls these specified retrieval operations, 409 and does not impact any other operations or the non-volatile storage 410 of configuration data. 412 The element is defined in the XML namespace for the 413 ietf-netconf-with-system.yang module in Section 7, not the XML 414 namespace for the , and operations. 416 If the element is not present, the server MUST follow 417 its basic mode behavior as indicated by the :with-system capability 418 identifier's 'basic-mode' parameter, defined in Section 6.2. 420 The and operations support a separate filtering 421 mechanism, using the parameter. The system configuration 422 data filtering is conceptually done before the parameter is 423 processed. For example, if the parameter is equal to 424 'report-all', then the parameter is conceptually applied to 425 all data nodes and all system configuration data. 427 6.3.2. Operation 429 The operation has several editing modes. The 'create', 430 and 'delete' editing operations are affected by the system 431 configuration data handling basic mode. The other enumeration values 432 for the NETCONF operation attribute are not affected. 434 If the operation attribute contains the value 'create', and the data 435 node already exists in the target configuration datastore, then the 436 server MUST return an response with a 'invalid-value' 437 error-tag. 439 If the client sets a data node that is explicitly set by the server, 440 the server MUST accept the request if it is valid. The server MUST 441 keep or discard the new value based on its system configuration data 442 handling basic mode. 444 7. YANG Module for the Parameter 446 The following YANG module defines the addition of the with-system 447 element to the , , and operations. 448 The YANG language is defined in [RFC6020]. The above operations are 449 defined in YANG in [RFC6241]. Every NETCONF server which supports 450 the :with-system capability MUST implement this YANG module. 452 file="ietf-netconf-with-system@2019-12-31.yang" 453 module ietf-netconf-with-system { 454 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-with-system"; 455 prefix ncws; 456 import ietf-netconf { prefix nc; } 458 organization 459 "IETF NETCONF (Network Configuration Protocol) Working Group"; 461 contact 462 "WG Web: 463 WG List: 464 WG Chair: 465 Editor: 466 "; 467 description 468 "This module defines an extension to the NETCONF protocol 469 that allows the NETCONF client to control how system configuration 470 data are handled by the server in particular NETCONF operations. 472 Copyright (c) 2010 IETF Trust and the persons identified as 473 the document authors. All rights reserved. 475 Redistribution and use in source and binary forms, with or 476 without modification, is permitted pursuant to, and subject 477 to the license terms contained in, the Simplified BSD License 478 set forth in Section 4.c of the IETF Trust's Legal Provisions 479 Relating to IETF Documents 480 (http://trustee.ietf.org/license-info). 482 This version of this YANG module is part of RFC XXXX; see 483 the RFC itself for full legal notices."; 484 // RFC Ed.: replace XXXX with actual RFC number and remove this note 486 revision 2019-12-31 { 487 description 488 "Initial version."; 489 reference 490 "RFC XXXX: With-system capability for NETCONF"; 491 } 493 typedef with-system-mode { 494 description 495 "Possible modes to report system configuration data."; 496 reference 497 "RFC XXXX; section 3."; 498 // RFC Ed.: replace XXXX with actual 499 // RFC number and remove this note 501 type enumeration { 502 enum report-all { 503 description 504 "All system configuration data is reported."; 505 reference 506 "RFC XXXX; section 3.1"; 507 // RFC Ed.: replace XXXX with actual 508 // RFC number and remove this note 510 } 511 enum report-all-tagged { 512 description 513 "All system configuration data is reported. 514 Any nodes considered to be system configuration 515 data will contain a 'origin' XML attribute, 516 set to 'system'."; 517 reference 518 "RFC XXXX; section 3.4"; 519 // RFC Ed.: replace XXXX with actual 520 // RFC number and remove this note 521 } 522 enum trim { 523 description 524 "Values are not reported if they contain the system 525 configuration data."; 526 reference 527 "RFC XXXX; section 3.2"; 528 // RFC Ed.: replace XXXX with actual 529 // RFC number and remove this note 531 } 532 enum explicit { 533 description 534 "Report values that contain the definition of 535 explicitly set data."; 536 reference 537 "RFC XXXX; section 3.3"; 538 // RFC Ed.: replace XXXX with actual 539 // RFC number and remove this note 540 } 541 } 542 } 544 grouping with-system-parameters { 545 description 546 "Contains the parameter for control 547 of system configuration data in NETCONF retrieval 548 operations."; 550 leaf with-system { 551 description 552 "The explicit system configuration data processing 553 mode requested."; 554 reference 555 "RFC XXXX; section 4.6.1"; 556 // RFC Ed.: replace XXXX with actual 557 // RFC number and remove this note 559 type with-system-mode; 560 } 561 } 563 // extending the get-config operation 564 augment /nc:get-config/nc:input { 565 description 566 "Adds the parameter to the 567 input of the NETCONF operation."; 569 reference 570 "RFC XXXX; section 4.6.1"; 571 // RFC Ed.: replace XXXX with actual 572 // RFC number and remove this note 574 uses with-system-parameters; 575 } 577 // extending the get operation 578 augment /nc:get/nc:input { 579 description 580 "Adds the parameter to 581 the input of the NETCONF operation."; 582 reference 583 "RFC XXXX; section 4.6.1"; 584 // RFC Ed.: replace XXXX with actual 585 // RFC number and remove this note 587 uses with-system-parameters; 588 } 589 } 590 592 8. IANA Considerations 594 This document registers the following capability identifier URN in 595 the 'Network Configuration Protocol Capability URNs registry': 597 urn:ietf:params:netconf:capability:with-system:1.0 599 This document registers two XML namespace URNs in the 'IETF XML 600 registry', following the format defined in [RFC3688]. 602 URI: urn:ietf:params:xml:ns:netconf:system:1.0 603 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-with-system 605 Registrant Contact: The NETCONF WG of the IETF. 607 XML: N/A, the requested URIs are XML namespaces. 609 This document registers one module name in the 'YANG Module Names' 610 registry, defined in [RFC6020] . 612 name: ietf-netconf-with-system 613 prefix: ncws 614 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-system 615 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 617 9. Acknowledgements 619 10. References 621 10.1. Normative References 623 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 624 Requirement Levels", BCP 14, RFC 2119, 625 DOI 10.17487/RFC2119, March 1997, 626 . 628 10.2. Informative References 630 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 631 and A. Bierman, Ed., "Network Configuration Protocol 632 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 633 . 635 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 636 RFC 7950, DOI 10.17487/RFC7950, August 2016, 637 . 639 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 640 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 641 May 2017, . 643 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 644 and R. Wilton, "Network Management Datastore Architecture 645 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 646 . 648 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 649 Documents Containing YANG Data Models", BCP 216, RFC 8407, 650 DOI 10.17487/RFC8407, October 2018, 651 . 653 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 654 and R. Wilton, "YANG Library", RFC 8525, 655 DOI 10.17487/RFC8525, March 2019, 656 . 658 Appendix A. Usage Examples 660 A.1. Example YANG Module 662 The following YANG module defines an example interfaces table to 663 demonstrate how the parameter behaves for a specific 664 data model. 666 container interfaces { 667 list interface { 668 key name; 669 leaf name { 670 type string; 671 } 672 leaf description { 673 type string; 674 } 675 leaf-list ip-address { 676 type inet:ip-address; 677 } 678 } 679 } 681 A.2. Example Data Set 683 The following data element shows the conceptual contents of the 684 example server for the protocol operation examples in the next 685 section. This includes all the configuration data nodes and system 686 configuration leafs. 688 689 690 691 lo0 692 127.0.0.1 693 ::1 694 695 696 lo1 697 loopback 698 127.0.0.1 699 ::2 700 701 702 lo2 703 loopback 704 127.0.0.1 705 ::3 706 707 708 lo3 709 127.0.0.1 710 ::1 711 712 713 715 In this example, the 'ip-address' field for each interface entry is 716 set in the following manner: 718 +---------+----------+-------+ 719 | name |ip-address| set by| 720 +---------+----------+-------+ 721 | lo0 |127.0.0.1 | server| 722 | lo0 | ::1 | server| 723 | lo1 |127.0.0.1 | server| 724 | lo1 | ::2 | client| 725 | lo2 |127.0.0.1 | server| 726 | lo2 | ::3 | client| 727 | lo3 |127.0.0.1 | server| 728 | lo3 | ::1 | server| 729 +---------+----------+-------+ 731 A.3. Protocol Operation Examples 733 The following examples show some operations using the 'with- 734 system' element. The data model used for these examples is defined 735 in Appendix A.1. 737 The client is retrieving all the data nodes within the 'interfaces' 738 object, filtered with the parameter. 740 A.3.1. = 'report-all' 742 The behavior of the parameter handling for the value 743 'report-all' is demonstrated in this example. 745 747 748 749 750 751 753 report-all 754 755 756 758 760 761 762 763 lo0 764 127.0.0.1 765 ::1 766 767 768 lo1 769 loopback 770 127.0.0.1 771 ::2 772 773 774 lo2 775 loopback 776 127.0.0.1 777 ::3 778 779 780 lo3 781 127.0.0.1 782 ::1 783 784 785 786 788 A.3.2. = 'report-all-tagged' 790 The behavior of the parameter handling for the value 791 'report-all-tagged' is demonstrated in this example. A 'tagged' data 792 node is an element that contains the 'origin' XML attribute, set to 793 'system'. 795 The actual data nodes tagged by the server depend on the system 796 configuration data handling basic mode used by the server. Only the 797 data nodes that are considered to be system configuration data will 798 be tagged. 800 In this example, the server's basic mode is 'explicit', then only 801 data nodes that are not explicitly set data are tagged. If the 802 server's basic mode is 'report-all', then no data nodes are tagged. 804 806 807 808 809 810 812 report-all-tagged 813 814 815 816 818 xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"> 819 820 821 822 lo0 823 127.0.0.1 824 ::1 825 826 827 lo1 828 loopback 829 127.0.0.1 830 ::2 831 832 833 lo2 834 loopback 835 127.0.0.1 836 ::3 837 838 839 lo3 840 127.0.0.1 841 ::1 842 843 844 845 847 A.3.3. = 'explicit' 849 The behavior of the parameter handling for the value 850 'explicit' is demonstrated in this example. 852 854 855 856 857 858 860 explicit 861 862 863 864 866 867 868 869 lo0 870 871 872 lo1 873 loopback 874 ::2 875 876 877 lo2 878 loopback 879 ::3 880 881 882 lo3 883 884 885 886 888 A.3.4. = 'trim' 890 The behavior of the parameter handling for the value 891 'trim' is demonstrated in this example. 893 895 896 897 898 899 901 trim 902 903 904 906 908 909 910 911 lo0 912 127.0.0.1 913 ::1 914 915 916 lo1 917 loopback 918 127.0.0.1 919 920 921 lo2 922 loopback 923 127.0.0.1 924 925 926 lo3 927 127.0.0.1 928 ::1 929 930 931 932 934 Authors' Addresses 935 Feng Chong 936 Huawei 937 101 Software Avenue, Yuhua District 938 Nanjing, Jiangsu 210012 939 China 941 Email: frank.fengchong@huawei.com 943 Qiufang Ma 944 Huawei 945 101 Software Avenue, Yuhua District 946 Nanjing, Jiangsu 210012 947 China 949 Email: maqiufang1@huawei.com