tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 6241

 
 
 

Network Configuration Protocol (NETCONF)

Part 3 of 5, p. 35 to 61
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 35 
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 can 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 YANG module in Appendix C.  The following sections
   describe the semantics of each protocol operation.

7.1.  <get-config>

   Description:  Retrieve all or part of a specified configuration
      datastore.

   Parameters:

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

Top      Up      ToC       Page 36 
      filter:  This parameter identifies the portions of the device
         configuration datastore to retrieve.  If this parameter is not
         present, 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>

Top      Up      ToC       Page 37 
               <company-info>
                 <dept>1</dept>
                 <id>1</id>
               </company-info>
             </user>
             <!-- additional <user> elements appear here... -->
           </users>
         </top>
       </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 datastore.
      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 datastore 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.

      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.

      If the <edit-config> operation contains multiple sub-operations
      that apply to the same conceptual node in the underlying data
      model, then the result of the operation is undefined (i.e.,
      outside the scope of the NETCONF protocol).

   Attributes:

      operation:  Elements in the <config> subtree MAY contain an
         "operation" attribute, which belongs to the NETCONF namespace
         defined in Section 3.1.  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.

Top      Up      ToC       Page 38 
         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.  If no such configuration data exists in the
            configuration datastore, it is created.  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 in
            the configuration datastore.  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 from the configuration
            if and only if the configuration data currently exists in
            the configuration datastore.  If the configuration data does
            not exist, an <rpc-error> element is returned with an
            <error-tag> value of "data-missing".

         remove:  The configuration data identified by the element
            containing this attribute is deleted from the configuration
            if the configuration data currently exists in the
            configuration datastore.  If the configuration data does not
            exist, the "remove" operation is silently ignored by the
            server.

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

Top      Up      ToC       Page 39 
         The <default-operation> parameter is optional, but if provided,
         it has 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:1.1 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.

         test-only:  Perform only the validation test, without
            attempting to set.

      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.

Top      Up      ToC       Page 40 
         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
      can 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>

Top      Up      ToC       Page 41 
     <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>

Top      Up      ToC       Page 42 
             </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>

Top      Up      ToC       Page 43 
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-config> operation.

      source:  Name of the configuration datastore to use as the source
         of the <copy-config> operation, or the <config> element
         containing the complete configuration 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:password@example.com/cfg/new.txt</url>
         </source>
       </copy-config>
     </rpc>

Top      Up      ToC       Page 44 
     <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
      entire configuration datastore 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.

Top      Up      ToC       Page 45 
      An attempt to lock the configuration datastore 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 can be explicitly
      performed by the client, or implicitly performed by the server
      based on criteria such as failure of the underlying transport,
      simple inactivity timeout, or detection of abusive behavior on the
      part of the client.  These criteria are dependent on the
      implementation and the underlying transport.

      The <lock> operation takes a mandatory parameter, <target>.  The
      <target> parameter names the configuration datastore that will be
      locked.  When a lock is active, using the <edit-config> operation
      on the locked configuration datastore 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> operation 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 any 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 target configuration is <running>, and another NETCONF
         session has an ongoing confirmed commit (Section 8.4).

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

Top      Up      ToC       Page 46 
      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.

Top      Up      ToC       Page 47 
     <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 either of the following
      conditions is 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.

Top      Up      ToC       Page 48 
   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
         not present, 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.

Top      Up      ToC       Page 49 
   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.

Top      Up      ToC       Page 50 
   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.

Top      Up      ToC       Page 51 
   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>

8.  Capabilities

   This section defines a set of capabilities that a client or a server
   MAY implement.  Each peer advertises its capabilities by sending them
   during an initial capabilities exchange.  Each peer needs to
   understand only those capabilities that it might use and MUST ignore
   any capability received from the other peer that it does not require
   or does not understand.

   Additional capabilities can be defined using the template in
   Appendix D.  Future capability definitions can be published as
   standards by standards bodies or published as proprietary extensions.

   A NETCONF capability is identified with a URI.  The base capabilities
   are defined using URNs following the method described in RFC 3553
   [RFC3553].  Capabilities defined in this document have the following
   format:

      urn:ietf:params:netconf:capability:{name}:1.x

   where {name} is the name of the capability.  Capabilities are often
   referenced in discussions and email using the shorthand :{name}, or
   :{name}:{version} if the capability exists in multiple versions.  For
   example, the foo capability would have the formal name
   "urn:ietf:params:netconf:capability:foo:1.0" and be called ":foo".
   The shorthand form MUST NOT be used inside the protocol.

