idnits 2.17.1 draft-ietf-netconf-with-defaults-08.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 20, 2010) is 5089 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) ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) == Outdated reference: A later version (-10) exists of draft-ietf-netconf-4741bis-02 == Outdated reference: A later version (-13) exists of draft-ietf-netmod-yang-12 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF A. Bierman 3 Internet-Draft InterWorking Labs 4 Intended status: Standards Track B. Lengyel 5 Expires: November 21, 2010 Ericsson 6 May 20, 2010 8 With-defaults capability for NETCONF 9 draft-ietf-netconf-with-defaults-08 11 Abstract 13 The NETCONF protocol defines ways to read and edit configuration data 14 from a NETCONF server. Part of this data may not be set by the 15 NETCONF client, but rather a default value is used. In many 16 situations the NETCONF client has a priori knowledge about default 17 data, so the NETCONF server does not need to save it in a NETCONF 18 datastore or send it to the client in a retrieval operation reply. 19 In other situations the NETCONF client will need this data as part of 20 the NETCONF messages. Not all server implementations 21 treat this default data the same way. This document defines a 22 capability-based extension to the NETCONF protocol that allows the 23 NETCONF client to identify how defaults are handled by the server, 24 and control whether default values are part of NETCONF 25 messages or output to a file. 27 Status of this Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on November 21, 2010. 44 Copyright Notice 46 Copyright (c) 2010 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 63 1.2. Defaults Handling Behavior . . . . . . . . . . . . . . . . 5 64 1.3. Client Controlled Retrieval of Default Data . . . . . . . 5 65 2. Defaults Handling Basic Modes . . . . . . . . . . . . . . . . 6 66 2.1. 'report-all' Basic Mode . . . . . . . . . . . . . . . . . 6 67 2.1.1. 'report-all' Basic Mode Retrieval . . . . . . . . . . 6 68 2.1.2. 'report-all' Retrieval . . . . . . . . 6 69 2.1.3. 'report-all' Behavior . . . . . . . . . 6 70 2.1.4. 'report-all' Non-volatile Storage Behavior . . . . . . 7 71 2.2. 'trim' Basic Mode . . . . . . . . . . . . . . . . . . . . 7 72 2.2.1. 'trim' Basic Mode Retrieval . . . . . . . . . . . . . 7 73 2.2.2. 'trim' Retrieval . . . . . . . . . . . 7 74 2.2.3. 'trim' Behavior . . . . . . . . . . . . 7 75 2.2.4. 'trim' Non-volatile Storage Behavior . . . . . . . . . 8 76 2.3. 'explicit' Basic Mode . . . . . . . . . . . . . . . . . . 8 77 2.3.1. 'explicit' Basic Mode Retrieval . . . . . . . . . . . 8 78 2.3.2. 'explicit' Retrieval . . . . . . . . . 8 79 2.3.3. 'explicit' Behavior . . . . . . . . . . 8 80 2.3.4. 'explicit' Non-volatile Storage Behavior . . . . . . . 9 81 3. Retrieval of Default Data . . . . . . . . . . . . . . . . . . 9 82 3.1. 'report-all-tagged' Retrieval Mode . . . . . . . . . . . . 9 83 4. With-defaults Capability . . . . . . . . . . . . . . . . . . . 10 84 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 10 85 4.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 10 86 4.3. Conformance . . . . . . . . . . . . . . . . . . . . . . . 10 87 4.4. Capability Identifier . . . . . . . . . . . . . . . . . . 10 88 4.5. New Operations . . . . . . . . . . . . . . . . . . . . . . 11 89 4.6. Modifications to Existing Operations . . . . . . . . . . . 11 90 4.6.1. , , and Operations . . 11 91 4.6.2. Operation . . . . . . . . . . . . . . . 12 92 4.6.3. Other Operations . . . . . . . . . . . . . . . . . . . 12 93 4.7. Interactions with Other Capabilities . . . . . . . . . . . 13 94 5. YANG Module for the Parameter . . . . . . . . 13 95 6. XSD for the 'wd:default' Attribute . . . . . . . . . . . . . . 15 96 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 97 8. Security Considerations . . . . . . . . . . . . . . . . . . . 17 98 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 99 10. Normative References . . . . . . . . . . . . . . . . . . . . . 17 100 Appendix A. Usage Examples . . . . . . . . . . . . . . . . . . . 18 101 A.1. Example YANG Module . . . . . . . . . . . . . . . . . . . 18 102 A.2. Example Data Set . . . . . . . . . . . . . . . . . . . . . 20 103 A.3. Protocol Operation Examples . . . . . . . . . . . . . . . 21 104 A.3.1. = 'report-all' . . . . . . . . . . . . 21 105 A.3.2. = 'report-all-tagged' . . . . . . . . 22 106 A.3.3. = 'trim' . . . . . . . . . . . . . . . 25 107 A.3.4. = 'explicit' . . . . . . . . . . . . . 26 108 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 27 109 B.1. 07-08 . . . . . . . . . . . . . . . . . . . . . . . . . . 27 110 B.2. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 27 111 B.3. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 27 112 B.4. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 28 113 B.5. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 28 114 B.6. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 28 115 B.7. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 116 B.8. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 117 B.9. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 118 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 120 1. Introduction 122 The NETCONF protocol [RFC4741] defines ways to read configuration and 123 state data from a NETCONF server. Part of the configuration data may 124 not be set by the NETCONF client, but rather by a default value from 125 the data model. In many situations the NETCONF client has a priori 126 knowledge about default data, so the NETCONF server does not need to 127 send it to the client. A priori knowledge can be e.g., a document 128 formally describing the data models supported by the NETCONF server. 130 It can be important for a client to know exactly how a server 131 implementation will handle default data. There are subtle 132 differences in some protocol operations where the defaults handling 133 behavior of the server will affect the outcome of the operation. 135 1.1. Terminology 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 139 document are to be interpreted as described in [RFC2119]. 141 Data model schema: A document or set of documents describing the 142 data models supported by the NETCONF server. 143 Management Application: A computer program running outside the 144 NETCONF server that configures or supervises the NETCONF server. 145 A management application can reach the device e.g. via NETCONF, 146 CLI or SNMP. 147 Schema default data: Data specified in the data model schema as 148 default, that is set or used by the device whenever the NETCONF 149 client or other management application/user does not provide a 150 specific value for the relevant data item. Schema default data 151 MAY or may not be stored as part of a configuration datastore, 152 depending on the basic mode used by a particular server. 153 Default data: Data considered by a particular server to contain a 154 default value. Default data is not kept in a configuration 155 datastore. 156 Explicitly set data: Data that is set to any value by a NETCONF 157 client or other management application by the way of an actual 158 management operation, including any data model schema default 159 value. Any value set by the NETCONF server which is not the 160 schema defined default value is also considered explicitly set 161 data. 163 The following terms are defined in [RFC4741]: 164 o client 165 o datastore 166 o operation 167 o server 169 The following term is defined in [I-D.ietf-netmod-yang]: 170 o data node 172 1.2. Defaults Handling Behavior 174 The defaults handling behavior used by a server will impact NETCONF 175 protocol operations in three ways: 177 1. Data retrieval: A server is normally allowed to exclude data 178 nodes which it considers to contain the default value. The 179 actual nodes omitted depends on the defaults handling behavior 180 used by the server. The nodes that are returned in this case are 181 the only nodes the server considers to exist in the datastore. 183 2. Create and delete operations: The 'operation' 184 attribute can be used to create and/or delete specific data 185 nodes. These operations depend on whether the target node 186 currently exists or not. The server's defaults handling behavior 187 will determine whether the requested node currently exists in the 188 datastore or not. 190 3. NV Storage: The server's defaults handling behavior will affect 191 which data nodes are saved in non-volatile storage. 193 1.3. Client Controlled Retrieval of Default Data 195 A networking device may have a large number of default values. Often 196 the default values are not interesting or specifically defined with a 197 "reasonable" value, so that the management user does not have to 198 handle them. For these reasons it is quite common for networking 199 devices to suppress the output of parameters having the default 200 value. 202 However, there are use-cases when a NETCONF client will need the 203 default data from the server: 205 o The management application often needs a single, definitive and 206 complete set of configuration values that determine how the a 207 networking device works. 208 o Documentation about default values can be unreliable or 209 unavailable. 210 o Some management applications might not have the capabilities to 211 correctly parse and interpret formal data models. 213 o Human users might want to understand the received data without 214 consultation of the documentation. 216 In all these cases the NETCONF client will need default data as part 217 of the NETCONF messages. 219 This document defines a NETCONF protocol capability to identify the 220 server defaults handling behavior, and a YANG module extension to the 221 NETCONF protocol that allows the NETCONF client to control whether 222 default data is returned in certain NETCONF messages. 224 2. Defaults Handling Basic Modes 226 Not all server implementations treat default data in the same way. 227 Instead of forcing a single implementation strategy, this document 228 allows a server to advertise a particular style of defaults handling, 229 and the client can adjust accordingly. 231 NETCONF servers report default data in different ways. This document 232 specifies three standard defaults handling basic modes that a server 233 implementor may choose from: 235 o report-all 236 o trim 237 o explicit 239 A server MUST select one of the three basic modes defined in this 240 section for handling default data. 242 2.1. 'report-all' Basic Mode 244 A server which uses the 'report-all' basic mode does not consider any 245 data node to be default data. 247 2.1.1. 'report-all' Basic Mode Retrieval 249 All data nodes MUST be reported. 251 2.1.2. 'report-all' Retrieval 253 All data nodes MUST be reported, including any data nodes considered 254 to be default data by the server. 256 2.1.3. 'report-all' Behavior 258 The server MUST consider every data node to exist, even those 259 represented by a schema default value. 261 o A valid 'create' operation for a data node that contains its 262 schema default value MUST fail with a 'data-exists' error-tag. 263 o A valid 'delete' operation for a data node that contains its 264 schema default value MUST succeed, even though the data node is 265 immediately replaced by the server with the default value. 267 2.1.4. 'report-all' Non-volatile Storage Behavior 269 All data nodes MUST be saved in non-volatile storage. 271 2.2. 'trim' Basic Mode 273 A server which uses the 'trim' basic mode MUST consider any data node 274 set to its schema default value to be default data. 276 2.2.1. 'trim' Basic Mode Retrieval 278 Data nodes MUST NOT be reported if they match the schema default 279 value. Non-configuration data nodes containing the schema default 280 value MUST NOT be reported. 282 2.2.2. 'trim' Retrieval 284 Data nodes MUST NOT be reported if they match the schema default 285 value. Non-configuration data nodes containing the schema default 286 value MUST NOT be reported. 288 2.2.3. 'trim' Behavior 290 The server MUST consider any data node that does not contain its 291 schema default value to exist. 293 o A valid 'create' operation for a data node that has a schema 294 default value defined MUST succeed. 295 o A valid 'delete' operation for a missing data node that has a 296 schema default value MUST fail with a 'data-missing' error-tag. 297 o If a client sets a data node to its schema default value, using 298 any valid operation, it MUST succeed, although the data node MUST 299 NOT be saved in the NETCONF datastore. This has the same affect 300 as removing the data node and treating it as default data. 302 If the server supports the 'report-all-tagged' retrieval mode in its 303 with-defaults capability, then the 'wd:default' attribute MUST be 304 accepted in configuration input. If all NETCONF sub-operation 305 parameters are valid, then the server will treat a tagged data node 306 as a request to return that node to default data. If this request is 307 valid within the context of the requested NETCONF operation, then the 308 data node is removed and returned to its default value. If the data 309 node within the NETCONF message contains a value in this case, it 310 MUST be equal to the schema default value. 312 2.2.4. 'trim' Non-volatile Storage Behavior 314 All data nodes, except those set to their schema default value, MUST 315 be saved in non-volatile storage. 317 2.3. 'explicit' Basic Mode 319 A server which uses the 'explicit' basic mode MUST consider any data 320 node that is not explicitly set data to be default data. 322 2.3.1. 'explicit' Basic Mode Retrieval 324 If a client set a data node to its schema default value, it MUST 325 always be reported. If the server set a data node to its schema 326 default value, it MUST NOT be reported. Non-configuration data nodes 327 containing the schema default value MUST be reported. 329 2.3.2. 'explicit' Retrieval 331 If a client set a data node to its schema default value, it MUST be 332 reported. If the server set a data node to its schema default value, 333 it MUST NOT be reported. Non-configuration data nodes containing the 334 schema default value MUST be reported. 336 2.3.3. 'explicit' Behavior 338 The server considers any data node that is explicitly set data to 339 exist. 341 o A valid 'create' operation for a data node that has been set by a 342 client to its schema default value MUST fail with a 'data-exists' 343 error-tag. 344 o A valid 'create' operation for a data node that has been set by 345 the server to its schema default value MUST succeed. 346 o A valid 'delete' operation for a data node that has been set by a 347 client to its schema default value MUST succeed. 348 o A valid 'delete' operation for a data node that has been set by 349 the server to its schema default value MUST fail with a 'data- 350 missing' error-tag. 352 If the server supports the 'report-all-tagged' retrieval mode in its 353 with-defaults capability, then the 'wd:default' attribute MUST be 354 accepted in configuration input. If all NETCONF sub-operation 355 parameters are valid, then the server will treat a tagged data node 356 as a request to return that node to default data. If this request is 357 valid within the context of the requested NETCONF operation, then the 358 data node is removed and returned to its default value. If the data 359 node within the NETCONF message contains a value in this case, it 360 MUST be equal to the schema default value. 362 2.3.4. 'explicit' Non-volatile Storage Behavior 364 All data nodes that are explicitly set data MUST be saved in non- 365 volatile storage. 367 3. Retrieval of Default Data 369 This document defines a new parameter, called , which 370 can be added to specific NETCONF operation request messages to 371 control how retrieval of default data is treated by the server. 373 The server MUST accept the parameter containing the 374 enumeration for any of the defaults handling modes it supports, as 375 defined in Section 5. 377 The parameter contains one of the three basic mode 378 enumerations defined above, to request that the retrieval operation 379 be performed using the specified defaults handling basic mode. 381 3.1. 'report-all-tagged' Retrieval Mode 383 In addition to the basic modes, a special variant of 'report-all' 384 basic mode is available called 'report-all-tagged'. This mode MUST 385 be supported on a server if the 'also-supported' parameter in the 386 'with-defaults' capability contains the 'report-all-tagged' option. 387 Refer to Section 4 for encoding details for this capability. 389 In this mode the server returns all data nodes, just like the 390 'report-all' mode, except a data node that is considered by the 391 server to contain default data will include an XML attribute to 392 indicate this condition. This is useful for an application to 393 determine which nodes are considered to contain default data by the 394 server, within a single retrieval operation. 396 A server which supports 'report-all-tagged' MUST also accept the 'wd: 397 default' XML attribute it is present within configuration input to 398 the or operations. Refer to Section 6 399 for XML encoding details of the 'wd:default' XML attribute. 401 4. With-defaults Capability 403 4.1. Overview 405 The :with-defaults capability indicates that the NETCONF server 406 supports a specific defaults handling basic mode. It may also 407 indicate support for additional defaults retrieval modes. These 408 retrieval modes allow a NETCONF client to control whether default 409 data is part of NETCONF messages. The capability affects 410 both configuration and state data (while acknowledging that the usage 411 of default values for state data is less prevalent). Sending of 412 default data is controlled for each individual operation separately. 414 A NETCONF server implementing the :with-defaults capability: 416 o MUST indicate its basic mode behavior by including the 'basic- 417 mode' parameter in the capability URI, as defined in Section 4.4. 418 o MUST support the YANG module defined in Section 5. 419 o SHOULD support the 'report-all' or 'report-all-tagged' defaults 420 handling mode. 421 o MAY support additional defaults handling modes. 423 4.2. Dependencies 425 None 427 4.3. Conformance 429 Every NETCONF server SHOULD implement this capability. 431 4.4. Capability Identifier 433 urn:ietf:params:netconf:capability:with-defaults:1.0 435 The identifier MUST have a parameter: "basic-mode". This indicates 436 how the server will treat default data, as defined in Section 2. 438 The allowed values of this parameter are 'report-all', 'trim', and 439 'explicit', as defined in Section 2. 441 The identifier MAY have another parameter: "also-supported". This 442 parameter indicates which additional default handling modes the 443 server supports. The value of the parameter is a comma separated 444 list of one or more modes that are supported beside the mode 445 indicated in the 'basic-mode' parameter. Possible modes are 'report- 446 all', 'report-all-tagged', 'trim', and 'explicit', as defined in 447 Section 5. 449 Note that this protocol capability URI is separate from the YANG 450 module capability URI for the YANG module in Section 5. A server 451 which implements this module MUST also advertise a YANG module 452 capability URI according to the rules specified in 453 [I-D.ietf-netmod-yang]. 455 Examples: 457 urn:ietf:params:netconf:capability:with-defaults:1.0?basic- 458 mode=explicit 460 urn:ietf:params:netconf:capability:with-defaults:1.0?basic- 461 mode=explicit&also-supported=report-all,report-all-tagged 463 4.5. New Operations 465 None 467 4.6. Modifications to Existing Operations 469 4.6.1. , , and Operations 471 A new XML element is added to the input for the 472 , and operations. If the element is present, it controls the reporting of default 474 data. The server MUST return default data in the NETCONF 475 messages according to the value of this element, if the server 476 supports the specified retrieval mode. 478 This parameter only controls these specified retrieval operations, 479 and does not impact any other operations or the non-volatile storage 480 of configuration data. 482 The element is defined in the XML namespace for the 483 ietf-netconf-with-defaults.yang module in Section 5, not the XML 484 namespace for the , and operations. 486 Allowed values of the with-defaults element are taken from the list 487 in Section 2. The allowed values are restricted to the values that 488 the device indicates it supports within the with-defaults capability, 489 in the 'basic-mode' and 'also-supported' parameters. 491 If an unsupported value is used, the NETCONF server MUST return an 492 with an element. The SHOULD be 493 'invalid-value', and the SHOULD be 'with-defaults- 494 mode-not-supported'. 496 If the element is not present, the server MUST follow 497 its basic mode behavior as indicated by the with-defaults capability 498 identifier's 'basic-mode' parameter, defined in Section 4.4. 500 The operation is only affected if the target of the 501 operation is specified with the parameter. If the target is a 502 NETCONF datastore (i.e., running, candidate or startup), the 503 capability has no effect. The server MUST use its basic mode when 504 copying data to a NETCONF datastore. If the with-defaults parameter 505 is present in this case, it MUST be silently ignored by the server. 507 4.6.2. Operation 509 The operation has four sub-operations. The 'create' 510 and 'delete' sub-operations are affected by the defaults handling 511 basic mode. 513 The 'create' sub-operation MUST fail with a 'data-exists' error-tag 514 value if the server considers the target data node to already have a 515 current value. 517 If the client sets a data node to its schema default value, the 518 server MUST accept the request if it is valid. The server MUST keep 519 or discard the new value based on its defaults handling basic mode. 520 For the 'trim' basic mode, all schema default values are discarded, 521 otherwise a client-provided schema default value is saved in a 522 NETCONF datastore. 524 If the server supports the 'report-all-tagged' mode, then the 'wd: 525 default' attribute defined in Section 6 also impacts the edit-config 526 operation. If the wd:default attribute is present and set to 'true', 527 then the server MUST treat the new data node as a request to return 528 that node to its default value (i.e., remove it from the database). 530 If this editing mode is used, then the effective sub-operation for 531 the target data node MUST be 'create', 'merge' or 'replace'. If 532 'create' is the effective sub-operation, then the create request must 533 be valid on its own (e.g., current data node MUST NOT exist). The 534 procedure for determining the effective sub-operation is defined in 535 [I-D.ietf-netconf-4741bis]. It is derived from the 'default- 536 operation' parameter and/or any 'nc:operation' attribute that are 537 present in the data node or any of its ancestor nodes, within the 538 request message. 540 4.6.3. Other Operations 542 Other operations that return configuration data SHOULD also handle 543 default data according to the rules set in this document, and 544 explicitly state this in their documentation. If this is not 545 specified in the document defining the respective operation, the 546 default handling rules described herein do not affect these 547 operations. 549 4.7. Interactions with Other Capabilities 551 None 553 5. YANG Module for the Parameter 555 The following YANG module defines the addition of the with-defaults 556 element to the , and operations. The 557 YANG language is defined in [I-D.ietf-netmod-yang]. The above 558 operations are defined in YANG in [I-D.ietf-netconf-4741bis]. Every 559 NETCONF server which supports the :with-defaults capability MUST 560 implement this YANG module. 562 file="ietf-netconf-with-defaults@2010-05-19.yang" 564 module ietf-netconf-with-defaults { 566 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults"; 568 prefix nwd; 570 import ietf-netconf { prefix nc; } 572 organization 573 "IETF NETCONF (Network Configuration Protocol) Working Group"; 575 contact 576 "WG Web: 577 WG List: 579 WG Chair: Bert Wijnen 580 582 WG Chair: Mehmet Ersue 583 585 Editor: Andy Bierman 586 588 Editor: Balazs Lengyel 589 "; 591 description 592 "This module defines a capability-based extension to the 593 NETCONF protocol that allows the NETCONF client to control 594 whether default values are part of NETCONF 595 messages or output to the target URL. 597 Copyright (c) 2010 IETF Trust and the persons identified as 598 the document authors. All rights reserved. 600 Redistribution and use in source and binary forms, with or 601 without modification, is permitted pursuant to, and subject 602 to the license terms contained in, the Simplified BSD License 603 set forth in Section 4.c of the IETF Trust's Legal Provisions 604 Relating to IETF Documents 605 (http://trustee.ietf.org/license-info). 607 This version of this YANG module is part of RFC XXXX; see 608 the RFC itself for full legal notices."; 609 // RFC Ed.: replace XXXX with actual RFC number and remove this note 611 // RFC Ed.: remove this note 612 // Note: extracted from draft-ietf-netmod-with-defaults-08.txt 614 revision 2010-05-19 { 615 description 616 "Initial version."; 617 reference 618 "RFC XXXX: With-defaults capability for NETCONF"; 619 } 620 // RFC Ed.: replace XXXX with actual RFC number and remove this note 622 typedef with-defaults-mode { 623 description 624 "Possible modes to report default data in 625 rpc-reply messages."; 626 type enumeration { 627 enum report-all { 628 description 629 "All default data is reported."; 630 } 631 enum report-all-tagged { 632 description 633 "All default data is reported. 634 Any nodes considered to be default data 635 will contain a 'wd:default' XML attribute, 636 set to 'true'."; 637 } 638 enum trim { 639 description 640 "Values are not reported if they match the default."; 641 } 642 enum explicit { 643 description 644 "Report values that match the definition of 645 explicitly set data."; 646 } 647 } 648 } 650 grouping with-defaults-parameters { 651 leaf with-defaults { 652 description 653 "The explicit defaults processing mode requested."; 654 type with-defaults-mode; 655 } 656 } 658 // extending the get-config operation 659 augment /nc:get-config/nc:input { 660 uses with-defaults-parameters; 661 } 663 // extending the get operation 664 augment /nc:get/nc:input { 665 uses with-defaults-parameters; 666 } 668 // extending the copy-config operation 669 augment /nc:copy-config/nc:input { 670 uses with-defaults-parameters; 671 } 673 } 675 677 6. XSD for the 'wd:default' Attribute 679 The following XML Schema document defines the 'default' attribute, 680 described within this document. This XSD is only relevant if the 681 server supports the 'report-all-tagged' defaults retrieval mode. 683 file="defaults.xsd" 685 686 693 694 695 This schema defines the syntax for the 'default' attribute 696 described within this document. 697 698 700 703 707 708 709 This attribute indicates whether the data node represented 710 by the XML element containing this attribute is considered 711 by the server to be default data. If set to 'true' then 712 the data node is default data. If 'false', then the 713 data node is not default data. 714 715 716 718 720 722 7. IANA Considerations 724 This document registers the following capability identifier URN in 725 the 'Network Configuration Protocol Capability URNs registry': 727 urn:ietf:params:netconf:capability:with-defaults:1.0 729 Note that the capability URN is compliant to [RFC4741] section 10.3. 731 This document registers two XML namespace URNs in the 'IETF XML 732 registry', following the format defined in [RFC3688]. 734 URI: urn:ietf:params:xml:ns:netconf:default:1.0 735 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults 737 Registrant Contact: The NETCONF WG of the IETF. 739 XML: N/A, the requested URIs are XML namespaces. 741 This document registers one module name in the 'YANG Module Names' 742 registry, defined in [I-D.ietf-netmod-yang] . 744 name: ietf-netconf-with-defaults 745 prefix: nwd 746 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults 747 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 749 8. Security Considerations 751 This document defines a minor extension to existing NETCONF protocol 752 operations. It does not introduce any new or increased security 753 risks into the management system. 755 The 'with-defaults' capability gives client control over the 756 retrieval of particular types of XML data from a configuration 757 datastore. They only suppress data that can already be retrieved 758 with the standard protocol operations, and do not add any data to the 759 configuration datastore. 761 9. Acknowledgements 763 Thanks to Martin Bjorklund, Sharon Chisholm, Phil Shafer, Juergen 764 Schoenwaelder, Washam Fan and many other members of the NETCONF WG 765 for providing important input to this document. 767 10. Normative References 769 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 770 Requirement Levels", BCP 14, RFC 2119, March 1997. 772 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 773 January 2004. 775 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 776 December 2006. 778 [I-D.ietf-netconf-4741bis] 779 Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 780 Bierman, "Network Configuration Protocol (NETCONF)", 781 draft-ietf-netconf-4741bis-02 (work in progress), 782 February 2010. 784 [I-D.ietf-netmod-yang] 785 Bjorklund, M., "YANG - A data modeling language for 786 NETCONF", draft-ietf-netmod-yang-12 (work in progress), 787 April 2010. 789 [W3C.REC-xml-20081126] 790 Yergeau, F., Maler, E., Bray, T., Paoli, J., and C. 791 Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 792 (Fifth Edition)", World Wide Web Consortium 793 Recommendation REC-xml-20081126, November 2008, 794 . 796 Appendix A. Usage Examples 798 A.1. Example YANG Module 800 The following YANG module defines an example interfaces table to 801 demonstrate how the parameter behaves for a specific 802 data model. 804 Note that this is not a real module, and implementation of this 805 module is not required for conformance to the :with-defaults protocol 806 capability, defined in Section 4. This module is not to be 807 registered with IANA, and is not considered to be a code component. 808 It is intentionally very terse, and includes few descriptive 809 statements. 811 module example { 813 namespace "http://example.com/ns/interfaces"; 815 prefix exam; 817 typedef itf-status-type { 818 description "Interface status"; 819 type enumeration { 820 enum ok; 821 enum 'waking up'; 822 enum 'not feeling so good'; 823 enum 'better check it out'; 824 enum 'better call for help'; 825 } 826 default ok; 827 } 829 container interfaces { 830 description "Example interfaces group"; 832 list interface { 833 description "Example interface entry"; 834 key name; 836 leaf name { 837 description 838 "The administrative name of the interface. 839 This is an identifier which is only unique 840 within the scope of this list, and only 841 within a specific server."; 842 type string { 843 length "1 .. max"; 844 } 845 } 847 leaf mtu { 848 description 849 "The maximum transmission unit (MTU) value assigned to 850 this interface."; 851 type uint32; 852 default 1500; 853 } 855 leaf itf-status { 856 description 857 "The current status of this interface."; 858 type itf-status-type; 859 config false; 860 } 861 } 862 } 863 } 865 A.2. Example Data Set 867 The following data element shows the conceptual contents of the 868 example server for the protocol operation examples in the next 869 section. This includes all the configuration data nodes, non- 870 configuration data nodes, and default leafs. 872 873 874 875 eth0 876 8192 877 up 878 879 880 eth1 881 1500 882 up 883 884 885 eth2 886 9000 887 not feeling so good 888 889 890 eth3 891 1500 892 waking up 893 894 895 897 In this example, the 'mtu' field for each interface entry is set in 898 the following manner: 900 +--------------+--------------+--------------+ 901 | name | set by | mtu | 902 +--------------+--------------+--------------+ 903 | eth0 | client | 8192 | 904 | eth1 | server | 1500 | 905 | eth2 | client | 9000 | 906 | eth3 | client | 1500 | 907 +--------------+--------------+--------------+ 909 A.3. Protocol Operation Examples 911 The following examples shows some operations using the 'with- 912 defaults' element. The data model used for these examples is defined 913 in Appendix A.1. 915 The client is retrieving all the data nodes within the 'interfaces' 916 object, filtered with the parameter. 918 A.3.1. = 'report-all' 920 The behavior of the parameter handling for the value 921 'report-all' is demonstrated in this example. 923 925 926 927 928 929 931 report-all 932 933 934 936 938 939 940 941 eth0 942 8192 943 up 944 945 946 eth1 947 1500 948 up 949 950 951 eth2 952 9000 953 not feeling so good 954 955 956 eth3 957 1500 958 waking up 959 960 961 962 964 A.3.2. = 'report-all-tagged' 966 The behavior of the parameter handling for the value 967 'report-all-tagged' is demonstrated in this example. A 'tagged' data 968 node is an element that contains the wd:default XML attribute, set to 969 'true'. Any subtrees within the element are also considered to be 970 tagged as dafault data. 972 The actual data nodes tagged by the server depends on the defaults 973 handling basic mode used by the server. Only the data nodes that are 974 considered to be default data will be tagged. 976 In this example, the server's basic mode is equal to 'trim', so all 977 data nodes that would contain the schema default value are tagged. 978 If the server's basic mode is 'explicit', then only data nodes that 979 are not explicitly set data are tagged. If the server's basic mode 980 is 'report-all', then no data nodes are tagged. 982 984 985 986 987 988 990 report-all-tagged 991 992 993 995 998 999 1000 1001 eth0 1002 8192 1003 up 1004 1005 1006 eth1 1007 1500 1008 up 1009 1010 1011 eth2 1012 9000 1013 not feeling so good 1014 1015 1016 eth3 1017 1500 1018 waking up 1019 1020 1021 1022 1024 A.3.3. = 'trim' 1026 The behavior of the parameter handling for the value 1027 'trim' is demonstrated in this example. 1029 1031 1032 1033 1034 1035 1037 trim 1038 1039 1040 1042 1044 1045 1046 1047 eth0 1048 8192 1049 1050 1051 eth1 1052 1053 1054 eth2 1055 9000 1056 not feeling so good 1057 1058 1059 eth3 1060 waking up 1061 1062 1063 1064 1066 A.3.4. = 'explicit' 1068 The behavior of the parameter handling for the value 1069 'explicit' is demonstrated in this example. 1071 1073 1074 1075 1076 1077 1079 explicit 1080 1081 1082 1084 1086 1087 1088 1089 eth0 1090 8192 1091 up 1092 1093 1094 eth1 1095 up 1096 1097 1098 eth2 1099 9000 1100 not feeling so good 1101 1102 1103 eth3 1104 1500 1105 waking up 1106 1107 1108 1109 1111 Appendix B. Change Log 1113 -- RFC Ed.: remove this section before publication. 1115 B.1. 07-08 1117 Added report-all-tagged mode. 1119 Changed conformance so report-all or report-all-tagged mode SHOULD be 1120 supported. 1122 Clarified capability requirements for each mode, for edit-config and 1123 NV storage requirements. 1125 Changed rpc-error details for unsupported with-defaults value. 1127 Added XSD for wd:default attribute 1129 Expanded example to show report-all-tagged for a basic-mode=trim 1130 server. 1132 B.2. 06-07 1134 Removed text in capability identifier section about adding YANG 1135 module capability URI parameters. 1137 Changed YANG module namespace to match YANG format, and updated 1138 examples to use this new namespace. 1140 Fixed some typos. 1142 B.3. 05-06 1144 Removed ':1.0' from capability URI. 1146 Removed open issues section because all known issues are closed. 1148 Moved examples to a separate appendix, and expanded them. 1150 Added example.yang as an appendix to properly explain the examples 1151 used within the document. 1153 Replaced normative term 'SHALL' with 'MUST' to be consistent within 1154 this document. 1156 Clarified behavior for non-configuration data nodes. 1158 Clarified various sections based on WGLC comments on mailing list. 1160 Removed some unused terms. 1162 Reversed the order of the change log sections so the most recent 1163 changes are shown first. 1165 B.4. 04-05 1167 Updated I-D and YANG module boiler-plate. 1169 Removed redundant 'with-defaults' YANG feature. 1171 Changed definition of 'explicit' mode to match the YANG definition 1173 Removed XSD because the YANG is normative and the XSD is 1174 unconstrained, and does not properly extend the 3 affected NETCONF 1175 operations. 1177 Made the YANG module a normative section instead of non-normative 1178 appendix. 1180 Changed YANG from an informative to a normative reference, 1182 Changed 4741bis from an informative to a normative reference because 1183 the YANG module imports the ietf-netconf module in order to augment 1184 some operations. 1186 Updated capability requirements to include YANG module capability 1187 parameters. 1189 Added a description statement to the with-defaults leaf definition. 1191 Update open issues section; ready to close all open issues. 1193 B.5. 03-04 1195 Clarifications 1197 Added non-netconf interfaces to the definition of explicitly set 1198 default data 1200 B.6. 02-03 1202 Clarifications 1204 YAM added 1206 Use the same URN for the capability and the XML namespace to 1207 accommodate YANG, and avoid two separate URN/URIs being advertised in 1208 the HELLO message, for such a small function. 1210 B.7. 01-02 1212 report-all made mandatory 1214 Placeholder for YAM added, XSD will be removed when 4741 provides the 1215 NETCONF YAM 1217 with-defaults is valid for state data as well (if state data has a 1218 defined default which might not be so frequent). The definition of 1219 explicit was modified for state data. 1221 B.8. 00-01 1223 Changed value set of with-default capability and element 1225 Added version to URI 1227 B.9. -00 1229 Created from draft-bierman-netconf-with-defaults-01.txt 1231 It was decided by the NETCONF mailing list, that with-defaults should 1232 be a sub-element of each affected operation. While this violates the 1233 XSD of RFC4741 this is acceptable and follows the ideas behind 1234 NETCONF and YANG. 1236 Hopefully it will be clarified in the 4741bis RFC whether such 1237 extensions are allowed. 1239 Authors' Addresses 1241 Andy Bierman 1242 InterWorking Labs 1243 Scotts Valley, CA 1244 USA 1246 Phone: +1 831 460 7010 1247 Email: andyb@iwl.com 1248 Balazs Lengyel 1249 Ericsson 1250 Budapest, 1251 Hungary 1253 Email: balazs.lengyel@ericsson.com