draft-ietf-netconf-with-defaults-04.txt   draft-ietf-netconf-with-defaults-05.txt 
NETCONF A. Bierman NETCONF A. Bierman
Internet-Draft Netconf Central Internet-Draft InterWorking Labs
Intended status: Standards Track B. Lengyel Intended status: Standards Track B. Lengyel
Expires: April 25, 2010 Ericsson Expires: September 6, 2010 Ericsson
October 22, 2009 March 5, 2010
With-defaults capability for NETCONF With-defaults capability for NETCONF
draft-ietf-netconf-with-defaults-04 draft-ietf-netconf-with-defaults-05
Abstract
The NETCONF protocol defines ways to read configuration data from a
NETCONF server. Part of this data is not set by the NETCONF client,
but rather a default value is used. In many situations the NETCONF
client has a priori knowledge about default data, so the NETCONF
server does not need to send it to the client. In other situations
the NETCONF client will need this data as part of the NETCONF <rpc-
reply> messages. This document defines a capability-based extension
to the NETCONF protocol that allows the NETCONF client to control
whether default values are part of NETCONF <rpc-reply> messages or
<copy-config> output to the target URL.
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
skipping to change at page 1, line 33 skipping to change at page 1, line 46
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on April 25, 2010. This Internet-Draft will expire on September 6, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of Provisions Relating to IETF Documents
publication of this document (http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
Abstract include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the BSD License.
The NETCONF protocol defines ways to read configuration data from a This document may contain material from IETF Documents or IETF
NETCONF server. Part of this data is not set by the NETCONF client, Contributions published or made publicly available before November
but rather a default value is used. In many situations the NETCONF 10, 2008. The person(s) controlling the copyright in some of this
client has a priori knowledge about default data, so the NETCONF material may not have granted the IETF Trust the right to allow
server does not need to send it to the client. In other situations modifications of such material outside the IETF Standards Process.
the NETCONF client will need this data as part of the NETCONF <rpc- Without obtaining an adequate license from the person(s) controlling
reply> messages. This document defines a capability-based extension the copyright in such materials, this document may not be modified
to the NETCONF protocol that allows the NETCONF client to control outside the IETF Standards Process, and derivative works of it may
whether default values are part of NETCONF <rpc-reply> messages or not be created outside the IETF Standards Process, except to format
<copy-config> output to the target URL. it for publication as an RFC or to translate it into languages other
than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Current handling of default data . . . . . . . . . . . . . 4 1.2. Current handling of default data . . . . . . . . . . . . . 5
2. With-defaults Capability . . . . . . . . . . . . . . . . . . . 5 2. With-defaults Capability . . . . . . . . . . . . . . . . . . . 6
2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 6
2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 5 2.3. Conformance . . . . . . . . . . . . . . . . . . . . . . . 6
2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Capability Identifier . . . . . . . . . . . . . . . . . . 6
2.5. Modifications to Existing Operations . . . . . . . . . . . 6 2.5. New Operations . . . . . . . . . . . . . . . . . . . . . . 7
3. Interactions with Other Capabilities . . . . . . . . . . . . . 7 2.6. Modifications to Existing Operations . . . . . . . . . . . 7
4. Data Model XSD . . . . . . . . . . . . . . . . . . . . . . . . 8 2.7. Interactions with Other Capabilities . . . . . . . . . . . 9
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 9 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
8. Appendix A - YANG Module for with-defaults (non-normative) . 9 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13
9. Appendix B - Change Log . . . . . . . . . . . . . . . . . . 12 7. Normative References . . . . . . . . . . . . . . . . . . . . . 13
9.1. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . . 13
9.2. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 14
9.3. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 B.1. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
9.4. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 B.2. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 14
9.5. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 13 B.3. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 14
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 B.4. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 14
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 B.5. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 15
11.1. Normative References . . . . . . . . . . . . . . . . . . . 14 B.6. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 15
11.2. Informative References . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction 1. Introduction
The NETCONF protocol defines ways to read configuration data from a The NETCONF protocol [RFC4741] defines ways to read configuration
NETCONF server. Part of this data is not set by the NETCONF client, data from a NETCONF server. Part of this data is not set by the
but rather a default value is used. In many situations the NETCONF NETCONF client, but rather a default value is used. In many
client has a priori knowledge about default data, so the NETCONF situations the NETCONF client has a priori knowledge about default
server does not need to send it to the client. A priori knowledge data, so the NETCONF server does not need to send it to the client.
can be e.g., a document formally describing the data models supported A priori knowledge can be e.g., a document formally describing the
by the NETCONF server. data models supported by the NETCONF server.
A networking device may have a large number of default values. Often A networking device may have a large number of default values. Often
the default values are not interesting or specifically defined with a the default values are not interesting or specifically defined with a
"reasonable" value, so that the management user does not have to "reasonable" value, so that the management user does not have to
handle them. For these reasons it is quite common for networking handle them. For these reasons it is quite common for networking
devices to suppress the output of parameters having the default devices to suppress the output of parameters having the default
value. value.
However there are use-cases when a NETCONF client will need the However there are use-cases when a NETCONF client will need the
default data from the node: default data from the node:
skipping to change at page 3, line 48 skipping to change at page 4, line 48
This document defines a capability-based extension to the NETCONF This document defines a capability-based extension to the NETCONF
protocol that allows the NETCONF client to control whether default protocol that allows the NETCONF client to control whether default
data is part of NETCONF <rpc-reply> messages. data is part of NETCONF <rpc-reply> messages.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
o Data model schema is a document or set of documents describing the Data model schema: A document or set of documents describing the
data models supported by the NETCONF server. 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.
o Explicitly set default data: Is default data that is set by a Management Application: A computer program running outside the
NETCONF client or other external management application/user by NETCONF server that configures or supervises the NETCONF server.
the way of an actual management operation to the value specified A management application can reach the device e.g. via the
as its default in the data model schema. Some servers MAY treat NETCONF, CLI or SNMP.
explicitly set default data as simple default data, as they may Default data: Data specified in the data model schema as default,
not be able to differentiate between them. that is set or used by the device whenever the NETCONF client or
Data, that is set to a value other then its default value, is not other management application/user does not provide a specific
default data, so its handling is outside the scope of this value for the relevant data item. Default data MAY or MAY NOT be
document. stored as part of a configuration datastore.
Explicitly set data: Data that is set to any value by a NETCONF
client or other management application by the way of an actual
management operation, including any data model schema default
value. Any value set by the NETCONF server which is not the
schema defined default value is also considered explicitly set
data.
In addition the following terms are defined in RFC 4741 and are not In addition the following terms are defined in RFC 4741 and are not
redefined here: redefined here:
o application
o client o client
o operation o operation
o RPC o RPC
o RPC request o RPC request
o RPC response o RPC response
o server o server
1.2. Current handling of default data 1.2. Current handling of default data
[NETCONF] does not define whether default data is part of the NETCONF does not define whether default data is part of the
datastore/data model, or if it is meta-data that influences the datastore/data model, or if it is meta-data that influences the
behavior of the NETCONF server, but is not actually part of the behavior of the NETCONF server, but is not actually part of the
datastore. This document is intended to support either type of datastore. This document is intended to support either type of
implementation, without deciding which approach is better. implementation, without deciding which approach is better.
As a consequence of this issue, NETCONF servers that do not implement As a consequence of this approach, NETCONF servers that do not
the :with-defaults capability may or may not return default data. implement the :with-defaults capability may or may not return default
data.
Different NETCONF servers report default data in different ways. Different NETCONF servers report default data in different ways.
This document specifies the following three basic modes: This document specifies the following three basic modes:
o report-all: All default data is always reported. report-all: All default data is always reported.
o trim: Values are not reported if they match the default. trim: Values are not reported if they match the default value (as
o explicit: Default data is not reported except explicitly set specified in the data model schema).
default data. For state data this has the same effect as report- explicit: Report only values that match the definition of explicitly
all. set data.
2. With-defaults Capability 2. With-defaults Capability
2.1. Overview 2.1. Overview
The :with-defaults capability indicates that the NETCONF server makes The :with-defaults capability indicates that the NETCONF server makes
it possible for the NETCONF client to control whether default data is it possible for the NETCONF client to control whether default data is
part of NETCONF <rpc-reply> messages. The capability affects both part of NETCONF <rpc-reply> messages. The capability affects both
configuration and state data (while acknowledging that the usage of configuration and state data (while acknowledging that the usage of
default values for state data is less prevalent). Sending of default default values for state data is less prevalent). Sending of default
data is controlled for each individual operation separately. data is controlled for each individual operation separately.
A NETCONF server implementing the :with-defaults capability MUST A NETCONF server implementing the :with-defaults capability MUST
indicate its basic behavior, whether it sends default data in the indicate its basic behavior, whether it sends default data in the
absence of any specific request from the NETCONF client; and MUST absence of any specific request from the NETCONF client; and MUST
support the 'report-all' handling mode and MAY support other modes. support the 'report-all' handling mode and MAY support other modes.
A server indicating 'explicit' either in the basic or the also- A server indicating 'explicit' either in the basic or the also-
supported parameter MUST be able to differentiate between normal supported parameter MUST be able to differentiate between normal
default data and explicitly set default data. default data and explicitly set data.
2.2. Dependencies 2.2. Dependencies
None None
2.3. Capability Identifier 2.3. Conformance
Every NETCONF server SHOULD implement this capability.
2.4. Capability Identifier
urn:ietf:params:netconf:capability:with-defaults:1.0 urn:ietf:params:netconf:capability:with-defaults:1.0
The identifier MUST have a parameter: "basic". This indicates how The identifier MUST have a parameter: "basic-mode". This indicates
the server reports default data in <rpc-reply> messages, in the case how the server reports default data in <rpc-reply> messages, in the
the client does not specify the required behavior in the <rpc> case the client does not specify the required behavior in the <rpc>
request. The allowed values of this parameter are report-all, trim, request. The allowed values of this parameter are report-all, trim,
explicit as listed in Section 1.2. explicit as listed in Section 1.2.
The identifier MAY have another parameter: "also-supported". This The identifier MAY have another parameter: "also-supported". This
parameter indicates which additional default handling modes the parameter indicates which additional default handling modes the
server supports. The value of the parameter is a comma separated server supports. The value of the parameter is a comma separated
list of one or two modes that are supported beside the mode indicated list of one or two modes that are supported beside the mode indicated
in the basic parameter. Possible modes are taken from the list in in the basic parameter. Possible modes are taken from the list in
Section 1.2. Section 1.2.
In addition to these parameters, the identifier MUST have the YANG
'module' and 'revision' parameters if the ietf-with-defaults YANG
module is supported, as defined in section 5.6.4 of
[I-D.ietf-netmod-yang].
Example: Example:
urn:ietf:params:netconf:capability:with-defaults:1.0?basic=report-all urn:ietf:params:netconf:capability:with-defaults:1.0?module=ietf-
netconf-with-defaults&revision=2010-03-05&basic-mode=report-all
urn:ietf:params:netconf:capability:with-defaults:1.0?basic=report- urn:ietf:params:netconf:capability:with-defaults:1.0?module=ietf-
all&also-supported=trim,explicit netconf-with-defaults&revision=2010-03-05&basic-mode=report-all&
also-supported=trim,explicit
2.4. New Operations 2.5. New Operations
None None
2.5. Modifications to Existing Operations 2.6. Modifications to Existing Operations
A new <with-defaults> XML child element is added to the method-name A new <with-defaults> XML [W3C.REC-xml-20001006] child element is
element. This is the element that indicates the type of the added to the method-name element. This is the element that indicates
operation e.g. <get>, <get-config> or <copy-config>. If the <with- the type of the operation e.g. <get>, <get-config> or <copy-config>.
defaults> element is present, it controls the reporting of default If the <with-defaults> element is present, it controls the reporting
data. The server MUST return default data in the NETCONF <rpc-reply> of default data. The server MUST return default data in the NETCONF
messages according to the value of the element. <rpc-reply> messages according to the value of the element.
Allowed values of the with-defaults element are taken from the list Allowed values of the with-defaults element are taken from the list
in Section 1.2. The allowed values are restricted to the values that in Section 1.2. The allowed values are restricted to the values that
the device indicates support for in the with-defaults capability in the device indicates support for in the with-defaults capability in
the basic and also-supported parameters. the basic and also-supported parameters.
If a not allowed value is used the NETCONF server SHALL return an
If an unsupported value is used, the NETCONF server SHALL return an
<rpc-reply> with an <rpc-error> element. The <error-tag> SHALL be <rpc-reply> with an <rpc-error> element. The <error-tag> SHALL be
'operation-not-supported', the <error-app-tag> SHALL be "with- 'operation-not-supported', and the <error-app-tag> SHALL be 'with-
defaults-mode-not-supported', and <error-info> SHALL contain the defaults-mode-not-supported'.
requested mode.
If the <with-defaults> element is not present, the server follows its If the <with-defaults> element is not present, the server follows its
basic behavior as indicated by the capability identifier's parameter basic behavior as indicated by the capability identifier's parameter
see Section 2.3. see Section 2.4.
Affected operations: Affected operations:
o <get> o <get>
o <get-config> o <get-config>
o <copy-config> o <copy-config>
<copy-config> is only affected if the target of the operation is a <copy-config> is only affected if the target of the operation is a
URL. If the target is a NETCONF datastore (running, candidate or URL. If the target is a NETCONF datastore (running, candidate or
startup) the capability has no effect; the with-defaults parameter, startup) the capability has no effect; the with-defaults parameter,
if present, SHALL be silently ignored. if present, SHALL be silently ignored.
skipping to change at page 7, line 44 skipping to change at page 9, line 39
<interface> <interface>
<name>eth1</name> <name>eth1</name>
<mtu>1500</mtu> <mtu>1500</mtu>
</interface> </interface>
</interfaces> </interfaces>
</data> </data>
</rpc-reply> </rpc-reply>
Figure 1 Figure 1
3. Interactions with Other Capabilities 2.7. Interactions with Other Capabilities
None None
4. Data Model XSD 3. YANG Module
This section contains an XML Schema Definition
[W3C.REC-xmlschema-2-20041028] which defines the XML syntax
associated for the with-defaults XML element.
-- RFC Ed.: Insert license information for code as appropriate
<CODE BEGINS>
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns="urn:ietf:params:netconf:capability:with-defaults:1.0"
targetNamespace="urn:ietf:params:netconf:capability:with-defaults:1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" attributeFormDefault="unqualified"
xml:lang="en">
<xs:annotation>
<xs:documentation>
Schema defining the with-defaults element.
Organization: "IETF NETCONF Working Group"
Contact Info: balazs.lengyel@ericsson.com
</xs:documentation>
</xs:annotation>
<xs:element name="with-defaults" >
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="report-all"/>
<xs:enumeration value="trim"/>
<xs:enumeration value="explicit"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:schema>
<CODE ENDS>
5. IANA Considerations
This document registers one capability identifier URN from the
"Network Configuration Protocol [NETCONF] Capability URNs" registry,
and registers the same URN for the NETCONF XML namespace in the "IETF
XML registry" [RFC3688]. Note that the capability URN is compliant
to [NETCONF] section 10.3.
+---------------+---------------------------------------------------+
| Index | Capability Identifier |
+---------------+---------------------------------------------------+
| :with-default | urn:ietf:params:netconf:capability:with-defaults: |
| s | 1.0 |
+---------------+---------------------------------------------------+
6. Security Considerations
This document defines a minor extension to existing NETCONF protocol
operations. It does not introduce any new or increased security
risks into the management system.
The 'with-defaults' capability gives client control over the
retrieval of particular types of XML data from a configuration
database. They only suppress data that can already be retrieved with
the standard protocol operations, and do not add any data to the
configuration database.
7. Open Issues
Is the definition of defaults OK?
Shall we wait for YANG and 4741bis and make the YANG normative?
Shall we make with-defaults mandatory?
8. Appendix A - YANG Module for with-defaults (non-normative)
The following YANG module defines the addition of the with-defaults The following YANG module defines the addition of the with-defaults
element to the <get>, <get-config> and <copy-config> operations. The element to the <get>, <get-config> and <copy-config> operations. The
YANG language is defined in [I-D.ietf-netmod-yang]. The above YANG language is defined in [I-D.ietf-netmod-yang]. The above
operations are defined in YANG in [I-D.ietf-netconf-4741bis]. operations are defined in YANG in [I-D.ietf-netconf-4741bis]. Every
NETCONF server SHOULD implement this YANG module.
-- RFC Ed.: Insert license information for code as appropriate -- RFC Ed.: Insert license information for code as appropriate
<CODE BEGINS> <CODE BEGINS> file="ietf-netconf-with-defaults.yang"
module ietf-netconf-with-defaults { module ietf-netconf-with-defaults {
namespace "urn:ietf:params:netconf:capability:with-defaults:1.0"; namespace "urn:ietf:params:netconf:capability:with-defaults:1.0";
prefix nwd; prefix nwd;
// for the uri data type
import ietf-netconf { prefix nc; } import ietf-netconf { prefix nc; }
organization
"IETF NETCONF (Network Configuration Protocol) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
WG Chair: Bert Wijnen
<mailto:bertietf@bwijnen.net>
WG Chair: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com>
Editor: Andy Bierman
<mailto:andyb@iwl.com>
Editor: Balazs Lengyel
<mailto:balazs.lengyel@ericsson.com>";
description description
"This module defines a capability-based extension to the "This module defines a capability-based extension to the
NETCONF protocol that allows the NETCONF client to control NETCONF protocol that allows the NETCONF client to control
whether default values are part of NETCONF whether default values are part of NETCONF
<rpc-reply> messages or <copy-config> output to the target URL. <rpc-reply> messages or <copy-config> output to the target URL.
Copyright (c) 2009 IETF Trust and the persons identified as Copyright (c) 2010 IETF Trust and the persons identified as
the document authors. All rights reserved. the document authors. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the without modification, is permitted pursuant to, and subject
following conditions are met: to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
- Redistributions of source code must retain the above Relating to IETF Documents
copyright notice, this list of conditions and the (http://trustee.ietf.org/license-info).
following disclaimer.
- Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other
materials provided with the distribution.
- Neither the name of Internet Society, IETF or IETF
Trust, nor the names of specific contributors, may be
used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this note // RFC Ed.: replace XXXX with actual RFC number and remove this note
reference "RFC XXXX"; // RFC Ed.: remove this note
// Note: extracted from draft-ietf-netmod-with-defaults-05.txt
// RFC Ed.: replace XXXX with actual RFC number and remove this note
// reference "draft-ietf-netconf-with-defaults-03.txt";
// RFC Ed.: remove the reference statement above and this note.
contact
"Send comments to the NETCONF WG mailing list.
<netconf@ietf.org>";
revision 2009-07-01 { revision 2010-03-05 {
description description
"Initial version"; "Initial version.";
} reference
"RFC XXXX: With-defaults capability for NETCONF";
// with-defaults capability defined as a feature
feature with-defaults {
description
"NETCONF :with-defaults capability;
If the server advertises the :with-defaults
capability for a session, then this feature MUST
also be enabled for that session. Otherwise,
this feature MUST NOT be enabled.";
// RFC Ed.: replace XXXX with actual RFC number and
// remove this note
reference "RFC XXXX";
} }
// RFC Ed.: replace XXXX with actual RFC number and remove this note
typedef with-defaults-mode { typedef with-defaults-mode {
description description
"Possible modes to report default data in "Possible modes to report default data in
rpc-reply messages."; rpc-reply messages.";
type enumeration { type enumeration {
enum report-all { enum report-all {
description description
"All default data is always reported."; "All default data is always reported.";
} }
enum trim { enum trim {
description description
"Values are not reported if they match the default."; "Values are not reported if they match the default.";
} }
enum explicit { enum explicit {
description description
"Report values if they are explicitly set. "Report values that match the definition of
For state data this has the same effect explicitly set data.";
as report-all";
} }
} }
} }
grouping with-defaults-parameters {
leaf with-defaults {
description
"The explicit defaults processing mode requested.";
type with-defaults-mode;
}
}
// extending the get-config operation // extending the get-config operation
augment /nc:get-config/nc:input { augment /nc:get-config/nc:input {
leaf with-defaults { uses with-defaults-parameters;
type with-defaults-mode;
}
} }
// extending the get operation // extending the get operation
augment /nc:get/nc:input { augment /nc:get/nc:input {
leaf with-defaults { uses with-defaults-parameters;
type with-defaults-mode;
}
} }
// extending the copy-congig operation // extending the copy-config operation
augment /nc:copy-config/nc:input { augment /nc:copy-config/nc:input {
leaf with-defaults { uses with-defaults-parameters;
type with-defaults-mode;
}
} }
} }
<CODE ENDS> <CODE ENDS>
9. Appendix B - Change Log 4. IANA Considerations
9.1. -00 This document registers one capability identifier URN from the
'Network Configuration Protocol [RFC4741] Capability URNs' registry,
and registers the same URN for the NETCONF XML namespace in the "IETF
XML registry" [RFC3688]. Note that the capability URN is compliant
to [RFC4741] section 10.3.
+---------------+---------------------------------------------------+
| Index | Capability Identifier |
+---------------+---------------------------------------------------+
| :with-default | urn:ietf:params:netconf:capability:with-defaults: |
| s | 1.0 |
+---------------+---------------------------------------------------+
5. Security Considerations
This document defines a minor extension to existing NETCONF protocol
operations. It does not introduce any new or increased security
risks into the management system.
The 'with-defaults' capability gives client control over the
retrieval of particular types of XML data from a configuration
database. They only suppress data that can already be retrieved with
the standard protocol operations, and do not add any data to the
configuration database.
6. Acknowledgements
Thanks to Martin Bjorklund, Sharon Chisholm, Phil Shafer, Juergen
Schoenwaelder, Washam Fan and many other members of the NETCONF WG
for providing important input to this document.
7. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
[RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006.
[I-D.ietf-netconf-4741bis]
Enns, R., Bjorklund, M., Schoenwaelder, J., and A.
Bierman, "Network Configuration Protocol (NETCONF)",
draft-ietf-netconf-4741bis-02 (work in progress),
February 2010.
[I-D.ietf-netmod-yang]
Bjorklund, M., "YANG - A data modeling language for
NETCONF", draft-ietf-netmod-yang-11 (work in progress),
February 2010.
[W3C.REC-xml-20001006]
Sperberg-McQueen, C., Maler, E., Paoli, J., and T. Bray,
"Extensible Markup Language (XML) 1.0 (Second Edition)",
World Wide Web Consortium FirstEdition REC-xml-20001006,
October 2000,
<http://www.w3.org/TR/2000/REC-xml-20001006>.
Appendix A. Open Issues
This section will be removed. The open issues are closed in this
revision of the draft, pending working group approval.
Is the definition of defaults OK? [The definition of explicitly set
default data has been changed to 'explicitly set data', and now
aligns with the YANG definition.]
Shall we wait for YANG and 4741bis and make the YANG normative?
[Yes.]
Shall we make with-defaults mandatory? [No. It is SHOULD, not
MUST.]
Appendix B. Change Log
-- RFC Ed.: remove this section before publication.
B.1. -00
Created from draft-bierman-netconf-with-defaults-01.txt Created from draft-bierman-netconf-with-defaults-01.txt
It was decided by the NETCONF mailing list, that with-defaults should It was decided by the NETCONF mailing list, that with-defaults should
be a sub-element of each affected operation. While this violates the be a sub-element of each affected operation. While this violates the
XSD of RFC4741 this is acceptable and follows the ideas behind XSD of RFC4741 this is acceptable and follows the ideas behind
NETCONF and YANG. NETCONF and YANG.
Hopefully it will be clarified in the 4741bis RFC whether such Hopefully it will be clarified in the 4741bis RFC whether such
extensions are allowed. extensions are allowed.
9.2. 00-01 B.2. 00-01
Changed value set of with-default capability and element Changed value set of with-default capability and element
Added version to URI Added version to URI
9.3. 01-02 B.3. 01-02
report-all made mandatory report-all made mandatory
Placeholder for YAM added, XSD will be removed when 4741 provides the Placeholder for YAM added, XSD will be removed when 4741 provides the
NETCONF YAM NETCONF YAM
with-defaults is valid for state data as well (if state data has a with-defaults is valid for state data as well (if state data has a
defined default which might not be so frequent). The definition of defined default which might not be so frequent). The definition of
explicit was modified for state data. explicit was modified for state data.
9.4. 02-03 B.4. 02-03
Clarifications Clarifications
YAM added YAM added
Use the same URN for the capability and the XML namespace to Use the same URN for the capability and the XML namespace to
accommodate YANG, and avoid two separate URN/URIs being advertised in accommodate YANG, and avoid two separate URN/URIs being advertised in
the HELLO message, for such a small function. the HELLO message, for such a small function.
9.5. 03-04 B.5. 03-04
Clarifications Clarifications
Added non-netconf interfaces to the definition of explicitly set Added non-netconf interfaces to the definition of explicitly set
default data default data
10. Acknowledgements B.6. 04-05
Thanks to Martin Bjorklund, Sharon Chisholm, Phil Shafer, Juergen Updated I-D and YANG module boiler-plate.
Schoenwaelder, Washam Fan and many other members of the NETCONF WG
for providing important input to this document.
11. References Removed redundant 'with-defaults' YANG feature.
11.1. Normative References Changed definition of 'explicit' mode to match the YANG definition
[W3C.REC-xmlschema-2-20041028] Removed XSD because the YANG is normative and the XSD is
Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes unconstrained, and does not properly extend the 3 affected NETCONF
Second Edition", World Wide Web Consortium operations.
Recommendation REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
[NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, Made the YANG module a normative section instead of non-normative
December 2006. appendix.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Changed YANG from an informative to a normative reference,
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, Changed 4741bis from an informative to a normative reference because
January 2004. the YANG module imports the ietf-netconf module in order to augment
some RPC operations.
11.2. Informative References Updated capability requirements to include YANG module capability
parameters.
[I-D.ietf-netmod-yang] Added a description statement to the with-defaults leaf definition.
Bjorklund, M., "YANG - A data modeling language for
NETCONF", draft-ietf-netmod-yang-08 (work in progress),
October 2009.
[I-D.ietf-netconf-4741bis] Update open issues section; ready to close all open issues.
Enns, R., Bjorklund, M., Schoenwaelder, J., and A.
Bierman, "NETCONF Configuration Protocol",
draft-ietf-netconf-4741bis-01 (work in progress),
July 2009.
Authors' Addresses Authors' Addresses
Andy Bierman Andy Bierman
Netconf Central InterWorking Labs
Simi Valley, CA 303 Potrero Street, Suite 52
Santa Cruz, CA 95060-2760
USA USA
Email: andy@netconfcentral.com Phone: +1 831 460 7010
Email: andyb@iwl.com
Balazs Lengyel Balazs Lengyel
Ericsson Ericsson
Budapest, Budapest,
Hungary Hungary
Email: balazs.lengyel@ericsson.com Email: balazs.lengyel@ericsson.com
 End of changes. 67 change blocks. 
292 lines changed or deleted 286 lines changed or added

This html diff was produced by rfcdiff 1.38. The latest version is available from http://tools.ietf.org/tools/rfcdiff/