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 C.  Future capability definitions may 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
   [6].  Capabilities defined in this document have the following
   format:

      urn:ietf:params:netconf:capability:{name}:1.0

   where {name} is the name of the capability.  Capabilities are often
   referenced in discussions and email using the shorthand :{name}.  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
   base NETCONF capability, "urn:ietf:params:netconf:base:1.0".

   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 <session-id> element MUST NOT continue the
   NETCONF session.  Similarly, a client that does not receive a
   <session-id> element in the server's <hello> message MUST NOT
   continue the NETCONF session.  In both cases, the underlying
   transport should be closed.

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

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 may be made to this data to construct the
   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 capability (Section 8.4) would make no sense as
   a "copy confirmed" operation.

   The candidate configuration may be shared among multiple sessions.
   Unless a client has specific information that the candidate
   configuration is not shared, it must assume that other sessions may
   be 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 a 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.

         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 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 should not be
   committed, the <discard-changes> operation can be used to revert the
   candidate configuration to the current running configuration.

     <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> <!-- any NETCONF operation -->
         <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:

     <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 capability indicates that the server will
   support the <confirmed> and <confirm-timeout> parameters for the
   <commit> protocol operation.  See Section 8.3 for further details on
   the <commit> operation.

   A confirmed commit operation MUST be reverted if a follow-up commit
   (called the "confirming commit") is not issued within 600 seconds (10
   minutes).  The timeout period can be adjusted with the
   <confirm-timeout> element.  The confirming commit can itself include
   a <confirmed> parameter.

   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.

   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.  Note that any commit operation, including a commit which
   introduces additional changes to the configuration, will serve as a
   confirming commit.  Thus to cancel a confirmed commit and revert
   changes without waiting for the confirm timeout to expire, the
   manager can explicitly restore the configuration to its state before
   the confirmed commit was issued.

   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 databases,
   configuration locking should also be used.

8.4.2.  Dependencies

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

8.4.3.  Capability Identifier

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

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

8.4.4.  New Operations

   None.

8.4.5.  Modifications to Existing Operations

8.4.5.1.  <commit>

   The :confirmed-commit capability allows 2 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.

   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>

8.5.  Rollback on Error Capability

8.5.1.  Description

   This capability indicates that the server will support the
   'rollback-on-error' value in the <error-option> parameter to the
   <edit-config> 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 databases,
   configuration locking also be used.

8.5.2.  Dependencies

   None

8.5.3.  Capability Identifier

   The :rollback-on-error capability is identified by the following
   capability string:

      urn:ietf:params:netconf:capability:rollback-on-error:1.0

8.5.4.  New Operations

   None.

8.5.5.  Modifications to Existing Operations

8.5.5.1.  <edit-config>

   The :rollback-on-error capability allows the 'rollback-on-error'
   value to the <error-option> parameter on the <edit-config> operation.


     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <edit-config>
         <target>
           <running/>
         </target>
         <error-option>rollback-on-error</error-option>
         <config>
           <top xmlns="http://example.com/schema/1.2/config">

             <interface>
               <name>Ethernet0/0</name>
               <mtu>100000</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>

8.6.  Validate Capability

8.6.1.  Description

   Validation consists of checking a candidate configuration for
   syntactical and semantic errors before applying the configuration to
   the device.

   If this capability is advertised, the device supports the <validate>
   protocol operation and checks at least for syntax errors.  In
   addition, this capability supports the test-option parameter to the
   <edit-config> operation and, when it is provided, checks at least for
   syntax errors.

8.6.2.  Dependencies

   None.

8.6.3.  Capability Identifier

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

      urn:ietf:params:netconf:capability:validate:1.0

8.6.4.  New Operations

8.6.4.1.  <validate>

   Description:

         This protocol operation validates the contents of the specified
         configuration.

   Parameters:

      source:

            Name of the configuration datastore being validated, such as
            <candidate> or the <config> element containing the
            configuration subtree to validate.

   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.

         A validate operation can fail for any of the following reasons:

         +  Syntax errors

         +  Missing parameters

         +  References to undefined configuration data

   Example:

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

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

8.7.  Distinct Startup Capability

8.7.1.  Description

   The device supports separate running and startup configuration
   datastores.  Operations that affect the running configuration will
   not be automatically copied to the startup configuration.  An
   explicit <copy-config> operation from the <running> to the <startup>
   must be invoked to update the startup configuration to the current
   contents of the running configuration.  NETCONF protocol operations
   refer to the startup datastore using the <startup> element.

8.7.2.  Dependencies

   None.

8.7.3.  Capability Identifier

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

      urn:ietf:params:netconf:capability:startup:1.0

8.7.4.  New Operations

   None.

8.7.5.  Modifications to Existing Operations

