6.  Subtree Filtering

6.1.  Overview

   XML subtree filtering is a mechanism that allows an application to
   select particular XML subtrees to include in the <rpc-reply> for a
   <get> or <get-config> operation.  A small set of filters for
   inclusion, simple content exact-match, and selection is provided,
   which allows some useful, but also very limited, selection
   mechanisms.  The agent does not need to utilize any data-model-
   specific semantics during processing, allowing for simple and
   centralized implementation strategies.

   Conceptually, a subtree filter is comprised of zero or more element
   subtrees, which represent the filter selection criteria.  At each
   containment level within a subtree, the set of sibling nodes is
   logically processed by the server to determine if its subtree and
   path of elements to the root are included in the filter output.

   All elements present in a particular subtree within a filter must
   match associated nodes present in the server's conceptual data model.
   XML namespaces may be specified (via 'xmlns' declarations) within the
   filter data model.  If they are, the declared namespace must first
   exactly match a namespace supported by the server.  Note that prefix
   values for qualified namespaces are not relevant when comparing
   filter elements to elements in the underlying data model.  Only data
   associated with a specified namespace will be included in the filter
   output.

   Each node specified in a subtree filter represents an inclusive
   filter.  Only associated nodes in underlying data model(s) within the
   specified configuration datastore on the server are selected by the
   filter.  A node must exactly match the namespace and hierarchy of
   elements given in the filter data, except that the filter absolute
   path name is adjusted to start from the layer below <filter>.

   Response messages contain only the subtrees selected by the filter.
   Any selection criteria that were present in the request, within a
   particular selected subtree, are also included in the response.  Note
   that some elements expressed in the filter as leaf nodes will be
   expanded (i.e., subtrees included) in the filter output.  Specific
   data instances are not duplicated in the response in the event that
   the request contains multiple filter subtree expressions that select
   the same data.

6.2.  Subtree Filter Components

   A subtree filter is comprised of XML elements and their XML
   attributes.  There are five types of components that may be present
   in a subtree filter:

   o  Namespace Selection

   o  Attribute Match Expressions

   o  Containment Nodes

   o  Selection Nodes

   o  Content Match Nodes

6.2.1.  Namespace Selection

   If namespaces are used, then the filter output will only include
   elements from the specified namespace.  A namespace is considered to
   match (for filter purposes) if the content of the 'xmlns' attributes
   are the same in the filter and the underlying data model.  Note that
   namespace selection cannot be used by itself.  At least one element
   must be specified in the filter any elements to be included in the
   filter output.

   Example:

     <filter type="subtree">
       <top xmlns="http://example.com/schema/1.2/config"/>
     </filter>

   In this example, the <top> element is a selection node, and only this
   node and any child nodes (from the underlying data model) in the
   'http://example.com/schema/1.2/config' namespace will be included in
   the filter output.

6.2.2.  Attribute Match Expressions

   An attribute that appears in a subtree filter is part of an
   "attribute match expression".  Any number of (unqualified or
   qualified) XML attributes may be present in any type of filter node.
   In addition to the selection criteria normally applicable to that
   node, the selected data must have matching values for every attribute
   specified in the node.  If an element is not defined to include a
   specified attribute, then it is not selected in the filter output.

   Example:

     <filter type="subtree">
       <t:top xmlns:t="http://example.com/schema/1.2/config">
         <t:interfaces>
           <t:interface t:ifName="eth0"/>
         </t:interfaces>
       </t:top>
     </filter>

   In this example, the <top>, <interfaces>, and <interface> elements
   are containment nodes, and 'ifName' is an attribute match expression.
   Only 'interface' nodes in the 'http://example.com/schema/1.2/config'
   namespace that have an 'ifName' attribute with the value 'eth0' and
   occur within 'interfaces' nodes within 'top' nodes will be included
   in the filter output.

6.2.3.  Containment Nodes

   Nodes that contain child elements within a subtree filter are called
   "containment nodes".  Each child element can be any type of node,
   including another containment node.  For each containment node
   specified in a subtree filter, all data model instances that exactly
   match the specified namespaces, element hierarchy, and any attribute
   match expressions are included in the filter output.

   Example:

     <filter type="subtree">
       <top xmlns="http://example.com/schema/1.2/config">
         <users/>
       </top>
     </filter>

   In this example, the <top> element is a containment node.

