idnits 2.17.1 draft-bierman-netconf-with-defaults-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 391. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 402. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 409. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 415. 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 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 22, 2008) is 5655 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 (==), 7 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, 2009 Ericsson 6 October 22, 2008 8 With-defaults capability for NETCONF 9 draft-bierman-netconf-with-defaults-01 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on April 25, 2009. 36 Copyright Notice 38 Copyright (C) The IETF Trust (2008). 40 Abstract 42 The NETCONF protocol defines ways to read configuration data from a 43 NETCONF agent. Part of this data is not set by the NETCONF manager, 44 but rather a default value is used. In many situations the NETCONF 45 manager has a priori knowledge about default data, so the NETCONF 46 agent does not need to send it to the manager. In other situations 47 the NETCONF manger will need this data as part of the NETCONF rpc 48 reply messages. This document defines a capability-based extension 49 to the NETCONF protocol that allows the NETCONF manager to control 50 whether default values are part of NETCONF rpc reply messages. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1.1. Requirements Notation . . . . . . . . . . . . . . . . 3 57 1.1.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . 3 58 2. With-defaults Capability . . . . . . . . . . . . . . . . . . . 4 59 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 2.1.1. Basic handling of default data . . . . . . . . . . . . 4 61 2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 5 62 2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 5 63 2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 5 64 2.5. Modifications to Existing Operations . . . . . . . . . . . 5 65 3. Interactions with Other Capabilities . . . . . . . . . . . . . 6 66 4. Data Model XSD . . . . . . . . . . . . . . . . . . . . . . . . 7 67 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 69 7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 7.1. Augmenting the base RPCs . . . . . . . . . . . . . . . . . 10 71 7.2. Other default handling methods in the real world? . . . . 10 72 8. Normative References . . . . . . . . . . . . . . . . . . . . . 11 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 74 Intellectual Property and Copyright Statements . . . . . . . . . . 13 76 1. Introduction 78 The NETCONF protocol defines ways to read configuration data from a 79 NETCONF agent. Part of this data is not set by the NETCONF manager, 80 but rather a default value is used. In many situations the NETCONF 81 manager has a priori knowledge about default data, so the NETCONF 82 agent does not need to send it to the manager. A priori knowledge 83 can be e.g. a document formally describing the data models supported 84 by the NETCONF agent. 86 A networking device may have a large number of default values. Often 87 the default values are not interesting or specifically defined with a 88 "reasonable" value, so that the management user does not have to 89 handle them. For these reasons it is quite common for networking 90 devices to suppress the output of parameters having the default 91 value. 93 However there are use-cases when a NETCONF manager will need the 94 default data from the node: 96 o Documentation about default values can be unreliable or 97 unavailable. 98 o Some management applications might not have the capabilities to 99 correctly parse and interpret formal data models. 100 o Human users might want to understand the received data without 101 consultation of the documentation. 103 In all theses cases the NETCONF manager will need default data as 104 part of the NETCONF rpc reply messages. 106 This document defines a capability-based extension to the NETCONF 107 protocol that allows the NETCONF manager to control whether default 108 data is part of NETCONF rpc reply messages. 110 1.1. Terminology 112 1.1.1. Requirements Notation 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 116 document are to be interpreted as described in [RFC2119]. 118 1.1.2. NETCONF Terms 120 o Default data: Data that is set or used by the NETCONF agent 121 whenever the NETCONF manager does not provide a specific value for 122 the relevant data item. In the context of this document only 123 configuration data is considered, state data is excluded. 125 o Explicitly set default data: Data that is explicitly set by the 126 NETCONF manager to it's default value. Some agents MIGHT treat 127 explicitly set default data as simple default data, as they MIGHT 128 not be able to differentiate between them. 130 In addition the following terms are defined in RFC 4741 and are not 131 redefined here: 132 o agent 133 o application 134 o manager 135 o operation 136 o RPC 137 o RPC request 138 o RPC response 140 2. With-defaults Capability 142 2.1. Overview 144 The :with-defaults capability indicates that the NETCONF agent makes 145 it possible for the NETCONF manager to control whether default data 146 is part of NETCONF rpc reply messages. The capability only effects 147 configuration data not state data. Sending of default data is 148 controlled for each individual operation separately. The NETCONF 149 agent MUST also indicate it's basic behavior, whether it sends 150 default data in the absence of any specific request from the NETCONF 151 manager. 153 This capability effects the , and 154 operations. Other operations that MIGHT return configuration data 155 are not effected, unless this is specified in the document defining 156 the respective operation. 158 2.1.1. Basic handling of default data 160 It is not defined in [RFC4741], whether default data is part of the 161 datastore/data model, or if it is meta data, that influences the 162 behavior of the NETCONF server, device but is not actually part of 163 the datastore. This document intentionally avoids deciding this 164 question. 166 As a consequence of this issue, NETCONF servers that do not implement 167 the :with-defaults capability may or may not return default data in 168 NETCONF rpc reply messages. 169 Management agents report default data in different ways. This 170 document specifies the following three basic methods: 172 o Report all: All default data is always reported. 173 o Trim: Values are not reported if they match the default. 174 o Explicit: Report values if they are explicitly set. 176 2.2. Dependencies 178 None 180 2.3. Capability Identifier 182 urn:ietf:params:netconf:capability:with-defaults 184 The identifier MUST have an additional parameter: "basic". This 185 indicates how the agent reports default data in rpc reply messages, 186 in the case the manager does not specify the required behavior in the 187 rpc request. The allowed values of this parameter are report-all, 188 trim, explicit as defined in Section 2.1.1. E.g.: 190 urn:ietf:params:netconf:capability:with-defaults?basic=report-all 192 2.4. New Operations 194 None 196 2.5. Modifications to Existing Operations 198 A new 'with-defaults' XML attribute is used to control the reporting 199 of default data. If the 'with-defaults' attribute is present in the 200 element of the affected operations, the agent MUST return 201 default data in the NETCONF rpc reply messages according to the value 202 of the attribute. 204 Allowed values of the with-defaults attribute are: 205 o false: indicates that default data will be returned as if the 206 manager has omitted the attribute, using its basic handling method 207 for defaults. The basic behavior is indicated by the attribute on 208 the capability. See Section 2.3 209 o true: indicates that all default data MUST be returned. 211 The 'with-defaults' attribute is defined in the namespace specified 212 as the 'targetNamespace' in Section 4. However, an agent MUST accept 213 it even if no namespace is used. 215 Affected operations: 216 o 217 o 218 o 220 The following example shows a operation which is using the 221 'with-defaults' attribute. The manager is retrieving the 222 'interfaces' object, defined in the example.com Interfaces data 223 model. (In this simple example, the 'name' field is defined as the 224 key, and the 'mtu' field is the only other data in the 225 element). The default value of mtu is '1500'. The basic default 226 handling for the agent is "trim". As the 'with-defaults' attribute 227 is set to 'true', the mtu is returned not just for eth0 but also for 228 eth1. 230 232 233 234 235 236 237 239 241 242 243 244 eth0 245 8192 246 247 248 eth1 249 1500 250 251 252 253 255 Figure 1 257 3. Interactions with Other Capabilities 259 None 261 4. Data Model XSD 263 This section contains an XML Schema Definition 264 [W3C.REC-xmlschema-2-20041028] which defines the XML syntax 265 associated for the with-defaults XML attribute. 267 268 274 275 276 Schema defining the with-defaults attribute. 278 Organization: "IETF NETCONF Working Group" 279 Contact Info: balazs.lengyel@ericsson.com 280 281 283 286 288 5. IANA Considerations 290 This document registers two URIs for the NETCONF XML namespace in the 291 IETF XML registry [RFC3688]. Note that the capability URN is 292 compliant to [RFC4741] section 10.3. 294 +---------------+---------------------------------------------------+ 295 | Index | Capability Identifier | 296 +---------------+---------------------------------------------------+ 297 | :with-default | urn:ietf:params:netconf:capability:with-defaults: | 298 | s | 1.0 | 299 +---------------+---------------------------------------------------+ 301 URI: urn:ietf:params:xml:ns:netconf:with-defaults:1.0 303 Registrant Contact: The IESG. 305 XML: N/A, the requested URI is an XML namespace. 307 6. Security Considerations 309 This document defines a minor extension to existing NETCONF protocol 310 operations. it does not introduce any new or increased security risks 311 into the management system. 313 The 'with-defaults' capability provides manager controls over the 314 retrieval of particular types of XML data from a configuration 315 database. They only suppress data that can already be retrieved with 316 the standard protocol operations, and do not add any data to the 317 configuration database. 319 7. Open Issues 321 7.1. Augmenting the base RPCs 323 Instead of using an attribute on the RPC element we could "augment" 324 the relevant NETCONF operations with an extra XML element with a 325 similar meaning. 327 Pro: parameters on RPC are for vendor extensions. We should not put 328 standard stuff there. 330 Contra: Some people might consider this a violation of [RFC4741] as 331 the XSD does not allow adding new elements. As there is no NETCONF 332 YAM (at least not yet), what do we actually augment? Also there are 333 multiple ways of defining RFC4741 in YANG. The description will be 334 perfectly clear, but it can never be fed into YANG tools. 336 Conclusion: While augmenting has a certain elegance, we should stick 337 to the attribute based solution. 339 7.2. Other default handling methods in the real world? 341 Are there any other basic default handling methods out there we need 342 to include? 344 8. Normative References 346 [W3C.REC-xmlschema-2-20041028] 347 Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes 348 Second Edition", World Wide Web Consortium 349 Recommendation REC-xmlschema-2-20041028, October 2004, 350 . 352 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 353 December 2006. 355 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 356 Requirement Levels", BCP 14, RFC 2119, March 1997. 358 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 359 January 2004. 361 Authors' Addresses 363 Andy Bierman 364 Netconf Central 365 Simi Valley, CA 366 USA 368 Email: andy@netconfcentral.com 370 Balazs Lengyel 371 Ericsson 372 Budapest, 373 Hungary 375 Email: balazs.lengyel@ericsson.com 377 Full Copyright Statement 379 Copyright (C) The IETF Trust (2008). 381 This document is subject to the rights, licenses and restrictions 382 contained in BCP 78, and except as set forth therein, the authors 383 retain all their rights. 385 This document and the information contained herein are provided on an 386 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 387 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 388 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 389 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 390 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 391 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 393 Intellectual Property 395 The IETF takes no position regarding the validity or scope of any 396 Intellectual Property Rights or other rights that might be claimed to 397 pertain to the implementation or use of the technology described in 398 this document or the extent to which any license under such rights 399 might or might not be available; nor does it represent that it has 400 made any independent effort to identify any such rights. Information 401 on the procedures with respect to rights in RFC documents can be 402 found in BCP 78 and BCP 79. 404 Copies of IPR disclosures made to the IETF Secretariat and any 405 assurances of licenses to be made available, or the result of an 406 attempt made to obtain a general license or permission for the use of 407 such proprietary rights by implementers or users of this 408 specification can be obtained from the IETF on-line IPR repository at 409 http://www.ietf.org/ipr. 411 The IETF invites any interested party to bring to its attention any 412 copyrights, patents or patent applications, or other proprietary 413 rights that may cover technology that may be required to implement 414 this standard. Please address the information to the IETF at 415 ietf-ipr@ietf.org. 417 Acknowledgment 419 Funding for the RFC Editor function is provided by the IETF 420 Administrative Support Activity (IASA).