8.1.  Capabilities Exchange

   Capabilities are advertised in messages sent by each peer during
   session establishment.  When the NETCONF session is opened, each peer
   (both client and server) MUST send a <hello> element containing a
   list of that peer's capabilities.  Each peer MUST send at least the

Top      Up      ToC       Page 52 
   base NETCONF capability, "urn:ietf:params:netconf:base:1.1".  A peer
   MAY include capabilities for previous NETCONF versions, to indicate
   that it supports multiple protocol versions.

   Both NETCONF peers MUST verify that the other peer has advertised a
   common protocol version.  When comparing protocol version capability
   URIs, only the base part is used, in the event any parameters are
   encoded at the end of the URI string.  If no protocol version
   capability in common is found, the NETCONF peer MUST NOT continue the
   session.  If more than one protocol version URI in common is present,
   then the highest numbered (most recent) protocol version MUST be used
   by both peers.

   A server sending the <hello> element MUST include a <session-id>
   element containing the session ID for this NETCONF session.  A client
   sending the <hello> element MUST NOT include a <session-id> element.

   A server receiving a <hello> message with a <session-id> element MUST
   terminate the NETCONF session.  Similarly, a client that does not
   receive a <session-id> element in the server's <hello> message MUST
   terminate the NETCONF session (without first sending a
   <close-session>).

   In the following example, a server advertises the base NETCONF
   capability, one NETCONF capability defined in the base NETCONF
   document, and one implementation-specific capability.

   <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
     <capabilities>
       <capability>
         urn:ietf:params:netconf:base:1.1
       </capability>
       <capability>
         urn:ietf:params:netconf:capability:startup:1.0
       </capability>
       <capability>
         http://example.net/router/2.3/myfeature
       </capability>
     </capabilities>
     <session-id>4</session-id>
   </hello>

   Each peer sends its <hello> element simultaneously as soon as the
   connection is open.  A peer MUST NOT wait to receive the capability
   set from the other side before sending its own set.

Top      Up      ToC       Page 53 
8.2.  Writable-Running Capability

8.2.1.  Description

   The :writable-running capability indicates that the device supports
   direct writes to the <running> configuration datastore.  In other
   words, the device supports <edit-config> and <copy-config> operations
   where the <running> configuration is the target.

8.2.2.  Dependencies

   None.

8.2.3.  Capability Identifier

   The :writable-running capability is identified by the following
   capability string:

      urn:ietf:params:netconf:capability:writable-running:1.0

8.2.4.  New Operations

   None.

8.2.5.  Modifications to Existing Operations

8.2.5.1.  <edit-config>

   The :writable-running capability modifies the <edit-config> operation
   to accept the <running> element as a <target>.

8.2.5.2.  <copy-config>

   The :writable-running capability modifies the <copy-config> operation
   to accept the <running> element as a <target>.

8.3.  Candidate Configuration Capability

8.3.1.  Description

   The candidate configuration capability, :candidate, indicates that
   the device supports a candidate configuration datastore, which is
   used to hold configuration data that can be manipulated without
   impacting the device's current configuration.  The candidate
   configuration is a full configuration data set that serves as a work
   place for creating and manipulating configuration data.  Additions,
   deletions, and changes can be made to this data to construct the