6.2.4.  Selection Nodes

   An empty leaf node within a filter is called a "selection node", and
   it represents an "explicit selection" filter on the underlying data
   model.  Presence of any selection nodes within a set of sibling nodes
   will cause the filter to select the specified subtree(s) and suppress
   automatic selection of the entire set of sibling nodes in the
   underlying data model.  For filtering purposes, an empty leaf node
   can be declared either with an empty tag (e.g., <foo/>) or with
   explicit start and end tags (e.g., <foo> </foo>).  Any whitespace
   characters are ignored in this form.

   Example:

     <filter type="subtree">
       <top xmlns="http://example.com/schema/1.2/config">
         <users/>
       </top>
     </filter>

   In this example, the <top> element is a containment node, and the
   <users> element is a selection node.  Only 'users' nodes in the
   'http://example.com/schema/1.2/config' namespace that occur within a
   'top' element that is the root of the configuration datastore will be
   included in the filter output.

6.2.5.  Content Match Nodes

   A leaf node that contains simple content is called a "content match
   node".  It is used to select some or all of its sibling nodes for
   filter output, and it represents an exact-match filter on the leaf
   node element content.  The following constraints apply to content
   match nodes:

   o  A content match node must not contain nested elements (i.e., must
      resolve to a simpleType in the XML Schema Definition (XSD)).

   o  Multiple content match nodes (i.e., sibling nodes) are logically
      combined in an "AND" expression.

   o  Filtering of mixed content is not supported.

   o  Filtering of list content is not supported.

   o  Filtering of whitespace-only content is not supported.

   o  A content match node must contain non-whitespace characters.  An
      empty element (e.g., <foo></foo>) will be interpreted as a
      selection node (e.g., <foo/>).

   o  Leading and trailing whitespace characters are ignored, but any
      whitespace characters within a block of text characters are not
      ignored or modified.

   If all specified sibling content match nodes in a subtree filter
   expression are 'true', then the filter output nodes are selected in
   the following manner:

   o  Each content match node in the sibling set is included in the
      filter output.

   o  If any containment nodes are present in the sibling set, then they
      are processed further and included if any nested filter criteria
      are also met.

   o  If any selection nodes are present in the sibling set, then all of
      them are included in the filter output.

   o  Otherwise (i.e., there are no selection or containment nodes in
      the filter sibling set), all the nodes defined at this level in
      the underlying data model (and their subtrees, if any) are
      returned in the filter output.

   If any of the sibling content match node tests are 'false', then no
   further filter processing is performed on that sibling set, and none
   of the sibling subtrees are selected by the filter, including the
   content match node(s).

   Example:

     <filter type="subtree">
       <top xmlns="http://example.com/schema/1.2/config">
         <users>
           <user>
             <name>fred</name>
           </user>
         </users>
       </top>
     </filter>

   In this example, the <users> and <user> nodes are both containment
   nodes, and <name> is a content match node.  Since no sibling nodes of
   <name> are specified (and therefore no containment or selection
   nodes), all of the sibling nodes of <name> are returned in the filter

   output.  Only 'user' nodes in the
   'http://example.com/schema/1.2/config' namespace that match the
   element hierarchy and for which the <name> element is equal to 'fred'
   will be included in the filter output.

6.3.  Subtree Filter Processing

   The filter output (the set of selected nodes) is initially empty.

   Each subtree filter can contain one or more data model fragments,
   which represent portions of the data model that should be selected
   (with all child nodes) in the filter output.

   Each subtree data fragment is compared by the server to the internal
   data models supported by the server.  If the entire subtree data-
   fragment filter (starting from the root to the innermost element
   specified in the filter) exactly matches a corresponding portion of
   the supported data model, then that node and all its children are
   included in the result data.

   The server processes all nodes with the same parent node (sibling
   set) together, starting from the root to the leaf nodes.  The root
   elements in the filter are considered in the same sibling set
   (assuming they are in the same namespace), even though they do not
   have a common parent.

   For each sibling set, the server determines which nodes are included
   (or potentially included) in the filter output, and which sibling
   subtrees are excluded (pruned) from the filter output.  The server
   first determines which types of nodes are present in the sibling set
   and processes the nodes according to the rules for their type.  If
   any nodes in the sibling set are selected, then the process is
   recursively applied to the sibling sets of each selected node.  The
   algorithm continues until all sibling sets in all subtrees specified
   in the filter have been processed.

6.4.  Subtree Filtering Examples

6.4.1.  No Filter

   Leaving out the filter on the get operation returns the entire data
   model.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get/>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <data>
         <!-- ... entire set of data returned ... -->
       </data>
     </rpc-reply>