8.7.5.1.  General

   The :startup capability adds the <startup/> configuration datastore
   to arguments of several NETCONF operations.  The server MUST support
   the following additional values:

   +--------------------+--------------------------+-------------------+
   | Operation          | Parameters               | Notes             |
   +--------------------+--------------------------+-------------------+
   | <get-config>       | <source>                 |                   |
   |                    |                          |                   |
   | <copy-config>      | <source> <target>        |                   |
   |                    |                          |                   |
   | <lock>             | <target>                 |                   |
   |                    |                          |                   |
   | <unlock>           | <target>                 |                   |
   |                    |                          |                   |
   | <validate>         | <source>                 | If :validate is   |
   |                    |                          | advertised        |
   +--------------------+--------------------------+-------------------+

   To save the startup configuration, use the copy-config operation to
   copy the <running> configuration datastore to the <startup>
   configuration datastore.

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

8.8.  URL Capability

8.8.1.  Description

   The NETCONF peer has the ability to accept the <url> element in
   <source> and <target> parameters.  The capability is further
   identified by URL arguments indicating the URL schemes supported.

8.8.2.  Dependencies

   None.

8.8.3.  Capability Identifier

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

   urn:ietf:params:netconf:capability:url:1.0?scheme={name,...}

   The :url capability URI MUST contain a "scheme" argument assigned a
   comma-separated list of scheme names indicating which schemes the
   NETCONF peer supports.  For example:

      urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file

8.8.4.  New Operations

   None.

8.8.5.  Modifications to Existing Operations

8.8.5.1.  <edit-config>

   The :url capability modifies the <edit-config> operation to accept
   the <url> element as an alternative to the <config> parameter.  If
   the <url> element is specified, then it should identify a local
   configuration file.

8.8.5.2.  <copy-config>

   The :url capability modifies the <copy-config> operation to accept
   the <url> element as the value of the <source> and the <target>
   parameters.

8.8.5.3.  <delete-config>

   The :url capability modifies the <delete-config> operation to accept
   the <url> element as the value of the <target> parameters.  If this
   parameter contains a URL, then it should identify a local
   configuration file.

8.8.5.4.  <validate>

   The :url capability modifies the <validate> operation to accept the
   <url> element as the value of the <source> parameter.

8.9.  XPath Capability

8.9.1.  Description

   The XPath capability indicates that the NETCONF peer supports the use
   of XPath expressions in the <filter> element.  XPath is described in
   [2].

   The XPath expression must return a node-set.

   The XPath expression is evaluated in a context where the context node
   is the root node, and the set of namespace declarations are those in
   scope on the filter element, including the default namespace.

8.9.2.  Dependencies

   None.

8.9.3.  Capability Identifier

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

      urn:ietf:params:netconf:capability:xpath:1.0

8.9.4.  New Operations

   None.

8.9.5.  Modifications to Existing Operations

8.9.5.1.  <get-config> and <get>

   The :xpath capability modifies the <get> and <get-config> operations
   to accept the value "xpath" in the type attribute of the filter
   element.  When the type attribute is set to "xpath", a select
   attribute MUST be present on the filter element.  The select
   attribute will be treated as an XPath expression and used to filter
   the returned data.  The filter element itself MUST be empty in this
   case.

   For example:

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

         </source>
         <!-- get the user named fred -->
         <filter type="xpath" select="top/users/user[name='fred']"/>
        </get-config>
     </rpc>

