Network Working Group A. Bierman
Internet-Draft YumaWorks
Intended status: Standards Track October 9, 2012
Expires: April 12, 2013
The NETCONF <get2> Operation
draft-bierman-netconf-get2-02
Abstract
This document describes NETCONF protocol enhancements to improve data
retrieval capabilities.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on April 12, 2013.
Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
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 Simplified BSD License.
Bierman Expires April 12, 2013 [Page 1]
Internet-Draft <get2> October 2012
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Problem Statement . . . . . . . . . . . . . . . . . . . . 3
1.1.1. Wrong Data Type Returned . . . . . . . . . . . . . . . 3
1.1.2. No Last-Modified Indication or Time Filtering . . . . 3
1.1.3. No Simple Instance Discovery Mechanism . . . . . . . . 3
1.1.4. No Subtree Depth Control . . . . . . . . . . . . . . . 4
1.1.5. Content Filter Specification is not Extensible . . . . 4
1.1.6. Source of Operational Data Unknown . . . . . . . . . . 4
1.2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
1.3.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 5
1.3.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3.3. Terms . . . . . . . . . . . . . . . . . . . . . . . . 6
2. <get2> Operation . . . . . . . . . . . . . . . . . . . . . . . 7
2.1. Depth Filters . . . . . . . . . . . . . . . . . . . . . . 7
2.2. Time Filters . . . . . . . . . . . . . . . . . . . . . . . 8
3. Operational Data Source Reporting . . . . . . . . . . . . . . 9
3.1. Identifying Data Sources . . . . . . . . . . . . . . . . . 9
4. XSD for the "last-modified" Attribute . . . . . . . . . . . . 10
5. XSD for the "data-source" Attribute . . . . . . . . . . . . . 11
6. data-source YANG Module . . . . . . . . . . . . . . . . . . . 12
7. <get2> YANG Module . . . . . . . . . . . . . . . . . . . . . . 15
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
9. Security Considerations . . . . . . . . . . . . . . . . . . . 22
10. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 23
10.1. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 23
10.2. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 23
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24
11.1. Normative References . . . . . . . . . . . . . . . . . . . 24
11.2. Informative References . . . . . . . . . . . . . . . . . . 24
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 25
A.1. YANG Module Used in Examples . . . . . . . . . . . . . . . 25
A.2. YANG Data Used in Examples . . . . . . . . . . . . . . . . 26
A.3. Example: Operational Datastore . . . . . . . . . . . . . . 26
A.4. Example: If-Modified-Since Non-Empty Filter Retrieval . . 28
A.5. Example: If-Modified-Since Empty Filter Retrieval . . . . 29
A.6. Example: Keys Only Filter Retrieval . . . . . . . . . . . 30
A.7. Example: Testing for Node Existence with Depth=1 . . . . . 31
A.8. Example: Keys Only Filter Retrieval with Depth=3 . . . . . 32
A.9. Example: Operational Data Sources (tree height) . . . . . 33
A.10. Example: Operational Data Sources (ietf-system) . . . . . 35
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 38
Bierman Expires April 12, 2013 [Page 2]
Internet-Draft <get2> October 2012
1. Introduction
There is a need for standard mechanisms to allow NETCONF [RFC6241]
application designers to retrieve data from NETCONF servers more
efficiently.
1.1. Problem Statement
This document attempts to address the following problems with NETCONF
data retrieval mechanisms.
1.1.1. Wrong Data Type Returned
The NETCONF <get> operation allows a client to retrieve data from the
server but it returns all data, including configuration datastore
nodes. The <get-config> operation already returns all configuration
datastore nodes.
It was originally thought that <get> should return all nodes so the
client would not have to correlate configuration and non-
configuration data nodes, since they would be mixed together in the
reply.
Operational experience has shown that the <get> operation without
reasonable filters to reduce the returned data can significantly
degrade device performance and return enormous XML instance documents
in the <rpc-reply>.
1.1.2. No Last-Modified Indication or Time Filtering
The NETCONF protocol has no standard mechanisms to indicate to a
client when a datastore was last modified, or to allow a client to
retrieve data only if it has been modified since a specified time.
This makes polling applications very inefficient because they will
regularly burden the server and the network and themselves with
retrieval and processing requests for data that has not changed.
1.1.3. No Simple Instance Discovery Mechanism
Sometimes the client application wants to discover what data exists
on the server, particularly list entries. There is a need for a
simple mechanism to retrieve just the key leaf nodes within a
subtree.
The NETCONF subtree filtering mechanism does provide a very complex
way for the client to request just key leafs for specific list
entries. A simpler mechanism is needed which will allow the client
to discover the list instances present.
Bierman Expires April 12, 2013 [Page 3]
Internet-Draft <get2> October 2012
1.1.4. No Subtree Depth Control
NETCONF filters allow the client to select specific sub-trees within
the conceptual datastore on the server. However, sometimes the
client does not really need the entire subtree, which may contain
many nested list entries, and be very large.
There is sometimes a need to limit the depth of the sub-trees
retrieved from the server. A consistent and simple algorithm for
determining what data nodes start a new level is needed.
1.1.5. Content Filter Specification is not Extensible
The NETCONF <get> and <get-config> operations use a hard-coded
content filtering mechanism. They use a "type" XML attribute to
indicate which of two filter specification types they support, and a
"select" XML attribute if the :xpath capability is supported and an
XPath [XPATH] expression filter specification is provided.
This design does not allow additional content filter specification
types to be supported by an implementation. It does not allow the
standard to be easily extended in a modular fashion.
In addition, this design does not allow YANG statements to be used to
properly describe the protocol operation. The special
"get-filter-element-attributes" YANG extension in the ietf-netconf
module is not extensible, and it does not really count as proper
YANG, since this extension is outside the YANG language definition.
1.1.6. Source of Operational Data Unknown
The operational data nodes returned by the server can sometimes
represent server state parameters which may be derived from different
sources.
For example, an operational node representing the current date and
time in use on a system might be derived from the Network Time
Protocol (NTP) or from an action operation to set the current time.
A list representing a routing entries in use in a router might
include entries learned from a routing protocol and entries
statically configured in the running datastore.
There is a need for standard mechanisms to:
o identify data-model specific sources of operational data.
Bierman Expires April 12, 2013 [Page 4]
Internet-Draft <get2> October 2012
o identify which nodes in a datastore that the server should
maintain data source information
o allow the client to retrieve the data source information.
1.2. Solution
This document defines a new NETCONF protocol operation called <get2>
to address the deficiencies described in the previous section. It
can be implemented existing NETCONF servers without requiring a
change in the protocol version.
1.3. Terminology
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14, [RFC2119].
1.3.1. NETCONF
The following terms are defined in [RFC6241]:
o candidate configuration datastore
o client
o configuration data
o datastore
o configuration datastore
o protocol operation
o running configuration datastore
o server
o startup configuration datastore
1.3.2. YANG
The following terms are defined in [RFC6020]:
o anyxml
Bierman Expires April 12, 2013 [Page 5]
Internet-Draft <get2> October 2012
o container
o data node
o key leaf
o leaf
o leaf-list
o list
o presence container (or P-container)
o non-presence container (or NP-container)
1.3.3. Terms
The following terms are defined:
o non-configuration data node: a data node which is not a
configuration data node, i.e. config=false.
o operational datastore: the collection of all conceptual YANG data
nodes which represent non-configuration data. This conceptual
datastore also includes ancestor container and list nodes for any
nested non-configuration data nodes, as well as list keys for any
list data nodes in this datastore.
o operational data node: A data node which is is contained within
the operational datastore. Ancestor container, list, and key leaf
nodes for any nested non-configuration nodes are only operational
data nodes if they are also non-configuration data nodes.
o depth filter: A mechanism implemented within the NETCONF server to
allow a client to retrieve only a limited number of levels within
the a subtree, instead of retrieving the entire subtree.
o time filter: A mechanism implemented within the NETCONF server to
allow a client to retrieve only data that has been modified since
a specified data and time.
Bierman Expires April 12, 2013 [Page 6]
Internet-Draft <get2> October 2012
2. <get2> Operation
The <get2> operation is defined with a YANG "rpc" statement. A
specific datastore is selected for the source of the retrieval
operation. Several different types of filters are provided. Filters
are combined in a conceptual "logical-AND" operation, and are
optional to use by the client. Not all filtering mechanisms are
mandatory-to-implement for the server.
The <get2> protocol operation contains the following input
parameters:
o source: A container indicating the conceptual datastore for the
retrieval request.
o filter-spec: A choice indicating the content filter specification
for the retrieval request.
o keys-only: A leaf indicating that only the key leafs, combined
with other filtering criteria, should be returned.
o if-modified-since: A leaf indicating the time filter specification
for the retrieval request, according to the procedures in
Section 2.2.
o depth: A leaf indicating the subtree depth level for the retrieval
request, according to the procedures in Section 2.1.
o with-defaults: A leaf indicating the type of defaults handling
requested, according to procedures in [RFC6243].
o with-timestamps: A leaf indicating that "last-modified" XML
attributes are requested, encoded according to the schema in
Section 4.
o with-data-sources: A leaf indicating that "data-source" XML
attributes are requested, encoded according to the schema in
Section 5.
2.1. Depth Filters
A depth filter indicates how many subtree levels should be returned
in the <rpc-reply>. This filter is specified with the "depth" input
parameter for the <get2> protocol operation. The default "0"
indicates that all levels from the requested subtrees should be
returned.
A new level is started for each YANG data node within the requested
Bierman Expires April 12, 2013 [Page 7]
Internet-Draft <get2> October 2012
subtree. All top level data nodes are considered to be child nodes
(level 1) of a conceptual <config> root.
If no content filters are provided, then level 1 is considered to
include all top-level data nodes within the source datastore.
Otherwise only the levels in selected subtrees will be considered,
and not any additional top-level data nodes.
If the depth requested is equal to "1", then only the requested data
nodes (or top-level data nodes) will be returned. This mechanism can
be used to detect the existence of containers and list entries within
a particular subtree, without returning any of the descendant nodes.
Higher depth values indicates the number of descendant nodes to
include in the response. For example, if the depth requested is
equal to "2", then only the requested data nodes (or top-level data
nodes) and their immediate child data nodes will be returned.
2.2. Time Filters
A time filter indicates that only data which has been modified since
the indicated date and time should be included in the reply.
If this feature is supported, then the server will maintain a last-
modified timestamp for the source datastore. It MAY support
additional nested timestamps for data nodes within the datastore.
When a request containing the "if-modified-since" parameter is
received, the server will compare that timestamp to the last-modified
timestamp for the source datastore. If it is greater than the
specified value then data may be returned (depending on other
filters). If the datastore timestamp value is less than or equal to
the specified value, then an empty <data> element will be returned in
the <rpc-reply>.
If the server maintains "last-modified" timestamps for any data nodes
within the source datastore then the same type of comparison will be
done for the data node to determine if it should be included in the
response. If no "last-modified" timestamp is maintained for a data
node, then the server will use the "last-modified" timestamp for its
nearest ancestor, or for the datastore itself if there are none.
Bierman Expires April 12, 2013 [Page 8]
Internet-Draft <get2> October 2012
3. Operational Data Source Reporting
Operational data source reporting is supported if the server
advertises the "data-source" feature.
If the "with-data-sources" parameter is present in the <get2>
request, and the server supports the "data-source" feature, then data
source reporting will be done for the applicable nodes.
An operational data source applies only to operational data nodes,
and only if the "data-source" YANG extension statement defined in
Section 6 is present in the YANG data definition statement for the
data node.
If the "data-source" extension applies to a data node, then a server
that implements the "data-source" feature is expected to return the
"data-source" XML attribute for that node.
3.1. Identifying Data Sources
Operational data sources are defined with YANG identity statements.
The YANG module in Section 6 contains the base identity
"data-sources", and a few common data sources:
o server: normal case: the server instrumentation is the source of
the operational data value.
o running: the operational data value is derived from a value in the
running configuration datastore.
o operation: the operational data value is derived from a direct or
side effect of a client-initiated protocol operation.
o ntp: the operational data value is derived from NTP information
o dns: the operational data value is derived from DNS information
Other modules can define new data source identities, such as the
"thfp" protocol in the "example-get2" module.
The "data-source" YANG extension is defined in Section 6. It is used
within other YANG modules to identify which operational data nodes
should have data source information maintained by the server.
Bierman Expires April 12, 2013 [Page 9]
Internet-Draft <get2> October 2012
4. XSD for the "last-modified" Attribute
The following XML Schema document [XSD] defines the "last-modified"
attribute, described within this document. This XSD is only relevant
if the server supports the "timestamps" YANG feature within the
"ietf-netconf-get2" YANG module.
The "last-modified" attribute uses the XSD data type "dateTime", in
accordance with Section 3.2.7.1 of XML Schema Part 2: Datatypes.
This is equivalent to the YANG data type "date-and-time".
<CODE BEGINS> file "last-modified.xsd"
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:netconf:default:1.0"
targetNamespace="urn:ietf:params:xml:ns:netconf:last-modified:1.0"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
xml:lang="en">
<xs:annotation>
<xs:documentation>
This schema defines the syntax for the "last-modified" attribute
described within this document.
</xs:documentation>
</xs:annotation>
<!--
last-modified attribute
-->
<xs:attribute name="last-modified" type="xs:dateTime">
<xs:annotation>
<xs:documentation>
This attribute indicates the date and time when
a modification was last detected by the server
for the datastore or data node corresponding to
the XML element containing this attribute.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:schema>
<CODE ENDS>
Bierman Expires April 12, 2013 [Page 10]
Internet-Draft <get2> October 2012
5. XSD for the "data-source" Attribute
The following XML Schema document [XSD] defines the "data-source"
attribute, described within this document. This attribute uses the
XSD data type "QName", in accordance with Section 3.2.18.1 of XML
Schema Part 2: Datatypes.
This is an XML encoding of the YANG "identityref" data type:
o the module namespace statement value for the YANG module
containing the identity statement is represented in
the"namespace-name" part.
o the identity name is represented in the local part.
<CODE BEGINS> file "data-source.xsd"
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:netconf:default:1.0"
targetNamespace="urn:ietf:params:xml:ns:netconf:data-source:1.0"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
xml:lang="en">
<xs:annotation>
<xs:documentation>
This schema defines the syntax for the "data-source" attribute
described within this document.
</xs:documentation>
</xs:annotation>
<!--
data-source attribute
-->
<xs:attribute name="data-source" type="xs:QName">
<xs:annotation>
<xs:documentation>
This attribute indicates the identity statement
for the configuration source for the data node
corresponding to the XML element containing this
attribute.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:schema>
<CODE ENDS>
Bierman Expires April 12, 2013 [Page 11]
Internet-Draft <get2> October 2012
6. data-source YANG Module
RFC Ed.: update the date below with the date of RFC publication and
remove this note.
<CODE BEGINS> file "ietf-netconf-data-source@2012-10-09.yang"
module ietf-netconf-data-source {
namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-data-source";
prefix datasrc;
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: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com>
WG Chair: Bert Wijnen
<mailto:bertietf@bwijnen.net>
Editor: Andy Bierman
<mailto:andy@yumaworks.com>";
description
"This module contains a collection of YANG definitions for
identifying the data source of operational data nodes.
Copyright (c) 2012 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
Bierman Expires April 12, 2013 [Page 12]
Internet-Draft <get2> October 2012
// RFC Ed.: remove this note
// Note: extracted from draft-bierman-netconf-get2-02.txt
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
revision "2012-10-09" {
description
"Initial revision.";
reference
"RFC XXXX: The NETCONF <get2> Operation";
}
/* Extensions */
extension data-source {
description
"This extension indicates that the data node containing it
is expected to support the 'data-source' XML attribute
in replies for the <get2> operation.
This extension is ignored if it is not within a YANG
data definition statement for an operational data node.";
}
/* Identities */
identity data-sources {
description
"Base identity for all data sources.";
}
identity server {
base data-sources;
description
"Indicates the server instrumentation as the data source.";
}
identity running {
base data-sources;
description
"Indicates the running datastore as the data source.";
}
identity operation {
base data-sources;
description
"Indicates a client-initiated protocol operation as
the data source.";
Bierman Expires April 12, 2013 [Page 13]
Internet-Draft <get2> October 2012
}
identity ntp {
base data-sources;
description
"Indicates the NTP protocol as the data source.";
reference
"RFC 5905: Network Time Protocol Version 4:
Protocol and Algorithms Specification";
}
identity dns {
base data-sources;
description
"Indicates the DNS protocol as the data source.";
// reference TBD
}
}
<CODE ENDS>
Bierman Expires April 12, 2013 [Page 14]
Internet-Draft <get2> October 2012
7. <get2> YANG Module
This module imports the "with-defaults-parameters" grouping from
[RFC6243].
Several YANG features are imported from [RFC6241].
Some data types are imported from [RFC6021].
RFC Ed.: update the date below with the date of RFC publication and
remove this note.
<CODE BEGINS> file "ietf-netconf-get2@2012-10-09.yang"
module ietf-netconf-get2 {
namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-get2";
prefix get2;
import ietf-inet-types {
prefix inet;
}
import ietf-netconf {
prefix nc;
}
import ietf-netconf-with-defaults {
prefix ncwd;
}
import ietf-yang-types {
prefix yang;
}
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: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com>
WG Chair: Bert Wijnen
<mailto:bertietf@bwijnen.net>
Bierman Expires April 12, 2013 [Page 15]
Internet-Draft <get2> October 2012
Editor: Andy Bierman
<mailto:andy@yumaworks.com>";
description
"This module contains a collection of YANG definitions for the
retrieval of information from a NETCONF server.
Copyright (c) 2012 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
// RFC Ed.: remove this note
// Note: extracted from draft-bierman-netconf-get2-02.txt
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
revision "2012-10-09" {
description
"Initial revision.";
reference
"RFC XXXX: The NETCONF <get2> Operation";
}
/* Features */
feature timestamps {
description
"This feature indicates that the server implements
the <get2> operations parameters which require
last modification timestamps to be maintained by
the server.
If this feature is advertised then one global
'last-modified' timestamp for the entire
running datastore MUST be supported.
Bierman Expires April 12, 2013 [Page 16]
Internet-Draft <get2> October 2012
The server MAY support additional timestamps
for additional datastores and data nodes
within a datastore. The 'with-timestamps'
parameter can be used to identify
which data nodes support a last-modified-time
timestamp.";
}
feature with-defaults {
description
"This feature indicates that the server supports the
'with-defaults' parameter for the <get2> operation.
A NETCONF server SHOULD support this feature.";
reference
"RFC 6243: With-defaults Capability for NETCONF";
}
feature data-sources {
description
"This feature indicates that the server supports the
'with-data-sources' parameter for the <get2> operation.
A NETCONF server SHOULD support this feature.";
reference
"RFC XXXX: The NETCONF <get2> Operation";
}
/* Protocol Operations */
rpc get2 {
description
"Retrieve NETCONF datastore information";
input {
container source {
choice datastore-source {
default running;
description
"The configuration source for the retrieval operation.
The running configuration is the default choice if
this parameter is not present.";
leaf candidate {
if-feature nc:candidate;
type empty;
description
"The candidate configuration datastore is the
retrieval source.";
}
leaf running {
type empty;
Bierman Expires April 12, 2013 [Page 17]
Internet-Draft <get2> October 2012
description
"The running configuration datastore is the
retrieval source.";
}
leaf operational {
type empty;
description
"The collection of non-configuration
data nodes supported by the server is the
retrieval source.";
}
leaf startup {
if-feature nc:startup;
type empty;
description
"The startup configuration datastore is the
retrieval source.";
}
leaf url {
if-feature nc:url;
type inet:uri;
description
"The URL-based configuration is the
retrieval source.";
}
}
}
choice filter-spec {
anyxml subtree-filter {
description
"This parameter identifies the portions of the
target datastore to retrieve.";
reference "RFC 6241, Section 6.";
}
leaf xpath-filter {
if-feature nc:xpath;
type yang:xpath1.0;
description
"This parameter contains an XPath expression
identifying the portions of the target
datastore to retrieve.";
}
}
leaf keys-only {
type empty;
description
Bierman Expires April 12, 2013 [Page 18]
Internet-Draft <get2> October 2012
"This parameter selects only data nodes which
are key leaf nodes. Parent container and
list nodes are also returned, but no other leafs,
or any leaf-lists will be included in the reply.";
}
leaf if-modified-since {
if-feature timestamps;
type yang:date-and-time;
description
"This parameter selects only data nodes which
have been modified since the specified time.";
}
leaf depth {
type uint32;
default 0;
description
"This parameter selects how many conceptual
sub-tree levels should be returned in the
<rpc-reply>.
If this parameter is equal to '0', then entire
subtrees will be returned.
If this parameter is greater than '0', then
only the specified number of subtree levels will
be returned.";
reference "RFC XXXX, section 2.1.";
}
uses ncwd:with-defaults-parameters {
if-feature with-defaults;
description
"This parameter controls the retrieval of
default values.";
reference
"RFC 6243: With-defaults Capability for NETCONF";
}
leaf with-timestamps {
if-feature timestamps;
type empty;
description
"This parameter will cause the server to return
XML attributes identifying the last modification
time within one or more elements within the
<rpc-reply>.";
Bierman Expires April 12, 2013 [Page 19]
Internet-Draft <get2> October 2012
reference "RFC XXXX, sections 2.2 and 3.";
}
leaf with-data-sources {
if-feature data-sources;
when "../source/operational";
type empty;
description
"This parameter will cause the server to return
XML attributes identifying the operational
data sources for elements within the
<rpc-reply> that support the 'data-source'
YANG extension statement.";
reference "RFC XXXX, sections 2.2 and 3.";
}
}
output {
anyxml data {
description
"Copy of the requested datastore subset which
matched the filter criteria (if any).
An empty data container indicates that the
request did not produce any results.";
}
}
}
}
<CODE ENDS>
Bierman Expires April 12, 2013 [Page 20]
Internet-Draft <get2> October 2012
8. IANA Considerations
This document registers a URI in the IETF XML registry [RFC3688].
Following the format in RFC 3688, the following 2 registrations are
requested to be made.
URI: urn:ietf:params:xml:ns:yang:ietf-netconf-data-source
Registrant Contact: The NETCONF WG of the IETF.
XML: N/A, the requested URI is an XML namespace.
URI: urn:ietf:params:xml:ns:yang:ietf-netconf-get2
Registrant Contact: The NETCONF WG of the IETF.
XML: N/A, the requested URI is an XML namespace.
This document registers 2 YANG modules in the YANG Module Names
registry [RFC6020].
name: ietf-netconf-data-source
namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-data-source
prefix: cfgsrc
reference: RFC XXXX
name: ietf-netconf-get2
namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-get2
prefix: get2
reference: RFC XXXX
Bierman Expires April 12, 2013 [Page 21]
Internet-Draft <get2> October 2012
9. Security Considerations
This document does not introduce any new security concerns in
addition to those specified in [RFC6241], section 9.
Bierman Expires April 12, 2013 [Page 22]
Internet-Draft <get2> October 2012
10. Change Log
-- RFC Ed.: remove this section before publication.
10.1. 00-01
o removed subtree-filter YANG feature
o changed depth filter to exactly match the XML layering
o renamed filter to subtree-filter
o renamed select to xpath-filter
o added some new examples
10.2. 01-02
o added operational data source support
o added 'ietf-netconf-data-source' module
o clarified terminology
Bierman Expires April 12, 2013 [Page 23]
Internet-Draft <get2> October 2012
11. References
11.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010.
[RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021,
October 2010.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, June 2011.
[RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for
NETCONF", RFC 6243, June 2011.
[XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath)
Version 1.0", World Wide Web Consortium
Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>.
[XSD] Malhotra, A. and P. Biron, "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>.
11.2. Informative References
[I-D.ietf-netmod-system-mgmt]
Bierman, A. and B. Bjorklund, "YANG Data Model for System
Management", draft-ietf-netmod-system-mgmt-03 (work in
progress), September 2012.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
Bierman Expires April 12, 2013 [Page 24]
Internet-Draft <get2> October 2012
Appendix A. Examples
A.1. YANG Module Used in Examples
module example-get2 {
namespace "http://example.com/ns/example-get2";
prefix exget2;
import ietf-netconf-data-source { prefix datasrc; }
revision 2012-10-09;
identity thfp {
base datasrc:data-sources;
description
"The Tree Height Finder Protocol is
the source of the operational data.";
}
identity manual {
base datasrc:data-sources;
description
"The height was derived manually by on-site
measurement crews.";
}
container forests {
list forest {
key name;
leaf name {
type string;
}
leaf tree-count {
config false;
type uint32;
}
container trees {
list tree {
key name;
leaf name {
type string;
}
leaf location {
Bierman Expires April 12, 2013 [Page 25]
Internet-Draft <get2> October 2012
type string;
}
leaf height {
datasrc:data-source;
config false;
type decimal64 {
fraction-digits 3;
}
units meters;
}
} // list tree
} // container trees
} // list forest
} // container forests
}
A.2. YANG Data Used in Examples
The follow instances are assumed in the following examples.
list forest: "north":
list tree: "birch", "ash", "maple"
list forest: "south":
list tree: "banyan", "palm"
The forests and trees are configured, which represent trees the
company has planted and growing over time.
The operational data (tree height) represents the data that the
company monitors for each tree over time.
There are 2 operational data sources for tree height data in this
example:
o thfp: Tree Height Finder Protocol
o manual: Manual measurement by work crews
The north forest was measured with the mythical Tree Height Finder
protocol and the south forest was measured manually.
A.3. Example: Operational Datastore
This example simply retrieves the "forests" subtree data from the
operational datastore.
Bierman Expires April 12, 2013 [Page 26]
Internet-Draft <get2> October 2012
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get2 xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<source>
<operational />
</source>
<subtree-filter>
<forests xmlns="http://example.com/ns/example-get2" />
</subtree-filter>
</get2>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<forests xmlns="http://example.com/ns/example-get2">
<forest>
<name>north</name>
<tree-count>3</tree-count>
<trees>
<tree>
<name>birch</name>
<height>41.013</height>
</tree>
<tree>
<name>ash</name>
<height>16.523</height>
</tree>
<tree>
<name>maple</name>
<height>51.204</height>
</tree>
</trees>
</forest>
<forest>
<name>south</name>
<tree-count>2</tree-count>
<trees>
<tree>
<name>banyan</name>
<height>91.433</height>
</tree>
<tree>
<name>palm</name>
<height>83.439</height>
</tree>
</trees>
</forest>
Bierman Expires April 12, 2013 [Page 27]
Internet-Draft <get2> October 2012
</forests>
</data>
</rpc-reply>
A.4. Example: If-Modified-Since Non-Empty Filter Retrieval
In this example, the running datastore was last modified at
"2012-09-09T01:43:27Z" because the forest named "north" was modified
at this time.
o The forest named "north" was last modified after the specified
"if-modified-since" timestamp.
o The forest named "south" was last modified before the specified
"if-modified-since" timestamp.
o The server maintains a last-modified timestamp for the running
datastore and the "forest" list entries.
o The client is also requesting that timestamps be returned for the
nodes that have been modified. If any part of the "forest"
subtree is modified then this timestamp will be updated.
Bierman Expires April 12, 2013 [Page 28]
Internet-Draft <get2> October 2012
<rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get2 xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<subtree-filter>
<forests xmlns="http://example.com/ns/example-get2" />
</subtree-filter>
<if-modified-since>2012-09-09T01:43:27Z</if-modified-since>
<with-timestamps />
</get2>
</rpc>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:lm="urn:ietf:params:xml:ns:netconf:last-modified:1.0">
<data
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2"
lm:last-modified="2012-09-09T02:00:00Z">
<forests xmlns="http://example.com/ns/example-get2">
<forest lm:last-modified="2012-09-09T02:00:00Z">
<name>north</name>
<trees>
<tree>
<name>birch</name>
<location>hillside</location>
</tree>
<tree>
<name>ash</name>
<location>southwest pasture</location>
</tree>
<tree>
<name>maple</name>
<location>east meadow</location>
</tree>
</trees>
</forest>
</forests>
</data>
</rpc-reply>
A.5. Example: If-Modified-Since Empty Filter Retrieval
In this example the client has changed the if-modified-since
timestamp to a time in the future.
o No "forest" list entry has been modified since this time so an
empty data node is returned.
Bierman Expires April 12, 2013 [Page 29]
Internet-Draft <get2> October 2012
o Note that the last-modified timestamp is returned for the node
representing the datastore, even though no data nodes have been
modified since the specified time. This allows the client to
easily retrieve the last-modified timestamp for the entire
datastore.
<rpc message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get2 xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<subtree-filter>
<forests xmlns="http://example.com/ns/example-get2" />
</subtree-filter>
<if-modified-since>2012-09-09T03:43:27Z</if-modified-since>
<with-timestamps />
</get2>
</rpc>
<rpc-reply message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:lm="urn:ietf:params:xml:ns:netconf:last-modified:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2"
lm:last-modified="2012-09-09T02:00:00Z" />
</rpc-reply>
A.6. Example: Keys Only Filter Retrieval
This example retrieves the names-only from the "forests" subtree in
the running datastore.
o The default source (running) is used.
o The default depth="0" is used to retrieve all subtree levels.
o The xpath-filter is used instead of the subtree-filter
o Whitespace added to xpath-filter element for display purposes only
Bierman Expires April 12, 2013 [Page 30]
Internet-Draft <get2> October 2012
<rpc message-id="104"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get2 xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<xpath-filter xmlns:ex=http://example.com/ns/example-get2">
/ex:forests
</xpath-filter>
<keys-only />
</get2>
</rpc>
<rpc-reply message-id="104"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<forests xmlns="http://example.com/ns/example-get2">
<forest>
<name>north</name>
<trees>
<tree>
<name>birch</name>
</tree>
<tree>
<name>ash</name>
</tree>
<tree>
<name>maple</name>
</tree>
</trees>
</forest>
<forest>
<name>south</name>
<trees>
<tree>
<name>banyan</name>
</tree>
<tree>
<name>palm</name>
</tree>
</trees>
</forest>
</forests>
</data>
</rpc-reply>
A.7. Example: Testing for Node Existence with Depth=1
This example retrieves the "trees" node to determine which forests
have any trees.
Bierman Expires April 12, 2013 [Page 31]
Internet-Draft <get2> October 2012
o Only 1 subtree level is requested, instead of the default of all
levels.
o The default source (running) is used.
o The depth parameter is set to "1" to only retrieve the requested
layer (trees) and its ancestor nodes and the configuration leaf
nodes from each "forest" entry.
<rpc message-id="105"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get2 xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<subtree-filter>
<forests xmlns="http://example.com/ns/example-get2">
<forest>
<trees />
</forest>
</forests>
</subtree-filter>
<depth>1</depth>
</get2>
</rpc>
<rpc-reply message-id="105"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<forests xmlns="http://example.com/ns/example-get2">
<forest>
<name>north</name>
<trees />
</forest>
<forest>
<name>south</name>
<trees />
</forest>
</forests>
</data>
</rpc-reply>
A.8. Example: Keys Only Filter Retrieval with Depth=3
This example retrieves the names-only from the "forest" list within
the "forests" subtree, in the running datastore.
o Only 3 subtree levels are requested, instead of the default of all
levels.
Bierman Expires April 12, 2013 [Page 32]
Internet-Draft <get2> October 2012
o The default source (running) is used.
o The depth parameter is set to "3" to only retrieve the requested
layer (forests), its child nodes (forest), and the key leaf nodes
from each "forest" entry. Without the "keys-only" parameter,
other leafs from the "forest" list would be returned as well.
<rpc message-id="106"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get2 xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<subtree-filter>
<forests xmlns="http://example.com/ns/example-get2" />
</subtree-filter>
<keys-only />
<depth>3</depth>
</get2>
</rpc>
<rpc-reply message-id="106"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<forests xmlns="http://example.com/ns/example-get2">
<forest>
<name>north</name>
</forest>
<forest>
<name>south</name>
</forest>
</forests>
</data>
</rpc-reply>
A.9. Example: Operational Data Sources (tree height)
This example simply retrieves the "forests" subtree data from the
operational datastore, but requesting that data-source XML attributes
be added as required in the reply.
<rpc message-id="107"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get2 xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<source>
<operational />
</source>
<subtree-filter>
<forests xmlns="http://example.com/ns/example-get2" />
</subtree-filter>
Bierman Expires April 12, 2013 [Page 33]
Internet-Draft <get2> October 2012
<with-data-sources />
</get2>
</rpc>
<rpc-reply message-id="107"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:ds="urn:ietf:params:xml:ns:netconf:data-source:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<forests xmlns="http://example.com/ns/example-get2"
xmlns:ex="http://example.com/ns/example-get2">
<forest>
<name>north</name>
<tree-count>3</tree-count>
<trees>
<tree>
<name>birch</name>
<height ds:data-source="ex:thfp">41.013</height>
</tree>
<tree>
<name>ash</name>
<height ds:data-source="ex:thfp">16.523</height>
</tree>
<tree>
<name ds:data-source="ex:thfp">maple</name>
<height>51.204</height>
</tree>
</trees>
</forest>
<forest>
<name>south</name>
<tree-count>2</tree-count>
<trees>
<tree>
<name>banyan</name>
<height ds:data-source="ex:manual">91.433</height>
</tree>
<tree>
<name>palm</name>
<height ds:data-source="ex:manual">83.439</height>
</tree>
</trees>
</forest>
</forests>
</data>
</rpc-reply>
Bierman Expires April 12, 2013 [Page 34]
Internet-Draft <get2> October 2012
A.10. Example: Operational Data Sources (ietf-system)
This example shows how the data-source reporting can be used with a
real YANG module. The ietf-system module defined in
[I-D.ietf-netmod-system-mgmt] contains an operational data node
called "current-datetime". The data source for this node can either
be NTP or the "set-current-datetime" operation defined in the module.
To implement data source reporting, the "data-source" extension needs
to added to the "current-datetime" leaf as follows:
leaf current-datetime {
datasrc:data-source;
type yang:date-and-time;
config false;
description
"The current system date and time.";
}
The following example shows the retrieval of the "current-datetime"
leaf if the data source is NTP. The extra whitespace shown for the
"current-datetime" leaf is for display purposes only.
Bierman Expires April 12, 2013 [Page 35]
Internet-Draft <get2> October 2012
<rpc message-id="108"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get2 xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<source>
<operational />
</source>
<subtree-filter>
<system xmlns="urn:ietf:params:xml:ns:yang:ietf-system">
<clock>
<current-datetime />
</clock>
</system>
</subtree-filter>
<with-data-sources />
</get2>
</rpc>
<rpc-reply message-id="108"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:ds="urn:ietf:params:xml:ns:netconf:data-source:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<system xmlns="urn:ietf:params:xml:ns:yang:ietf-system">
<clock>
<current-datetime ds:data-source="ds:ntp">
2012-09-09T01:11:27Z
</current-datetime>
</clock>
</system>
</data>
</rpc-reply>
The following example shows the retrieval of the "current-datetime"
leaf if the data source is the "set-current-datetime" operation. The
extra whitespace shown for the "current-datetime" leaf is for display
purposes only.
Bierman Expires April 12, 2013 [Page 36]
Internet-Draft <get2> October 2012
<rpc message-id="109"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get2 xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<source>
<operational />
</source>
<subtree-filter>
<system xmlns="urn:ietf:params:xml:ns:yang:ietf-system">
<clock>
<current-datetime />
</clock>
</system>
</subtree-filter>
<with-data-sources />
</get2>
</rpc>
<rpc-reply message-id="109"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:ds="urn:ietf:params:xml:ns:netconf:data-source:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-get2">
<system xmlns="urn:ietf:params:xml:ns:yang:ietf-system">
<clock>
<current-datetime ds:data-source="ds:operation">
2012-09-09T01:11:27Z
</current-datetime>
</clock>
</system>
</data>
</rpc-reply>
Bierman Expires April 12, 2013 [Page 37]
Internet-Draft <get2> October 2012
Author's Address
Andy Bierman
YumaWorks
Email: andy@yumaworks.com
Bierman Expires April 12, 2013 [Page 38]