idnits 2.17.1 draft-ietf-netconf-with-defaults-12.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 (October 14, 2010) is 4940 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-04 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF A. Bierman 3 Internet-Draft Brocade 4 Intended status: Standards Track B. Lengyel 5 Expires: April 17, 2011 Ericsson 6 October 14, 2010 8 With-defaults capability for NETCONF 9 draft-ietf-netconf-with-defaults-12 11 Abstract 13 The NETCONF protocol defines ways to read and edit configuration data 14 from a NETCONF server. In some cases, part of this data may not be 15 set by the NETCONF client, but rather a default value known to the 16 server is used instead. In many situations the NETCONF client has a 17 priori knowledge about default data, so the NETCONF server does not 18 need to save it in a NETCONF configuration datastore or send it to 19 the client in a retrieval operation reply. In other situations the 20 NETCONF client will need this data from the server. Not all server 21 implementations treat this default data the same way. This document 22 defines a capability-based extension to the NETCONF protocol that 23 allows the NETCONF client to identify how defaults are processed by 24 the server, and also defines new mechanisms for client control of 25 server processing of default data. 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 April 17, 2011. 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 . . . . . . . . . . 7 68 2.1.2. 'report-all' Retrieval . . . . . . . . 7 69 2.1.3. 'report-all' and 70 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' and Behavior . . . 8 75 2.3. 'explicit' Basic Mode . . . . . . . . . . . . . . . . . . 8 76 2.3.1. 'explicit' Basic Mode Retrieval . . . . . . . . . . . 8 77 2.3.2. 'explicit' Retrieval . . . . . . . . . 8 78 2.3.3. 'explicit' and Behavior . 8 79 3. Retrieval of Default Data . . . . . . . . . . . . . . . . . . 9 80 3.1. 'report-all' Retrieval Mode . . . . . . . . . . . . . . . 9 81 3.2. 'trim' Retrieval Mode . . . . . . . . . . . . . . . . . . 9 82 3.3. 'explicit' Retrieval Mode . . . . . . . . . . . . . . . . 9 83 3.4. 'report-all-tagged' Retrieval Mode . . . . . . . . . . . . 10 84 4. With-defaults Capability . . . . . . . . . . . . . . . . . . . 10 85 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 10 86 4.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 10 87 4.3. Conformance . . . . . . . . . . . . . . . . . . . . . . . 11 88 4.4. Capability Identifier . . . . . . . . . . . . . . . . . . 11 89 4.5. New Operations . . . . . . . . . . . . . . . . . . . . . . 11 90 4.6. Modifications to Existing Operations . . . . . . . . . . . 11 91 4.6.1. , , and Operations . . 11 92 4.6.2. Operation . . . . . . . . . . . . . . . 13 93 4.6.3. Other Operations . . . . . . . . . . . . . . . . . . . 13 94 4.7. Interactions with Other Capabilities . . . . . . . . . . . 14 95 5. YANG Module for the Parameter . . . . . . . . 14 96 6. XSD for the 'wd:default' Attribute . . . . . . . . . . . . . . 17 97 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 98 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 99 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 19 100 10. Normative References . . . . . . . . . . . . . . . . . . . . . 19 101 Appendix A. Usage Examples . . . . . . . . . . . . . . . . . . . 20 102 A.1. Example YANG Module . . . . . . . . . . . . . . . . . . . 20 103 A.2. Example Data Set . . . . . . . . . . . . . . . . . . . . . 22 104 A.3. Protocol Operation Examples . . . . . . . . . . . . . . . 23 105 A.3.1. = 'report-all' . . . . . . . . . . . . 23 106 A.3.2. = 'report-all-tagged' . . . . . . . . 24 107 A.3.3. = 'trim' . . . . . . . . . . . . . . . 27 108 A.3.4. = 'explicit' . . . . . . . . . . . . . 28 109 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 29 110 B.1. 11-12 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 111 B.2. 10-11 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 112 B.3. 09-10 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 113 B.4. 08-09 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 114 B.5. 07-08 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 115 B.6. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 30 116 B.7. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 30 117 B.8. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 30 118 B.9. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 31 119 B.10. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 31 120 B.11. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 31 121 B.12. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 31 122 B.13. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 123 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 32 125 1. Introduction 127 The NETCONF protocol [RFC4741] defines ways to read configuration and 128 state data from a NETCONF server. Part of the configuration data may 129 not be set by the NETCONF client, but rather by a default value from 130 the data model. In many situations the NETCONF client has a priori 131 knowledge about default data, so the NETCONF server does not need to 132 send it to the client. A priori knowledge can be obtained, e.g., a 133 document formally describing the data models supported by the NETCONF 134 server. 136 It can be important for a client to know exactly how a server 137 implementation will handle default data. There are subtle 138 differences in some protocol operations where the defaults handling 139 behavior of the server will affect the outcome of the operation. 141 1.1. Terminology 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 145 document are to be interpreted as described in [RFC2119]. 147 Data model schema: A document or set of documents describing the 148 data models supported by the NETCONF server. 149 Management Application: A computer program running outside the 150 NETCONF server that configures or supervises the NETCONF server. 151 A management application can reach the device e.g. via NETCONF, 152 command line interface (CLI) or Simple Network Management Protocol 153 (SNMP). 154 Schema default data: Data specified in the data model schema as 155 default, that is set or used by the device whenever the NETCONF 156 client or other management application/user does not provide a 157 specific value for the relevant data node. Schema default data 158 may or may not be stored as part of a configuration datastore, 159 depending on the basic mode used by a particular server. 160 Default data: Conceptual data containing a default value. Default 161 data is not kept in a datastore. Not all servers use the same 162 criteria to decide if a data node is actually instantiated in a 163 datastore. If a data node is not present in a datastore, and a 164 schema default definition is in use by the server instead, then it 165 is considered to be a default data node. 166 Default value: A default value is a value for a data node instance 167 that is conceptually in use by the server, when the data node 168 instance does not exist. 170 Explicitly set data: Data that is set to any value by a NETCONF 171 client or other management application by the way of an explicit 172 management operation, including any data model schema default 173 value. Any value set by the NETCONF server which is not the 174 schema defined default value is also considered explicitly set 175 data. 176 retrieval: Refers to a protocol operation which 177 includes the parameter to control the handling of 178 default data. 179 :with-defaults: The shorthand notation for the with-defaults 180 capability identifier. 182 The following terms are defined in [RFC4741]: 183 o client 184 o datastore 185 o operation 186 o server 188 The following term is defined in [RFC6020]: 189 o data node 191 1.2. Defaults Handling Behavior 193 The defaults handling behavior used by a server will impact NETCONF 194 protocol operations in two ways: 196 1. Data retrieval: A server is normally allowed to exclude data 197 nodes which it considers to contain the default value. The 198 actual nodes omitted depends on the defaults handling behavior 199 used by the server. 201 2. Create and delete operations: The 'operation' 202 attribute can be used to create and/or delete specific data 203 nodes. These operations depend on whether the target node 204 currently exists or not. The server's defaults handling behavior 205 will determine whether the requested node currently exists in the 206 configuration datastore or not. 208 1.3. Client Controlled Retrieval of Default Data 210 A networking device may have a large number of default values. Often 211 the default values are specifically defined with a reasonable value, 212 documented and well-known, so that the management user does not need 213 to handle them. For these reasons it is quite common for networking 214 devices to suppress the output of parameters having the default 215 value. 217 However, there are use-cases when a NETCONF client will need the 218 default data from the server: 220 o The management application often needs a single, definitive and 221 complete set of configuration values that determine how the 222 networking device works. 223 o Documentation about default values can be unreliable or 224 unavailable. 225 o Some management applications might not have the capabilities to 226 correctly parse and interpret formal data models. 227 o Human users might want to understand the received data without 228 consultation of the documentation. 230 In all these cases, the NETCONF client will need a mechanism to 231 retrieve default data from a NETCONF server. 233 This document defines a NETCONF protocol capability to identify the 234 server defaults handling behavior, an XML attribute to identify 235 default data, and a YANG module extension to the NETCONF protocol 236 that allows the NETCONF client to control whether default data is 237 returned by the server. 239 2. Defaults Handling Basic Modes 241 Not all server implementations treat default data in the same way. 242 Instead of forcing a single implementation strategy, this document 243 allows a server to advertise a particular style of defaults handling, 244 and the client can adjust accordingly. 246 NETCONF servers report default data in different ways. This document 247 specifies three standard defaults handling basic modes that a server 248 implementor may choose from: 250 o report-all 251 o trim 252 o explicit 254 A server MUST select one of the three basic modes defined in this 255 section for handling default data. 257 2.1. 'report-all' Basic Mode 259 A server which uses the 'report-all' basic mode does not consider any 260 data node to be default data, even schema default data. 262 2.1.1. 'report-all' Basic Mode Retrieval 264 When data is retrieved from a server using the 'report-all' basic 265 mode, and the parameter is not present, all data 266 nodes MUST be reported. 268 2.1.2. 'report-all' Retrieval 270 The server MUST support the parameter with a value 271 equal to 'report-all', as specified in Section 3.1. 273 2.1.3. 'report-all' and Behavior 275 The server MUST consider every data node to exist, even those 276 containing a schema default value. A valid 'create' operation 277 attribute for a data node that contains its schema default value MUST 278 fail with a 'data-exists' error-tag. A valid 'delete' operation 279 attribute for a data node that contains its schema default value MUST 280 succeed, even though the data node is immediately replaced by the 281 server with the default value. 283 A server which uses the 'report-all' basic-mode has no concept of a 284 default node, so the 'report-all-tagged' retrieval 285 mode is not relevant. There will never be any tagged nodes, since 286 there are no nodes which are omitted in a basic-mode retrieval 287 operation. If the wd:default attribute is present in any 288 configuration data, the server MUST return an response 289 with an 'unknown-attribute' error-tag. 291 2.2. 'trim' Basic Mode 293 A server which uses the 'trim' basic mode MUST consider any data node 294 set to its schema default value to be default data. 296 2.2.1. 'trim' Basic Mode Retrieval 298 When data is retrieved from a server using the 'trim' basic mode, and 299 the parameter is not present, data nodes MUST NOT be 300 reported if they contain the schema default value. Non-configuration 301 data nodes containing the schema default value MUST NOT be reported. 303 2.2.2. 'trim' Retrieval 305 The server MUST support the parameter with a value 306 equal to 'trim', as specified in Section 3.1. 308 2.2.3. 'trim' and Behavior 310 The server MUST consider any data node that does not contain its 311 schema default value to exist. A valid 'create' operation attribute 312 for a data node that has a schema default value defined MUST succeed. 313 A valid 'delete' operation attribute for a missing data node that has 314 a schema default value MUST fail. The server MUST return an response with a 'data-missing' error-tag. 317 If a client sets a data node to its schema default value, using any 318 valid operation, it MUST succeed, although the data node MUST NOT be 319 saved in the NETCONF configuration datastore. This has the same 320 effect as removing the data node and treating it as default data. 322 If the server supports the 'report-all-tagged' value for the parameter, then the 'wd:default' attribute MUST be accepted 324 in configuration input, as described in Section 4.6.1 and 325 Section 4.6.2. 327 2.3. 'explicit' Basic Mode 329 A server which uses the 'explicit' basic mode MUST consider any data 330 node that is not explicitly set data to be default data. 332 2.3.1. 'explicit' Basic Mode Retrieval 334 If a client sets a data node to its schema default value, it MUST 335 always be reported. If the server sets a data node to its schema 336 default value, it MUST NOT be reported. Non-configuration data nodes 337 containing the schema default value MUST be reported. 339 2.3.2. 'explicit' Retrieval 341 The server MUST support the parameter with a value 342 equal to 'explicit', as specified in Section 3.3. 344 2.3.3. 'explicit' and Behavior 346 The server considers any data node that is explicitly set data to 347 exist. A valid 'create' operation attribute for a data node that has 348 been set by a client to its schema default value MUST fail with a 349 'data-exists' error-tag. A valid 'create' operation attribute for a 350 data node that has been set by the server to its schema default value 351 MUST succeed. A valid 'delete' operation attribute for a data node 352 that has been set by a client to its schema default value MUST 353 succeed. A valid 'delete' operation attribute for a data node that 354 has been set by the server to its schema default value MUST fail with 355 a 'data-missing' error-tag. 357 If the server supports the 'report-all-tagged' retrieval mode in its 358 :with-defaults capability, then the 'wd:default' attribute MUST be 359 accepted in configuration input. If all NETCONF or 360 parameters are valid, then the server will treat a wd: 361 default="true" tagged data node as a request to return that node to 362 default data. If this request is valid within the context of the 363 requested NETCONF operation, then the data node is removed and 364 returned to its default value. The data node within the NETCONF 365 message MUST contain a value in this case, which MUST be equal to the 366 schema default value. If not, the server MUST return an 367 response with a 'invalid-value' error-tag. 369 3. Retrieval of Default Data 371 This document defines a new parameter, called , which 372 can be added to specific NETCONF operation request messages to 373 control how retrieval of default data is treated by the server. 375 A server which implements this specification MUST accept the parameter containing the enumeration for any of the 377 defaults handling modes it supports. The parameter 378 contains one of the four enumerations defined in this section. 380 3.1. 'report-all' Retrieval Mode 382 When data is retrieved with a parameter equal to 383 'report-all', all data nodes MUST be reported, including any data 384 nodes considered to be default data by the server. 386 3.2. 'trim' Retrieval Mode 388 When data is retrieved with a parameter equal to 389 'trim', data nodes MUST NOT be reported if they contain the schema 390 default value. Non-configuration data nodes containing the schema 391 default value MUST NOT be reported. 393 3.3. 'explicit' Retrieval Mode 395 When data is retrieved with a parameter equal to 396 'explicit', a data node which was set by a client to its schema 397 default value MUST be reported. A conceptual data node which would 398 be set by the server to the schema default value MUST NOT be 399 reported. Non-configuration data nodes containing the schema default 400 value MUST be reported. 402 3.4. 'report-all-tagged' Retrieval Mode 404 In addition to the basic modes, a special variant of the 'report-all' 405 basic mode is available called 'report-all-tagged'. This mode MUST 406 be supported on a server if the 'also-supported' parameter in the 407 :with-defaults capability contains the 'report-all-tagged' option. 408 Refer to Section 4 for encoding details for this capability. 410 In this mode the server returns all data nodes, just like the 411 'report-all' mode, except a data node that is considered by the 412 server to contain default data will include an XML attribute to 413 indicate this condition. This is useful for an application to 414 determine which nodes are considered to contain default data by the 415 server, within a single retrieval operation. 417 A server which supports 'report-all-tagged' MUST also accept the 'wd: 418 default' XML attribute within configuration input to the or operations. Refer to Section 6 for XML 420 encoding details of the 'wd:default' XML attribute. 422 4. With-defaults Capability 424 4.1. Overview 426 The :with-defaults capability indicates which defaults handling basic 427 mode is supported by the server. It may also indicate support for 428 additional defaults retrieval modes. These retrieval modes allow a 429 NETCONF client to control whether default data is returned by the 430 server. The capability affects both configuration and state data 431 (while acknowledging that the usage of default values for state data 432 is less prevalent). Sending of default data is controlled for each 433 individual operation separately. 435 A NETCONF server implementing the :with-defaults capability: 437 o MUST indicate its basic mode behavior by including the 'basic- 438 mode' parameter in the capability URI, as defined in Section 4.4. 439 o MUST support the YANG module defined in Section 5. 440 o SHOULD support the 'report-all' or 'report-all-tagged' defaults 441 handling mode. 442 o MAY support additional defaults handling modes. 444 4.2. Dependencies 446 None 448 4.3. Conformance 450 Every NETCONF server SHOULD implement this capability. 452 4.4. Capability Identifier 454 urn:ietf:params:netconf:capability:with-defaults:1.0 456 The identifier MUST have a parameter: "basic-mode". This indicates 457 how the server will treat default data, as defined in Section 2. The 458 allowed values of this parameter are 'report-all', 'trim', and 459 'explicit', as defined in Section 2. 461 The identifier MAY have another parameter: "also-supported". This 462 parameter indicates which additional default handling modes the 463 server supports. The value of the parameter is a comma separated 464 list of one or more modes that are supported beside the mode 465 indicated in the 'basic-mode' parameter. Possible modes are 'report- 466 all', 'report-all-tagged', 'trim', and 'explicit', as defined in 467 Section 3. 469 Note that this protocol capability URI is separate from the YANG 470 module capability URI for the YANG module in Section 5. A server 471 which implements this module MUST also advertise a YANG module 472 capability URI according to the rules specified in [RFC6020]. 474 Examples: 476 urn:ietf:params:netconf:capability:with-defaults:1.0?basic- 477 mode=explicit 479 urn:ietf:params:netconf:capability:with-defaults:1.0?basic- 480 mode=explicit&also-supported=report-all,report-all-tagged 482 4.5. New Operations 484 None 486 4.6. Modifications to Existing Operations 488 4.6.1. , , and Operations 490 A new XML element is added to the input for the 491 , and operations. If the element is present, it controls the reporting of default 493 data. The server MUST return default data in the NETCONF 494 messages according to the value of this element, if the server 495 supports the specified retrieval mode. 497 This parameter only controls these specified retrieval operations, 498 and does not impact any other operations or the non-volatile storage 499 of configuration data. 501 The element is defined in the XML namespace for the 502 ietf-netconf-with-defaults.yang module in Section 5, not the XML 503 namespace for the , and operations. 505 Allowed values of the with-defaults element are taken from the 'with- 506 defaults-type' typedef in Section 5. The allowed values for a 507 particular server are restricted to the values that the server 508 indicates it supports within the :with-defaults capability, in the 509 'basic-mode' and 'also-supported' parameters. 511 If an unsupported value is used, the NETCONF server MUST return an 512 response with an 'invalid-value' error-tag. 514 If the element is not present, the server MUST follow 515 its basic mode behavior as indicated by the :with-defaults capability 516 identifier's 'basic-mode' parameter, defined in Section 4.4. 518 The and operations support a separate filtering 519 mechanism, using the parameter. The defaults filtering is 520 conceptually done before the parameter is processed. For 521 example, if the parameter is equal to 'report-all', 522 then the parameter is conceptually applied to all data nodes 523 and all default data. 525 The operation is only affected by the 526 parameter if the target of the operation is specified with the 527 parameter. If the target is a NETCONF configuration datastore (i.e., 528 running, candidate or startup), the parameter has no 529 effect. The server MUST use its basic mode when copying data to a 530 NETCONF configuration datastore. If the parameter is 531 present in this case, it MUST be silently ignored by the server. 533 If the server supports the 'report-all-tagged' mode, then the 'wd: 534 default' attribute defined in Section 6 also impacts the operation. If the wd:default attribute is present and set to 536 'true', then the server MUST treat the new data node as a request to 537 return that node to its default value (i.e., remove it from the 538 configuration datastore). The data node within the NETCONF message 539 MUST contain a value in this case, which MUST be equal to the schema 540 default value. If not, the server MUST return an 541 response with a 'invalid-value' error-tag. 543 4.6.2. Operation 545 The operation has several editing modes. The 'create' 546 and 'delete' editing operations are affected by the defaults handling 547 basic mode. The other enumeration values for the NETCONF operation 548 attribute are not affected. 550 If the operation attribute contains the value 'create', and the data 551 node already exists in the target configuration datastore, then the 552 server MUST return an response with a 'invalid-value' 553 error-tag. 555 If the client sets a data node to its schema default value, the 556 server MUST accept the request if it is valid. The server MUST keep 557 or discard the new value based on its defaults handling basic mode. 558 For the 'trim' basic mode, all schema default values are discarded, 559 otherwise a client-provided schema default value is saved in a 560 NETCONF configuration datastore. 562 If the server supports the 'report-all-tagged' mode, then the 'wd: 563 default' attribute defined in Section 6 also impacts the operation. If the wd:default attribute is present and set to 565 'true', then the server MUST treat the new data node as a request to 566 return that node to its default value (i.e., remove it from the 567 configuration datastore). The data node within the NETCONF message 568 MUST contain a value in this case, which MUST be equal to the schema 569 default value. If not, the server MUST return an 570 response with a 'invalid-value' error-tag. 572 If the wd:default attribute is present, then the effective operation 573 for the target data node MUST be 'create', 'merge' or 'replace'. If 574 not, then the server MUST return an response with an 575 'invalid-value' error-tag. For example, if 'create' is the effective 576 operation, then the create request must be valid on its own (e.g., 577 current data node MUST NOT exist). The procedure for determining the 578 effective operation is defined in [I-D.ietf-netconf-4741bis]. It is 579 derived from the 'default-operation' parameter and/or any operation 580 attributes that are present in the data node or any of its ancestor 581 nodes, within the request. 583 4.6.3. Other Operations 585 Other operations that return configuration data SHOULD also handle 586 default data according to the rules set in this document, and 587 explicitly state this in their documentation. If this is not 588 specified in the document defining the respective operation, the 589 default handling rules described herein do not affect these 590 operations. 592 4.7. Interactions with Other Capabilities 594 None 596 5. YANG Module for the Parameter 598 The following YANG module defines the addition of the with-defaults 599 element to the , , and operations. 600 The YANG language is defined in [RFC6020]. The above operations are 601 defined in YANG in [I-D.ietf-netconf-4741bis]. Every NETCONF server 602 which supports the :with-defaults capability MUST implement this YANG 603 module. 605 file="ietf-netconf-with-defaults@2010-06-09.yang" 607 module ietf-netconf-with-defaults { 609 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults"; 611 prefix ncwd; 613 import ietf-netconf { prefix nc; } 615 organization 616 "IETF NETCONF (Network Configuration Protocol) Working Group"; 618 contact 619 "WG Web: 620 WG List: 622 WG Chair: Bert Wijnen 623 625 WG Chair: Mehmet Ersue 626 628 Editor: Andy Bierman 629 631 Editor: Balazs Lengyel 632 "; 634 description 635 "This module defines an extension to the NETCONF protocol 636 that allows the NETCONF client to control how default 637 values are handled by the server in particular NETCONF operations. 639 Copyright (c) 2010 IETF Trust and the persons identified as 640 the document authors. All rights reserved. 642 Redistribution and use in source and binary forms, with or 643 without modification, is permitted pursuant to, and subject 644 to the license terms contained in, the Simplified BSD License 645 set forth in Section 4.c of the IETF Trust's Legal Provisions 646 Relating to IETF Documents 647 (http://trustee.ietf.org/license-info). 649 This version of this YANG module is part of RFC XXXX; see 650 the RFC itself for full legal notices."; 651 // RFC Ed.: replace XXXX with actual RFC number and remove this note 653 // RFC Ed.: remove this note 654 // Note: extracted from draft-ietf-netmod-with-defaults-10.txt 656 revision 2010-06-09 { 657 description 658 "Initial version."; 659 reference 660 "RFC XXXX: With-defaults capability for NETCONF"; 661 } 662 // RFC Ed.: replace XXXX with actual 663 // RFC number and remove this note 665 typedef with-defaults-mode { 666 description 667 "Possible modes to report default data."; 668 reference 669 "RFC XXXX; section 3."; 670 // RFC Ed.: replace XXXX with actual 671 // RFC number and remove this note 673 type enumeration { 674 enum report-all { 675 description 676 "All default data is reported."; 677 reference 678 "RFC XXXX; section 3.1"; 679 // RFC Ed.: replace XXXX with actual 680 // RFC number and remove this note 682 } 683 enum report-all-tagged { 684 description 685 "All default data is reported. 686 Any nodes considered to be default data 687 will contain a 'wd:default' XML attribute, 688 set to 'true'."; 689 reference 690 "RFC XXXX; section 3.4"; 691 // RFC Ed.: replace XXXX with actual 692 // RFC number and remove this note 693 } 694 enum trim { 695 description 696 "Values are not reported if they contain the default."; 697 reference 698 "RFC XXXX; section 3.2"; 699 // RFC Ed.: replace XXXX with actual 700 // RFC number and remove this note 702 } 703 enum explicit { 704 description 705 "Report values that contain the definition of 706 explicitly set data."; 707 reference 708 "RFC XXXX; section 3.3"; 709 // RFC Ed.: replace XXXX with actual 710 // RFC number and remove this note 711 } 712 } 713 } 715 grouping with-defaults-parameters { 716 description 717 "Contains the parameter for control 718 of defaults in NETCONF retrieval operations."; 720 leaf with-defaults { 721 description 722 "The explicit defaults processing mode requested."; 723 reference 724 "RFC XXXX; section 4.6.1"; 725 // RFC Ed.: replace XXXX with actual 726 // RFC number and remove this note 728 type with-defaults-mode; 729 } 730 } 732 // extending the get-config operation 733 augment /nc:get-config/nc:input { 734 description 735 "Adds the parameter to the 736 input of the NETCONF operation."; 737 reference 738 "RFC XXXX; section 4.6.1"; 739 // RFC Ed.: replace XXXX with actual 740 // RFC number and remove this note 742 uses with-defaults-parameters; 743 } 745 // extending the get operation 746 augment /nc:get/nc:input { 747 description 748 "Adds the parameter to 749 the input of the NETCONF operation."; 750 reference 751 "RFC XXXX; section 4.6.1"; 752 // RFC Ed.: replace XXXX with actual 753 // RFC number and remove this note 755 uses with-defaults-parameters; 756 } 758 // extending the copy-config operation 759 augment /nc:copy-config/nc:input { 760 description 761 "Adds the parameter to 762 the input of the NETCONF operation."; 763 reference 764 "RFC XXXX; section 4.6.1"; 765 // RFC Ed.: replace XXXX with actual 766 // RFC number and remove this note 768 uses with-defaults-parameters; 769 } 771 } 773 775 6. XSD for the 'wd:default' Attribute 777 The following XML Schema document defines the 'default' attribute, 778 described within this document. This XSD is only relevant if the 779 server supports the 'report-all-tagged' defaults retrieval mode. 781 file="defaults.xsd" 783 784 791 792 793 This schema defines the syntax for the 'default' attribute 794 described within this document. 795 796 798 801 802 803 804 This attribute indicates whether the data node represented 805 by the XML element containing this attribute is considered 806 by the server to be default data. If set to 'true' then 807 the data node is default data. If 'false', then the 808 data node is not default data. 809 810 811 813 815 817 7. IANA Considerations 819 This document registers the following capability identifier URN in 820 the 'Network Configuration Protocol Capability URNs registry': 822 urn:ietf:params:netconf:capability:with-defaults:1.0 824 Note that the capability URN is compliant to [RFC4741] section 10.3. 826 This document registers two XML namespace URNs in the 'IETF XML 827 registry', following the format defined in [RFC3688]. 829 URI: urn:ietf:params:xml:ns:netconf:default:1.0 830 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults 832 Registrant Contact: The NETCONF WG of the IETF. 834 XML: N/A, the requested URIs are XML namespaces. 836 This document registers one module name in the 'YANG Module Names' 837 registry, defined in [RFC6020] . 839 name: ietf-netconf-with-defaults 840 prefix: ncwd 841 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults 842 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 844 8. Security Considerations 846 This document defines an extension to existing NETCONF protocol 847 operations. It does not introduce any new or increased security 848 risks into the management system. 850 The 'with-defaults' capability gives clients control over the 851 retrieval of default data from a NETCONF datastore. The security 852 consideration of [I-D.ietf-netconf-4741bis] apply to this document as 853 well. 855 9. Acknowledgements 857 Thanks to Martin Bjorklund, Sharon Chisholm, Phil Shafer, Juergen 858 Schoenwaelder, Kent Watsen, Washam Fan and many other members of the 859 NETCONF WG for providing important input to this document. 861 10. Normative References 863 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 864 Requirement Levels", BCP 14, RFC 2119, March 1997. 866 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 867 January 2004. 869 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 870 December 2006. 872 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 873 Network Configuration Protocol (NETCONF)", RFC 6020, 874 October 2010. 876 [I-D.ietf-netconf-4741bis] 877 Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 878 Bierman, "Network Configuration Protocol (NETCONF)", 879 draft-ietf-netconf-4741bis-04 (work in progress), 880 August 2010. 882 [W3C.REC-xml-20081126] 883 Sperberg-McQueen, C., Yergeau, F., Bray, T., Paoli, J., 884 and E. Maler, "Extensible Markup Language (XML) 1.0 (Fifth 885 Edition)", World Wide Web Consortium Recommendation REC- 886 xml-20081126, November 2008, 887 . 889 Appendix A. Usage Examples 891 A.1. Example YANG Module 893 The following YANG module defines an example interfaces table to 894 demonstrate how the parameter behaves for a specific 895 data model. 897 Note that this is not a real module, and implementation of this 898 module is not required for conformance to the :with-defaults 899 capability, defined in Section 4. This module is not to be 900 registered with IANA, and is not considered to be a code component. 901 It is intentionally very terse, and includes few descriptive 902 statements. 904 module example { 906 namespace "http://example.com/ns/interfaces"; 908 prefix exam; 910 typedef status-type { 911 description "Interface status"; 912 type enumeration { 913 enum ok; 914 enum 'waking up'; 915 enum 'not feeling so good'; 916 enum 'better check it out'; 917 enum 'better call for help'; 918 } 919 default ok; 920 } 922 container interfaces { 923 description "Example interfaces group"; 925 list interface { 926 description "Example interface entry"; 927 key name; 929 leaf name { 930 description 931 "The administrative name of the interface. 932 This is an identifier which is only unique 933 within the scope of this list, and only 934 within a specific server."; 935 type string { 936 length "1 .. max"; 937 } 938 } 940 leaf mtu { 941 description 942 "The maximum transmission unit (MTU) value assigned to 943 this interface."; 944 type uint32; 945 default 1500; 946 } 948 leaf status { 949 description 950 "The current status of this interface."; 951 type status-type; 952 config false; 953 } 954 } 955 } 956 } 958 A.2. Example Data Set 960 The following data element shows the conceptual contents of the 961 example server for the protocol operation examples in the next 962 section. This includes all the configuration data nodes, non- 963 configuration data nodes, and default leafs. 965 966 967 968 eth0 969 8192 970 up 971 972 973 eth1 974 1500 975 up 976 977 978 eth2 979 9000 980 not feeling so good 981 982 983 eth3 984 1500 985 waking up 986 987 988 990 In this example, the 'mtu' field for each interface entry is set in 991 the following manner: 993 +--------------+--------------+--------------+ 994 | name | set by | mtu | 995 +--------------+--------------+--------------+ 996 | eth0 | client | 8192 | 997 | eth1 | server | 1500 | 998 | eth2 | client | 9000 | 999 | eth3 | client | 1500 | 1000 +--------------+--------------+--------------+ 1002 A.3. Protocol Operation Examples 1004 The following examples shows some operations using the 'with- 1005 defaults' element. The data model used for these examples is defined 1006 in Appendix A.1. 1008 The client is retrieving all the data nodes within the 'interfaces' 1009 object, filtered with the parameter. 1011 A.3.1. = 'report-all' 1013 The behavior of the parameter handling for the value 1014 'report-all' is demonstrated in this example. 1016 1018 1019 1020 1021 1022 1024 report-all 1025 1026 1027 1029 1031 1032 1033 1034 eth0 1035 8192 1036 up 1037 1038 1039 eth1 1040 1500 1041 up 1042 1043 1044 eth2 1045 9000 1046 not feeling so good 1047 1048 1049 eth3 1050 1500 1051 waking up 1052 1053 1054 1055 1057 A.3.2. = 'report-all-tagged' 1059 The behavior of the parameter handling for the value 1060 'report-all-tagged' is demonstrated in this example. A 'tagged' data 1061 node is an element that contains the wd:default XML attribute, set to 1062 'true'. 1064 The actual data nodes tagged by the server depends on the defaults 1065 handling basic mode used by the server. Only the data nodes that are 1066 considered to be default data will be tagged. 1068 In this example, the server's basic mode is equal to 'trim', so all 1069 data nodes that would contain the schema default value are tagged. 1070 If the server's basic mode is 'explicit', then only data nodes that 1071 are not explicitly set data are tagged. If the server's basic mode 1072 is 'report-all', then no data nodes are tagged. 1074 1076 1077 1078 1079 1080 1082 report-all-tagged 1083 1084 1085 1087 1090 1091 1092 1093 eth0 1094 8192 1095 up 1096 1097 1098 eth1 1099 1500 1100 up 1101 1102 1103 eth2 1104 9000 1105 not feeling so good 1106 1107 1108 eth3 1109 1500 1110 waking up 1111 1112 1113 1114 1116 A.3.3. = 'trim' 1118 The behavior of the parameter handling for the value 1119 'trim' is demonstrated in this example. 1121 1123 1124 1125 1126 1127 1129 trim 1130 1131 1132 1134 1136 1137 1138 1139 eth0 1140 8192 1141 1142 1143 eth1 1144 1145 1146 eth2 1147 9000 1148 not feeling so good 1149 1150 1151 eth3 1152 waking up 1153 1154 1155 1156 1158 A.3.4. = 'explicit' 1160 The behavior of the parameter handling for the value 1161 'explicit' is demonstrated in this example. 1163 1165 1166 1167 1168 1169 1171 explicit 1172 1173 1174 1176 1178 1179 1180 1181 eth0 1182 8192 1183 up 1184 1185 1186 eth1 1187 up 1188 1189 1190 eth2 1191 9000 1192 not feeling so good 1193 1194 1195 eth3 1196 1500 1197 waking up 1198 1199 1200 1201 1203 Appendix B. Change Log 1205 -- RFC Ed.: remove this section before publication. 1207 B.1. 11-12 1209 Made editorial clarifications based on AD review. 1211 B.2. 10-11 1213 Changed term 'database' to 'configuration datastore' or generic 1214 'datastore'. 1216 B.3. 09-10 1218 Changed term 'datastore' to 'database'. 1220 Added term 'default value'. 1222 Clarified verbage for data node containing a default value. 1224 B.4. 08-09 1226 Removed non-volatile server requirements. 1228 Moved some text from basic-mode section into the the retrieval modes 1229 section. 1231 Added description and reference statements to the YANG module. 1233 Many bugfixes and clarifications, based on WGLC review comments. 1235 B.5. 07-08 1237 Added report-all-tagged mode. 1239 Changed conformance so report-all or report-all-tagged mode SHOULD be 1240 supported. 1242 Clarified capability requirements for each mode, for edit-config and 1243 NV storage requirements. 1245 Changed rpc-error details for unsupported with-defaults value. 1247 Added XSD for wd:default attribute 1249 Expanded example to show report-all-tagged for a basic-mode=trim 1250 server. 1252 B.6. 06-07 1254 Removed text in capability identifier section about adding YANG 1255 module capability URI parameters. 1257 Changed YANG module namespace to match YANG format, and updated 1258 examples to use this new namespace. 1260 Fixed some typos. 1262 B.7. 05-06 1264 Removed ':1.0' from capability URI. 1266 Removed open issues section because all known issues are closed. 1268 Moved examples to a separate appendix, and expanded them. 1270 Added example.yang as an appendix to properly explain the examples 1271 used within the document. 1273 Replaced normative term 'SHALL' with 'MUST' to be consistent within 1274 this document. 1276 Clarified behavior for non-configuration data nodes. 1278 Clarified various sections based on WGLC comments on mailing list. 1280 Removed some unused terms. 1282 Reversed the order of the change log sections so the most recent 1283 changes are shown first. 1285 B.8. 04-05 1287 Updated I-D and YANG module boiler-plate. 1289 Removed redundant 'with-defaults' YANG feature. 1291 Changed definition of 'explicit' mode to match the YANG definition 1293 Removed XSD because the YANG is normative and the XSD is 1294 unconstrained, and does not properly extend the 3 affected NETCONF 1295 operations. 1297 Made the YANG module a normative section instead of non-normative 1298 appendix. 1300 Changed YANG from an informative to a normative reference, 1302 Changed 4741bis from an informative to a normative reference because 1303 the YANG module imports the ietf-netconf module in order to augment 1304 some operations. 1306 Updated capability requirements to include YANG module capability 1307 parameters. 1309 Added a description statement to the with-defaults leaf definition. 1311 Update open issues section; ready to close all open issues. 1313 B.9. 03-04 1315 Clarifications 1317 Added non-netconf interfaces to the definition of explicitly set 1318 default data 1320 B.10. 02-03 1322 Clarifications 1324 YAM added 1326 Use the same URN for the capability and the XML namespace to 1327 accommodate YANG, and avoid two separate URN/URIs being advertised in 1328 the HELLO message, for such a small function. 1330 B.11. 01-02 1332 report-all made mandatory 1334 Placeholder for YAM added, XSD will be removed when 4741 provides the 1335 NETCONF YAM 1337 with-defaults is valid for state data as well (if state data has a 1338 defined default which might not be so frequent). The definition of 1339 explicit was modified for state data. 1341 B.12. 00-01 1343 Changed value set of with-default capability and element 1345 Added version to URI 1347 B.13. -00 1349 Created from draft-bierman-netconf-with-defaults-01.txt 1351 It was decided by the NETCONF mailing list, that with-defaults should 1352 be a sub-element of each affected operation. While this violates the 1353 XSD of RFC4741 this is acceptable and follows the ideas behind 1354 NETCONF and YANG. 1356 Hopefully it will be clarified in the 4741bis RFC whether such 1357 extensions are allowed. 1359 Authors' Addresses 1361 Andy Bierman 1362 Brocade 1364 Email: andy.bierman@brocade.com 1366 Balazs Lengyel 1367 Ericsson 1368 Budapest, 1369 Hungary 1371 Email: balazs.lengyel@ericsson.com