idnits 2.17.1 draft-ietf-netconf-with-defaults-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 (August 05, 2009) is 5378 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 (ref. 'NETCONF') (Obsoleted by RFC 6241) == Outdated reference: A later version (-13) exists of draft-ietf-netmod-yang-07 Summary: 2 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 Netconf Central 4 Intended status: Standards Track B. Lengyel 5 Expires: February 6, 2010 Ericsson 6 August 05, 2009 8 With-defaults capability for NETCONF 9 draft-ietf-netconf-with-defaults-03 11 Status of this Memo 13 This Internet-Draft is submitted to IETF in full conformance with the 14 provisions of BCP 78 and BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on February 6, 2010. 34 Copyright Notice 36 Copyright (c) 2009 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents in effect on the date of 41 publication of this document (http://trustee.ietf.org/license-info). 42 Please review these documents carefully, as they describe your rights 43 and restrictions with respect to this document. 45 Abstract 47 The NETCONF protocol defines ways to read configuration data from a 48 NETCONF server. Part of this data is not set by the NETCONF client, 49 but rather a default value is used. In many situations the NETCONF 50 client has a priori knowledge about default data, so the NETCONF 51 server does not need to send it to the client. In other situations 52 the NETCONF manger will need this data as part of the NETCONF messages. This document defines a capability-based extension 54 to the NETCONF protocol that allows the NETCONF client to control 55 whether default values are part of NETCONF messages. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1.1. Requirements Notation . . . . . . . . . . . . . . . . 3 62 1.1.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . 4 63 1.2. Current handling of default data . . . . . . . . . . . . . 4 64 2. With-defaults Capability . . . . . . . . . . . . . . . . . . . 4 65 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 5 67 2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 5 68 2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 5 69 2.5. Modifications to Existing Operations . . . . . . . . . . . 6 70 3. Interactions with Other Capabilities . . . . . . . . . . . . . 7 71 4. Data Model XSD . . . . . . . . . . . . . . . . . . . . . . . . 7 72 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 73 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 74 7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 9 75 7.1. Other default handling modes in the real world? . . . . . 9 76 8. Appendix A - YANG Module for with-defaults (non-normative) . 9 77 9. Appendix B - Change Log . . . . . . . . . . . . . . . . . . 12 78 9.1. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 12 79 9.2. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 12 80 9.3. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 12 81 9.4. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 82 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 83 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 84 11.1. Normative References . . . . . . . . . . . . . . . . . . . 13 85 11.2. Informative References . . . . . . . . . . . . . . . . . . 13 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14 88 1. Introduction 90 The NETCONF protocol defines ways to read configuration data from a 91 NETCONF server. Part of this data is not set by the NETCONF client, 92 but rather a default value is used. In many situations the NETCONF 93 client has a priori knowledge about default data, so the NETCONF 94 server does not need to send it to the client. A priori knowledge 95 can be e.g., a document formally describing the data models supported 96 by the NETCONF server. 98 A networking device may have a large number of default values. Often 99 the default values are not interesting or specifically defined with a 100 "reasonable" value, so that the management user does not have to 101 handle them. For these reasons it is quite common for networking 102 devices to suppress the output of parameters having the default 103 value. 105 However there are use-cases when a NETCONF client will need the 106 default data from the node: 108 o The management application often needs a single, definitive and 109 complete set of configuration values that determine how the a 110 networking device works. 111 o Documentation about default values can be unreliable or 112 unavailable. 113 o Some management applications might not have the capabilities to 114 correctly parse and interpret formal data models. 115 o Human users might want to understand the received data without 116 consultation of the documentation. 118 In all theses cases the NETCONF client will need default data as part 119 of the NETCONF messages. 121 This document defines a capability-based extension to the NETCONF 122 protocol that allows the NETCONF client to control whether default 123 data is part of NETCONF messages. 125 1.1. Terminology 127 1.1.1. Requirements Notation 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [RFC2119]. 133 1.1.2. NETCONF Terms 135 o Default data: Data that is set or used by the NETCONF server 136 whenever the NETCONF client does not provide a specific value for 137 the relevant data item. Default values SHOULD be specified in 138 documents describing the data models supported by the NETCONF 139 server. 141 o Explicitly set default data: Data that is explicitly set by the 142 NETCONF client to its default value. Some servers MAY treat 143 explicitly set default data as simple default data, as they may 144 not be able to differentiate between them. 146 In addition the following terms are defined in RFC 4741 and are not 147 redefined here: 148 o application 149 o client 150 o operation 151 o RPC 152 o RPC request 153 o RPC response 154 o server 156 1.2. Current handling of default data 158 [NETCONF] does not define whether default data is part of the 159 datastore/data model, or if it is meta-data that influences the 160 behavior of the NETCONF server, but is not actually part of the 161 datastore. This document is intended to support either type of 162 implementation, without deciding which approach is better. 164 As a consequence of this issue, NETCONF servers that do not implement 165 the :with-defaults capability may or may not return default data in 166 NETCONF messages. 168 Different NETCONF servers report default data in different ways. 169 This document specifies the following three basic modes: 171 o report-all: All default data is always reported. 172 o trim: Values are not reported if they match the default. 173 o explicit: Report values if they are explicitly set. For state 174 data this has the same effect as report-all 176 2. With-defaults Capability 177 2.1. Overview 179 The :with-defaults capability indicates that the NETCONF server makes 180 it possible for the NETCONF client to control whether default data is 181 part of NETCONF messages. The capability affects both 182 configuration and state data (while acknowledging that the usage of 183 default values for state data is less prevalent). Sending of default 184 data is controlled for each individual operation separately. 186 A NETCONF servers implementing the :with-defaults capability MUST 187 indicate its basic behavior, whether it sends default data in the 188 absence of any specific request from the NETCONF client; and MUST 189 support the 'report-all' handling mode and MAY support other modes. 191 2.2. Dependencies 193 None 195 2.3. Capability Identifier 197 urn:ietf:params:netconf:capability:with-defaults:1.0 199 The identifier MUST have a parameter: "basic". This indicates how 200 the server reports default data in messages, in the case 201 the client does not specify the required behavior in the 202 request. The allowed values of this parameter are report-all, trim, 203 explicit as listed in Section 1.2. 205 The identifier MAY have another parameter: "also-supported". This 206 indicates what other default handling modes does the server support. 207 The value of the parameter is a comma separated list of one or two 208 modes that are supported beside the mode indicated in the basic 209 parameter Possible modes are taken from the list in Section 1.2. 211 Example: 213 urn:ietf:params:netconf:capability:with-defaults:1.0?basic=report-all 215 urn:ietf:params:netconf:capability:with-defaults:1.0?basic=report- 216 all&also-supported=trim,explicit 218 2.4. New Operations 220 None 222 2.5. Modifications to Existing Operations 224 A new XML child element is added to the method-name 225 element. This is the element that indicates the type of the 226 operation e.g. , or . If the element is present, it controls the reporting of default 228 data. The server MUST return default data in the NETCONF 229 messages according to the value of the element. 231 Allowed values of the with-defaults element are taken from the list 232 in Section 1.2. The allowed values are restricted to the values that 233 the device indicates support for in the with-defaults capability in 234 the basic and also-supported parameters. 236 If the element is not present, the server follows its 237 basic behavior as indicated by the capability identifier's parameter 238 see Section 2.3. 240 Affected operations: 241 o 242 o 243 o 245 is only affected if the target of the operation is a 246 URL. If the target is a NETCONF datastore (running, candidate or 247 startup) the capability has no effect. 249 Other operations that return configuration data SHOULD also handle 250 default data according to the rules set in this document, and 251 explicitly state this in their documentation. If this is not 252 specified in the document defining the respective operation, the 253 default handling rules described herein do not affect these 254 operations. 256 The following example shows a operation which is using 257 the 'with-defaults' element. The client is retrieving the 258 'interfaces' object, defined in the example.com data model. (In this 259 simple example, the 'name' field is defined as the key, and the 'mtu' 260 field is the only other data in the element). The 261 default value of mtu is '1500'. The basic default handling for the 262 server is "trim". As the 'with-defaults' element has the value 263 'report-all', the mtu is returned not just for eth0 but also for 264 eth1. 266 268 269 270 271 272 273 274 275 277 report-all 278 279 280 282 284 285 286 287 eth0 288 8192 289 290 291 eth1 292 1500 293 294 295 296 298 Figure 1 300 3. Interactions with Other Capabilities 302 None 304 4. Data Model XSD 306 This section contains an XML Schema Definition 307 [W3C.REC-xmlschema-2-20041028] which defines the XML syntax 308 associated for the with-defaults XML element. 310 311 317 318 319 Schema defining the with-defaults element. 321 Organization: "IETF NETCONF Working Group" 322 Contact Info: balazs.lengyel@ericsson.com 323 324 326 327 328 329 330 331 332 333 334 336 338 5. IANA Considerations 340 This document registers one capability identifier URN from the 341 "Network Configuration Protocol (NETCONF) Capability URNs" registry, 342 and registers the same URN for the NETCONF XML namespace in the "IETF 343 XML registry" [RFC3688]. Note that the capability URN is compliant 344 to [NETCONF] section 10.3. 346 +---------------+---------------------------------------------------+ 347 | Index | Capability Identifier | 348 +---------------+---------------------------------------------------+ 349 | :with-default | urn:ietf:params:netconf:capability:with-defaults: | 350 | s | 1.0 | 351 +---------------+---------------------------------------------------+ 353 6. Security Considerations 355 This document defines a minor extension to existing NETCONF protocol 356 operations. it does not introduce any new or increased security risks 357 into the management system. 359 The 'with-defaults' capability provides client controls over the 360 retrieval of particular types of XML data from a configuration 361 database. They only suppress data that can already be retrieved with 362 the standard protocol operations, and do not add any data to the 363 configuration database. 365 7. Open Issues 367 7.1. Other default handling modes in the real world? 369 Are there any other basic default handling modes out there we need to 370 include? 372 8. Appendix A - YANG Module for with-defaults (non-normative) 374 The following YANG module defines the addition of the with-defaults 375 element to the , and operations. The 376 YANG language is defined in [I-D.ietf-netmod-yang]. The above 377 operations are defined in YANG in [I-D.ietf-netconf-4741bis]. 379 module ietf-netconf-with-defaults { 381 namespace "urn:ietf:params:netconf:capability:with-defaults:1.0"; 383 prefix nwd; 385 // for the uri data type 386 import ietf-netconf { prefix nc; } 388 description 389 "This module defines a capability-based extension to the 390 NETCONF protocol that allows the NETCONF client to control 391 whether default values are part of NETCONF 392 messages. 394 Copyright (c) 2009 IETF Trust and the persons identified as 395 the document authors. All rights reserved. 397 Redistribution and use in source and binary forms, with or 398 without modification, are permitted provided that the 399 following conditions are met: 401 - Redistributions of source code must retain the above 402 copyright notice, this list of conditions and the 403 following disclaimer. 405 - Redistributions in binary form must reproduce the above 406 copyright notice, this list of conditions and the 407 following disclaimer in the documentation and/or other 408 materials provided with the distribution. 410 - Neither the name of Internet Society, IETF or IETF 411 Trust, nor the names of specific contributors, may be 412 used to endorse or promote products derived from this 413 software without specific prior written permission. 415 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 416 CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED 417 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 418 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 419 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 420 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 421 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 422 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 423 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 424 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 425 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 426 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 427 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 428 POSSIBILITY OF SUCH DAMAGE. 430 This version of this YANG module is part of RFC XXXX; see 431 the RFC itself for full legal notices."; 433 // RFC Ed.: replace XXXX with actual RFC number and remove this note 435 reference "RFC XXXX"; 437 // RFC Ed.: replace XXXX with actual RFC number and remove this note 439 // reference "draft-ietf-netconf-with-defaults-03.txt"; 441 // RFC Ed.: remove the reference statement above and this note. 443 contact 444 "Send comments to the NETCONF WG mailing list. 445 "; 447 revision 2009-07-01 { 448 description 449 "Initial version"; 450 } 452 // with-defaults capability defined as a feature 453 feature with-defaults { 454 description 455 "NETCONF :with-defaults capability; 456 If the agent advertises the :with-defaults 457 capability for a session, then this feature MUST 458 also be enabled for that session. Otherwise, 459 this feature MUST NOT be enabled."; 460 // RFC Ed.: replace XXXX with actual RFC number and 461 // remove this note 462 reference "RFC XXXX"; 463 } 465 typedef with-defaults-mode-type { 466 description 467 "Possible modes to report default data in 468 rpc-reply messages."; 469 type enumeration { 470 enum report-all { 471 description 472 "All default data is always reported."; 473 } 474 enum trim { 475 description 476 "Values are not reported if they match the default."; 477 } 478 enum explicit { 479 description 480 "Report values if they are explicitly set. 481 For state data this has the same effect 482 as report-all"; 483 } 484 } 485 } 487 // extending the get-config operation 488 augment /nc:get-config/nc:input { 489 leaf with-defaults { 490 type with-defaults-mode-type; 491 } 492 } 494 // extending the get operation 495 augment /nc:get/nc:input { 496 leaf with-defaults { 497 type with-defaults-mode-type; 498 } 499 } 501 // extending the copy-congig operation 502 augment /nc:copy-config/nc:input { 503 leaf with-defaults { 504 type with-defaults-mode-type; 505 } 506 } 508 } 510 9. Appendix B - Change Log 512 9.1. 02-03 514 Clarifications 516 YAM added 518 Use the same URN for the capability and the XML namespace to 519 accommodate YANG, and avoid two separate URN/URIs being advertised in 520 the HELLO message, for such a small function. 522 9.2. 01-02 524 report-all made mandatory 526 Placeholder for YAM added, XSD will be removed when 4741 provides the 527 NETCONF YAM 529 with-defaults is valid for state data as well (if state data has a 530 defined default which might not be so frequent). The definition of 531 explicit was modified for state data. 533 9.3. 00-01 535 Changed value set of with-default capability and element 537 Added version to URI 539 9.4. -00 541 Created from draft-bierman-netconf-with-defaults-01.txt 543 It was decided by the NETCONF mailing list, that with-defaults should 544 be a sub-element of each affected operation. While this violates the 545 XSD of RFC4741 this is acceptable and follows the ideas behind 546 NETCONF and YANG. 548 Hopefully it will be clarified in the 4741bis RFC whether such 549 extensions are allowed. 551 10. Acknowledgements 553 Thanks to Martin Bjorklund, Sharon Chisholm, Phil Shafer, Juergen 554 Schoenwaelder, Washam Fan and many other members of the NETCONF WG 555 for providing important input to this document. 557 11. References 559 11.1. Normative References 561 [W3C.REC-xmlschema-2-20041028] 562 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 563 Second Edition", World Wide Web Consortium 564 Recommendation REC-xmlschema-2-20041028, October 2004, 565 . 567 [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 568 December 2006. 570 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 571 Requirement Levels", BCP 14, RFC 2119, March 1997. 573 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 574 January 2004. 576 11.2. Informative References 578 [I-D.ietf-netmod-yang] 579 Bjorklund, M., "YANG - A data modeling language for 580 NETCONF", draft-ietf-netmod-yang-07 (work in progress), 581 July 2009. 583 [I-D.ietf-netconf-4741bis] 584 Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 586 Bierman, "NETCONF Configuration Protocol", 587 draft-ietf-netconf-4741bis-01 (work in progress), 588 July 2009. 590 Authors' Addresses 592 Andy Bierman 593 Netconf Central 594 Simi Valley, CA 595 USA 597 Email: andy@netconfcentral.com 599 Balazs Lengyel 600 Ericsson 601 Budapest, 602 Hungary 604 Email: balazs.lengyel@ericsson.com