6.4.2.  Empty Filter

   An empty filter will select nothing because no content match or
   selection nodes are present.  This is not an error.  The filter type
   attribute used in these examples is discussed further in Section 7.1.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get>
         <filter type="subtree">
         </filter>
       </get>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <data>
       </data>
     </rpc-reply>

6.4.3.  Select the Entire <users> Subtree

   The filter in this example contains one selection node (<users>), so
   just that subtree is selected by the filter.  This example represents
   the fully-populated <users> data model in most of the filter examples
   that follow.  In a real data model, the <company-info> would not
   likely be returned with the list of users for a particular host or
   network.

   NOTE: The filtering and configuration examples used in this document
   appear in the namespace "http://example.com/schema/1.2/config".  The
   root element of this namespace is <top>.  The <top> element and its
   descendents represent an example configuration data model only.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get-config>
         <source>
           <running/>
         </source>
         <filter type="subtree">

           <top xmlns="http://example.com/schema/1.2/config">
             <users/>
           </top>
         </filter>
       </get-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <data>
         <top xmlns="http://example.com/schema/1.2/config">
           <users>
             <user>
               <name>root</name>
               <type>superuser</type>
               <full-name>Charlie Root</full-name>
               <company-info>
                 <dept>1</dept>
                 <id>1</id>
               </company-info>
             </user>
             <user>
               <name>fred</name>
               <type>admin</type>
               <full-name>Fred Flintstone</full-name>
               <company-info>
                 <dept>2</dept>
                 <id>2</id>
               </company-info>
             </user>
             <user>
               <name>barney</name>
               <type>admin</type>
               <full-name>Barney Rubble</full-name>
               <company-info>
                 <dept>2</dept>
                 <id>3</id>
               </company-info>
             </user>
           </users>
         </top>
       </data>
     </rpc-reply>

   The following filter request would have produced the same result, but
   only because the container <users> defines one child element
   (<user>).

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get-config>
         <source>
           <running/>
         </source>
         <filter type="subtree">
           <top xmlns="http://example.com/schema/1.2/config">
             <users>
               <user/>
             </users>
           </top>
         </filter>
       </get-config>
     </rpc>

6.4.4.  Select All <name> Elements within the <users> Subtree

   This filter contains two containment nodes (<users>, <user>) and one
   selector node (<name>).  All instances of the <name> element in the
   same sibling set are selected in the filter output.  The manager may
   need to know that <name> is used as an instance identifier in this
   particular data structure, but the server does not need to know that
   meta-data in order to process the request.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get-config>
         <source>
           <running/>
         </source>
         <filter type="subtree">
           <top xmlns="http://example.com/schema/1.2/config">
             <users>
               <user>
                 <name/>
               </user>
             </users>
           </top>
         </filter>
       </get-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <data>
         <top xmlns="http://example.com/schema/1.2/config">
           <users>

             <user>
               <name>root</name>
             </user>
             <user>
               <name>fred</name>
             </user>
             <user>
               <name>barney</name>
             </user>
           </users>
         </top>
       </data>
     </rpc-reply>

6.4.5.  One Specific <user> Entry

   This filter contains two containment nodes (<users>, <user>) and one
   content match node (<name>).  All instances of the sibling set
   containing <name> for which the value of <name> equals "fred" are
   selected in the filter output.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get-config>
         <source>
           <running/>
         </source>
         <filter type="subtree">
           <top xmlns="http://example.com/schema/1.2/config">
             <users>
               <user>
                 <name>fred</name>
               </user>
             </users>
           </top>
         </filter>
       </get-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <data>
         <top xmlns="http://example.com/schema/1.2/config">
           <users>
             <user>
               <name>fred</name>
               <type>admin</type>
               <full-name>Fred Flintstone</full-name>

               <company-info>
                 <dept>2</dept>
                 <id>2</id>
               </company-info>
             </user>
           </users>
         </top>
       </data>
     </rpc-reply>

6.4.6.  Specific Elements from a Specific <user> Entry

   This filter contains two containment nodes (<users>, <user>), one
   content match node (<name>), and two selector nodes (<type>,
   <full-name>).  All instances of the <type> and <full-name> elements
   in the same sibling set containing <name> for which the value of
   <name> equals "fred" are selected in the filter output.  The
   <company-info> element is not included because the sibling set
   contains selection nodes.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get-config>
         <source>
           <running/>
         </source>
         <filter type="subtree">
           <top xmlns="http://example.com/schema/1.2/config">
             <users>
               <user>
                 <name>fred</name>
                 <type/>
                 <full-name/>
               </user>
             </users>
           </top>
         </filter>
       </get-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <data>
         <top xmlns="http://example.com/schema/1.2/config">
           <users>
             <user>
               <name>fred</name>
               <type>admin</type>

               <full-name>Fred Flintstone</full-name>
             </user>
           </users>
         </top>
       </data>
     </rpc-reply>

