idnits 2.17.1 draft-ietf-netconf-with-defaults-13.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 9, 2010) is 4910 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-06 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: May 13, 2011 Ericsson 6 November 9, 2010 8 With-defaults capability for NETCONF 9 draft-ietf-netconf-with-defaults-13 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 13, 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. 12-13 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 110 B.2. 11-12 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 111 B.3. 10-11 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 112 B.4. 09-10 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 113 B.5. 08-09 . . . . . . . . . . . . . . . . . . . . . . . . . . 29 114 B.6. 07-08 . . . . . . . . . . . . . . . . . . . . . . . . . . 30 115 B.7. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 30 116 B.8. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 30 117 B.9. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 31 118 B.10. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 31 119 B.11. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 31 120 B.12. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 121 B.13. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 32 122 B.14. -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 If the 'report-all' basic mode is used by the server, then the server 271 MUST support the parameter with a value equal to 272 'report-all', as specified in Section 3.1. 274 2.1.3. 'report-all' and Behavior 276 The server MUST consider every data node to exist, even those 277 containing a schema default value. A valid 'create' operation 278 attribute for a data node that contains its schema default value MUST 279 fail with a 'data-exists' error-tag. A valid 'delete' operation 280 attribute for a data node that contains its schema default value MUST 281 succeed, even though the data node is immediately replaced by the 282 server with the default value. 284 A server which uses the 'report-all' basic-mode has no concept of a 285 default node, so the 'report-all-tagged' retrieval 286 mode is not relevant. There will never be any tagged nodes, since 287 there are no nodes which are omitted in a basic-mode retrieval 288 operation. If the 'default' attribute is present in any 289 configuration data, the server MUST return an response 290 with an 'unknown-attribute' error-tag. 292 2.2. 'trim' Basic Mode 294 A server which uses the 'trim' basic mode MUST consider any data node 295 set to its schema default value to be default data. 297 2.2.1. 'trim' Basic Mode Retrieval 299 When data is retrieved from a server using the 'trim' basic mode, and 300 the parameter is not present, data nodes MUST NOT be 301 reported if they contain the schema default value. Non-configuration 302 data nodes containing the schema default value MUST NOT be reported. 304 2.2.2. 'trim' Retrieval 306 If the 'trim' basic mode is used by the server, then the server MUST 307 support the parameter with a value equal to 'trim', 308 as specified in Section 3.2. 310 2.2.3. 'trim' and Behavior 312 The server MUST consider any data node that does not contain its 313 schema default value to exist. A valid 'create' operation attribute 314 for a data node that has a schema default value defined MUST succeed. 315 A valid 'delete' operation attribute for a missing data node that has 316 a schema default value MUST fail. The server MUST return an response with a 'data-missing' error-tag. 319 If a client sets a data node to its schema default value, using any 320 valid operation, it MUST succeed, although the data node MUST NOT be 321 saved in the NETCONF configuration datastore. This has the same 322 effect as removing the data node and treating it as default data. 324 If the server supports the 'report-all-tagged' value for the parameter, then the 'default' attribute MUST be accepted in 326 configuration input, as described in Section 4.5.1 and Section 4.5.2. 328 2.3. 'explicit' Basic Mode 330 A server which uses the 'explicit' basic mode MUST consider any data 331 node that is not explicitly set data to be default data. 333 2.3.1. 'explicit' Basic Mode Retrieval 335 When data is retrieved from a server using the 'explicit' basic mode, 336 and the parameter is not present, data nodes MUST be 337 reported if explicitly set by the client, even if they contain the 338 schema default value. Non-configuration data nodes containing the 339 schema default value MUST be reported. 341 2.3.2. 'explicit' Retrieval 343 If the 'explicit' basic mode is used by the server, the server MUST 344 support the parameter with a value equal to 345 'explicit', as specified in Section 3.3. 347 2.3.3. 'explicit' and Behavior 349 The server considers any data node that is explicitly set data to 350 exist. A valid 'create' operation attribute for a data node that has 351 been set by a client to its schema default value MUST fail with a 352 'data-exists' error-tag. A valid 'create' operation attribute for a 353 data node that has been set by the server to its schema default value 354 MUST succeed. A valid 'delete' operation attribute for a data node 355 that has been set by a client to its schema default value MUST 356 succeed. A valid 'delete' operation attribute for a data node that 357 has been set by the server to its schema default value MUST fail with 358 a 'data-missing' error-tag. 360 If the server supports the 'report-all-tagged' retrieval mode in its 361 :with-defaults capability, then the 'default' attribute MUST be 362 accepted in configuration input. If all NETCONF or 363 parameters are valid, then the server will treat a 364 tagged data node (i.e., the 'default' attribute set to 'true' or '1') 365 as a request to return that node to default data. If this request is 366 valid within the context of the requested NETCONF operation, then the 367 data node is removed and returned to its default value. The data 368 node within the NETCONF message MUST contain a value in this case, 369 which MUST be equal to the schema default value. If not, the server 370 MUST return an response with a 'invalid-value' error-tag. 372 3. Retrieval of Default Data 374 This document defines a new parameter, called , which 375 can be added to specific NETCONF operation request messages to 376 control how retrieval of default data is treated by the server. 378 A server which implements this specification MUST accept the parameter containing the enumeration for any of the 380 defaults handling modes it supports. The parameter 381 contains one of the four enumerations defined in this section. 383 3.1. 'report-all' Retrieval Mode 385 When data is retrieved with a parameter equal to 386 'report-all', all data nodes MUST be reported, including any data 387 nodes considered to be default data by the server. 389 3.2. 'trim' Retrieval Mode 391 When data is retrieved with a parameter equal to 392 'trim', data nodes MUST NOT be reported if they contain the schema 393 default value. Non-configuration data nodes containing the schema 394 default value MUST NOT be reported. 396 3.3. 'explicit' Retrieval Mode 398 When data is retrieved with a parameter equal to 399 'explicit', a data node which was set by a client to its schema 400 default value MUST be reported. A conceptual data node which would 401 be set by the server to the schema default value MUST NOT be 402 reported. Non-configuration data nodes containing the schema default 403 value MUST be reported. 405 3.4. 'report-all-tagged' Retrieval Mode 407 In addition to the basic modes, a special variant of the 'report-all' 408 basic mode is available called 'report-all-tagged'. This mode MUST 409 be supported on a server if the 'also-supported' parameter in the 410 :with-defaults capability contains the 'report-all-tagged' option. 411 Refer to Section 4 for encoding details for this capability. 413 In this mode the server returns all data nodes, just like the 414 'report-all' mode, except a data node that is considered by the 415 server to contain default data will include an XML attribute to 416 indicate this condition. This is useful for an application to 417 determine which nodes are considered to contain default data by the 418 server, within a single retrieval operation. 420 A server which supports 'report-all-tagged' MUST also accept the 421 'default' XML attribute within configuration input to the or operations. Refer to Section 6 for XML 423 encoding details of the 'default' XML attribute. 425 4. With-defaults Capability 427 4.1. Overview 429 The :with-defaults capability indicates which defaults handling basic 430 mode is supported by the server. It may also indicate support for 431 additional defaults retrieval modes. These retrieval modes allow a 432 NETCONF client to control whether default data is returned by the 433 server. The capability affects both configuration and state data 434 (while acknowledging that the usage of default values for state data 435 is less prevalent). Sending of default data is controlled for each 436 individual operation separately. 438 A NETCONF server implementing the :with-defaults capability: 440 o MUST indicate its basic mode behavior by including the 'basic- 441 mode' parameter in the capability URI, as defined in Section 4.3. 442 o MUST support the YANG module defined in Section 5 for the defaults 443 handling mode indicated by the 'basic-mode' parameter. 444 o SHOULD support the YANG module in Section 5 for the defaults 445 handling mode identified by the 'report-all' or 'report-all- 446 tagged' enumeration value. 447 o If the 'report-all-tagged' defaults handling mode is supported, 448 then the 'default' attribute MUST be supported. 449 o MAY support the YANG module in Section 5 for additional defaults 450 handling modes. 452 4.2. Dependencies 454 None 456 4.3. Capability Identifier 458 urn:ietf:params:netconf:capability:with-defaults:1.0 460 The identifier MUST have a parameter: "basic-mode". This indicates 461 how the server will treat default data, as defined in Section 2. The 462 allowed values of this parameter are 'report-all', 'trim', and 463 'explicit', as defined in Section 2. 465 The identifier MAY have another parameter: "also-supported". This 466 parameter indicates which additional enumeration values (besides the 467 basic-mode enumeration), the server will accept for the parameter in Section 5. The value of the parameter is a 469 comma separated list of one or more modes that are supported beside 470 the mode indicated in the 'basic-mode' parameter. Possible modes are 471 'report-all', 'report-all-tagged', 'trim', and 'explicit', as defined 472 in Section 3. 474 Note that this protocol capability URI is separate from the YANG 475 module capability URI for the YANG module in Section 5. A server 476 which implements this module MUST also advertise a YANG module 477 capability URI according to the rules specified in [RFC6020]. 479 Examples: 481 urn:ietf:params:netconf:capability:with-defaults:1.0?basic- 482 mode=explicit 484 urn:ietf:params:netconf:capability:with-defaults:1.0?basic- 485 mode=explicit&also-supported=report-all,report-all-tagged 487 4.4. New Operations 489 None 491 4.5. Modifications to Existing Operations 493 4.5.1. , , and Operations 495 A new XML element is added to the input for the 496 , and operations. If the element is present, it controls the reporting of default 498 data. The server MUST return default data in the NETCONF 499 messages according to the value of this element, if the server 500 supports the specified retrieval mode. 502 This parameter only controls these specified retrieval operations, 503 and does not impact any other operations or the non-volatile storage 504 of configuration data. 506 The element is defined in the XML namespace for the 507 ietf-netconf-with-defaults.yang module in Section 5, not the XML 508 namespace for the , and operations. 510 Allowed values of the with-defaults element are taken from the 'with- 511 defaults-type' typedef in Section 5. The allowed values for a 512 particular server are restricted to the values that the server 513 indicates it supports within the :with-defaults capability, in the 514 'basic-mode' and 'also-supported' parameters. 516 If an unsupported value is used, the NETCONF server MUST return an 517 response with an 'invalid-value' error-tag. 519 If the element is not present, the server MUST follow 520 its basic mode behavior as indicated by the :with-defaults capability 521 identifier's 'basic-mode' parameter, defined in Section 4.3. 523 The and operations support a separate filtering 524 mechanism, using the parameter. The defaults filtering is 525 conceptually done before the parameter is processed. For 526 example, if the parameter is equal to 'report-all', 527 then the parameter is conceptually applied to all data nodes 528 and all default data. 530 The operation is only affected by the 531 parameter if the target of the operation is specified with the 532 parameter. If the target is a NETCONF configuration datastore (i.e., 533 running, candidate or startup), the parameter has no 534 effect. The server MUST use its basic mode when copying data to a 535 NETCONF configuration datastore. If the parameter is 536 present in this case, it MUST be silently ignored by the server. 538 If the server supports the 'report-all-tagged' mode, then the 539 'default' attribute defined in Section 6 also impacts the operation. If the 'default' attribute is present and set to 541 'true' or '1', then the server MUST treat the new data node as a 542 request to return that node to its default value (i.e., remove it 543 from the configuration datastore). The data node within the NETCONF 544 message MUST contain a value in this case, which MUST be equal to the 545 schema default value. If not, the server MUST return an 546 response with a 'invalid-value' error-tag. 548 4.5.2. Operation 550 The operation has several editing modes. The 'create' 551 and 'delete' editing operations are affected by the defaults handling 552 basic mode. The other enumeration values for the NETCONF operation 553 attribute are not affected. 555 If the operation attribute contains the value 'create', and the data 556 node already exists in the target configuration datastore, then the 557 server MUST return an response with a 'invalid-value' 558 error-tag. 560 If the client sets a data node to its schema default value, the 561 server MUST accept the request if it is valid. The server MUST keep 562 or discard the new value based on its defaults handling basic mode. 563 For the 'trim' basic mode, all schema default values are discarded, 564 otherwise a client-provided schema default value is saved in a 565 NETCONF configuration datastore. 567 If the server supports the 'report-all-tagged' mode, then the 568 'default' attribute defined in Section 6 also impacts the operation. If the 'default' attribute is present and set to 570 'true' or '1', then the server MUST treat the new data node as a 571 request to return that node to its default value (i.e., remove it 572 from the configuration datastore). The data node within the NETCONF 573 message MUST contain a value in this case, which MUST be equal to the 574 schema default value. If not, the server MUST return an 575 response with a 'invalid-value' error-tag. 577 If the 'default' attribute is present, then the effective operation 578 for the target data node MUST be 'create', 'merge' or 'replace'. If 579 not, then the server MUST return an response with an 580 'invalid-value' error-tag. For example, if 'create' is the effective 581 operation, then the create request must be valid on its own (e.g., 582 current data node MUST NOT exist). The procedure for determining the 583 effective operation is defined in [I-D.ietf-netconf-4741bis]. It is 584 derived from the 'default-operation' parameter and/or any operation 585 attributes that are present in the data node or any of its ancestor 586 nodes, within the request. 588 4.5.3. Other Operations 590 Other operations that return configuration data SHOULD also handle 591 default data according to the rules set in this document, and 592 explicitly state this in their documentation. If this is not 593 specified in the document defining the respective operation, the 594 default handling rules described herein do not affect these 595 operations. 597 4.6. Interactions with Other Capabilities 599 None 601 5. YANG Module for the Parameter 603 The following YANG module defines the addition of the with-defaults 604 element to the , , and operations. 605 The YANG language is defined in [RFC6020]. The above operations are 606 defined in YANG in [I-D.ietf-netconf-4741bis]. Every NETCONF server 607 which supports the :with-defaults capability MUST implement this YANG 608 module. 610 file="ietf-netconf-with-defaults@2010-11-09.yang" 612 module ietf-netconf-with-defaults { 614 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults"; 616 prefix ncwd; 618 import ietf-netconf { prefix nc; } 620 organization 621 "IETF NETCONF (Network Configuration Protocol) Working Group"; 623 contact 624 "WG Web: 625 WG List: 627 WG Chair: Bert Wijnen 628 630 WG Chair: Mehmet Ersue 631 633 Editor: Andy Bierman 634 636 Editor: Balazs Lengyel 637 "; 639 description 640 "This module defines an extension to the NETCONF protocol 641 that allows the NETCONF client to control how default 642 values are handled by the server in particular NETCONF operations. 644 Copyright (c) 2010 IETF Trust and the persons identified as 645 the document authors. All rights reserved. 647 Redistribution and use in source and binary forms, with or 648 without modification, is permitted pursuant to, and subject 649 to the license terms contained in, the Simplified BSD License 650 set forth in Section 4.c of the IETF Trust's Legal Provisions 651 Relating to IETF Documents 652 (http://trustee.ietf.org/license-info). 654 This version of this YANG module is part of RFC XXXX; see 655 the RFC itself for full legal notices."; 656 // RFC Ed.: replace XXXX with actual RFC number and remove this note 658 // RFC Ed.: remove this note 659 // Note: extracted from draft-ietf-netmod-with-defaults-13.txt 661 revision 2010-11-09 { 662 description 663 "Initial version."; 664 reference 665 "RFC XXXX: With-defaults capability for NETCONF"; 666 } 667 // RFC Ed.: replace XXXX with actual 668 // RFC number and remove this note 670 typedef with-defaults-mode { 671 description 672 "Possible modes to report default data."; 673 reference 674 "RFC XXXX; section 3."; 675 // RFC Ed.: replace XXXX with actual 676 // RFC number and remove this note 678 type enumeration { 679 enum report-all { 680 description 681 "All default data is reported."; 682 reference 683 "RFC XXXX; section 3.1"; 684 // RFC Ed.: replace XXXX with actual 685 // RFC number and remove this note 687 } 688 enum report-all-tagged { 689 description 690 "All default data is reported. 691 Any nodes considered to be default data 692 will contain a 'default' XML attribute, 693 set to 'true' or '1'."; 694 reference 695 "RFC XXXX; section 3.4"; 696 // RFC Ed.: replace XXXX with actual 697 // RFC number and remove this note 698 } 699 enum trim { 700 description 701 "Values are not reported if they contain the default."; 702 reference 703 "RFC XXXX; section 3.2"; 704 // RFC Ed.: replace XXXX with actual 705 // RFC number and remove this note 707 } 708 enum explicit { 709 description 710 "Report values that contain the definition of 711 explicitly set data."; 712 reference 713 "RFC XXXX; section 3.3"; 714 // RFC Ed.: replace XXXX with actual 715 // RFC number and remove this note 716 } 717 } 718 } 720 grouping with-defaults-parameters { 721 description 722 "Contains the parameter for control 723 of defaults in NETCONF retrieval operations."; 725 leaf with-defaults { 726 description 727 "The explicit defaults processing mode requested."; 728 reference 729 "RFC XXXX; section 4.6.1"; 730 // RFC Ed.: replace XXXX with actual 731 // RFC number and remove this note 733 type with-defaults-mode; 734 } 735 } 737 // extending the get-config operation 738 augment /nc:get-config/nc:input { 739 description 740 "Adds the parameter to the 741 input of the NETCONF operation."; 742 reference 743 "RFC XXXX; section 4.6.1"; 744 // RFC Ed.: replace XXXX with actual 745 // RFC number and remove this note 747 uses with-defaults-parameters; 748 } 750 // extending the get operation 751 augment /nc:get/nc:input { 752 description 753 "Adds the parameter to 754 the input of the NETCONF operation."; 755 reference 756 "RFC XXXX; section 4.6.1"; 757 // RFC Ed.: replace XXXX with actual 758 // RFC number and remove this note 760 uses with-defaults-parameters; 761 } 763 // extending the copy-config operation 764 augment /nc:copy-config/nc:input { 765 description 766 "Adds the parameter to 767 the input of the NETCONF operation."; 768 reference 769 "RFC XXXX; section 4.6.1"; 770 // RFC Ed.: replace XXXX with actual 771 // RFC number and remove this note 773 uses with-defaults-parameters; 774 } 776 } 778 780 6. XSD for the 'default' Attribute 782 The following XML Schema document [W3C.REC-xml-20081126] defines the 783 'default' attribute, described within this document. This XSD is 784 only relevant if the server supports the 'report-all-tagged' defaults 785 retrieval mode. 787 The 'default' attribute uses the XSD data type 'boolean'. In 788 accordance with Section 3.2.2.1 of XML Schema Part 2: Datatypes, the 789 allowable lexical representations for the xs:boolean datatype are the 790 strings "0" and "false" for the concept of false and the strings "1" 791 and "true" for the concept of true. Implementations MUST support 792 both styles of lexical representation. 794 file="defaults.xsd" 796 797 804 805 806 This schema defines the syntax for the 'default' attribute 807 described within this document. 808 809 811 814 815 816 817 This attribute indicates whether the data node represented 818 by the XML element containing this attribute is considered 819 by the server to be default data. If set to 'true' or '1' then 820 the data node is default data. If 'false' or '0', then the 821 data node is not default data. 822 823 824 826 828 830 7. IANA Considerations 832 This document registers the following capability identifier URN in 833 the 'Network Configuration Protocol Capability URNs registry': 835 urn:ietf:params:netconf:capability:with-defaults:1.0 837 Note that the capability URN is compliant to [RFC4741] section 10.3. 839 This document registers two XML namespace URNs in the 'IETF XML 840 registry', following the format defined in [RFC3688]. 842 URI: urn:ietf:params:xml:ns:netconf:default:1.0 843 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults 845 Registrant Contact: The NETCONF WG of the IETF. 847 XML: N/A, the requested URIs are XML namespaces. 849 This document registers one module name in the 'YANG Module Names' 850 registry, defined in [RFC6020] . 852 name: ietf-netconf-with-defaults 853 prefix: ncwd 854 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults 855 RFC: XXXX // RFC Ed.: replace XXXX and remove this comment 857 8. Security Considerations 859 This document defines an extension to existing NETCONF protocol 860 operations. It does not introduce any new or increased security 861 risks into the management system. 863 The 'with-defaults' capability gives clients control over the 864 retrieval of default data from a NETCONF datastore. The security 865 consideration of [I-D.ietf-netconf-4741bis] apply to this document as 866 well. 868 9. Acknowledgements 870 Thanks to Martin Bjorklund, Sharon Chisholm, Phil Shafer, Juergen 871 Schoenwaelder, Kent Watsen, Washam Fan and many other members of the 872 NETCONF WG for providing important input to this document. 874 10. Normative References 876 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 877 Requirement Levels", BCP 14, RFC 2119, March 1997. 879 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 880 January 2004. 882 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 883 December 2006. 885 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 886 Network Configuration Protocol (NETCONF)", RFC 6020, 887 October 2010. 889 [I-D.ietf-netconf-4741bis] 890 Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 891 Bierman, "Network Configuration Protocol (NETCONF)", 892 draft-ietf-netconf-4741bis-06 (work in progress), 893 October 2010. 895 [W3C.REC-xml-20081126] 896 Yergeau, F., Maler, E., Paoli, J., Sperberg-McQueen, C., 897 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 898 Edition)", World Wide Web Consortium Recommendation REC- 899 xml-20081126, November 2008, 900 . 902 [W3C.REC-xmlschema-0-20041028] 903 Walmsley, P. and D. Fallside, "XML Schema Part 0: Primer 904 Second Edition", World Wide Web Consortium 905 Recommendation REC-xmlschema-0-20041028, October 2004, 906 . 908 Appendix A. Usage Examples 910 A.1. Example YANG Module 912 The following YANG module defines an example interfaces table to 913 demonstrate how the parameter behaves for a specific 914 data model. 916 Note that this is not a real module, and implementation of this 917 module is not required for conformance to the :with-defaults 918 capability, defined in Section 4. This module is not to be 919 registered with IANA, and is not considered to be a code component. 920 It is intentionally very terse, and includes few descriptive 921 statements. 923 module example { 925 namespace "http://example.com/ns/interfaces"; 927 prefix exam; 929 typedef status-type { 930 description "Interface status"; 931 type enumeration { 932 enum ok; 933 enum 'waking up'; 934 enum 'not feeling so good'; 935 enum 'better check it out'; 936 enum 'better call for help'; 937 } 938 default ok; 939 } 941 container interfaces { 942 description "Example interfaces group"; 944 list interface { 945 description "Example interface entry"; 946 key name; 948 leaf name { 949 description 950 "The administrative name of the interface. 951 This is an identifier which is only unique 952 within the scope of this list, and only 953 within a specific server."; 954 type string { 955 length "1 .. max"; 956 } 957 } 959 leaf mtu { 960 description 961 "The maximum transmission unit (MTU) value assigned to 962 this interface."; 963 type uint32; 964 default 1500; 965 } 967 leaf status { 968 description 969 "The current status of this interface."; 970 type status-type; 971 config false; 972 } 973 } 974 } 975 } 977 A.2. Example Data Set 979 The following data element shows the conceptual contents of the 980 example server for the protocol operation examples in the next 981 section. This includes all the configuration data nodes, non- 982 configuration data nodes, and default leafs. 984 985 986 987 eth0 988 8192 989 up 990 991 992 eth1 993 1500 994 up 995 996 997 eth2 998 9000 999 not feeling so good 1000 1001 1002 eth3 1003 1500 1004 waking up 1005 1006 1007 1009 In this example, the 'mtu' field for each interface entry is set in 1010 the following manner: 1012 +--------------+--------------+--------------+ 1013 | name | set by | mtu | 1014 +--------------+--------------+--------------+ 1015 | eth0 | client | 8192 | 1016 | eth1 | server | 1500 | 1017 | eth2 | client | 9000 | 1018 | eth3 | client | 1500 | 1019 +--------------+--------------+--------------+ 1021 A.3. Protocol Operation Examples 1023 The following examples shows some operations using the 'with- 1024 defaults' element. The data model used for these examples is defined 1025 in Appendix A.1. 1027 The client is retrieving all the data nodes within the 'interfaces' 1028 object, filtered with the parameter. 1030 A.3.1. = 'report-all' 1032 The behavior of the parameter handling for the value 1033 'report-all' is demonstrated in this example. 1035 1037 1038 1039 1040 1041 1043 report-all 1044 1045 1046 1048 1050 1051 1052 1053 eth0 1054 8192 1055 up 1056 1057 1058 eth1 1059 1500 1060 up 1061 1062 1063 eth2 1064 9000 1065 not feeling so good 1066 1067 1068 eth3 1069 1500 1070 waking up 1071 1072 1073 1074 1076 A.3.2. = 'report-all-tagged' 1078 The behavior of the parameter handling for the value 1079 'report-all-tagged' is demonstrated in this example. A 'tagged' data 1080 node is an element that contains the 'default' XML attribute, set to 1081 'true' or '1'. 1083 The actual data nodes tagged by the server depends on the defaults 1084 handling basic mode used by the server. Only the data nodes that are 1085 considered to be default data will be tagged. 1087 In this example, the server's basic mode is equal to 'trim', so all 1088 data nodes that would contain the schema default value are tagged. 1089 If the server's basic mode is 'explicit', then only data nodes that 1090 are not explicitly set data are tagged. If the server's basic mode 1091 is 'report-all', then no data nodes are tagged. 1093 1095 1096 1097 1098 1099 1101 report-all-tagged 1102 1103 1104 1106 1109 1110 1111 1112 eth0 1113 8192 1114 up 1115 1116 1117 eth1 1118 1500 1119 up 1120 1121 1122 eth2 1123 9000 1124 not feeling so good 1125 1126 1127 eth3 1128 1500 1129 waking up 1130 1131 1132 1133 1135 A.3.3. = 'trim' 1137 The behavior of the parameter handling for the value 1138 'trim' is demonstrated in this example. 1140 1142 1143 1144 1145 1146 1148 trim 1149 1150 1151 1153 1155 1156 1157 1158 eth0 1159 8192 1160 1161 1162 eth1 1163 1164 1165 eth2 1166 9000 1167 not feeling so good 1168 1169 1170 eth3 1171 waking up 1172 1173 1174 1175 1177 A.3.4. = 'explicit' 1179 The behavior of the parameter handling for the value 1180 'explicit' is demonstrated in this example. 1182 1184 1185 1186 1187 1188 1190 explicit 1191 1192 1193 1195 1197 1198 1199 1200 eth0 1201 8192 1202 up 1203 1204 1205 eth1 1206 up 1207 1208 1209 eth2 1210 9000 1211 not feeling so good 1212 1213 1214 eth3 1215 1500 1216 waking up 1217 1218 1219 1220 1222 Appendix B. Change Log 1224 -- RFC Ed.: remove this section before publication. 1226 B.1. 12-13 1228 Removed with-defaults capability conformance section. 1230 Changed 'wd:default' to 'default'. 1232 Added normative reference to XSD. 1234 Clarified conditional support for with-defaults enumerations, based 1235 on capability parameters. 1237 Clarified that all xs:boolean encoding values must be supported. 1239 Clarified purpose of also-supported parameter in capability URI. 1241 B.2. 11-12 1243 Made editorial clarifications based on AD review. 1245 B.3. 10-11 1247 Changed term 'database' to 'configuration datastore' or generic 1248 'datastore'. 1250 B.4. 09-10 1252 Changed term 'datastore' to 'database'. 1254 Added term 'default value'. 1256 Clarified verbage for data node containing a default value. 1258 B.5. 08-09 1260 Removed non-volatile server requirements. 1262 Moved some text from basic-mode section into the the retrieval modes 1263 section. 1265 Added description and reference statements to the YANG module. 1267 Many bugfixes and clarifications, based on WGLC review comments. 1269 B.6. 07-08 1271 Added report-all-tagged mode. 1273 Changed conformance so report-all or report-all-tagged mode SHOULD be 1274 supported. 1276 Clarified capability requirements for each mode, for edit-config and 1277 NV storage requirements. 1279 Changed rpc-error details for unsupported with-defaults value. 1281 Added XSD for wd:default attribute 1283 Expanded example to show report-all-tagged for a basic-mode=trim 1284 server. 1286 B.7. 06-07 1288 Removed text in capability identifier section about adding YANG 1289 module capability URI parameters. 1291 Changed YANG module namespace to match YANG format, and updated 1292 examples to use this new namespace. 1294 Fixed some typos. 1296 B.8. 05-06 1298 Removed ':1.0' from capability URI. 1300 Removed open issues section because all known issues are closed. 1302 Moved examples to a separate appendix, and expanded them. 1304 Added example.yang as an appendix to properly explain the examples 1305 used within the document. 1307 Replaced normative term 'SHALL' with 'MUST' to be consistent within 1308 this document. 1310 Clarified behavior for non-configuration data nodes. 1312 Clarified various sections based on WGLC comments on mailing list. 1314 Removed some unused terms. 1316 Reversed the order of the change log sections so the most recent 1317 changes are shown first. 1319 B.9. 04-05 1321 Updated I-D and YANG module boiler-plate. 1323 Removed redundant 'with-defaults' YANG feature. 1325 Changed definition of 'explicit' mode to match the YANG definition 1327 Removed XSD because the YANG is normative and the XSD is 1328 unconstrained, and does not properly extend the 3 affected NETCONF 1329 operations. 1331 Made the YANG module a normative section instead of non-normative 1332 appendix. 1334 Changed YANG from an informative to a normative reference, 1336 Changed 4741bis from an informative to a normative reference because 1337 the YANG module imports the ietf-netconf module in order to augment 1338 some operations. 1340 Updated capability requirements to include YANG module capability 1341 parameters. 1343 Added a description statement to the with-defaults leaf definition. 1345 Update open issues section; ready to close all open issues. 1347 B.10. 03-04 1349 Clarifications 1351 Added non-netconf interfaces to the definition of explicitly set 1352 default data 1354 B.11. 02-03 1356 Clarifications 1358 YAM added 1360 Use the same URN for the capability and the XML namespace to 1361 accommodate YANG, and avoid two separate URN/URIs being advertised in 1362 the HELLO message, for such a small function. 1364 B.12. 01-02 1366 report-all made mandatory 1368 Placeholder for YAM added, XSD will be removed when 4741 provides the 1369 NETCONF YAM 1371 with-defaults is valid for state data as well (if state data has a 1372 defined default which might not be so frequent). The definition of 1373 explicit was modified for state data. 1375 B.13. 00-01 1377 Changed value set of with-default capability and element 1379 Added version to URI 1381 B.14. -00 1383 Created from draft-bierman-netconf-with-defaults-01.txt 1385 It was decided by the NETCONF mailing list, that with-defaults should 1386 be a sub-element of each affected operation. While this violates the 1387 XSD of RFC4741 this is acceptable and follows the ideas behind 1388 NETCONF and YANG. 1390 Hopefully it will be clarified in the 4741bis RFC whether such 1391 extensions are allowed. 1393 Authors' Addresses 1395 Andy Bierman 1396 Brocade 1398 Email: andy.bierman@brocade.com 1400 Balazs Lengyel 1401 Ericsson 1402 Budapest, 1403 Hungary 1405 Email: balazs.lengyel@ericsson.com