Internet DRAFT - draft-bierman-netconf-get2

draft-bierman-netconf-get2






Network Working Group                                         A. Bierman
Internet-Draft                                           YumaWorks, Inc.
Intended status: Standards Track                           April 8, 2013
Expires: October 10, 2013


                      The NETCONF <get2> Operation
                     draft-bierman-netconf-get2-03

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 October 10, 2013.

Copyright Notice

   Copyright (c) 2013 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 October 10, 2013                [Page 1]

Internet-Draft                   <get2>                       April 2013


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Problem Statement  . . . . . . . . . . . . . . . . . . . .  3
       1.1.1.  Cannot Retrieve Just the Non-Configuration Data  . . .  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.2.  Solution . . . . . . . . . . . . . . . . . . . . . . . . .  4
     1.3.  Terminology  . . . . . . . . . . . . . . . . . . . . . . .  4
       1.3.1.  NETCONF  . . . . . . . . . . . . . . . . . . . . . . .  4
       1.3.2.  YANG . . . . . . . . . . . . . . . . . . . . . . . . .  5
       1.3.3.  Terms  . . . . . . . . . . . . . . . . . . . . . . . .  5
   2.  <get2> Operation . . . . . . . . . . . . . . . . . . . . . . .  7
     2.1.  Depth Filters  . . . . . . . . . . . . . . . . . . . . . .  7
     2.2.  Time Filters . . . . . . . . . . . . . . . . . . . . . . .  8
   3.  XSD for the "last-modified" Attribute  . . . . . . . . . . . .  9
   4.  <get2> YANG Module . . . . . . . . . . . . . . . . . . . . . . 10
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 16
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 17
   7.  Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 18
     7.1.  00-01  . . . . . . . . . . . . . . . . . . . . . . . . . . 18
     7.2.  01-02  . . . . . . . . . . . . . . . . . . . . . . . . . . 18
     7.3.  02-03  . . . . . . . . . . . . . . . . . . . . . . . . . . 18
   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 19
     8.2.  Informative References . . . . . . . . . . . . . . . . . . 19
   Appendix A.  Examples  . . . . . . . . . . . . . . . . . . . . . . 20
     A.1.  YANG Module Used in Examples . . . . . . . . . . . . . . . 20
     A.2.  YANG Data Used in Examples . . . . . . . . . . . . . . . . 21
     A.3.  Example: If-Modified-Since Non-Empty Filter Retrieval  . . 21
     A.4.  Example: If-Modified-Since Empty Filter Retrieval  . . . . 22
     A.5.  Example: Keys Only Filter Retrieval  . . . . . . . . . . . 23
     A.6.  Example: Testing for Node Existence with Depth=1 . . . . . 24
     A.7.  Example: Keys Only Filter Retrieval with Depth=3 . . . . . 25
     A.8.  Example: Retrieve Only Non-Configuration Data Nodes  . . . 26
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 28













Bierman                 Expires October 10, 2013                [Page 2]

Internet-Draft                   <get2>                       April 2013


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.  Cannot Retrieve Just the Non-Configuration Data

   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 October 10, 2013                [Page 3]

Internet-Draft                   <get2>                       April 2013


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.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]:





Bierman                 Expires October 10, 2013                [Page 4]

Internet-Draft                   <get2>                       April 2013


   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

   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  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.




Bierman                 Expires October 10, 2013                [Page 5]

Internet-Draft                   <get2>                       April 2013


   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 October 10, 2013                [Page 6]

Internet-Draft                   <get2>                       April 2013


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 3.

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
   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



Bierman                 Expires October 10, 2013                [Page 7]

Internet-Draft                   <get2>                       April 2013


   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 October 10, 2013                [Page 8]

Internet-Draft                   <get2>                       April 2013


3.  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 October 10, 2013                [Page 9]

Internet-Draft                   <get2>                       April 2013


4.  <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@2013-04-08.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 October 10, 2013               [Page 10]

