NETCONF A. Bierman
Internet-Draft Netconf Central
Intended status: Standards Track B. Lengyel
Expires: April 25, 2009 Ericsson
October 22, 2008
With-defaults capability for NETCONF
draft-bierman-netconf-with-defaults-01
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on April 25, 2009.
Copyright Notice
Copyright (C) The IETF Trust (2008).
Abstract
The NETCONF protocol defines ways to read configuration data from a
NETCONF agent. Part of this data is not set by the NETCONF manager,
but rather a default value is used. In many situations the NETCONF
manager has a priori knowledge about default data, so the NETCONF
agent does not need to send it to the manager. In other situations
the NETCONF manger will need this data as part of the NETCONF rpc
reply messages. This document defines a capability-based extension
Bierman & Lengyel Expires April 25, 2009 [Page 1]
Internet-Draft with-defaults October 2008
to the NETCONF protocol that allows the NETCONF manager to control
whether default values are part of NETCONF rpc reply messages.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.1. Requirements Notation . . . . . . . . . . . . . . . . 3
1.1.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . 3
2. With-defaults Capability . . . . . . . . . . . . . . . . . . . 4
2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.1. Basic handling of default data . . . . . . . . . . . . 4
2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 5
2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 5
2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 5
2.5. Modifications to Existing Operations . . . . . . . . . . . 5
3. Interactions with Other Capabilities . . . . . . . . . . . . . 6
4. Data Model XSD . . . . . . . . . . . . . . . . . . . . . . . . 7
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
6. Security Considerations . . . . . . . . . . . . . . . . . . . 9
7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1. Augmenting the base RPCs . . . . . . . . . . . . . . . . . 10
7.2. Other default handling methods in the real world? . . . . 10
8. Normative References . . . . . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12
Intellectual Property and Copyright Statements . . . . . . . . . . 13
Bierman & Lengyel Expires April 25, 2009 [Page 2]
Internet-Draft with-defaults October 2008
1. Introduction
The NETCONF protocol defines ways to read configuration data from a
NETCONF agent. Part of this data is not set by the NETCONF manager,
but rather a default value is used. In many situations the NETCONF
manager has a priori knowledge about default data, so the NETCONF
agent does not need to send it to the manager. A priori knowledge
can be e.g. a document formally describing the data models supported
by the NETCONF agent.
A networking device may have a large number of default values. Often
the default values are not interesting or specifically defined with a
"reasonable" value, so that the management user does not have to
handle them. For these reasons it is quite common for networking
devices to suppress the output of parameters having the default
value.
However there are use-cases when a NETCONF manager will need the
default data from the node:
o Documentation about default values can be unreliable or
unavailable.
o Some management applications might not have the capabilities to
correctly parse and interpret formal data models.
o Human users might want to understand the received data without
consultation of the documentation.
In all theses cases the NETCONF manager will need default data as
part of the NETCONF rpc reply messages.
This document defines a capability-based extension to the NETCONF
protocol that allows the NETCONF manager to control whether default
data is part of NETCONF rpc reply messages.
1.1. Terminology
1.1.1. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
1.1.2. NETCONF Terms
o Default data: Data that is set or used by the NETCONF agent
whenever the NETCONF manager does not provide a specific value for
the relevant data item. In the context of this document only
configuration data is considered, state data is excluded.
Bierman & Lengyel Expires April 25, 2009 [Page 3]
Internet-Draft with-defaults October 2008
o Explicitly set default data: Data that is explicitly set by the
NETCONF manager to it's default value. Some agents MIGHT treat
explicitly set default data as simple default data, as they MIGHT
not be able to differentiate between them.
In addition the following terms are defined in RFC 4741 and are not
redefined here:
o agent
o application
o manager
o operation
o RPC
o RPC request
o RPC response
2. With-defaults Capability
2.1. Overview
The :with-defaults capability indicates that the NETCONF agent makes
it possible for the NETCONF manager to control whether default data
is part of NETCONF rpc reply messages. The capability only effects
configuration data not state data. Sending of default data is
controlled for each individual operation separately. The NETCONF
agent MUST also indicate it's basic behavior, whether it sends
default data in the absence of any specific request from the NETCONF
manager.
This capability effects the <get>, <get-config> and <copy-config>
operations. Other operations that MIGHT return configuration data
are not effected, unless this is specified in the document defining
the respective operation.
2.1.1. Basic handling of default data
It is not defined in [RFC4741], whether default data is part of the
datastore/data model, or if it is meta data, that influences the
behavior of the NETCONF server, device but is not actually part of
the datastore. This document intentionally avoids deciding this
question.
As a consequence of this issue, NETCONF servers that do not implement
the :with-defaults capability may or may not return default data in
NETCONF rpc reply messages.
Management agents report default data in different ways. This
document specifies the following three basic methods:
Bierman & Lengyel Expires April 25, 2009 [Page 4]
Internet-Draft with-defaults October 2008
o Report all: All default data is always reported.
o Trim: Values are not reported if they match the default.
o Explicit: Report values if they are explicitly set.
2.2. Dependencies
None
2.3. Capability Identifier
urn:ietf:params:netconf:capability:with-defaults
The identifier MUST have an additional parameter: "basic". This
indicates how the agent reports default data in rpc reply messages,
in the case the manager does not specify the required behavior in the
rpc request. The allowed values of this parameter are report-all,
trim, explicit as defined in Section 2.1.1. E.g.:
urn:ietf:params:netconf:capability:with-defaults?basic=report-all
2.4. New Operations
None
2.5. Modifications to Existing Operations
A new 'with-defaults' XML attribute is used to control the reporting
of default data. If the 'with-defaults' attribute is present in the
<rpc> element of the affected operations, the agent MUST return
default data in the NETCONF rpc reply messages according to the value
of the attribute.
Allowed values of the with-defaults attribute are:
o false: indicates that default data will be returned as if the
manager has omitted the attribute, using its basic handling method
for defaults. The basic behavior is indicated by the attribute on
the capability. See Section 2.3
o true: indicates that all default data MUST be returned.
The 'with-defaults' attribute is defined in the namespace specified
as the 'targetNamespace' in Section 4. However, an agent MUST accept
it even if no namespace is used.
Affected operations:
o <get>
o <get-config>
Bierman & Lengyel Expires April 25, 2009 [Page 5]
Internet-Draft with-defaults October 2008
o <copy-config>
The following example shows a <get> operation which is using the
'with-defaults' attribute. The manager is retrieving the
'interfaces' object, defined in the example.com Interfaces data
model. (In this simple example, the 'name' field is defined as the
key, and the 'mtu' field is the only other data in the <interface>
element). The default value of mtu is '1500'. The basic default
handling for the agent is "trim". As the 'with-defaults' attribute
is set to 'true', the mtu is returned not just for eth0 but also for
eth1.
<rpc message-id="102" with-defaults="true"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<interfaces xmlns="http://example.com/interfaces/1.2"/>
</filter>
</get>
</rpc>
<rpc-reply message-id="102" with-defaults="true"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<interfaces xmlns="http://example.com/interfaces/1.2">
<interface>
<name>eth0</name>
<mtu>8192</mtu>
</interface>
<interface>
<name>eth1</name>
<mtu>1500</mtu>
</interface>
</interfaces>
</data>
</rpc-reply>
Figure 1
3. Interactions with Other Capabilities
None
Bierman & Lengyel Expires April 25, 2009 [Page 6]
Internet-Draft with-defaults October 2008
4. Data Model XSD
This section contains an XML Schema Definition
[W3C.REC-xmlschema-2-20041028] which defines the XML syntax
associated for the with-defaults XML attribute.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns="urn:ietf:params:xml:ns:netconf:with-defaults:1.0"
targetNamespace="urn:ietf:params:xml:ns:netconf: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 attribute.
Organization: "IETF NETCONF Working Group"
Contact Info: balazs.lengyel@ericsson.com
</xs:documentation>
</xs:annotation>
<xs:attribute name="with-defaults"
type="xs:boolean"/>
</xs:schema>
5. IANA Considerations
This document registers two URIs 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 |
+---------------+---------------------------------------------------+
URI: urn:ietf:params:xml:ns:netconf:with-defaults:1.0
Registrant Contact: The IESG.
Bierman & Lengyel Expires April 25, 2009 [Page 7]
Internet-Draft with-defaults October 2008
XML: N/A, the requested URI is an XML namespace.
Bierman & Lengyel Expires April 25, 2009 [Page 8]
Internet-Draft with-defaults October 2008
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 provides manager controls 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.
Bierman & Lengyel Expires April 25, 2009 [Page 9]
Internet-Draft with-defaults October 2008
7. Open Issues
7.1. Augmenting the base RPCs
Instead of using an attribute on the RPC element we could "augment"
the relevant NETCONF operations with an extra XML element with a
similar meaning.
Pro: parameters on RPC are for vendor extensions. We should not put
standard stuff there.
Contra: Some people might consider this a violation of [RFC4741] as
the XSD does not allow adding new elements. As there is no NETCONF
YAM (at least not yet), what do we actually augment? Also there are
multiple ways of defining RFC4741 in YANG. The description will be
perfectly clear, but it can never be fed into YANG tools.
Conclusion: While augmenting has a certain elegance, we should stick
to the attribute based solution.
7.2. Other default handling methods in the real world?
Are there any other basic default handling methods out there we need
to include?
Bierman & Lengyel Expires April 25, 2009 [Page 10]
Internet-Draft with-defaults October 2008
8. Normative References
[W3C.REC-xmlschema-2-20041028]
Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
Second Edition", World Wide Web Consortium
Recommendation REC-xmlschema-2-20041028, October 2004,
<http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
[RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006.
[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.
Bierman & Lengyel Expires April 25, 2009 [Page 11]
Internet-Draft with-defaults October 2008
Authors' Addresses
Andy Bierman
Netconf Central
Simi Valley, CA
USA
Email: andy@netconfcentral.com
Balazs Lengyel
Ericsson
Budapest,
Hungary
Email: balazs.lengyel@ericsson.com
Bierman & Lengyel Expires April 25, 2009 [Page 12]
Internet-Draft with-defaults October 2008
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Bierman & Lengyel Expires April 25, 2009 [Page 13]