One document matched: draft-bierman-netconf-with-defaults-00.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY xsdspec PUBLIC '' 'reference.W3C.REC-xmlschema-2.xml'>
]>
<rfc category="std" docName="draft-bierman-netconf-with-defaults-00" ipr="full3978">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes"?>
<?rfc comments="no" ?>
<?rfc inline="no" ?>
<?rfc editing="no" ?>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="no" ?>
<?rfc compact="yes"?>
<?rfc iprnotified="no"?>
<front>
<title abbrev="with-defaults">
With-defaults capability for NETCONF
</title>
<author fullname="Andy Bierman" initials="A.B."
surname="Bierman">
<organization>netconfcentral.org</organization>
<address>
<postal>
<street></street>
<city>Simi Valley</city>
<region>CA</region>
<code></code>
<country>USA</country>
</postal>
<email>ietf@andybierman.com</email>
</address>
</author>
<author fullname="Balazs Lengyel" initials="B. L."
surname="Lengyel">
<organization>Ericsson</organization>
<address>
<postal>
<street></street>
<city></city>
<region></region>
<code></code>
<country>Hungary</country>
</postal>
<email>balazs.lengyel@ericsson.com</email>
</address>
</author>
<date month="August" year="2008" />
<area>OPS</area>
<workgroup>NETCONF</workgroup>
<keyword>with-defaults</keyword>
<keyword>XML</keyword>
<abstract>
<t>
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 set to a default value by the NETCONF agent. In many situations the
NETCONF manager has a priori knowledge about this 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 to
the NETCONF protocol that allows the NETCONF manager to control whether
default values are part of NETCONF rpc reply messages.
</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
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 set to a default value by the NETCONF agent. In many situations the
NETCONF manager has a priori knowledge about this 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.
It is quite common for networking devices to
suppress the output of parameters set to the default value.
This is done to save CPU time and non-volatile memory.
In addition, there are likely to be a large number of
such parameters. Is is often not useful for network operators
to view all these default values. It is usually more
interesting to view just the parameters which have
been explicitly set by the network operator.
<vspace blankLines="1"/>
However there are perfectly valid use-cases when a NETCONF manager
will need the default data from the node. Documentation about default values
is often unreliable or unavailable. Some management
applications might not have the capabilities to correctly parse and interpret
formal data models. Human users might want to understand the received
data without extensive consultation of the documentation. In all theses cases
the NETCONF manager will need default data as part of the NETCONF rpc reply messages.
<vspace blankLines="1"/>
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.
</t>
<section title="Terminology">
<section title="Requirements Notation">
<t>
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 <xref target="RFC2119"/>.
</t>
</section>
<section title="NETCONF Terms">
<t>
<list style="symbols">
<t>Default data: Data that is set 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. <vspace blankLines="1"/></t>
<t>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
default data, as they might not be able to differentiate between them.</t>
</list>
</t>
<t>
In addition the following terms are defined in RFC 4741 and are not redefined here:
<list style="symbols">
<t>agent</t>
<t>application</t>
<t>manager</t>
<t>operation</t>
<t>RPC</t>
<t>RPC request</t>
<t>RPC response</t>
</list>
</t>
</section>
</section>
</section>
<section title="With-defaults Capability">
<section title="Overview"><t>
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 default behavior, whether it sends default data in
the absence of any specific request from the NETCONF manager.
<vspace blankLines="1"/>
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.
<vspace blankLines="1"/>
TODO: what about model defined RPCs? Will they be effected? How can it be stated in YANG whether yes or no?
</t>
<section title="Basic handling of default data">
<t>
It is not defined in <xref target="RFC4741"/> whether default data is part of the datastore/data
model, or if it 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.
The described functionality should work in both cases.
<vspace blankLines="1"/>
As a consequence of this issue basic
NETCONF servers that do not implement the :with-defaults capability may or may not
return default data in NETCONF rpc reply messages.
</t>
</section>
</section>
<section title="Dependencies"><t>None</t></section>
<section title="Capability Identifier" anchor="capabilityIdChapter">
<t>
urn:ietf:params:netconf:capability:with-defaults
<vspace blankLines="1"/>
The identifier MUST have an additional parameter indicating the default value of with-defaults for the NETCONF agent.
The allowed values of with-defaults attribute can be used as a default value see <xref target="modifications"/>.
<vspace blankLines="1"/>
urn:ietf:params:netconf:capability:with-defaults?default=false
<vspace blankLines="1"/>
The identifier MAY have a second parameter indicating how it treats
explicitly set default data. If the explicit-default parameter is set to "unrecognized" the agent MUST treat explicitly set default data as normal default data.
If the parameter is set to recognized this means that such data is not treated as default data.
All other values for the parameter or a missing parameter is handled as the value unrecognized.
<vspace blankLines="1"/>
urn:ietf:params:netconf:capability:with-defaults?default=false&explicit-default=recognized
</t>
</section>
<section title="New Operations"><t>None</t></section>
<section title="Modifications to Existing Operations" anchor="modifications">
<t>
A new 'with-defaults' XML attribute is used
to control the generation of default data.
If the 'with-defaults' attribute is present in the <rpc>
element, of the affected operations, the agent will
use it's value to control whether
default data is returned in the NETCONF rpc reply messages.
</t>
<t>
Allowed values of the with-defaults attribute are:
<list style="symbols">
<t>true: indicates that all default data MUST be returned.</t>
<t>false: indicates that default data MUST NOT be returned.</t>
</list>
</t>
<t>
The 'with-defaults' attribute is defined in the
namespace specified as the 'targetNamespace' in
<xref target="XSD"/>. However, an agent should
accept it even if no namespace is used.
</t>
<t>
If the 'with-defaults' attribute is not present it's default value as specified in
the capability string <xref target="capabilityIdChapter"/> will be used.
</t>
</section>
<t>
Affected operations:
<list style="symbols">
<t><get></t>
<t><get-config></t>
<t><copy-config></t>
</list>
<vspace blankLines="1"/>
Index clause components are not subject to default suppression.
If an element within the configuration database
is considered to be part of a key, and represents
one of the naming components for a conceptual
data structure which allows multiple named instances
of an ancestor node, then this element is never
suppressed, regardless of the value of the 'with-defaults'
attribute.
</t>
<t>
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 MTU value of '1500' is not returned
for the interface named 'Eth1' because it is set
to the default value, and the 'with-defaults'
attribute is set to 'false'.
</t>
<t>
<figure anchor="with_defaults_example">
<artwork>
<![CDATA[
<rpc message-id="102" with-defaults="false"
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="false"
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>
</interface>
<interface>
<name>loopback</name>
<mtu>8192</mtu>
</interface>
</interfaces>
</data>
</rpc-reply>
]]>
</artwork>
</figure>
</t>
</section>
<section title="Interactions with Other Capabilities"><t>None</t></section>
<section title="Data Model XSD" anchor="XSD">
<t>
This section contains an XML Schema Definition
<xref target="W3C.REC-xmlschema-2-20041028"/> which
defines the XML syntax associated for the with-defaults XML attribute..
</t>
<t>
<figure anchor="NCX-ACM_XSD">
<artwork>
<![CDATA[
BEGIN
<?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" version="1.0" >
<xs:annotation>
<xs:documentation>
Schema defining the partial-lock and unlock operations.
organization "IETF NETCONF Working Group"
Version: 1.0
Contact Info: ietf@andybierman.com
balazs.lengyel@ericsson.com
</xs:documentation>
</xs:annotation>
<xs:attribute name="with-defaults"
type="xs:boolean"/>
</xs:schema>
END
]]>
</artwork>
</figure>
</t>
</section>
<!-- Possibly a 'Contributors' section ... -->
<section anchor="IANA" title="IANA Considerations">
<t>This document registers two URIs for the NETCONF XML namespace in
the IETF XML registry <xref target="RFC3688"></xref>. Note that the capability URN is compliant to
<xref target="RFC4741"></xref> section 10.3.</t>
<texttable>
<ttcol align="left" width="20%">Index</ttcol>
<ttcol align="left">Capability Identifier</ttcol>
<c>:with-defaults</c>
<c>urn:ietf:params:netconf:capability:with-defaults:1.0</c>
</texttable>
<?rfc compact="no"?>
<t>URI: urn:ietf:params:xml:ns:netconf:with-defaults:1.0
<vspace blankLines="1"/>
Registrant Contact: The IESG.
<vspace blankLines="1"/>
XML: N/A, the requested URI is an XML namespace.
</t>
</section>
<section anchor="Security" title="Security Considerations">
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title="Open Issues">
<section title="Augmenting the base RPCs">
<t>
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.
<vspace blankLines="1"/>
Pro: parameters on RPC are for vendor extensions. We should not put standard stuff there.
<vspace blankLines="1"/>
Contra: Some people might consider this a violation of <xref target="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.
<vspace blankLines="1"/>
Conclusion: While augmenting has a certain elegance, we should stick to the attribute based solution.
</t>
</section>
<section title="Third option: Trim">
<t>
This is another can o' worms. I preserve user specified values
even when the value matches the default. This allows users complete
control over what appears in their config. Values to not disappear
simply because the match the default.
<vspace blankLines="1"/>
If you want this behavior, I'd suggest making your "with-defaults"
a tri-state value:
<vspace blankLines="1"/>
<list>
<t>"all" -- report all default values</t>
<t>"trim" -- do not report values if they match the default</t>
<t>"explicit" -- report any values explicitly set</t>
</list>
Do we need the trim option ?
</t>
</section>
<section title="List affected operations or generalize">
<t>
Should we list affected operations <get>, <get-config>, <copy-config>
or should we just say "any of the protocol operations which return
the contents of a configuration database", or should we do both?
</t>
</section>
</section>
</middle>
<!-- ***** BACK MATTER ***** -->
<back>
<references title="Normative References">
&xsdspec;
<reference anchor='RFC4741'>
<front>
<title>NETCONF Configuration Protocol</title>
<author initials='R.' surname='Enns' fullname='R. Enns'>
<organization /></author>
<date year='2006' month='December' />
<abstract>
<t>The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized on top of a simple Remote Procedure Call (RPC) layer. [STANDARDS TRACK]</t></abstract></front>
<seriesInfo name='RFC' value='4741' />
<format type='TXT' octets='173914' target='ftp://ftp.isi.edu/in-notes/rfc4741.txt' />
</reference>
<reference anchor='RFC2119'>
<front>
<title abbrev='RFC Key Words'>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='Scott Bradner'>
<organization>Harvard University</organization>
<address>
<postal>
<street>1350 Mass. Ave.</street>
<street>Cambridge</street>
<street>MA 02138</street></postal>
<phone>- +1 617 495 3864</phone>
<email>sob@harvard.edu</email></address></author>
<date year='1997' month='March' />
<area>General</area>
<keyword>keyword</keyword>
<abstract>
<t>
In many standards track documents several words are used to signify
the requirements in the specification. These words are often
capitalized. This document defines these words as they should be
interpreted in IETF documents. Authors who follow these guidelines
should incorporate this phrase near the beginning of their document:
<list>
<t>
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
RFC 2119.
</t></list></t>
<t>
Note that the force of these words is modified by the requirement
level of the document in which they are used.
</t></abstract></front>
<seriesInfo name='BCP' value='14' />
<seriesInfo name='RFC' value='2119' />
<format type='TXT' octets='4723' target='ftp://ftp.isi.edu/in-notes/rfc2119.txt' />
<format type='HTML' octets='17491' target='http://xml.resource.org/public/rfc/html/rfc2119.html' />
<format type='XML' octets='5777' target='http://xml.resource.org/public/rfc/xml/rfc2119.xml' />
</reference>
<reference anchor='RFC3688'>
<front>
<title>The IETF XML Registry</title>
<author initials='M.' surname='Mealling' fullname='M. Mealling'>
<organization /></author>
<date year='2004' month='January' />
<abstract>
<t>This document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas.</t></abstract></front>
<seriesInfo name='BCP' value='81' />
<seriesInfo name='RFC' value='3688' />
<format type='TXT' octets='17325' target='ftp://ftp.isi.edu/in-notes/rfc3688.txt' />
</reference>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 08:54:44 |