One document matched: draft-kwatsen-netmod-opstate-00.xml
<?xml version='1.0'?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY rfc6020 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6020.xml">
<!ENTITY rfc6241 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6241.xml">
]>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="no"?>
<?rfc subcompact="no"?>
<?rfc linkmailto="no" ?>
<?rfc editing="no" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes"?>
<?rfc rfcedstyle="yes"?>
<?rfc-ext allow-markup-in-artwork="yes" ?>
<?rfc-ext include-index="no" ?>
<!--<?rfc strict="no"?> -->
<rfc category="std"
ipr="trust200902"
docName="draft-kwatsen-netmod-opstate-00">
<front>
<title abbrev="Op-State Enhancements">Operational State Enhancements for YANG, NETCONF, and RESTCONF</title>
<author initials="K.W." surname="Watsen" fullname="Kent Watsen">
<organization>Juniper Networks</organization>
<address>
<email>kwatsen@juniper.net</email>
</address>
</author>
<author initials="A.B." surname="Bierman" fullname="Andy Bierman">
<organization>Yumaworks</organization>
<address>
<email>andy@yumaworks.com</email>
</address>
</author>
<author initials="M.B." surname="Bjorklund" fullname="Martin Bjorklund">
<organization>Tail-f Systems</organization>
<address>
<email>mbj@tail-f.com</email>
</address>
</author>
<author initials="J.S." surname="Schoenwaelder" fullname="Juergen Schoenwaelder">
<organization>Jacobs University Bremen</organization>
<address>
<email>j.schoenwaelder@jacobs-university.de</email>
</address>
</author>
<date/>
<area>Operations</area>
<workgroup>NETMOD Working Group</workgroup>
<abstract>
<t>This document presents enhancements to YANG, NETCONF, and
RESTCONF to better support the definition of and access to
operational state data.</t>
</abstract>
<!--
<note title="Editorial Note (To be removed by RFC Editor)">
<t>The following Appendix sections are to be removed prior to publication:
<list style="symbols">
<t>Appendix A. Change Log</t>
<t>Appendix B. Open Issues</t>
</list>
</t>
</note>
-->
</front>
<middle>
<section title="Introduction" anchor="intro">
<t>Support for operational state has been defined in YANG <xref target="RFC6020"/>,
NETCONF <xref target="RFC6241"/>, and RESTCONF <xref target="draft-ietf-netconf-restconf"/>
since their beginnings. However, after some operational experience, the support
defined by these standards has been found to be limiting
<xref target="draft-openconfig-netmod-opstate"/> as follows:
<list style="symbols">
<t>YANG
<list>
<t>Inability to associate operational state with configured state</t>
</list>
</t>
<t>NETCONF
<list>
<t>Inability to retrieve operational state without also retrieving running configuration</t>
<t>Inability to inspect the configuration as it is operationally running</t>
</list>
</t>
<t>RESTCONF
<list>
<t>Inability to inspect the configuration as it is operationally running</t>
</list>
</t>
</list>
</t>
<t>Addressing these limitations is the focus of this document.</t>
</section>
<section title="Terminology" anchor="terms">
<t>The following terms are defined in <xref target="draft-openconfig-netmod-opstate"/>,
but are redefined here as follows:
<list style="symbols">
<t>intended configuration - this data represents the configuration state that the network operator
intends the configuration controlled by the NETCONF/RESTCONF server to be in. In the NETCONF
protocol, the intended configuration is specified in the "running" datastore. In the RESTCONF
protocol, the intended configuration is specified in its conceptual datastore.</t>
<t>applied configuration - this data represents the configuration state that the NETCONF/RESTCONF
server is actually in, i.e., that which is currently being run by particular software
modules (e.g., the BGP daemon), or other systems within the server (e.g., a secondary
control-plane, or line card). The data model for applied configuration is the same as the
intended configuration's data model. That is, the applied configuration data model is
also defined by the config true nodes in YANG modules supported by the NETCONF/RESTCONF
server. The data within the applied configuration is the same as the data within the
intended configuration except as follows:
<list>
<t>When the intended configuration has not been communicated to an external
software entity</t>
<t>When post-processing or flattening of the intended configuration occurs to
present a simpler view to the external software entities</t>
</list>
The transition from intended config to applied config commences in NETCONF when
<edit-config> or <commit> is called, for :writable-running or :candidate respectively,
and in RESTCONF immediately whenever a POST, PUT, DELETE, or PATCH operation is
called. Neither NETCONF nor RESTCONF currently enable inspection of the applied
configuration.
</t>
<t>derived state - this data represents information which is
generated as part of the system's own interactions. For example,
derived state may consist of the results of protocol interactions
(the negotiated duplex state of an Ethernet link), statistics
(such as message queue depth), or counters (such as packet input
or output bytes). Derived stated is defined in YANG using config
false nodes, retrievable in NETCONF using the <get> RPC, and
retrievable in RESTCONF using the content=nonconfiguration query
parameter.</t>
</list>
</t>
<t>The following terms are defined in this document:
<list style="symbols">
<t>intended state - a synonym for "intended configuration".</t>
<t>operational state - the combination of applied state and derived state.</t>
</list>
</t>
<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 <xref target="RFC2119"/>.</t>
</section>
<section title="Conceptual Model" anchor="model">
<t>The following diagram illustrates the conceptual model presented
in this document:</t>
<figure>
<artwork><![CDATA[
+
intended | operational
state | state
|
|
+----------+ | +---------+
config true | intended | | | applied |
YANG nodes | config | | | config |
+----------+ | +---------+
|
+-------------------------------------------------------+
|
| +---------+
config false | | derived |
YANG nodes | | state |
| +---------+
|
+
]]></artwork>
</figure>
<t>Not illustrated in the diagram above:
<list style="symbols">
<t>The intended and applied configurations share the same
YANG-defined data model, specified by the config true nodes
in the YANG modules supported by the server.</t>
<t>The transition of the intended config to the applied
commences immediately, whenever the intended config
is updated.</t>
</list>
</t>
</section>
<section title="Enhancements to YANG" anchor="yang">
<section title="The related-state Statement">
<t>The "related-state" statement identifies a path to where
additional operational state associated for a config true
node can be found. This operational state being in addition
to any descendant config false nodes, which are implicitly
associated to the parent config true node.</t>
<t>The "related-state" statement takes as an argument a
string that is used to specify the path to a config false node
holding the associated operational state. The format of the
argument is the same as for the leafref's "path" statement,
Section 9.9.2 in <xref target="RFC6020"/>.</t>
<section title="YANG Module">
<figure>
<artwork>
module ietf-yang-related-state {
namespace urn:example:ietf-yang-related-state;
prefix yrs;
extension related-state {
argument path;
description
"The related-state statement is used to identify a node that
contains additional operational state associated for a config
true node.
The format of the argument is the same as for a leafref's "path"
statement.
The related-state statement can be specified in the following
YANG statements:
o leaf
o leaf-list
o container
o list
The related-state statement allows the following YANG substatements:
o description
Multiple related-state statements can be given in a specific node.";
}
}
</artwork>
</figure>
</section>
<section title="Usage Example">
<t>The following example illustrates the related-state statement in use:</t>
<figure>
<artwork><![CDATA[
module ex-interfaces {
namespace "http://example.com/interfaces";
prefix xif;
import ietf-yang-related-state {
prefix yrs;
}
container interfaces {
list interface {
key name;
yrs:related-state
"/interfaces-state/interface[name=current()/name]";
leaf name { type string }
leaf mtu { type uint16; }
...
}
}
container interfaces-state {
config false;
list interface {
key name;
leaf name { type string; }
...
}
}
}
]]></artwork>
</figure>
</section>
</section>
</section>
<section title="Enhancements to NETCONF" anchor="netconf">
<section title="The <get-state> Operation">
<t>One of the limitations identified in the <xref target="intro"/> section was the
inability for the NETCONF protocol to retrieve operational state without also
retrieving running configuration. That is, the only defined NETCONF operation
capable of returning operational state is the <get> operation (<xref
target="RFC6241"/>, Section 7.7), but it also returns the "running" configuration
for the nodes selected by the passed filter. While it is possible to construct
data-models whereby configuration and operational state are in completely
isolated sub-trees, and thereby eliminate the retrieval of configuration when
selecting an operational state node, requiring all models to be structured this
way is not ideal.</t>
<section title="YANG Module">
<figure>
<artwork>
module ietf-netconf-get-state {
namespace urn:example:ietf-netconf-get-state;
prefix ncgs;
import ietf-netconf {
prefix nc;
}
rpc get-state {
description
"Retrieve device state information.";
reference "RFC 6241, Section 7.7";
input {
anyxml filter {
description
"This parameter specifies the portion of the system
configuration and state data to retrieve.";
nc:get-filter-element-attributes;
}
}
output {
anyxml data {
description
"Copy of the running datastore subset and/or state
data that matched the filter criteria (if any).
An empty data container indicates that the request
did not produce any results.";
}
}
}
}
</artwork>
</figure>
</section>
</section>
<section title="The Applied Configuration Capability">
<section title="Description">
<t>The applied configuration capability indicates that the
device supports an applied configuration datastore, which is used to
hold a read-only copy of configuration data as it is known to the
operational components of the system (e.g., the data plane).</t>
<t>The applied configuration datastore contains applied configuration,
as defined in <xref target="terms"/>. </t>
</section>
<section title="Dependencies">
<t>None.</t>
</section>
<section title="Capability Identifier">
<t>The :applied capability is identified by the following capability string:
<list style="empty">
<t>:ietf:params:netconf:capability:applied:1.0</t>
</list>
</t>
</section>
<section title="New Operations">
<t>None.</t>
</section>
<section title="Modifications to Existing Operations">
<t>The :applied capability enables <applied/> to be passed as the <source>
argument to the <get-config> and <copy-config> operations.</t>
<t>The :applied capability does not modify any other existing operations. In
particular, the <applied/> value may not be used as the <target> argument
to any operation.</t>
<t>Note, the :applied capability has no impact to the <get> operation because
the <get> operation is defined as returning the "running" configuration, without
any <source> parameter to specify otherwise.</t>
<t>The <applied/> parameter is formally defined in <xref target="yang-mod-applied"/>.</t>
</section>
<section title="YANG Module" anchor="yang-mod-applied">
<figure>
<artwork>
module ietf-netconf-applied-config {
namespace urn:example:ietf-netconf-applied-config;
prefix ncac;
import ietf-netconf {
prefix nc;
}
augment /nc:get-config/nc:input/nc:source/nc:config-source {
leaf applied {
type empty;
}
}
augment /nc:copy-config/nc:input/nc:source/nc:config-source {
leaf applied {
type empty;
}
}
}
</artwork>
</figure>
</section>
<section title="Example">
<t>To retrieve the "/interfaces" subtree from the applied
configuration datastore:</t>
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<applied xmlns="urn:example:ietf-netconf-applied-config"/>
</source>
<filter type="subtree">
<interfaces xmlns="http://example.com/interfaces"/>
</filter>
</get-config>
</rpc>
]]></artwork>
</figure>
</section>
</section>
</section>
<section title="Enhancements to RESTCONF" anchor="restconf">
<section title="The Applied Configuration Capability">
<section title="Description">
<t>The applied configuration capability indicates that the
device supports an applied configuration datastore, which is used to
hold a read-only copy of configuration data as it is known to the
operational components of the system (e.g., the data plane).</t>
<t>The applied configuration datastore contains applied configuration,
as defined in section <xref target="terms"/>. </t>
</section>
<section title="The applied capability">
<t>A RESTCONF server supports the applied configuration datastore when it
presents the following URI in its "capability" leaf-list, as defined in
<xref target="RFC6241"/>, Section 9.3.</t>
<figure>
<artwork><![CDATA[
urn:ietf:params:restconf:capability:applied:1.0
]]></artwork>
</figure>
</section>
<section title="The "applied" Query Parameter">
<t>The "applied" parameter is only available when the RESTCONF server supports
the "urn:ietf:params:restconf:capability:applied:1.0" capability.</t>
<t>The "applied" parameter is used to specify that the GET request should
be directed to the applied configuration datastore.</t>
<t>The "applied" parameter does not have a value assignment.</t>
<t>This parameter is only allowed for GET methods on API, datastore, and
data resources. A 400 Bad Request error is returned if it used for
other methods or resource types.</t>
</section>
</section>
</section>
<section title="Security Considerations" anchor="sec-con">
<t>TBD</t>
</section>
<section title="IANA Considerations" anchor="iana-con">
<t>TBD</t>
</section>
<section title="Acknowledgements">
<t>TBD</t>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2119;
&rfc6241;
&rfc6020;
<reference anchor="draft-ietf-netconf-restconf" target="https://tools.ietf.org/html/draft-ietf-netconf-restconf">
<front>
<title>
RESTCONF Protocol
</title>
<author initials='A.B.' surname='Bierman' fullname='Andy Bierman'>
<organization>YumaWorks</organization>
</author>
<author initials='M.B.' surname='Bjorklund' fullname='Martin Bjorklund'>
<organization>Tail-f Systems</organization>
</author>
<author initials='K.W.' surname='Watsen' fullname='Kent Watsen'>
<organization>Juniper Networks</organization>
</author>
<date year='2014' />
</front>
<seriesInfo name='Internet-Draft' value='draft-ieft-netconf-restconf-04' />
</reference>
</references>
<references title="Informative References">
<reference anchor="draft-openconfig-netmod-opstate" target="https://tools.ietf.org/html/draft-openconfig-netmod-opstate">
<front>
<title>Consistent Modeling of Operational State Data in YANG</title>
<author initials="R.S." surname="Shakir" fullname="Rob Shakir">
</author>
<author initials="A.S." surname="Shaikh" fullname="Anees Shaikh">
<organization>Google</organization>
</author>
<author initials="M.H." surname="Hines" fullname="Marcus Hines">
<organization>Google</organization>
</author>
<date year="2015"/>
</front>
</reference>
</references>
<!--
<section title="Change Log">
<section title="00 to 01">
<t>
<list style="symbols">
</list>
</t>
</section>
</section>
<section title="Open Issues">
<t>TBD</t>
</section>
-->
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 04:10:52 |