6.4.7.  Multiple Subtrees

   This filter contains three subtrees (name=root, fred, barney).

   The "root" subtree filter contains two containment nodes (<users>,
   <user>), one content match node (<name>), and one selector node
   (<company-info>).  The subtree selection criteria is met, and just
   the company-info subtree for "root" is selected in the filter output.

   The "fred" subtree filter contains three containment nodes (<users>,
   <user>, <company-info>), one content match node (<name>), and one
   selector node (<id>).  The subtree selection criteria is met, and
   just the <id> element within the company-info subtree for "fred" is
   selected in the filter output.

   The "barney" subtree filter contains three containment nodes
   (<users>, <user>, <company-info>), two content match nodes (<name>,
   <type>), and one selector node (<dept>).  The subtree selection
   criteria is not met because user "barney" is not a "superuser", and
   the entire subtree for "barney" (including its parent <user> entry)
   is excluded from the filter output.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get-config>
         <source>
           <running/>
         </source>
         <filter type="subtree">
           <top xmlns="http://example.com/schema/1.2/config">
             <users>
               <user>
                 <name>root</name>
                 <company-info/>
               </user>
               <user>
                 <name>fred</name>
                 <company-info>
                   <id/>
                 </company-info>
               </user>

               <user>
                 <name>barney</name>
                 <type>superuser</type>
                 <company-info>
                   <dept/>
                 </company-info>
               </user>
             </users>
           </top>
         </filter>
       </get-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <data>
         <top xmlns="http://example.com/schema/1.2/config">
           <users>
             <user>
               <name>root</name>
               <company-info>
                 <dept>1</dept>
                 <id>1</id>
               </company-info>
             </user>
             <user>
               <name>fred</name>
               <company-info>
                 <id>2</id>
               </company-info>
             </user>
           </users>
         </top>
       </data>
     </rpc-reply>

6.4.8.  Elements with Attribute Naming

   In this example, the filter contains one containment node
   (<interfaces>), one attribute match expression (ifName), and one
   selector node (<interface>).  All instances of the <interface>
   subtree that have an ifName attribute equal to "eth0" are selected in
   the filter output.  The filter data elements and attributes must be
   qualified because the ifName attribute will not be considered part of
   the 'schema/1.2' namespace if it is unqualified.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get>
         <filter type="subtree">
           <t:top xmlns:t="http://example.com/schema/1.2/stats">
             <t:interfaces>
               <t:interface t:ifName="eth0"/>
             </t:interfaces>
           </t:top>
         </filter>
       </get>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <data>
         <t:top xmlns:t="http://example.com/schema/1.2/stats">
           <t:interfaces>
             <t:interface t:ifName="eth0">
               <t:ifInOctets>45621</t:ifInOctets>
               <t:ifOutOctets>774344</t:ifOutOctets>
             </t:interface>
           </t:interfaces>
         </t:top>
       </data>
     </rpc-reply>

   If ifName were a child node instead of an attribute, then the
   following request would produce similar results.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get>
         <filter type="subtree">
           <top xmlns="http://example.com/schema/1.2/stats">
             <interfaces>
               <interface>
                 <ifName>eth0</ifName>
               </interface>
             </interfaces>
           </top>
         </filter>
       </get>
     </rpc>

7.  Protocol Operations

   The NETCONF protocol provides a small set of low-level operations to
   manage device configurations and retrieve device state information.
   The base protocol provides operations to retrieve, configure, copy,
   and delete configuration datastores.  Additional operations are
   provided, based on the capabilities advertised by the device.

   The base protocol includes the following protocol operations:

   o  get

   o  get-config

   o  edit-config

   o  copy-config

   o  delete-config

   o  lock

   o  unlock

   o  close-session

   o  kill-session

   A protocol operation may fail for various reasons, including
   "operation not supported".  An initiator should not assume that any
   operation will always succeed.  The return values in any RPC reply
   should be checked for error responses.

   The syntax and XML encoding of the protocol operations are formally
   defined in the XML schema in Appendix B.  The following sections
   describe the semantics of each protocol operation.