9.  Security Considerations

   This document does not specify an authorization scheme, as such a
   scheme should be tied to a meta-data model or a data model.
   Implementors SHOULD provide a comprehensive authorization scheme with
   NETCONF.

   Authorization of individual users via the NETCONF server may or may
   not map 1:1 to other interfaces.  First, the data models may be
   incompatible.  Second, it may be desirable to authorize based on
   mechanisms available in the transport protocol layer (TELNET, SSH,
   etc).

   In addition, operations on configurations may have unintended
   consequences if those operations are also not guarded by the global
   lock on the files or objects being operated upon.  For instance, a
   partially complete access list could be committed from a candidate
   configuration unbeknownst to the owner of the lock of the candidate
   configuration, leading to either an insecure or inaccessible device
   if the lock on the candidate configuration does not also apply to the
   <copy-config> operation when applied to it.

   Configuration information is by its very nature sensitive.  Its
   transmission in the clear and without integrity checking leaves
   devices open to classic eavesdropping attacks.  Configuration
   information often contains passwords, user names, service
   descriptions, and topological information, all of which are
   sensitive.  Because of this, this protocol should be implemented
   carefully with adequate attention to all manner of attack one might
   expect to experience with other management interfaces.

   The protocol, therefore, must minimally support options for both
   confidentiality and authentication.  It is anticipated that the
   underlying protocol (SSH, BEEP, etc) will provide for both
   confidentiality and authentication, as is required.  It is further
   expected that the identity of each end of a NETCONF session will be
   available to the other in order to determine authorization for any
   given request.  One could also easily envision additional
   information, such as transport and encryption methods, being made
   available for purposes of authorization.  NETCONF itself provide no
   means to re-authenticate, much less authenticate.  All such actions
   occur at lower layers.

   Different environments may well allow different rights prior to and
   then after authentication.  Thus, an authorization model is not
   specified in this document.  When an operation is not properly
   authorized, a simple "access denied" is sufficient.  Note that
   authorization information may be exchanged in the form of
   configuration information, which is all the more reason to ensure the
   security of the connection.

   That having been said, it is important to recognize that some
   operations are clearly more sensitive by nature than others.  For
   instance, <copy-config> to the startup or running configurations is
   clearly not a normal provisioning operation, whereas <edit-config>
   is.  Such global operations MUST disallow the changing of information
   that an individual does not have authorization to perform.  For
   example, if a user A is not allowed to configure an IP address on an
   interface but user B has configured an IP address on an interface in
   the <candidate> configuration, user A must not be allowed to commit
   the <candidate> configuration.

   Similarly, just because someone says "go write a configuration
   through the URL capability at a particular place", this does not mean
   that an element should do it without proper authorization.

   The <lock> operation will demonstrate that NETCONF is intended for
   use by systems that have at least some trust of the administrator.
   As specified in this document, it is possible to lock portions of a
   configuration that a principal might not otherwise have access to.
   After all, the entire configuration is locked.  To mitigate this
   problem, there are two approaches.  It is possible to kill another
   NETCONF session programmatically from within NETCONF if one knows the
   session identifier of the offending session.  The other possible way
   to break a lock is to provide an function within the device's native
   user interface.  These two mechanisms suffer from a race condition
   that may be ameliorated by removing the offending user from an AAA
   server.  However, such a solution is not useful in all deployment
   scenarios, such as those where SSH public/private key pairs are used.

10.  IANA Considerations

10.1.  NETCONF XML Namespace

   This document registers a URI for the NETCONF XML namespace in the
   IETF XML registry [7].

   Following the format in RFC 3688, IANA has made the following
   registration.

   URI: urn:ietf:params:xml:ns:netconf:base:1.0

   Registrant Contact: The IESG.

   XML: N/A, the requested URI is an XML namespace.

10.2.  NETCONF XML Schema

   This document registers a URI for the NETCONF XML schema in the IETF
   XML registry [7].

   Following the format in RFC 3688, IANA has made the following
   registration.

   URI: urn:ietf:params:xml:schema:netconf

   Registrant Contact: The IESG.

   XML: Appendix B of this document.

10.3.  NETCONF Capability URNs

   This document creates a registry that allocates NETCONF capability
   identifiers.  Additions to the registry require IETF Standards
   Action.

   The initial content of the registry contains the capability URNs
   defined in Section 8.

   Following the guidelines in RFC 3553 [6], IANA assigned a NETCONF
   sub-namespace as follows:

   Registry name: netconf

   Specification: Section 8 of this document.

   Repository: The following table.

   +--------------------+----------------------------------------------+
   | Index              | Capability Identifier                        |
   +--------------------+----------------------------------------------+
   | :writable-running  | urn:ietf:params:netconf:capability:writable- |
   |                    | running:1.0                                  |
   |                    |                                              |
   | :candidate         | urn:ietf:params:netconf:capability:candidate |
   |                    | :1.0                                         |
   |                    |                                              |
   | :confirmed-commit  | urn:ietf:params:netconf:capability:confirmed |
   |                    | -commit:1.0                                  |
   |                    |                                              |
   | :rollback-on-error | urn:ietf:params:netconf:capability:rollback- |
   |                    | on-error:1.0                                 |
   |                    |                                              |
   | :validate          | urn:ietf:params:netconf:capability:validate: |
   |                    | 1.0                                          |
   |                    |                                              |
   | :startup           | urn:ietf:params:netconf:capability:startup:1 |
   |                    | .0                                           |
   |                    |                                              |
   | :url               | urn:ietf:params:netconf:capability:url:1.0   |
   |                    |                                              |
   | :xpath             | urn:ietf:params:netconf:capability:xpath:1.0 |
   +--------------------+----------------------------------------------+

   Index value: The capability name.

11.  Authors and Acknowledgements

   This document was written by:

      Andy Bierman

      Ken Crozier, Cisco Systems

      Rob Enns, Juniper Networks

      Ted Goddard, IceSoft

      Eliot Lear, Cisco Systems

      Phil Shafer, Juniper Networks

      Steve Waldbusser

      Margaret Wasserman, ThingMagic

   The authors would like to acknowledge the members of the NETCONF
   working group.  In particular, we would like to thank Wes Hardaker
   for his persistance and patience in assisting us with security
   considerations.  We would also like to thank Randy Presuhn, Sharon
   Chisholm, Juergen Schoenwalder, Glenn Waters, David Perkins, Weijing
   Chen, Simon Leinen, Keith Allen, and Dave Harrington for all of their
   valuable advice.