idnits 2.17.1 draft-ietf-netconf-with-defaults-04.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 exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: o Data model schema is a document or set of documents describing the data models supported by the NETCONF server. o Default data: Data specified in the data model schema as default, that is set or used by the device whenever the NETCONF client or other external management application/user does not provide a specific value for the relevant data item. External management application/user can reach the device e.g. via the NETCONF, CLI, SNMP, GUI. Default data MAY or MAY NOT be stored as part of a configuration datastore. -- The document date (October 22, 2009) is 5299 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-08 == Outdated reference: A later version (-10) exists of draft-ietf-netconf-4741bis-01 Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). 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: April 25, 2010 Ericsson 6 October 22, 2009 8 With-defaults capability for NETCONF 9 draft-ietf-netconf-with-defaults-04 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 April 25, 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 client 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 or 56 output to the target URL. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.2. Current handling of default data . . . . . . . . . . . . . 4 63 2. With-defaults Capability . . . . . . . . . . . . . . . . . . . 5 64 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 5 66 2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 5 67 2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 6 68 2.5. Modifications to Existing Operations . . . . . . . . . . . 6 69 3. Interactions with Other Capabilities . . . . . . . . . . . . . 7 70 4. Data Model XSD . . . . . . . . . . . . . . . . . . . . . . . . 8 71 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 73 7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 8. Appendix A - YANG Module for with-defaults (non-normative) . 9 75 9. Appendix B - Change Log . . . . . . . . . . . . . . . . . . 12 76 9.1. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 77 9.2. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 78 9.3. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 79 9.4. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 80 9.5. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 81 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 82 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 83 11.1. Normative References . . . . . . . . . . . . . . . . . . . 14 84 11.2. Informative References . . . . . . . . . . . . . . . . . . 14 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14 87 1. Introduction 89 The NETCONF protocol defines ways to read configuration data from a 90 NETCONF server. Part of this data is not set by the NETCONF client, 91 but rather a default value is used. In many situations the NETCONF 92 client has a priori knowledge about default data, so the NETCONF 93 server does not need to send it to the client. A priori knowledge 94 can be e.g., a document formally describing the data models supported 95 by the NETCONF server. 97 A networking device may have a large number of default values. Often 98 the default values are not interesting or specifically defined with a 99 "reasonable" value, so that the management user does not have to 100 handle them. For these reasons it is quite common for networking 101 devices to suppress the output of parameters having the default 102 value. 104 However there are use-cases when a NETCONF client will need the 105 default data from the node: 107 o The management application often needs a single, definitive and 108 complete set of configuration values that determine how the a 109 networking device works. 110 o Documentation about default values can be unreliable or 111 unavailable. 112 o Some management applications might not have the capabilities to 113 correctly parse and interpret formal data models. 114 o Human users might want to understand the received data without 115 consultation of the documentation. 117 In all these cases the NETCONF client will need default data as part 118 of the NETCONF messages. 120 This document defines a capability-based extension to the NETCONF 121 protocol that allows the NETCONF client to control whether default 122 data is part of NETCONF messages. 124 1.1. Terminology 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 128 document are to be interpreted as described in [RFC2119]. 130 o Data model schema is a document or set of documents describing the 131 data models supported by the NETCONF server. 132 o Default data: Data specified in the data model schema as default, 133 that is set or used by the device whenever the NETCONF client or 134 other external management application/user does not provide a 135 specific value for the relevant data item. External management 136 application/user can reach the device e.g. via the NETCONF, CLI, 137 SNMP, GUI. Default data MAY or MAY NOT be stored as part of a 138 configuration datastore. 140 o Explicitly set default data: Is default data that is set by a 141 NETCONF client or other external management application/user by 142 the way of an actual management operation to the value specified 143 as its default in the data model schema. Some servers MAY treat 144 explicitly set default data as simple default data, as they may 145 not be able to differentiate between them. 146 Data, that is set to a value other then its default value, is not 147 default data, so its handling is outside the scope of this 148 document. 150 In addition the following terms are defined in RFC 4741 and are not 151 redefined here: 152 o application 153 o client 154 o operation 155 o RPC 156 o RPC request 157 o RPC response 158 o server 160 1.2. Current handling of default data 162 [NETCONF] does not define whether default data is part of the 163 datastore/data model, or if it is meta-data that influences the 164 behavior of the NETCONF server, but is not actually part of the 165 datastore. This document is intended to support either type of 166 implementation, without deciding which approach is better. 168 As a consequence of this issue, NETCONF servers that do not implement 169 the :with-defaults capability may or may not return default data. 171 Different NETCONF servers report default data in different ways. 172 This document specifies the following three basic modes: 174 o report-all: All default data is always reported. 175 o trim: Values are not reported if they match the default. 176 o explicit: Default data is not reported except explicitly set 177 default data. For state data this has the same effect as report- 178 all. 180 2. With-defaults Capability 182 2.1. Overview 184 The :with-defaults capability indicates that the NETCONF server makes 185 it possible for the NETCONF client to control whether default data is 186 part of NETCONF messages. The capability affects both 187 configuration and state data (while acknowledging that the usage of 188 default values for state data is less prevalent). Sending of default 189 data is controlled for each individual operation separately. 191 A NETCONF server implementing the :with-defaults capability MUST 192 indicate its basic behavior, whether it sends default data in the 193 absence of any specific request from the NETCONF client; and MUST 194 support the 'report-all' handling mode and MAY support other modes. 196 A server indicating 'explicit' either in the basic or the also- 197 supported parameter MUST be able to differentiate between normal 198 default data and explicitly set default data. 200 2.2. Dependencies 202 None 204 2.3. Capability Identifier 206 urn:ietf:params:netconf:capability:with-defaults:1.0 208 The identifier MUST have a parameter: "basic". This indicates how 209 the server reports default data in messages, in the case 210 the client does not specify the required behavior in the 211 request. The allowed values of this parameter are report-all, trim, 212 explicit as listed in Section 1.2. 214 The identifier MAY have another parameter: "also-supported". This 215 parameter indicates which additional default handling modes the 216 server supports. The value of the parameter is a comma separated 217 list of one or two modes that are supported beside the mode indicated 218 in the basic parameter. Possible modes are taken from the list in 219 Section 1.2. 221 Example: 223 urn:ietf:params:netconf:capability:with-defaults:1.0?basic=report-all 225 urn:ietf:params:netconf:capability:with-defaults:1.0?basic=report- 226 all&also-supported=trim,explicit 228 2.4. New Operations 230 None 232 2.5. Modifications to Existing Operations 234 A new XML child element is added to the method-name 235 element. This is the element that indicates the type of the 236 operation e.g. , or . If the element is present, it controls the reporting of default 238 data. The server MUST return default data in the NETCONF 239 messages according to the value of the element. 241 Allowed values of the with-defaults element are taken from the list 242 in Section 1.2. The allowed values are restricted to the values that 243 the device indicates support for in the with-defaults capability in 244 the basic and also-supported parameters. 245 If a not allowed value is used the NETCONF server SHALL return an 246 with an element. The SHALL be 247 'operation-not-supported', the SHALL be "with- 248 defaults-mode-not-supported', and SHALL contain the 249 requested mode. 251 If the element is not present, the server follows its 252 basic behavior as indicated by the capability identifier's parameter 253 see Section 2.3. 255 Affected operations: 256 o 257 o 258 o 260 is only affected if the target of the operation is a 261 URL. If the target is a NETCONF datastore (running, candidate or 262 startup) the capability has no effect; the with-defaults parameter, 263 if present, SHALL be silently ignored. 265 Other operations that return configuration data SHOULD also handle 266 default data according to the rules set in this document, and 267 explicitly state this in their documentation. If this is not 268 specified in the document defining the respective operation, the 269 default handling rules described herein do not affect these 270 operations. 272 The following example shows a operation which is using 273 the 'with-defaults' element. The client is retrieving the 274 'interfaces' object, defined in the example.com data model. (In this 275 simple example, the 'name' field is defined as the key, and the 'mtu' 276 field is the only other data in the element). The 277 default value of mtu is '1500'. The basic default handling for the 278 server is "trim". As the 'with-defaults' element has the value 279 'report-all', the mtu is returned not just for eth0 but also for 280 eth1. 282 284 285 286 287 288 289 290 291 293 report-all 294 295 296 298 300 301 302 303 eth0 304 8192 305 306 307 eth1 308 1500 309 310 311 312 314 Figure 1 316 3. Interactions with Other Capabilities 318 None 320 4. Data Model XSD 322 This section contains an XML Schema Definition 323 [W3C.REC-xmlschema-2-20041028] which defines the XML syntax 324 associated for the with-defaults XML element. 326 -- RFC Ed.: Insert license information for code as appropriate 328 330 331 337 338 339 Schema defining the with-defaults element. 341 Organization: "IETF NETCONF Working Group" 342 Contact Info: balazs.lengyel@ericsson.com 343 344 346 347 348 349 350 351 352 353 354 356 358 360 5. IANA Considerations 362 This document registers one capability identifier URN from the 363 "Network Configuration Protocol [NETCONF] Capability URNs" registry, 364 and registers the same URN for the NETCONF XML namespace in the "IETF 365 XML registry" [RFC3688]. Note that the capability URN is compliant 366 to [NETCONF] section 10.3. 368 +---------------+---------------------------------------------------+ 369 | Index | Capability Identifier | 370 +---------------+---------------------------------------------------+ 371 | :with-default | urn:ietf:params:netconf:capability:with-defaults: | 372 | s | 1.0 | 373 +---------------+---------------------------------------------------+ 375 6. Security Considerations 377 This document defines a minor extension to existing NETCONF protocol 378 operations. It does not introduce any new or increased security 379 risks into the management system. 381 The 'with-defaults' capability gives client control over the 382 retrieval of particular types of XML data from a configuration 383 database. They only suppress data that can already be retrieved with 384 the standard protocol operations, and do not add any data to the 385 configuration database. 387 7. Open Issues 389 Is the definition of defaults OK? 391 Shall we wait for YANG and 4741bis and make the YANG normative? 393 Shall we make with-defaults mandatory? 395 8. Appendix A - YANG Module for with-defaults (non-normative) 397 The following YANG module defines the addition of the with-defaults 398 element to the , and operations. The 399 YANG language is defined in [I-D.ietf-netmod-yang]. The above 400 operations are defined in YANG in [I-D.ietf-netconf-4741bis]. 402 -- RFC Ed.: Insert license information for code as appropriate 404 406 module ietf-netconf-with-defaults { 408 namespace "urn:ietf:params:netconf:capability:with-defaults:1.0"; 410 prefix nwd; 412 // for the uri data type 413 import ietf-netconf { prefix nc; } 415 description 416 "This module defines a capability-based extension to the 417 NETCONF protocol that allows the NETCONF client to control 418 whether default values are part of NETCONF 419 messages or output to the target URL. 421 Copyright (c) 2009 IETF Trust and the persons identified as 422 the document authors. All rights reserved. 424 Redistribution and use in source and binary forms, with or 425 without modification, are permitted provided that the 426 following conditions are met: 428 - Redistributions of source code must retain the above 429 copyright notice, this list of conditions and the 430 following disclaimer. 432 - Redistributions in binary form must reproduce the above 433 copyright notice, this list of conditions and the 434 following disclaimer in the documentation and/or other 435 materials provided with the distribution. 437 - Neither the name of Internet Society, IETF or IETF 438 Trust, nor the names of specific contributors, may be 439 used to endorse or promote products derived from this 440 software without specific prior written permission. 442 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 443 CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED 444 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 445 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 446 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 447 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 448 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 449 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 450 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 451 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 452 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 453 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 454 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 455 POSSIBILITY OF SUCH DAMAGE. 457 This version of this YANG module is part of RFC XXXX; see 458 the RFC itself for full legal notices."; 460 // RFC Ed.: replace XXXX with actual RFC number and remove this note 462 reference "RFC XXXX"; 464 // RFC Ed.: replace XXXX with actual RFC number and remove this note 466 // reference "draft-ietf-netconf-with-defaults-03.txt"; 468 // RFC Ed.: remove the reference statement above and this note. 470 contact 471 "Send comments to the NETCONF WG mailing list. 472 "; 474 revision 2009-07-01 { 475 description 476 "Initial version"; 477 } 479 // with-defaults capability defined as a feature 480 feature with-defaults { 481 description 482 "NETCONF :with-defaults capability; 483 If the server advertises the :with-defaults 484 capability for a session, then this feature MUST 485 also be enabled for that session. Otherwise, 486 this feature MUST NOT be enabled."; 487 // RFC Ed.: replace XXXX with actual RFC number and 488 // remove this note 489 reference "RFC XXXX"; 490 } 492 typedef with-defaults-mode { 493 description 494 "Possible modes to report default data in 495 rpc-reply messages."; 496 type enumeration { 497 enum report-all { 498 description 499 "All default data is always reported."; 500 } 501 enum trim { 502 description 503 "Values are not reported if they match the default."; 504 } 505 enum explicit { 506 description 507 "Report values if they are explicitly set. 508 For state data this has the same effect 509 as report-all"; 510 } 511 } 512 } 514 // extending the get-config operation 515 augment /nc:get-config/nc:input { 516 leaf with-defaults { 517 type with-defaults-mode; 518 } 519 } 521 // extending the get operation 522 augment /nc:get/nc:input { 523 leaf with-defaults { 524 type with-defaults-mode; 525 } 526 } 528 // extending the copy-congig operation 529 augment /nc:copy-config/nc:input { 530 leaf with-defaults { 531 type with-defaults-mode; 532 } 533 } 535 } 537 539 9. Appendix B - Change Log 541 9.1. -00 543 Created from draft-bierman-netconf-with-defaults-01.txt 545 It was decided by the NETCONF mailing list, that with-defaults should 546 be a sub-element of each affected operation. While this violates the 547 XSD of RFC4741 this is acceptable and follows the ideas behind 548 NETCONF and YANG. 550 Hopefully it will be clarified in the 4741bis RFC whether such 551 extensions are allowed. 553 9.2. 00-01 555 Changed value set of with-default capability and element 557 Added version to URI 559 9.3. 01-02 561 report-all made mandatory 563 Placeholder for YAM added, XSD will be removed when 4741 provides the 564 NETCONF YAM 566 with-defaults is valid for state data as well (if state data has a 567 defined default which might not be so frequent). The definition of 568 explicit was modified for state data. 570 9.4. 02-03 572 Clarifications 574 YAM added 576 Use the same URN for the capability and the XML namespace to 577 accommodate YANG, and avoid two separate URN/URIs being advertised in 578 the HELLO message, for such a small function. 580 9.5. 03-04 582 Clarifications 584 Added non-netconf interfaces to the definition of explicitly set 585 default data 587 10. Acknowledgements 589 Thanks to Martin Bjorklund, Sharon Chisholm, Phil Shafer, Juergen 590 Schoenwaelder, Washam Fan and many other members of the NETCONF WG 591 for providing important input to this document. 593 11. References 595 11.1. Normative References 597 [W3C.REC-xmlschema-2-20041028] 598 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 599 Second Edition", World Wide Web Consortium 600 Recommendation REC-xmlschema-2-20041028, October 2004, 601 . 603 [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 604 December 2006. 606 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 607 Requirement Levels", BCP 14, RFC 2119, March 1997. 609 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 610 January 2004. 612 11.2. Informative References 614 [I-D.ietf-netmod-yang] 615 Bjorklund, M., "YANG - A data modeling language for 616 NETCONF", draft-ietf-netmod-yang-08 (work in progress), 617 October 2009. 619 [I-D.ietf-netconf-4741bis] 620 Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 621 Bierman, "NETCONF Configuration Protocol", 622 draft-ietf-netconf-4741bis-01 (work in progress), 623 July 2009. 625 Authors' Addresses 627 Andy Bierman 628 Netconf Central 629 Simi Valley, CA 630 USA 632 Email: andy@netconfcentral.com 633 Balazs Lengyel 634 Ericsson 635 Budapest, 636 Hungary 638 Email: balazs.lengyel@ericsson.com