7.1.  <get-config>

   Description:

      Retrieve all or part of a specified configuration.

   Parameters:

      source:

         Name of the configuration datastore being queried, such as
         <running/>.

      filter:

         The filter element identifies the portions of the device
         configuration to retrieve.  If this element is unspecified, the
         entire configuration is returned.

         The filter element may optionally contain a "type" attribute.
         This attribute indicates the type of filtering syntax used
         within the filter element.  The default filtering mechanism in
         NETCONF is referred to as subtree filtering and is described in
         Section 6.  The value "subtree" explicitly identifies this type
         of filtering.

         If the NETCONF peer supports the :xpath capability
         (Section 8.9), the value "xpath" may be used to indicate that
         the select attribute on the filter element contains an XPath
         expression.

   Positive Response:

      If the device can satisfy the request, the server sends an
      <rpc-reply> element containing a <data> element with the results
      of the query.

   Negative Response:

      An <rpc-error> element is included in the <rpc-reply> if the
      request cannot be completed for any reason.

   Example: To retrieve the entire <users> subtree:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get-config>
         <source>
           <running/>
         </source>
         <filter type="subtree">
           <top xmlns="http://example.com/schema/1.2/config">
             <users/>
           </top>

         </filter>
       </get-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <data>
         <top xmlns="http://example.com/schema/1.2/config">
           <users>
             <user>
               <name>root</name>
               <type>superuser</type>
               <full-name>Charlie Root</full-name>
               <company-info>
                 <dept>1</dept>
                 <id>1</id>
               </company-info>
             </user>
             <!-- additional <user> elements appear here... -->
           </users>
         </top>
       </data>
     </rpc-reply>

   If the configuration is available in multiple formats, such as XML
   and text, an XML namespace can be used to specify which format is
   desired.  In the following example, the client uses a specific
   element (<config-text>) in a specific namespace to indicate to the
   server the desire to receive the configuration in an alternative
   format.  The server may support any number of distinct formats or
   views into the configuration data, with the client using the <filter>
   parameter to select between them.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get-config>
         <source>
           <running/>
         </source>
         <filter type="subtree">
           <!-- request a text version of the configuration -->
           <config-text xmlns="http://example.com/text/1.2/config"/>
         </filter>
       </get-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

       <data>
         <config-text xmlns="http://example.com/text/1.2/config">
           <!-- configuration text... -->
         </config-text>
       </data>
     </rpc-reply>

      Section 6 contains additional examples of subtree filtering.