Internet-Draft                   <get2>                       April 2013


        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) 2013 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-03.txt

     // RFC Ed.: update the date below with the date of RFC publication
     // and remove this note.
     revision "2013-04-08" {
       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 October 10, 2013               [Page 11]

Internet-Draft                   <get2>                       April 2013


          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";
     }

     /* 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;
               description
                 "The running configuration datastore is the
                  retrieval source.";
             }
             leaf startup {
               if-feature nc:startup;
               type empty;
               description
                 "The startup configuration datastore is the



Bierman                 Expires October 10, 2013               [Page 12]

Internet-Draft                   <get2>                       April 2013


                  retrieval source.";
             }
             leaf url {
               if-feature nc:url;
               type inet:uri;
               description
                 "The URL-based configuration is the
                  retrieval source.";
             }
             leaf nonconfig {
               type empty;
               description
                "The retrieval source is the collection of all
                 non-configuration data nodes supported by the server.
                 Any ancestor container and/or list and list key nodes
                 are also returned. No other leafs or leaf-lists will
                 be included in the reply.

                 The server MAY return ancestor container, and/or list
                 and list key nodes that do not contain any
                 non-configuration nodes. This can occur for several
                 reasons, e.g., the implementation streams replies
                 and cannot defer instrumentation or access control
                 filtering of descendant data nodes.";
             }
           }
         }

         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 October 10, 2013               [Page 13]

Internet-Draft                   <get2>                       April 2013


             "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 October 10, 2013               [Page 14]

Internet-Draft                   <get2>                       April 2013


           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 October 10, 2013               [Page 15]

Internet-Draft                   <get2>                       April 2013


5.  IANA Considerations

   This document registers a URI in the IETF XML registry [RFC3688].
   Following the format in RFC 3688, the following registration is
   requested:

        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 1 YANG module in the YANG Module Names
   registry [RFC6020].

     name:         ietf-netconf-get2
     namespace:    urn:ietf:params:xml:ns:yang:ietf-netconf-get2
     prefix:       get2
     reference:    RFC XXXX


































Bierman                 Expires October 10, 2013               [Page 16]

Internet-Draft                   <get2>                       April 2013


6.  Security Considerations

   This document does not introduce any new security concerns in
   addition to those specified in [RFC6241], section 9.















































Bierman                 Expires October 10, 2013               [Page 17]

Internet-Draft                   <get2>                       April 2013


7.  Change Log

       -- RFC Ed.: remove this section before publication.

7.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

7.2.  01-02

   o  added operational data source support

   o  added 'ietf-netconf-data-source' module

   o  clarified terminology

7.3.  02-03

   o  removed operational data source support since this problem needs
      to be solved as part of the operational state work.

   o  removed 'operational' datastore from datastore-choice and replaced
      it with a datastore value called 'nonconfig'

   o  removed ietf-netconf-data-source YANG module


















Bierman                 Expires October 10, 2013               [Page 18]

Internet-Draft                   <get2>                       April 2013


8.  References

8.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>.

8.2.  Informative References

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              January 2004.
















Bierman                 Expires October 10, 2013               [Page 19]

Internet-Draft                   <get2>                       April 2013


Appendix A.  Examples

A.1.  YANG Module Used in Examples

   module example-get2 {

     namespace "http://example.com/ns/example-get2";
     prefix exget2;
     description "Module used in <get2> examples.";
     revision 2013-04-08;

     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 {
               type string;
             }
             leaf height {
               config false;
               type decimal64 {
                 fraction-digits 3;
               }
               units meters;
             }
           }  // list tree
         }  // container trees
       } // list forest
     }  // container forests
   }





Bierman                 Expires October 10, 2013               [Page 20]

Internet-Draft                   <get2>                       April 2013


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.

A.3.  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 October 10, 2013               [Page 21]

Internet-Draft                   <get2>                       April 2013


     <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">
         <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="101"
       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.4.  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.

   o  Note that the "last-modified" timestamp is returned for the node
      representing the datastore, even though no data nodes have been



Bierman                 Expires October 10, 2013               [Page 22]

Internet-Draft                   <get2>                       April 2013


      modified since the specified time.  This allows the client to
      easily retrieve the last-modified timestamp for the entire
      datastore.


     <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-09T03: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" />
     </rpc-reply>

A.5.  Example: Keys Only Filter Retrieval

   This example retrieves only the names 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 "keys-only" leaf is set

   o  The "forests" subtree is selected.  The xpath-filter is used
      instead of the subtree-filter.

   o  Whitespace added to xpath-filter element for display purposes
      only.












Bierman                 Expires October 10, 2013               [Page 23]

Internet-Draft                   <get2>                       April 2013


     <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">
         <xpath-filter xmlns:ex=http://example.com/ns/example-get2">
           /ex:forests
         </xpath-filter>
         <keys-only />
       </get2>
     </rpc>

     <rpc-reply message-id="103"
       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.6.  Example: Testing for Node Existence with Depth=1

   This example retrieves the "trees" node to determine which forests
   have any trees.




Bierman                 Expires October 10, 2013               [Page 24]

Internet-Draft                   <get2>                       April 2013


   o  Only 1 subtree level is requested, instead of the default of all
      levels.

   o  The default source (running) is used.

   o  The "trees" subtree is selected.

   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="104"
       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="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 />
           </forest>
           <forest>
             <name>south</name>
             <trees />
           </forest>
         </forests>
       </data>
     </rpc-reply>

A.7.  Example: Keys Only Filter Retrieval with Depth=3

   This example retrieves only the "name" leafs from the "forest" list
   within the "forests" subtree, in the running datastore.





Bierman                 Expires October 10, 2013               [Page 25]

Internet-Draft                   <get2>                       April 2013


   o  The default source (running) is used.

   o  The "keys-only" leaf is set

   o  The "forests" subtree is selected

   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="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" />
         </subtree-filter>
         <keys-only />
         <depth>3</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>
           </forest>
           <forest>
             <name>south</name>
           </forest>
         </forests>
       </data>
     </rpc-reply>

A.8.  Example: Retrieve Only Non-Configuration Data Nodes

   This example retrieves only the name leafs from the "forest" list
   within the "forests" subtree, in the running datastore.

   o  The "source" leaf is set to the "nonconfig" data source

   o  The "forests" subtree is selected






Bierman                 Expires October 10, 2013               [Page 26]

Internet-Draft                   <get2>                       April 2013


     <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">
         <source><nonconfig /></source>
         <subtree-filter>
           <forests xmlns="http://example.com/ns/example-get2" />
         </subtree-filter>
       </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>
             <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>
             <trees>
               <tree>
                 <name>banyan</name>
                 <height>91.433</height>
               </tree>
               <tree>
                 <name>palm</name>
                 <height>83.439</height>
               </tree>
             </trees>
           </forest>
         </forests>
       </data>
     </rpc-reply>




Bierman                 Expires October 10, 2013               [Page 27]

Internet-Draft                   <get2>                       April 2013


Author's Address

   Andy Bierman
   YumaWorks, Inc.

   Email: andy@yumaworks.com













































Bierman                 Expires October 10, 2013               [Page 28]