Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 4741

NETCONF Configuration Protocol

Pages: 95
Obsoleted by:  6241
Part 3 of 4 – Pages 49 to 68
First   Prev   Next

ToP   noToC   RFC4741 - Page 49   prevText

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.
ToP   noToC   RFC4741 - Page 50
   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
ToP   noToC   RFC4741 - Page 51

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.
ToP   noToC   RFC4741 - Page 52
   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.
ToP   noToC   RFC4741 - Page 53
   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:
ToP   noToC   RFC4741 - Page 54
     <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.
ToP   noToC   RFC4741 - Page 55

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.
ToP   noToC   RFC4741 - Page 56

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>
ToP   noToC   RFC4741 - Page 57

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">
ToP   noToC   RFC4741 - Page 58
             <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.
ToP   noToC   RFC4741 - Page 59
   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>
ToP   noToC   RFC4741 - Page 60

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:
ToP   noToC   RFC4741 - Page 61
   +--------------------+--------------------------+-------------------+
   | 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.
ToP   noToC   RFC4741 - Page 62

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.
ToP   noToC   RFC4741 - Page 63

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/>
ToP   noToC   RFC4741 - Page 64
         </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.
ToP   noToC   RFC4741 - Page 65
   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.
ToP   noToC   RFC4741 - Page 66

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.
ToP   noToC   RFC4741 - Page 67
   +--------------------+----------------------------------------------+
   | 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.
ToP   noToC   RFC4741 - Page 68

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.


(page 68 continued on part 4)

Next Section