7.2.  <edit-config>

   Description:

      The <edit-config> operation loads all or part of a specified
      configuration to the specified target configuration.  This
      operation allows the new configuration to be expressed in several
      ways, such as using a local file, a remote file, or inline.  If
      the target configuration does not exist, it will be created.  If a
      NETCONF peer supports the :url capability (Section 8.8), the <url>
      element can appear instead of the <config> parameter and should
      identify a local configuration file.

      The device analyzes the source and target configurations and
      performs the requested changes.  The target configuration is not
      necessarily replaced, as with the <copy-config> message.  Instead,
      the target configuration is changed in accordance with the
      source's data and requested operations.

   Attributes:

      operation:

         Elements in the <config> subtree may contain an "operation"
         attribute.  The attribute identifies the point in the
         configuration to perform the operation and MAY appear on
         multiple elements throughout the <config> subtree.

         If the operation attribute is not specified, the configuration
         is merged into the configuration datastore.

         The operation attribute has one of the following values:

         merge: The configuration data identified by the element
            containing this attribute is merged with the configuration
            at the corresponding level in the configuration datastore
            identified by the target parameter.  This is the default
            behavior.

         replace: The configuration data identified by the element
            containing this attribute replaces any related configuration
            in the configuration datastore identified by the target
            parameter.  Unlike a <copy-config> operation, which replaces
            the entire target configuration, only the configuration
            actually present in the config parameter is affected.

         create: The configuration data identified by the element
            containing this attribute is added to the configuration if
            and only if the configuration data does not already exist on
            the device.  If the configuration data exists, an
            <rpc-error> element is returned with an <error-tag> value of
            data-exists.

         delete: The configuration data identified by the element
            containing this attribute is deleted in the configuration
            datastore identified by the target parameter.

   Parameters:

      target:

         Name of the configuration datastore being edited, such as
         <running/> or <candidate/>.

      default-operation:

         Selects the default operation (as described in the "operation"
         attribute) for this <edit-config> request.  The default value
         for the default-operation parameter is "merge".

         The default-operation parameter is optional, but if provided,
         it must have one of the following values:

         merge: The configuration data in the <config> parameter is
            merged with the configuration at the corresponding level in
            the target datastore.  This is the default behavior.

         replace: The configuration data in the <config> parameter
            completely replaces the configuration in the target
            datastore.  This is useful for loading previously saved
            configuration data.

         none: The target datastore is unaffected by the configuration
            in the <config> parameter, unless and until the incoming
            configuration data uses the "operation" attribute to request
            a different operation.  If the configuration in the <config>
            parameter contains data for which there is not a

            corresponding level in the target datastore, an <rpc-error>
            is returned with an <error-tag> value of data-missing.
            Using "none" allows operations like "delete" to avoid
            unintentionally creating the parent hierarchy of the element
            to be deleted.

      test-option:

         The test-option element may be specified only if the device
         advertises the :validate capability (Section 8.6).

         The test-option element has one of the following values:

         test-then-set: Perform a validation test before attempting to
            set.  If validation errors occur, do not perform the
            <edit-config> operation.  This is the default test-option.

         set: Perform a set without a validation test first.

      error-option:

         The error-option element has one of the following values:

         stop-on-error: Abort the edit-config operation on first error.
            This is the default error-option.

         continue-on-error: Continue to process configuration data on
            error; error is recorded, and negative response is generated
            if any errors occur.

         rollback-on-error: If an error condition occurs such that an
            error severity <rpc-error> element is generated, the server
            will stop processing the edit-config operation and restore
            the specified configuration to its complete state at the
            start of this edit-config operation.  This option requires
            the server to support the :rollback-on-error capability
            described in Section 8.5.

      config:

         A hierarchy of configuration data as defined by one of the
         device's data models.  The contents MUST be placed in an
         appropriate namespace, to allow the device to detect the
         appropriate data model, and the contents MUST follow the
         constraints of that data model, as defined by its capability
         definition.  Capabilities are discussed in Section 8.

   Positive Response:

      If the device was able to satisfy the request, an <rpc-reply> is
      sent containing an <ok> element.

   Negative Response:

      An <rpc-error> response is sent if the request cannot be completed
      for any reason.

   Example:

      The <edit-config> examples in this section utilize a simple data
      model, in which multiple instances of the 'interface' element may
      be present, and an instance is distinguished by the 'name' element
      within each 'interface' element.

      Set the MTU to 1500 on an interface named "Ethernet0/0" in the
      running configuration:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <edit-config>
         <target>
           <running/>
         </target>
         <config>
           <top xmlns="http://example.com/schema/1.2/config">
             <interface>
               <name>Ethernet0/0</name>
               <mtu>1500</mtu>
             </interface>
           </top>
         </config>
       </edit-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/>
     </rpc-reply>

      Add an interface named "Ethernet0/0" to the running configuration,
      replacing any previous interface with that name:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <edit-config>

         <target>
           <running/>
         </target>
         <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
           <top xmlns="http://example.com/schema/1.2/config">
             <interface xc:operation="replace">
               <name>Ethernet0/0</name>
               <mtu>1500</mtu>
               <address>
                 <name>192.0.2.4</name>
                 <prefix-length>24</prefix-length>
               </address>
             </interface>
           </top>
         </config>
       </edit-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/>
     </rpc-reply>

      Delete the configuration for an interface named "Ethernet0/0" from
      the running configuration:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <edit-config>
         <target>
           <running/>
         </target>
         <default-operation>none</default-operation>
         <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
           <top xmlns="http://example.com/schema/1.2/config">
             <interface xc:operation="delete">
               <name>Ethernet0/0</name>
             </interface>
           </top>
         </config>
       </edit-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/>
     </rpc-reply>

      Delete interface 192.0.2.4 from an OSPF area (other interfaces
      configured in the same area are unaffected):

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <edit-config>
         <target>
           <running/>
         </target>
         <default-operation>none</default-operation>
         <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
           <top xmlns="http://example.com/schema/1.2/config">
             <protocols>
               <ospf>
                 <area>
                   <name>0.0.0.0</name>
                   <interfaces>
                     <interface xc:operation="delete">
                       <name>192.0.2.4</name>
                     </interface>
                   </interfaces>
                 </area>
               </ospf>
             </protocols>
           </top>
         </config>
       </edit-config>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/>
     </rpc-reply>