Top      Up      ToC       Page 54 
   desired configuration data.  A <commit> operation MAY be performed at
   any time that causes the device's running configuration to be set to
   the value of the candidate configuration.

   The <commit> operation effectively sets the running configuration to
   the current contents of the candidate configuration.  While it could
   be modeled as a simple copy, it is done as a distinct operation for a
   number of reasons.  In keeping high-level concepts as first-class
   operations, we allow developers to see more clearly both what the
   client is requesting and what the server must perform.  This keeps
   the intentions more obvious, the special cases less complex, and the
   interactions between operations more straightforward.  For example,
   the :confirmed-commit:1.1 capability (Section 8.4) would make no
   sense as a "copy confirmed" operation.

   The candidate configuration can be shared among multiple sessions.
   Unless a client has specific information that the candidate
   configuration is not shared, it MUST assume that other sessions are
   able to modify the candidate configuration at the same time.  It is
   therefore prudent for a client to lock the candidate configuration
   before modifying it.

   The client can discard any uncommitted changes to the candidate
   configuration by executing the <discard-changes> operation.  This
   operation reverts the contents of the candidate configuration to the
   contents of the running configuration.

8.3.2.  Dependencies

   None.

8.3.3.  Capability Identifier

   The :candidate capability is identified by the following capability
   string:

      urn:ietf:params:netconf:capability:candidate:1.0

8.3.4.  New Operations

8.3.4.1.  <commit>

   Description:

         When the candidate configuration's content is complete, the
         configuration data can be committed, publishing the data set to
         the rest of the device and requesting the device to conform to
         the behavior described in the new configuration.

Top      Up      ToC       Page 55 
         To commit the candidate configuration as the device's new
         current configuration, use the <commit> operation.

         The <commit> operation instructs the device to implement the
         configuration data contained in the candidate configuration.
         If the device is unable to commit all of the changes in the
         candidate configuration datastore, then the running
         configuration MUST remain unchanged.  If the device does
         succeed in committing, the running configuration MUST be
         updated with the contents of the candidate configuration.

         If the running or candidate configuration is currently locked
         by a different session, the <commit> operation MUST fail with
         an <error-tag> value of "in-use".

         If the system does not have the :candidate capability, the
         <commit> operation is not available.

   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">
       <commit/>
     </rpc>

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

8.3.4.2.  <discard-changes>

   If the client decides that the candidate configuration is not to be
   committed, the <discard-changes> operation can be used to revert the
   candidate configuration to the current running configuration.

Top      Up      ToC       Page 56 
     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <discard-changes/>
     </rpc>

   This operation discards any uncommitted changes by resetting the
   candidate configuration with the content of the running
   configuration.

8.3.5.  Modifications to Existing Operations

8.3.5.1.  <get-config>, <edit-config>, <copy-config>, and <validate>

   The candidate configuration can be used as a source or target of any
   <get-config>, <edit-config>, <copy-config>, or <validate> operation
   as a <source> or <target> parameter.  The <candidate> element is used
   to indicate the candidate configuration:

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

8.3.5.2.  <lock> and <unlock>

   The candidate configuration can be locked using the <lock> operation
   with the <candidate> element as the <target> parameter:

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

   Similarly, the candidate configuration is unlocked using the
   <candidate> element as the <target> parameter:

Top      Up      ToC       Page 57 
     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <unlock>
         <target>
           <candidate/>
         </target>
       </unlock>
     </rpc>

   When a client fails with outstanding changes to the candidate
   configuration, recovery can be difficult.  To facilitate easy
   recovery, any outstanding changes are discarded when the lock is
   released, whether explicitly with the <unlock> operation or
   implicitly from session failure.

8.4.  Confirmed Commit Capability

8.4.1.  Description

   The :confirmed-commit:1.1 capability indicates that the server will
   support the <cancel-commit> operation and the <confirmed>,
   <confirm-timeout>, <persist>, and <persist-id> parameters for the
   <commit> operation.  See Section 8.3 for further details on the
   <commit> operation.

   A confirmed <commit> operation MUST be reverted if a confirming
   commit is not issued within the timeout period (by default 600
   seconds = 10 minutes).  The confirming commit is a <commit> operation
   without the <confirmed> parameter.  The timeout period can be
   adjusted with the <confirm-timeout> parameter.  If a follow-up
   confirmed <commit> operation is issued before the timer expires, the
   timer is reset to the new value (600 seconds by default).  Both the
   confirming commit and a follow-up confirmed <commit> operation MAY
   introduce additional changes to the configuration.

   If the <persist> element is not given in the confirmed commit
   operation, any follow-up commit and the confirming commit MUST be
   issued on the same session that issued the confirmed commit.  If the
   <persist> element is given in the confirmed <commit> operation, a
   follow-up commit and the confirming commit can be given on any
   session, and they MUST include a <persist-id> element with a value
   equal to the given value of the <persist> element.

   If the server also advertises the :startup capability, a
   <copy-config> from running to startup is also necessary to save the
   changes to startup.

