idnits 2.17.1 draft-ietf-netconf-with-defaults-14.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 (November 11, 2010) is 4915 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) == Outdated reference: A later version (-10) exists of draft-ietf-netconf-4741bis-06 Summary: 0 errors (**), 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: May 15, 2011 Ericsson 6 November 11, 2010 8 With-defaults capability for NETCONF 9 draft-ietf-netconf-with-defaults-14 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 May 15, 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 . . . . . . . . . . . . . . . . . . . . . . . 11 87 4.3. Capability Identifier . . . . . . . . . . . . . . . . . . 11 88 4.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 11 89 4.5. Modifications to Existing Operations . . . . . . . . . . . 11 90 4.5.1. , , and Operations . . 11 91 4.5.2. Operation . . . . . . . . . . . . . . . 13 92 4.5.3. Other Operations . . . . . . . . . . . . . . . . . . . 13 93 4.6. Interactions with Other Capabilities . . . . . . . . . . . 14 94 5. YANG Module for the Parameter . . . . . . . . 14 95 6. XSD for the 'default' Attribute . . . . . . . . . . . . . . . 17 96 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 97 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 98 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 19 99 10. Normative References . . . . . . . . . . . . . . . . . . . . . 20 100 Appendix A. Usage Examples . . . . . . . . . . . . . . . . . . . 20 101 A.1. Example YANG Module . . . . . . . . . . . . . . . . . . . 20 102 A.2. Example Data Set . . . . . . . . . . . . . . . . . . . . . 22 103 A.3. Protocol Operation Examples . . . . . . . . . . . . . . . 23 104 A.3.1. = 'report-all' . . . . . . . . . . . . 23 105 A.3.2. = 'report-all-tagged' . . . . . . . . 24 106 A.3.3. = 'trim' . . . . . . . . . . . . . . . 27 107 A.3.4. = 'explicit' . . . . . . . . . . . . . 28 108 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 29 109 B.1. 13-14 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 110 B.2. 12-13 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 111 B.3. 11-12 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 112 B.4. 10-11 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 113 B.5. 09-10 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 114 B.6. 08-09 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 115 B.7. 07-08 . . . . . . . . . . . . . . . . . . . . . . . . . . 30 116 B.8. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 30 117 B.9. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 30 118 B.10. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 31 119 B.11. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 31 120 B.12. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 31 121 B.13. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 122 B.14. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 123 B.15. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 32 126 1. Introduction 128 The NETCONF protocol [I-D.ietf-netconf-4741bis] defines ways to read 129 configuration and state data from a NETCONF server. Part of the 130 configuration data may not be set by the NETCONF client, but rather 131 by a default value from the data model. In many situations the 132 NETCONF client has a priori knowledge about default data, so the 133 NETCONF server does not need to send it to the client. A priori 134 knowledge can be obtained, e.g., a document formally describing the 135 data models supported by the NETCONF server. 137 It can be important for a client to know exactly how a server 138 implementation will handle default data. There are subtle 139 differences in some protocol operations where the defaults handling 140 behavior of the server will affect the outcome of the operation. 142 1.1. Terminology 144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 146 document are to be interpreted as described in [RFC2119]. 148 Data model schema: A document or set of documents describing the 149 data models supported by the NETCONF server. 150 Management Application: A computer program running outside the 151 NETCONF server that configures or supervises the NETCONF server. 152 A management application can reach the device e.g. via NETCONF, 153 command line interface (CLI) or Simple Network Management Protocol 154 (SNMP). 155 Schema default data: Data specified in the data model schema as 156 default, that is set or used by the device whenever the NETCONF 157 client or other management application/user does not provide a 158 specific value for the relevant data node. Schema default data 159 may or may not be stored as part of a configuration datastore, 160 depending on the basic mode used by a particular server. 161 Default data: Conceptual data containing a default value. Default 162 data is not kept in a datastore. Not all servers use the same 163 criteria to decide if a data node is actually instantiated in a 164 datastore. If a data node is not present in a datastore, and a 165 schema default definition is in use by the server instead, then it 166 is considered to be a default data node. 167 Default value: A default value is a value for a data node instance 168 that is conceptually in use by the server, when the data node 169 instance does not exist. 171 Explicitly set data: Data that is set to any value by a NETCONF 172 client or other management application by the way of an explicit 173 management operation, including any data model schema default 174 value. Any value set by the NETCONF server which is not the 175 schema defined default value is also considered explicitly set 176 data. 177 retrieval: Refers to a protocol operation which 178 includes the parameter to control the handling of 179 default data. 180 :with-defaults: The shorthand notation for the with-defaults 181 capability identifier. 183 The following terms are defined in [I-D.ietf-netconf-4741bis]: 184 o client 185 o datastore 186 o operation 187 o server 189 The following term is defined in [RFC6020]: 190 o data node 192 1.2. Defaults Handling Behavior 194 The defaults handling behavior used by a server will impact NETCONF 195 protocol operations in two ways: 197 1. Data retrieval: A server is normally allowed to exclude data 198 nodes which it considers to contain the default value. The 199 actual nodes omitted depends on the defaults handling behavior 200 used by the server. 202 2. Create and delete operations: The 'operation' 203 attribute can be used to create and/or delete specific data 204 nodes. These operations depend on whether the target node 205 currently exists or not. The server's defaults handling behavior 206 will determine whether the requested node currently exists in the 207 configuration datastore or not. 209 1.3. Client Controlled Retrieval of Default Data 211 A networking device may have a large number of default values. Often 212 the default values are specifically defined with a reasonable value, 213 documented and well-known, so that the management user does not need 214 to handle them. For these reasons it is quite common for networking 215 devices to suppress the output of parameters having the default 216 value. 218 However, there are use-cases when a NETCONF client will need the 219 default data from the server: 221 o The management application often needs a single, definitive and 222 complete set of configuration values that determine how the 223 networking device works. 224 o Documentation about default values can be unreliable or 225 unavailable. 226 o Some management applications might not have the capabilities to 227 correctly parse and interpret formal data models. 228 o Human users might want to understand the received data without 229 consultation of the documentation. 231 In all these cases, the NETCONF client will need a mechanism to 232 retrieve default data from a NETCONF server. 234 This document defines a NETCONF protocol capability to identify the 235 server defaults handling behavior, an XML attribute to identify 236 default data, and a YANG module extension to the NETCONF protocol 237 that allows the NETCONF client to control whether default data is 238 returned by the server. 240 2. Defaults Handling Basic Modes 242 Not all server implementations treat default data in the same way. 243 Instead of forcing a single implementation strategy, this document 244 allows a server to advertise a particular style of defaults handling, 245 and the client can adjust accordingly. 247 NETCONF servers report default data in different ways. This document 248 specifies three standard defaults handling basic modes that a server 249 implementor may choose from: 251 o report-all 252 o trim 253 o explicit 255 A server MUST select one of the three basic modes defined in this 256 section for handling default data. 258 2.1. 'report-all' Basic Mode 260 A server which uses the 'report-all' basic mode does not consider any 261 data node to be default data, even schema default data. 263 2.1.1. 'report-all' Basic Mode Retrieval 265 When data is retrieved from a server using the 'report-all' basic 266 mode, and the parameter is not present, all data 267 nodes MUST be reported. 269 2.1.2. 'report-all' Retrieval 271 If the 'report-all' basic mode is used by the server, then the server 272 MUST support the parameter with a value equal to 273 'report-all', as specified in Section 3.1. 275 2.1.3. 'report-all' and Behavior 277 The server MUST consider every data node to exist, even those 278 containing a schema default value. A valid 'create' operation 279 attribute for a data node that contains its schema default value MUST 280 fail with a 'data-exists' error-tag. A valid 'delete' operation 281 attribute for a data node that contains its schema default value MUST 282 succeed, even though the data node is immediately replaced by the 283 server with the default value. 285 A server which uses the 'report-all' basic-mode has no concept of a 286 default node, so the 'report-all-tagged' retrieval 287 mode is not relevant. There will never be any tagged nodes, since 288 there are no nodes which are omitted in a basic-mode retrieval 289 operation. If the 'default' attribute is present in any 290 configuration data, the server MUST return an response 291 with an 'unknown-attribute' error-tag. 293 2.2. 'trim' Basic Mode 295 A server which uses the 'trim' basic mode MUST consider any data node 296 set to its schema default value to be default data. 298 2.2.1. 'trim' Basic Mode Retrieval 300 When data is retrieved from a server using the 'trim' basic mode, and 301 the parameter is not present, data nodes MUST NOT be 302 reported if they contain the schema default value. Non-configuration 303 data nodes containing the schema default value MUST NOT be reported. 305 2.2.2. 'trim' Retrieval 307 If the 'trim' basic mode is used by the server, then the server MUST 308 support the parameter with a value equal to 'trim', 309 as specified in Section 3.2. 311 2.2.3. 'trim' and Behavior 313 The server MUST consider any data node that does not contain its 314 schema default value to exist. A valid 'create' operation attribute 315 for a data node that has a schema default value defined MUST succeed. 316 A valid 'delete' operation attribute for a missing data node that has 317 a schema default value MUST fail. The server MUST return an response with a 'data-missing' error-tag. 320 If a client sets a data node to its schema default value, using any 321 valid operation, it MUST succeed, although the data node MUST NOT be 322 saved in the NETCONF configuration datastore. This has the same 323 effect as removing the data node and treating it as default data. 325 If the server supports the 'report-all-tagged' value for the parameter, then the 'default' attribute MUST be accepted in 327 configuration input, as described in Section 4.5.1 and Section 4.5.2. 329 2.3. 'explicit' Basic Mode 331 A server which uses the 'explicit' basic mode MUST consider any data 332 node that is not explicitly set data to be default data. 334 2.3.1. 'explicit' Basic Mode Retrieval 336 When data is retrieved from a server using the 'explicit' basic mode, 337 and the parameter is not present, data nodes MUST be 338 reported if explicitly set by the client, even if they contain the 339 schema default value. Non-configuration data nodes containing the 340 schema default value MUST be reported. 342 2.3.2. 'explicit' Retrieval 344 If the 'explicit' basic mode is used by the server, the server MUST 345 support the parameter with a value equal to 346 'explicit', as specified in Section 3.3. 348 2.3.3. 'explicit' and Behavior 350 The server considers any data node that is explicitly set data to 351 exist. A valid 'create' operation attribute for a data node that has 352 been set by a client to its schema default value MUST fail with a 353 'data-exists' error-tag. A valid 'create' operation attribute for a 354 data node that has been set by the server to its schema default value 355 MUST succeed. A valid 'delete' operation attribute for a data node 356 that has been set by a client to its schema default value MUST 357 succeed. A valid 'delete' operation attribute for a data node that 358 has been set by the server to its schema default value MUST fail with 359 a 'data-missing' error-tag. 361 If the server supports the 'report-all-tagged' retrieval mode in its 362 :with-defaults capability, then the 'default' attribute MUST be 363 accepted in configuration input. If all NETCONF or 364 parameters are valid, then the server will treat a 365 tagged data node (i.e., the 'default' attribute set to 'true' or '1') 366 as a request to return that node to default data. If this request is 367 valid within the context of the requested NETCONF operation, then the 368 data node is removed and returned to its default value. The data 369 node within the NETCONF message MUST contain a value in this case, 370 which MUST be equal to the schema default value. If not, the server 371 MUST return an response with a 'invalid-value' error-tag. 373 3. Retrieval of Default Data 375 This document defines a new parameter, called , which 376 can be added to specific NETCONF operation request messages to 377 control how retrieval of default data is treated by the server. 379 A server which implements this specification MUST accept the parameter containing the enumeration for any of the 381 defaults handling modes it supports. The parameter 382 contains one of the four enumerations defined in this section. 384 3.1. 'report-all' Retrieval Mode 386 When data is retrieved with a parameter equal to 387 'report-all', all data nodes MUST be reported, including any data 388 nodes considered to be default data by the server. 390 3.2. 'trim' Retrieval Mode 392 When data is retrieved with a parameter equal to 393 'trim', data nodes MUST NOT be reported if they contain the schema 394 default value. Non-configuration data nodes containing the schema 395 default value MUST NOT be reported. 397 3.3. 'explicit' Retrieval Mode 399 When data is retrieved with a parameter equal to 400 'explicit', a data node which was set by a client to its schema 401 default value MUST be reported. A conceptual data node which would 402 be set by the server to the schema default value MUST NOT be 403 reported. Non-configuration data nodes containing the schema default 404 value MUST be reported. 406 3.4. 'report-all-tagged' Retrieval Mode 408 In addition to the basic modes, a special variant of the 'report-all' 409 basic mode is available called 'report-all-tagged'. This mode MUST 410 be supported on a server if the 'also-supported' parameter in the 411 :with-defaults capability contains the 'report-all-tagged' option. 412 Refer to Section 4 for encoding details for this capability. 414 In this mode the server returns all data nodes, just like the 415 'report-all' mode, except a data node that is considered by the 416 server to contain default data will include an XML attribute to 417 indicate this condition. This is useful for an application to 418 determine which nodes are considered to contain default data by the 419 server, within a single retrieval operation. 421 A server which supports 'report-all-tagged' MUST also accept the 422 'default' XML attribute within configuration input to the or operations. Refer to Section 6 for XML 424 encoding details of the 'default' XML attribute. 426 4. With-defaults Capability 428 4.1. Overview 430 The :with-defaults capability indicates which defaults handling basic 431 mode is supported by the server. It may also indicate support for 432 additional defaults retrieval modes. These retrieval modes allow a 433 NETCONF client to control whether default data is returned by the 434 server. The capability affects both configuration and state data 435 (while acknowledging that the usage of default values for state data 436 is less prevalent). Sending of default data is controlled for each 437 individual operation separately. 439 A NETCONF server implementing the :with-defaults capability: 441 o MUST indicate its basic mode behavior by including the 'basic- 442 mode' parameter in the capability URI, as defined in Section 4.3. 443 o MUST support the YANG module defined in Section 5 for the defaults 444 handling mode indicated by the 'basic-mode' parameter. 445 o SHOULD support the YANG module in Section 5 for the defaults 446 handling mode identified by the 'report-all' or 'report-all- 447 tagged' enumeration value. 448 o If the 'report-all-tagged' defaults handling mode is supported, 449 then the 'default' attribute MUST be supported. 450 o MAY support the YANG module in Section 5 for additional defaults 451 handling modes. 453 4.2. Dependencies 455 None 457 4.3. Capability Identifier 459 urn:ietf:params:netconf:capability:with-defaults:1.0 461 The identifier MUST have a parameter: "basic-mode". This indicates 462 how the server will treat default data, as defined in Section 2. The 463 allowed values of this parameter are 'report-all', 'trim', and 464 'explicit', as defined in Section 2. 466 The identifier MAY have another parameter: "also-supported". This 467 parameter indicates which additional enumeration values (besides the 468 basic-mode enumeration), the server will accept for the parameter in Section 5. The value of the parameter is a 470 comma separated list of one or more modes that are supported beside 471 the mode indicated in the 'basic-mode' parameter. Possible modes are 472 'report-all', 'report-all-tagged', 'trim', and 'explicit', as defined 473 in Section 3. 475 Note that this protocol capability URI is separate from the YANG 476 module capability URI for the YANG module in Section 5. A server 477 which implements this module MUST also advertise a YANG module 478 capability URI according to the rules specified in [RFC6020]. 480 Examples: 482 urn:ietf:params:netconf:capability:with-defaults:1.0?basic- 483 mode=explicit 485 urn:ietf:params:netconf:capability:with-defaults:1.0?basic- 486 mode=explicit&also-supported=report-all,report-all-tagged 488 4.4. New Operations 490 None 492 4.5. Modifications to Existing Operations 494 4.5.1. , , and Operations 496 A new XML element is added to the input for the 497 , and operations. If the element is present, it controls the reporting of default 499 data. The server MUST return default data in the NETCONF 500 messages according to the value of this element, if the server 501 supports the specified retrieval mode. 503 This parameter only controls these specified retrieval operations, 504 and does not impact any other operations or the non-volatile storage 505 of configuration data. 507 The element is defined in the XML namespace for the 508 ietf-netconf-with-defaults.yang module in Section 5, not the XML 509 namespace for the , and operations. 511 Allowed values of the with-defaults element are taken from the 'with- 512 defaults-type' typedef in Section 5. The allowed values for a 513 particular server are restricted to the values that the server 514 indicates it supports within the :with-defaults capability, in the 515 'basic-mode' and 'also-supported' parameters. 517 If an unsupported value is used, the NETCONF server MUST return an 518 response with an 'invalid-value' error-tag. 520 If the element is not present, the server MUST follow 521 its basic mode behavior as indicated by the :with-defaults capability 522 identifier's 'basic-mode' parameter, defined in Section 4.3. 524 The and operations support a separate filtering 525 mechanism, using the parameter. The defaults filtering is 526 conceptually done before the parameter is processed. For 527 example, if the parameter is equal to 'report-all', 528 then the parameter is conceptually applied to all data nodes 529 and all default data. 531 The operation is only affected by the 532 parameter if the target of the operation is specified with the 533 parameter. If the target is a NETCONF configuration datastore (i.e., 534 running, candidate or startup), the parameter has no 535 effect. The server MUST use its basic mode when copying data to a 536 NETCONF configuration datastore. If the parameter is 537 present in this case, it MUST be silently ignored by the server. 539 If the server supports the 'report-all-tagged' mode, then the 540 'default' attribute defined in Section 6 also impacts the operation. If the 'default' attribute is present and set to 542 'true' or '1', then the server MUST treat the new data node as a 543 request to return that node to its default value (i.e., remove it 544 from the configuration datastore). The data node within the NETCONF 545 message MUST contain a value in this case, which MUST be equal to the 546 schema default value. If not, the server MUST return an 547 response with a 'invalid-value' error-tag. 549 4.5.2. Operation 551 The operation has several editing modes. The 'create' 552 and 'delete' editing operations are affected by the defaults handling 553 basic mode. The other enumeration values for the NETCONF operation 554 attribute are not affected. 556 If the operation attribute contains the value 'create', and the data 557 node already exists in the target configuration datastore, then the 558 server MUST return an response with a 'invalid-value' 559 error-tag. 561 If the client sets a data node to its schema default value, the 562 server MUST accept the request if it is valid. The server MUST keep 563 or discard the new value based on its defaults handling basic mode. 564 For the 'trim' basic mode, all schema default values are discarded, 565 otherwise a client-provided schema default value is saved in a 566 NETCONF configuration datastore. 568 If the server supports the 'report-all-tagged' mode, then the 569 'default' attribute defined in Section 6 also impacts the operation. If the 'default' attribute is present and set to 571 'true' or '1', then the server MUST treat the new data node as a 572 request to return that node to its default value (i.e., remove it 573 from the configuration datastore). The data node within the NETCONF 574 message MUST contain a value in this case, which MUST be equal to the 575 schema default value. If not, the server MUST return an 576 response with a 'invalid-value' error-tag. 578 If the 'default' attribute is present, then the effective operation 579 for the target data node MUST be 'create', 'merge' or 'replace'. If 580 not, then the server MUST return an response with an 581 'invalid-value' error-tag. For example, if 'create' is the effective 582 operation, then the create request must be valid on its own (e.g., 583 current data node MUST NOT exist). The procedure for determining the 584 effective operation is defined in [I-D.ietf-netconf-4741bis]. It is 585 derived from the 'default-operation' parameter and/or any operation 586 attributes that are present in the data node or any of its ancestor 587 nodes, within the request. 589 4.5.3. Other Operations 591 Other operations that return configuration data SHOULD also handle 592 default data according to the rules set in this document, and 593 explicitly state this in their documentation. If this is not 594 specified in the document defining the respective operation, the 595 default handling rules described herein do not affect these 596 operations. 598 4.6. Interactions with Other Capabilities 600 None 602 5. YANG Module for the Parameter 604 The following YANG module defines the addition of the with-defaults 605 element to the , , and operations. 606 The YANG language is defined in [RFC6020]. The above operations are 607 defined in YANG in [I-D.ietf-netconf-4741bis]. Every NETCONF server 608 which supports the :with-defaults capability MUST implement this YANG 609 module. 611 file="ietf-netconf-with-defaults@2010-11-11.yang" 613 module ietf-netconf-with-defaults { 615 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults"; 617 prefix ncwd; 619 import ietf-netconf { prefix nc; } 621 organization 622 "IETF NETCONF (Network Configuration Protocol) Working Group"; 624 contact 625 "WG Web: 626 WG List: 628 WG Chair: Bert Wijnen 629 631 WG Chair: Mehmet Ersue 632 634 Editor: Andy Bierman 635 637 Editor: Balazs Lengyel 638 "; 640 description 641 "This module defines an extension to the NETCONF protocol 642 that allows the NETCONF client to control how default 643 values are handled by the server in particular NETCONF operations. 645 Copyright (c) 2010 IETF Trust and the persons identified as 646 the document authors. All rights reserved. 648 Redistribution and use in source and binary forms, with or 649 without modification, is permitted pursuant to, and subject 650 to the license terms contained in, the Simplified BSD License 651 set forth in Section 4.c of the IETF Trust's Legal Provisions 652 Relating to IETF Documents 653 (http://trustee.ietf.org/license-info). 655 This version of this YANG module is part of RFC XXXX; see 656 the RFC itself for full legal notices."; 657 // RFC Ed.: replace XXXX with actual RFC number and remove this note 659 // RFC Ed.: remove this note 660 // Note: extracted from draft-ietf-netmod-with-defaults-14.txt 662 revision 2010-11-11 { 663 description 664 "Initial version."; 665 reference 666 "RFC XXXX: With-defaults capability for NETCONF"; 667 } 668 // RFC Ed.: replace XXXX with actual 669 // RFC number and remove this note 671 typedef with-defaults-mode { 672 description 673 "Possible modes to report default data."; 674 reference 675 "RFC XXXX; section 3."; 676 // RFC Ed.: replace XXXX with actual 677 // RFC number and remove this note 679 type enumeration { 680 enum report-all { 681 description 682 "All default data is reported."; 683 reference 684 "RFC XXXX; section 3.1"; 685 // RFC Ed.: replace XXXX with actual 686 // RFC number and remove this note 688 } 689 enum report-all-tagged { 690 description 691 "All default data is reported. 692 Any nodes considered to be default data 693 will contain a 'default' XML attribute, 694 set to 'true' or '1'."; 695 reference 696 "RFC XXXX; section 3.4"; 697 // RFC Ed.: replace XXXX with actual 698 // RFC number and remove this note 699 } 700 enum trim { 701 description 702 "Values are not reported if they contain the default."; 703 reference 704 "RFC XXXX; section 3.2"; 705 // RFC Ed.: replace XXXX with actual 706 // RFC number and remove this note 708 } 709 enum explicit { 710 description 711 "Report values that contain the definition of 712 explicitly set data."; 713 reference 714 "RFC XXXX; section 3.3"; 715 // RFC Ed.: replace XXXX with actual 716 // RFC number and remove this note 717 } 718 } 719 } 721 grouping with-defaults-parameters { 722 description 723 "Contains the parameter for control 724 of defaults in NETCONF retrieval operations."; 726 leaf with-defaults { 727 description 728 "The explicit defaults processing mode requested."; 729 reference 730 "RFC XXXX; section 4.6.1"; 731 // RFC Ed.: replace XXXX with actual 732 // RFC number and remove this note 734 type with-defaults-mode; 735 } 736 } 738 // extending the get-config operation 739 augment /nc:get-config/nc:input { 740 description 741 "Adds the parameter to the 742 input of the NETCONF operation."; 743 reference 744 "RFC XXXX; section 4.6.1"; 745 // RFC Ed.: replace XXXX with actual 746 // RFC number and remove this note 748 uses with-defaults-parameters; 749 } 751 // extending the get operation 752 augment /nc:get/nc:input { 753 description 754 "Adds the parameter to 755 the input of the NETCONF operation."; 756 reference 757 "RFC XXXX; section 4.6.1"; 758 // RFC Ed.: replace XXXX with actual 759 // RFC number and remove this note 761 uses with-defaults-parameters; 762 } 764 // extending the copy-config operation 765 augment /nc:copy-config/nc:input { 766 description 767 "Adds the parameter to 768 the input of the NETCONF operation."; 769 reference 770 "RFC XXXX; section 4.6.1"; 771 // RFC Ed.: replace XXXX with actual 772 // RFC number and remove this note 774 uses with-defaults-parameters; 775 } 777 } 779 781 6. XSD for the 'default' Attribute 783 The following XML Schema document [W3C.REC-xml-20081126] defines the 784 'default' attribute, described within this document. This XSD is 785 only relevant if the server supports the 'report-all-tagged' defaults 786 retrieval mode. 788 The 'default' attribute uses the XSD data type 'boolean'. In 789 accordance with Section 3.2.2.1 of XML Schema Part 2: Datatypes, the 790 allowable lexical representations for the xs:boolean datatype are the 791 strings "0" and "false" for the concept of false and the strings "1" 792 and "true" for the concept of true. Implementations MUST support 793 both styles of lexical representation. 795 file="defaults.xsd" 797 798 805 806 807 This schema defines the syntax for the 'default' attribute 808 described within this document. 809 810 812 815 816 817 818 This attribute indicates whether the data node represented 819 by the XML element containing this attribute is considered 820 by the server to be default data. If set to 'true' or '1' then 821 the data node is default data. If 'false' or '0', then the 822 data node is not default data. 823 824 825 827 829 831 7. IANA Considerations 833 This document registers the following capability identifier URN in 834 the 'Network Configuration Protocol Capability URNs registry': 836 urn:ietf:params:netconf:capability:with-defaults:1.0 838 Note that the capability URN is compliant to 839 [I-D.ietf-netconf-4741bis] section 10.3. 841 This document registers two XML namespace URNs in the 'IETF XML 842 registry', following the format defined in [RFC3688]. 844 URI: urn:ietf:params:xml:ns:netconf:default:1.0 845 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults 847 Registrant Contact: The NETCONF WG of the IETF. 849 XML: N/A, the requested URIs are XML namespaces. 851 This document registers one module name in the 'YANG Module Names' 852 registry, defined in [RFC6020] . 854 name: ietf-netconf-with-defaults 855 prefix: ncwd 856 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults 857 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 859 8. Security Considerations 861 This document defines an extension to existing NETCONF protocol 862 operations. It does not introduce any new or increased security 863 risks into the management system. 865 The 'with-defaults' capability gives clients control over the 866 retrieval of default data from a NETCONF datastore. The security 867 consideration of [I-D.ietf-netconf-4741bis] apply to this document as 868 well. 870 9. Acknowledgements 872 Thanks to Martin Bjorklund, Sharon Chisholm, Phil Shafer, Juergen 873 Schoenwaelder, Kent Watsen, Washam Fan and many other members of the 874 NETCONF WG for providing important input to this document. 876 10. Normative References 878 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 879 Requirement Levels", BCP 14, RFC 2119, March 1997. 881 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 882 January 2004. 884 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 885 Network Configuration Protocol (NETCONF)", RFC 6020, 886 October 2010. 888 [I-D.ietf-netconf-4741bis] 889 Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 890 Bierman, "Network Configuration Protocol (NETCONF)", 891 draft-ietf-netconf-4741bis-06 (work in progress), 892 October 2010. 894 [W3C.REC-xml-20081126] 895 Maler, E., Yergeau, F., Sperberg-McQueen, C., Paoli, J., 896 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 897 Edition)", World Wide Web Consortium Recommendation REC- 898 xml-20081126, November 2008, 899 . 901 [W3C.REC-xmlschema-0-20041028] 902 Walmsley, P. and D. Fallside, "XML Schema Part 0: Primer 903 Second Edition", World Wide Web Consortium 904 Recommendation REC-xmlschema-0-20041028, October 2004, 905 . 907 Appendix A. Usage Examples 909 A.1. Example YANG Module 911 The following YANG module defines an example interfaces table to 912 demonstrate how the parameter behaves for a specific 913 data model. 915 Note that this is not a real module, and implementation of this 916 module is not required for conformance to the :with-defaults 917 capability, defined in Section 4. This module is not to be 918 registered with IANA, and is not considered to be a code component. 919 It is intentionally very terse, and includes few descriptive 920 statements. 922 module example { 924 namespace "http://example.com/ns/interfaces"; 926 prefix exam; 928 typedef status-type { 929 description "Interface status"; 930 type enumeration { 931 enum ok; 932 enum 'waking up'; 933 enum 'not feeling so good'; 934 enum 'better check it out'; 935 enum 'better call for help'; 936 } 937 default ok; 938 } 940 container interfaces { 941 description "Example interfaces group"; 943 list interface { 944 description "Example interface entry"; 945 key name; 947 leaf name { 948 description 949 "The administrative name of the interface. 950 This is an identifier which is only unique 951 within the scope of this list, and only 952 within a specific server."; 953 type string { 954 length "1 .. max"; 955 } 956 } 958 leaf mtu { 959 description 960 "The maximum transmission unit (MTU) value assigned to 961 this interface."; 962 type uint32; 963 default 1500; 964 } 966 leaf status { 967 description 968 "The current status of this interface."; 969 type status-type; 970 config false; 971 } 972 } 973 } 974 } 976 A.2. Example Data Set 978 The following data element shows the conceptual contents of the 979 example server for the protocol operation examples in the next 980 section. This includes all the configuration data nodes, non- 981 configuration data nodes, and default leafs. 983 984 985 986 eth0 987 8192 988 up 989 990 991 eth1 992 1500 993 up 994 995 996 eth2 997 9000 998 not feeling so good 999 1000 1001 eth3 1002 1500 1003 waking up 1004 1005 1006 1008 In this example, the 'mtu' field for each interface entry is set in 1009 the following manner: 1011 +--------------+--------------+--------------+ 1012 | name | set by | mtu | 1013 +--------------+--------------+--------------+ 1014 | eth0 | client | 8192 | 1015 | eth1 | server | 1500 | 1016 | eth2 | client | 9000 | 1017 | eth3 | client | 1500 | 1018 +--------------+--------------+--------------+ 1020 A.3. Protocol Operation Examples 1022 The following examples shows some operations using the 'with- 1023 defaults' element. The data model used for these examples is defined 1024 in Appendix A.1. 1026 The client is retrieving all the data nodes within the 'interfaces' 1027 object, filtered with the parameter. 1029 A.3.1. = 'report-all' 1031 The behavior of the parameter handling for the value 1032 'report-all' is demonstrated in this example. 1034 1036 1037 1038 1039 1040 1042 report-all 1043 1044 1045 1047 1049 1050 1051 1052 eth0 1053 8192 1054 up 1055 1056 1057 eth1 1058 1500 1059 up 1060 1061 1062 eth2 1063 9000 1064 not feeling so good 1065 1066 1067 eth3 1068 1500 1069 waking up 1070 1071 1072 1073 1075 A.3.2. = 'report-all-tagged' 1077 The behavior of the parameter handling for the value 1078 'report-all-tagged' is demonstrated in this example. A 'tagged' data 1079 node is an element that contains the 'default' XML attribute, set to 1080 'true' or '1'. 1082 The actual data nodes tagged by the server depends on the defaults 1083 handling basic mode used by the server. Only the data nodes that are 1084 considered to be default data will be tagged. 1086 In this example, the server's basic mode is equal to 'trim', so all 1087 data nodes that would contain the schema default value are tagged. 1088 If the server's basic mode is 'explicit', then only data nodes that 1089 are not explicitly set data are tagged. If the server's basic mode 1090 is 'report-all', then no data nodes are tagged. 1092 1094 1095 1096 1097 1098 1100 report-all-tagged 1101 1102 1103 1105 1108 1109 1110 1111 eth0 1112 8192 1113 up 1114 1115 1116 eth1 1117 1500 1118 up 1119 1120 1121 eth2 1122 9000 1123 not feeling so good 1124 1125 1126 eth3 1127 1500 1128 waking up 1129 1130 1131 1132 1134 A.3.3. = 'trim' 1136 The behavior of the parameter handling for the value 1137 'trim' is demonstrated in this example. 1139 1141 1142 1143 1144 1145 1147 trim 1148 1149 1150 1152 1154 1155 1156 1157 eth0 1158 8192 1159 1160 1161 eth1 1162 1163 1164 eth2 1165 9000 1166 not feeling so good 1167 1168 1169 eth3 1170 waking up 1171 1172 1173 1174 1176 A.3.4. = 'explicit' 1178 The behavior of the parameter handling for the value 1179 'explicit' is demonstrated in this example. 1181 1183 1184 1185 1186 1187 1189 explicit 1190 1191 1192 1194 1196 1197 1198 1199 eth0 1200 8192 1201 up 1202 1203 1204 eth1 1205 up 1206 1207 1208 eth2 1209 9000 1210 not feeling so good 1211 1212 1213 eth3 1214 1500 1215 waking up 1216 1217 1218 1219 1221 Appendix B. Change Log 1223 -- RFC Ed.: remove this section before publication. 1225 B.1. 13-14 1227 Removed reference to RFC 4741 and using 4741bis instead. 1229 B.2. 12-13 1231 Removed with-defaults capability conformance section. 1233 Changed 'wd:default' to 'default'. 1235 Added normative reference to XSD. 1237 Clarified conditional support for with-defaults enumerations, based 1238 on capability parameters. 1240 Clarified that all xs:boolean encoding values must be supported. 1242 Clarified purpose of also-supported parameter in capability URI. 1244 B.3. 11-12 1246 Made editorial clarifications based on AD review. 1248 B.4. 10-11 1250 Changed term 'database' to 'configuration datastore' or generic 1251 'datastore'. 1253 B.5. 09-10 1255 Changed term 'datastore' to 'database'. 1257 Added term 'default value'. 1259 Clarified verbage for data node containing a default value. 1261 B.6. 08-09 1263 Removed non-volatile server requirements. 1265 Moved some text from basic-mode section into the the retrieval modes 1266 section. 1268 Added description and reference statements to the YANG module. 1270 Many bugfixes and clarifications, based on WGLC review comments. 1272 B.7. 07-08 1274 Added report-all-tagged mode. 1276 Changed conformance so report-all or report-all-tagged mode SHOULD be 1277 supported. 1279 Clarified capability requirements for each mode, for edit-config and 1280 NV storage requirements. 1282 Changed rpc-error details for unsupported with-defaults value. 1284 Added XSD for wd:default attribute 1286 Expanded example to show report-all-tagged for a basic-mode=trim 1287 server. 1289 B.8. 06-07 1291 Removed text in capability identifier section about adding YANG 1292 module capability URI parameters. 1294 Changed YANG module namespace to match YANG format, and updated 1295 examples to use this new namespace. 1297 Fixed some typos. 1299 B.9. 05-06 1301 Removed ':1.0' from capability URI. 1303 Removed open issues section because all known issues are closed. 1305 Moved examples to a separate appendix, and expanded them. 1307 Added example.yang as an appendix to properly explain the examples 1308 used within the document. 1310 Replaced normative term 'SHALL' with 'MUST' to be consistent within 1311 this document. 1313 Clarified behavior for non-configuration data nodes. 1315 Clarified various sections based on WGLC comments on mailing list. 1317 Removed some unused terms. 1319 Reversed the order of the change log sections so the most recent 1320 changes are shown first. 1322 B.10. 04-05 1324 Updated I-D and YANG module boiler-plate. 1326 Removed redundant 'with-defaults' YANG feature. 1328 Changed definition of 'explicit' mode to match the YANG definition 1330 Removed XSD because the YANG is normative and the XSD is 1331 unconstrained, and does not properly extend the 3 affected NETCONF 1332 operations. 1334 Made the YANG module a normative section instead of non-normative 1335 appendix. 1337 Changed YANG from an informative to a normative reference, 1339 Changed 4741bis from an informative to a normative reference because 1340 the YANG module imports the ietf-netconf module in order to augment 1341 some operations. 1343 Updated capability requirements to include YANG module capability 1344 parameters. 1346 Added a description statement to the with-defaults leaf definition. 1348 Update open issues section; ready to close all open issues. 1350 B.11. 03-04 1352 Clarifications 1354 Added non-netconf interfaces to the definition of explicitly set 1355 default data 1357 B.12. 02-03 1359 Clarifications 1361 YAM added 1363 Use the same URN for the capability and the XML namespace to 1364 accommodate YANG, and avoid two separate URN/URIs being advertised in 1365 the HELLO message, for such a small function. 1367 B.13. 01-02 1369 report-all made mandatory 1371 Placeholder for YAM added, XSD will be removed when 4741 provides the 1372 NETCONF YAM 1374 with-defaults is valid for state data as well (if state data has a 1375 defined default which might not be so frequent). The definition of 1376 explicit was modified for state data. 1378 B.14. 00-01 1380 Changed value set of with-default capability and element 1382 Added version to URI 1384 B.15. -00 1386 Created from draft-bierman-netconf-with-defaults-01.txt 1388 It was decided by the NETCONF mailing list, that with-defaults should 1389 be a sub-element of each affected operation. While this violates the 1390 XSD of RFC4741 this is acceptable and follows the ideas behind 1391 NETCONF and YANG. 1393 Hopefully it will be clarified in the 4741bis RFC whether such 1394 extensions are allowed. 1396 Authors' Addresses 1398 Andy Bierman 1399 Brocade 1401 Email: andy.bierman@brocade.com 1403 Balazs Lengyel 1404 Ericsson 1405 Budapest, 1406 Hungary 1408 Email: balazs.lengyel@ericsson.com