7.3.  <copy-config>

   Description:

      Create or replace an entire configuration datastore with the
      contents of another complete configuration datastore.  If the
      target datastore exists, it is overwritten.  Otherwise, a new one
      is created, if allowed.

      If a NETCONF peer supports the :url capability (Section 8.8), the
      <url> element can appear as the <source> or <target> parameter.

      Even if it advertises the :writable-running capability, a device
      may choose not to support the <running/> configuration datastore

      as the <target> parameter of a <copy-config> operation.  A device
      may choose not to support remote-to-remote copy operations, where
      both the <source> and <target> parameters use the <url> element.

      If the source and target parameters identify the same URL or
      configuration datastore, an error MUST be returned with an error-
      tag containing invalid-value.

   Parameters:

      target:

         Name of the configuration datastore to use as the destination
         of the copy operation.

      source:

         Name of the configuration datastore to use as the source of the
         copy operation or the <config> element containing the
         configuration subtree to copy.

   Positive Response:

      If the device was able to satisfy the request, an <rpc-reply> is
      sent that includes an <ok> element.

   Negative Response:

      An <rpc-error> element is included within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <copy-config>
         <target>
           <running/>
         </target>
         <source>
           <url>https://user@example.com:passphrase/cfg/new.txt</url>
         </source>
       </copy-config>
     </rpc>

     <rpc-reply message-id="101"
         xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/>
     </rpc-reply>

7.4.  <delete-config>

   Description:

      Delete a configuration datastore.  The <running> configuration
      datastore cannot be deleted.

      If a NETCONF peer supports the :url capability (Section 8.8), the
      <url> element can appear as the <target> parameter.

   Parameters:

      target:

         Name of the configuration datastore to delete.

   Positive Response:

      If the device was able to satisfy the request, an <rpc-reply> is
      sent that includes an <ok> element.

   Negative Response:

      An <rpc-error> element is included within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <delete-config>
         <target>
           <startup/>
         </target>
       </delete-config>
     </rpc>

      <rpc-reply message-id="101"
           xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/>
     </rpc-reply>

7.5.  <lock>

   Description:

      The lock operation allows the client to lock the configuration
      system of a device.  Such locks are intended to be short-lived and
      allow a client to make a change without fear of interaction with
      other NETCONF clients, non-NETCONF clients (e.g., SNMP and command
      line interface (CLI) scripts), and human users.

      An attempt to lock the configuration MUST fail if an existing
      session or other entity holds a lock on any portion of the lock
      target.

      When the lock is acquired, the server MUST prevent any changes to
      the locked resource other than those requested by this session.
      SNMP and CLI requests to modify the resource MUST fail with an
      appropriate error.

      The duration of the lock is defined as beginning when the lock is
      acquired and lasting until either the lock is released or the
      NETCONF session closes.  The session closure may be explicitly
      performed by the client, or implicitly performed by the server
      based on criteria such as failure of the underlying transport, or
      simple inactivity timeout.  This criteria is dependent on the
      implementation and the underlying transport.

      The lock operation takes a mandatory parameter, target.  The
      target parameter names the configuration that will be locked.
      When a lock is active, using the <edit-config> operation on the
      locked configuration and using the locked configuration as a
      target of the <copy-config> operation will be disallowed by any
      other NETCONF session.  Additionally, the system will ensure that
      these locked configuration resources will not be modified by other
      non-NETCONF management operations such as SNMP and CLI.  The
      <kill-session> message (at the RPC layer) can be used to force the
      release of a lock owned by another NETCONF session.  It is beyond
      the scope of this document to define how to break locks held by
      other entities.

      A lock MUST not be granted if either of the following conditions
      is true:

      *  A lock is already held by any NETCONF session or another
         entity.

      *  The target configuration is <candidate>, it has already been
         modified, and these changes have not been committed or rolled
         back.

      The server MUST respond with either an <ok> element or an
      <rpc-error>.

      A lock will be released by the system if the session holding the
      lock is terminated for any reason.

   Parameters:

      target:

         Name of the configuration datastore to lock.

   Positive Response:

      If the device was able to satisfy the request, an <rpc-reply> is
      sent that contains an <ok> element.

   Negative Response:

      An <rpc-error> element is included in the <rpc-reply> if the
      request cannot be completed for any reason.

      If the lock is already held, the <error-tag> element will be
      'lock-denied' and the <error-info> element will include the
      <session-id> of the lock owner.  If the lock is held by a non-
      NETCONF entity, a <session-id> of 0 (zero) is included.  Note that
      any other entity performing a lock on even a partial piece of a
      target will prevent a NETCONF lock (which is global) from being
      obtained on that target.

   Example:

      The following example shows a successful acquisition of a lock.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <lock>
         <target>
           <running/>
         </target>
       </lock>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/> <!-- lock succeeded -->
     </rpc-reply>

   Example:

      The following example shows a failed attempt to acquire a lock
      when the lock is already in use.


     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <lock>
         <target>
           <running/>
         </target>
       </lock>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <rpc-error> <!-- lock failed -->
         <error-type>protocol</error-type>
         <error-tag>lock-denied</error-tag>
         <error-severity>error</error-severity>
         <error-message>
           Lock failed, lock is already held
         </error-message>
         <error-info>
           <session-id>454</session-id>
           <!-- lock is held by NETCONF session 454 -->
         </error-info>
       </rpc-error>
     </rpc-reply>

