idnits 2.17.1 draft-ietf-netconf-with-defaults-00.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? -- It seems you're using the 'non-IETF stream' Licence Notice instead 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 (February 17, 2009) is 5547 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) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 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: August 21, 2009 Ericsson 6 February 17, 2009 8 With-defaults capability for NETCONF 9 draft-ietf-netconf-with-defaults-00 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 August 21, 2009. 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 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. 46 Abstract 48 The NETCONF protocol defines ways to read configuration data from a 49 NETCONF agent. Part of this data is not set by the NETCONF manager, 50 but rather a default value is used. In many situations the NETCONF 51 manager has a priori knowledge about default data, so the NETCONF 52 agent does not need to send it to the manager. In other situations 53 the NETCONF manger will need this data as part of the NETCONF messages. This document defines a capability-based extension 55 to the NETCONF protocol that allows the NETCONF manager to control 56 whether default values are part of NETCONF messages. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1.1. Requirements Notation . . . . . . . . . . . . . . . . 3 63 1.1.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . 3 64 2. With-defaults Capability . . . . . . . . . . . . . . . . . . . 4 65 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 2.1.1. Basic handling of default data . . . . . . . . . . . . 4 67 2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 5 68 2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 5 69 2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 5 70 2.5. Modifications to Existing Operations . . . . . . . . . . . 5 71 3. Interactions with Other Capabilities . . . . . . . . . . . . . 7 72 4. Data Model XSD . . . . . . . . . . . . . . . . . . . . . . . . 7 73 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 74 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 75 7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 10 76 7.1. Other default handling methods in the real world? . . . . 10 77 7.2. XSD needed? . . . . . . . . . . . . . . . . . . . . . . . 10 78 7.3. Use the NETCONF namespace? . . . . . . . . . . . . . . . . 10 79 8. Appendix A - Change Log . . . . . . . . . . . . . . . . . . 11 80 8.1. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 81 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 82 10. Normative References . . . . . . . . . . . . . . . . . . . . . 13 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14 85 1. Introduction 87 The NETCONF protocol defines ways to read configuration data from a 88 NETCONF agent. Part of this data is not set by the NETCONF manager, 89 but rather a default value is used. In many situations the NETCONF 90 manager has a priori knowledge about default data, so the NETCONF 91 agent does not need to send it to the manager. A priori knowledge 92 can be e.g. a document formally describing the data models supported 93 by the NETCONF agent. 95 A networking device may have a large number of default values. Often 96 the default values are not interesting or specifically defined with a 97 "reasonable" value, so that the management user does not have to 98 handle them. For these reasons it is quite common for networking 99 devices to suppress the output of parameters having the default 100 value. 102 However there are use-cases when a NETCONF manager will need the 103 default data from the node: 105 o Documentation about default values can be unreliable or 106 unavailable. 107 o Some management applications might not have the capabilities to 108 correctly parse and interpret formal data models. 109 o Human users might want to understand the received data without 110 consultation of the documentation. 112 In all theses cases the NETCONF manager will need default data as 113 part of the NETCONF messages. 115 This document defines a capability-based extension to the NETCONF 116 protocol that allows the NETCONF manager to control whether default 117 data is part of NETCONF messages. 119 1.1. Terminology 121 1.1.1. Requirements Notation 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 125 document are to be interpreted as described in [RFC2119]. 127 1.1.2. NETCONF Terms 129 o Default data: Data that is set or used by the NETCONF agent 130 whenever the NETCONF manager does not provide a specific value for 131 the relevant data item. Default values are often specified in 132 documents describing the data models supported by the NETCONF 133 agent. In the context of this document only configuration data is 134 considered, state data is excluded. 136 o Explicitly set default data: Data that is explicitly set by the 137 NETCONF manager to it's default value. Some agents MIGHT treat 138 explicitly set default data as simple default data, as they MIGHT 139 not be able to differentiate between them. 141 In addition the following terms are defined in RFC 4741 and are not 142 redefined here: 143 o agent 144 o application 145 o manager 146 o operation 147 o RPC 148 o RPC request 149 o RPC response 151 2. With-defaults Capability 153 2.1. Overview 155 The :with-defaults capability indicates that the NETCONF agent makes 156 it possible for the NETCONF manager to control whether default data 157 is part of NETCONF messages. The capability only affects 158 configuration data not state data. Sending of default data is 159 controlled for each individual operation separately. The NETCONF 160 agent MUST also indicate its basic behavior, whether it sends default 161 data in the absence of any specific request from the NETCONF manager. 163 2.1.1. Basic handling of default data 165 It is not defined in [RFC4741], whether default data is part of the 166 datastore/data model, or if it is meta data, that influences the 167 behavior of the NETCONF server, device but is not actually part of 168 the datastore. This document intentionally avoids deciding this 169 question. 171 As a consequence of this issue, NETCONF servers that do not implement 172 the :with-defaults capability may or may not return default data in 173 NETCONF messages. 175 Different NETCONF agents report default data in different ways. This 176 document specifies the following three basic methods: 178 o Report all: All default data is always reported. 179 o Trim: Values are not reported if they match the default. 180 o Explicit: Report values if they are explicitly set. 182 2.2. Dependencies 184 None 186 2.3. Capability Identifier 188 urn:ietf:params:netconf:capability:with-defaults 190 The identifier MUST have an additional parameter: "basic". This 191 indicates how the agent reports default data in messages, 192 in the case the manager does not specify the required behavior in the 193 request. The allowed values of this parameter are report-all, 194 trim, explicit as defined in Section 2.1.1. E.g.: 196 urn:ietf:params:netconf:capability:with-defaults?basic=report-all 198 2.4. New Operations 200 None 202 2.5. Modifications to Existing Operations 204 A new XML element is added to the 'method-name' 205 element. This is the element that indicates the type of the 206 operation e.g. , or . If the element is present, it controls the reporting of default 208 data. The agent MUST return default data in the NETCONF 209 messages according to the value of the element. 211 Allowed values of the with-defaults element are: 213 o false: default data SHOULD NOT be returned. 214 o true: all default data MUST be returned. 216 If the element is not present, the agent follows its 217 basic behavior as indicated by the capability identifier's parameter 218 see Section 2.3. 220 The 'with-defaults' element is defined in the namespace specified as 221 the 'targetNamespace' in Section 4. However, an agent MUST accept it 222 even if no namespace is used. 224 Affected operations: 226 o 227 o 228 o 230 Other operations that return configuration data SHOULD also handle 231 default data according to the rules set in this document, and 232 explicitly state this in their documentation. If this is not 233 specified in the document defining the respective operation, the 234 default handling rules described herein do not affect these 235 operations. 237 The following example shows a operation which is using the 238 'with-defaults' element. The manager is retrieving the 'interfaces' 239 object, defined in the example.com data model. (In this simple 240 example, the 'name' field is defined as the key, and the 'mtu' field 241 is the only other data in the element). The default 242 value of mtu is '1500'. The basic default handling for the agent is 243 "trim". As the 'with-defaults' element has the value 'true', the mtu 244 is returned not just for eth0 but also for eth1. 246 248 249 true 250 251 252 253 254 256 258 259 260 261 eth0 262 8192 263 264 265 eth1 266 1500 267 268 269 270 271 Figure 1 273 3. Interactions with Other Capabilities 275 None 277 4. Data Model XSD 279 This section contains an XML Schema Definition 280 [W3C.REC-xmlschema-2-20041028] which defines the XML syntax 281 associated for the with-defaults XML element. 283 284 290 291 292 Schema defining the with-defaults element. 294 Organization: "IETF NETCONF Working Group" 295 Contact Info: balazs.lengyel@ericsson.com 296 297 299 302 304 5. IANA Considerations 306 This document registers two URIs for the NETCONF XML namespace in the 307 IETF XML registry [RFC3688]. Note that the capability URN is 308 compliant to [RFC4741] section 10.3. 310 +---------------+---------------------------------------------------+ 311 | Index | Capability Identifier | 312 +---------------+---------------------------------------------------+ 313 | :with-default | urn:ietf:params:netconf:capability:with-defaults: | 314 | s | 1.0 | 315 +---------------+---------------------------------------------------+ 317 URI: urn:ietf:params:xml:ns:netconf:with-defaults:1.0 319 Registrant Contact: The IESG. 321 XML: N/A, the requested URI is an XML namespace. 323 6. Security Considerations 325 This document defines a minor extension to existing NETCONF protocol 326 operations. it does not introduce any new or increased security risks 327 into the management system. 329 The 'with-defaults' capability provides manager controls over the 330 retrieval of particular types of XML data from a configuration 331 database. They only suppress data that can already be retrieved with 332 the standard protocol operations, and do not add any data to the 333 configuration database. 335 7. Open Issues 337 7.1. Other default handling methods in the real world? 339 Are there any other basic default handling methods out there we need 340 to include? 342 7.2. XSD needed? 344 Is the XSD needed? Does it add any value, any clarity to the 345 document? 347 7.3. Use the NETCONF namespace? 349 Would it be possible to put the with-defaults element into the 350 NETCONF namespace? Is the current statement: "However, an agent MUST 351 accept it even if no namespace is used." acceptable? 353 8. Appendix A - Change Log 355 8.1. -00 357 Created from draft-bierman-netconf-with-defaults-01.txt 359 It was decided by the NETCONF mailing list, that with-defaults should 360 be a sub-element of each affected operation. While this violates the 361 XSD of RFC4741 this is acceptable and follows the ideas behind 362 NETCONF and YANG. 364 Hopefully it will be clarified in the 4741bis RFC whether such 365 extensions are allowed. 367 9. Acknowledgements 369 Thanks to Martin Bjorklund, Sharon Chisholm, Phil Shafer, Juergen 370 Schoenwaelder and many other members of the NETCONF WG for providing 371 important input to this document. 373 10. Normative References 375 [W3C.REC-xmlschema-2-20041028] 376 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 377 Second Edition", World Wide Web Consortium 378 Recommendation REC-xmlschema-2-20041028, October 2004, 379 . 381 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 382 December 2006. 384 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 385 Requirement Levels", BCP 14, RFC 2119, March 1997. 387 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 388 January 2004. 390 Authors' Addresses 392 Andy Bierman 393 Netconf Central 394 Simi Valley, CA 395 USA 397 Email: andy@netconfcentral.com 399 Balazs Lengyel 400 Ericsson 401 Budapest, 402 Hungary 404 Email: balazs.lengyel@ericsson.com