Top      Up      ToC       Page 58 
   If the session issuing the confirmed commit is terminated for any
   reason before the confirm timeout expires, the server MUST restore
   the configuration to its state before the confirmed commit was
   issued, unless the confirmed commit also included a <persist>
   element.

   If the device reboots for any reason before the confirm timeout
   expires, the server MUST restore the configuration to its state
   before the confirmed commit was issued.

   If a confirming commit is not issued, the device will revert its
   configuration to the state prior to the issuance of the confirmed
   commit.  To cancel a confirmed commit and revert changes without
   waiting for the confirm timeout to expire, the client can explicitly
   restore the configuration to its state before the confirmed commit
   was issued, by using the <cancel-commit> operation.

   For shared configurations, this feature can cause other configuration
   changes (for example, via other NETCONF sessions) to be inadvertently
   altered or removed, unless the configuration locking feature is used
   (in other words, the lock is obtained before the <edit-config>
   operation is started).  Therefore, it is strongly suggested that in
   order to use this feature with shared configuration datastores,
   configuration locking SHOULD also be used.

   Version 1.0 of this capability was defined in [RFC4741].  Version 1.1
   is defined in this document, and extends version 1.0 by adding a new
   operation, <cancel-commit>, and two new optional parameters,
   <persist> and <persist-id>.  For backwards compatibility with old
   clients, servers conforming to this specification MAY advertise
   version 1.0 in addition to version 1.1.

8.4.2.  Dependencies

   The :confirmed-commit:1.1 capability is only relevant if the
   :candidate capability is also supported.

8.4.3.  Capability Identifier

   The :confirmed-commit:1.1 capability is identified by the following
   capability string:

      urn:ietf:params:netconf:capability:confirmed-commit:1.1

Top      Up      ToC       Page 59 
8.4.4.  New Operations

8.4.4.1.  <cancel-commit>

   Description:

         Cancels an ongoing confirmed commit.  If the <persist-id>
         parameter is not given, the <cancel-commit> operation MUST be
         issued on the same session that issued the confirmed commit.

   Parameters:

      persist-id:

            Cancels a persistent confirmed commit.  The value MUST be
            equal to the value given in the <persist> parameter to the
            <commit> operation.  If the value does not match, the
            operation fails with an "invalid-value" error.

   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">
       <commit>
         <confirmed/>
       </commit>
     </rpc>

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

     <rpc message-id="102"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <cancel-commit/>
     </rpc>

Top      Up      ToC       Page 60 
     <rpc-reply message-id="102"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <ok/>
     </rpc-reply>

8.4.5.  Modifications to Existing Operations

8.4.5.1.  <commit>

   The :confirmed-commit:1.1 capability allows 4 additional parameters
   to the <commit> operation.

   Parameters:

      confirmed:

            Perform a confirmed <commit> operation.

      confirm-timeout:

            Timeout period for confirmed commit, in seconds.  If
            unspecified, the confirm timeout defaults to 600 seconds.

      persist:

            Make the confirmed commit survive a session termination, and
            set a token on the ongoing confirmed commit.

      persist-id:

            Used to issue a follow-up confirmed commit or a confirming
            commit from any session, with the token from the previous
            <commit> operation.

   Example:

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <commit>
         <confirmed/>
         <confirm-timeout>120</confirm-timeout>
       </commit>
     </rpc>

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

Top      Up      ToC       Page 61 
   Example:

     <!-- start a persistent confirmed-commit -->
     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <commit>
         <confirmed/>
         <persist>IQ,d4668</persist>
       </commit>
     </rpc>

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

     <!-- confirm the persistent confirmed-commit,
          possibly from another session -->
     <rpc message-id="102"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <commit>
         <persist-id>IQ,d4668</persist-id>
       </commit>
     </rpc>

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



(page 61 continued on part 4)

Next RFC Part