7.6.  <unlock>

   Description:

      The unlock operation is used to release a configuration lock,
      previously obtained with the <lock> operation.

      An unlock operation will not succeed if any of the following
      conditions are true:

      *  the specified lock is not currently active

      *  the session issuing the <unlock> operation is not the same
         session that obtained the lock

      The server MUST respond with either an <ok> element or an
      <rpc-error>.

   Parameters:

      target:

         Name of the configuration datastore to unlock.

         A NETCONF client is not permitted to unlock a configuration
         datastore that it did not lock.

   Positive Response:

      If the device was able to satisfy the request, an <rpc-reply> is
      sent that contains an <ok> element.

   Negative Response:

      An <rpc-error> element is included in the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <unlock>
         <target>
          <running/>
         </target>
       </unlock>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/>
     </rpc-reply>

7.7.  <get>

   Description:

      Retrieve running configuration and device state information.

   Parameters:

      filter:

         This parameter specifies the portion of the system
         configuration and state data to retrieve.  If this parameter is
         empty, all the device configuration and state information is
         returned.

         The filter element may optionally contain a 'type' attribute.
         This attribute indicates the type of filtering syntax used
         within the filter element.  The default filtering mechanism in
         NETCONF is referred to as subtree filtering and is described in
         Section 6.  The value 'subtree' explicitly identifies this type
         of filtering.

         If the NETCONF peer supports the :xpath capability
         (Section 8.9), the value "xpath" may be used to indicate that
         the select attribute of the filter element contains an XPath
         expression.

   Positive Response:

      If the device was able to satisfy the request, an <rpc-reply> is
      sent.  The <data> section contains the appropriate subset.

   Negative Response:

      An <rpc-error> element is included in the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <get>
         <filter type="subtree">
           <top xmlns="http://example.com/schema/1.2/stats">
             <interfaces>
               <interface>
                 <ifName>eth0</ifName>
               </interface>
             </interfaces>
           </top>
         </filter>
       </get>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <data>
         <top xmlns="http://example.com/schema/1.2/stats">
           <interfaces>
             <interface>
               <ifName>eth0</ifName>
               <ifInOctets>45621</ifInOctets>
               <ifOutOctets>774344</ifOutOctets>
             </interface>
           </interfaces>
         </top>
       </data>
     </rpc-reply>

7.8.  <close-session>

   Description:

      Request graceful termination of a NETCONF session.

      When a NETCONF server receives a <close-session> request, it will
      gracefully close the session.  The server will release any locks
      and resources associated with the session and gracefully close any
      associated connections.  Any NETCONF requests received after a
      <close-session> request will be ignored.

   Positive Response:

      If the device was able to satisfy the request, an <rpc-reply> is
      sent that includes an <ok> element.

   Negative Response:

      An <rpc-error> element is included in the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <close-session/>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/>
     </rpc-reply>

7.9.  <kill-session>

   Description:

      Force the termination of a NETCONF session.

      When a NETCONF entity receives a <kill-session> request for an
      open session, it will abort any operations currently in process,
      release any locks and resources associated with the session, and
      close any associated connections.

      If a NETCONF server receives a <kill-session> request while
      processing a confirmed commit (Section 8.4), it must restore the
      configuration to its state before the confirmed commit was issued.

      Otherwise, the <kill-session> operation does not roll back
      configuration or other device state modifications made by the
      entity holding the lock.

   Parameters:

      session-id:

         Session identifier of the NETCONF session to be terminated.  If
         this value is equal to the current session ID, an
         'invalid-value' error is returned.

   Positive Response:

      If the device was able to satisfy the request, an <rpc-reply> is
      sent that includes an <ok> element.

   Negative Response:

      An <rpc-error> element is included in the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <kill-session>
         <session-id>4</session-id>
       </kill-session>
     </rpc>

     <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/>
     </rpc-reply>