Network Working Group R. Enns, Ed. Internet-Draft Juniper Networks Intended status: Standards Track M. Bjorklund, Ed. Expires: August 8, 2010 Tail-f Systems J. Schoenwaelder, Ed. Jacobs University A. Bierman, Ed. InterWorking Labs February 4, 2010 Network Configuration Protocol (NETCONF) draft-ietf-netconf-4741bis-02 Abstract The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as Remote Procedure Calls (RPC). Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on August 8, 2010. Copyright Notice Enns, et al. Expires August 8, 2010 [Page 1] Internet-Draft NETCONF Protocol February 2010 Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the BSD License. This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. Enns, et al. Expires August 8, 2010 [Page 2] Internet-Draft NETCONF Protocol February 2010 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Protocol Overview . . . . . . . . . . . . . . . . . . . . 7 1.2. Capabilities . . . . . . . . . . . . . . . . . . . . . . 8 1.3. Separation of Configuration and State Data . . . . . . . 8 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 10 2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 10 2.2. Authentication, Integrity, and Confidentiality . . . . . 10 2.3. Authentication . . . . . . . . . . . . . . . . . . . . . 11 2.4. Mandatory Transport Protocol . . . . . . . . . . . . . . 11 3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 12 3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2. No Document Type Declarations . . . . . . . . . . . . . . 12 4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1. Element . . . . . . . . . . . . . . . . . . . . . . 13 4.2. Element . . . . . . . . . . . . . . . . . . . 14 4.3. Element . . . . . . . . . . . . . . . . . . . 15 4.4. Element . . . . . . . . . . . . . . . . . . . . . . 18 4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 18 5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 19 5.1. Configuration Datastores . . . . . . . . . . . . . . . . 19 5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 19 6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 20 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 20 6.2. Subtree Filter Components . . . . . . . . . . . . . . . . 21 6.2.1. Namespace Selection . . . . . . . . . . . . . . . . . 21 6.2.2. Attribute Match Expressions . . . . . . . . . . . . . 21 6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 22 6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 22 6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 23 6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 24 6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 25 6.4.1. No Filter . . . . . . . . . . . . . . . . . . . . . . 25 6.4.2. Empty Filter . . . . . . . . . . . . . . . . . . . . 26 6.4.3. Select the Entire Subtree . . . . . . . . . . 26 6.4.4. Select All Elements within the Subtree . . . . . . . . . . . . . . . . . . . . . . . 28 6.4.5. One Specific Entry . . . . . . . . . . . . . . 29 6.4.6. Specific Elements from a Specific Entry . . . 30 6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 31 6.4.8. Elements with Attribute Naming . . . . . . . . . . . 33 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 35 7.1. . . . . . . . . . . . . . . . . . . . . . . 35 7.2. . . . . . . . . . . . . . . . . . . . . . . 38 7.3. . . . . . . . . . . . . . . . . . . . . . . 45 7.4. . . . . . . . . . . . . . . . . . . . . . 47 7.5. . . . . . . . . . . . . . . . . . . . . . . . . . 47 Enns, et al. Expires August 8, 2010 [Page 3] Internet-Draft NETCONF Protocol February 2010 7.6. . . . . . . . . . . . . . . . . . . . . . . . . 50 7.7. . . . . . . . . . . . . . . . . . . . . . . . . . . 51 7.8. . . . . . . . . . . . . . . . . . . . . . 53 7.9. . . . . . . . . . . . . . . . . . . . . . 54 8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 56 8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 56 8.2. Writable-Running Capability . . . . . . . . . . . . . . . 57 8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 57 8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 57 8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 57 8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 57 8.2.5. Modifications to Existing Operations . . . . . . . . 57 8.3. Candidate Configuration Capability . . . . . . . . . . . 58 8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 58 8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 59 8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 59 8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 59 8.3.5. Modifications to Existing Operations . . . . . . . . 60 8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 61 8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 61 8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 62 8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 62 8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 62 8.4.5. Modifications to Existing Operations . . . . . . . . 62 8.5. Rollback on Error Capability . . . . . . . . . . . . . . 63 8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 63 8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 63 8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 64 8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 64 8.5.5. Modifications to Existing Operations . . . . . . . . 64 8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 64 8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 64 8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 65 8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 65 8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 65 8.6.5. Modifications to Existing Operations . . . . . . . . 66 8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 66 8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 66 8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 67 8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 67 8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 67 8.7.5. Modifications to Existing Operations . . . . . . . . 67 8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 68 8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 68 8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 68 8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 68 8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 68 8.8.5. Modifications to Existing Operations . . . . . . . . 68 Enns, et al. Expires August 8, 2010 [Page 4] Internet-Draft NETCONF Protocol February 2010 8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 69 8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 69 8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 70 8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 70 8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 70 8.9.5. Modifications to Existing Operations . . . . . . . . 70 9. Security Considerations . . . . . . . . . . . . . . . . . . . 72 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 74 10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 74 10.3. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 74 11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 76 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 12.1. Normative References . . . . . . . . . . . . . . . . . . 77 12.2. Informative References . . . . . . . . . . . . . . . . . 77 Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 79 Appendix B. XML Schema for NETCONF Messages Layer . . . . . . . 83 Appendix C. YANG Module for NETCONF Protocol Operations . . . . 88 Appendix D. Capability Template . . . . . . . . . . . . . . . . 102 D.1. capability-name (template) . . . . . . . . . . . . . . . 102 D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 102 D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 102 D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 102 D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 102 D.1.5. Modifications to Existing Operations . . . . . . . . 102 D.1.6. Interactions with Other Capabilities . . . . . . . . 102 Appendix E. Configuring Multiple Devices with NETCONF . . . . . 103 E.1. Operations on Individual Devices . . . . . . . . . . . . 103 E.1.1. Acquiring the Configuration Lock . . . . . . . . . . 103 E.1.2. Loading the Update . . . . . . . . . . . . . . . . . 104 E.1.3. Validating the Incoming Configuration . . . . . . . . 105 E.1.4. Checkpointing the Running Configuration . . . . . . . 105 E.1.5. Changing the Running Configuration . . . . . . . . . 106 E.1.6. Testing the New Configuration . . . . . . . . . . . . 107 E.1.7. Making the Change Permanent . . . . . . . . . . . . . 107 E.1.8. Releasing the Configuration Lock . . . . . . . . . . 108 E.2. Operations on Multiple Devices . . . . . . . . . . . . . 108 Appendix F. Changes from RFC 4741 . . . . . . . . . . . . . . . 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 111 Enns, et al. Expires August 8, 2010 [Page 5] Internet-Draft NETCONF Protocol February 2010 1. Introduction The NETCONF protocol defines a simple mechanism through which a network device can be managed, configuration data information can be retrieved, and new configuration data can be uploaded and manipulated. The protocol allows the device to expose a full, formal application programming interface (API). Applications can use this straightforward API to send and receive full and partial configuration data sets. The NETCONF protocol uses a remote procedure call (RPC) paradigm. A client encodes an RPC in XML [1] and sends it to a server using a secure, connection-oriented session. The server responds with a reply encoded in XML. The contents of both the request and the response are fully described in XML DTDs or XML schemas, or both, allowing both parties to recognize the syntax constraints imposed on the exchange. A key aspect of NETCONF is that it allows the functionality of the management protocol to closely mirror the native functionality of the device. This reduces implementation costs and allows timely access to new features. In addition, applications can access both the syntactic and semantic content of the device's native user interface. NETCONF allows a client to discover the set of protocol extensions supported by a server. These "capabilities" permit the client to adjust its behavior to take advantage of the features exposed by the device. The capability definitions can be easily extended in a noncentralized manner. Standard and non-standard capabilities can be defined with semantic and syntactic rigor. Capabilities are discussed in Section 8. The NETCONF protocol is a building block in a system of automated configuration. XML is the lingua franca of interchange, providing a flexible but fully specified encoding mechanism for hierarchical content. NETCONF can be used in concert with XML-based transformation technologies, such as XSLT [10], to provide a system for automated generation of full and partial configurations. The system can query one or more databases for data about networking topologies, links, policies, customers, and services. This data can be transformed using one or more XSLT scripts from a task-oriented, vendor-independent data schema into a form that is specific to the vendor, product, operating system, and software release. The resulting data can be passed to the device using the NETCONF protocol. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this Enns, et al. Expires August 8, 2010 [Page 6] Internet-Draft NETCONF Protocol February 2010 document are to be interpreted as described in RFC 2119 [3]. 1.1. Protocol Overview NETCONF uses a simple RPC-based mechanism to facilitate communication between a client and a server. The client can be a script or application typically running as part of a network manager. The server is typically a network device. The terms "device" and "server" are used interchangeably in this document, as are "client" and "application". A NETCONF session is the logical connection between a network administrator or network configuration application and a network device. A device MUST support at least one NETCONF session and SHOULD support multiple sessions. Global configuration attributes can be changed during any authorized session, and the effects are visible in all sessions. Session-specific attributes affect only the session in which they are changed. NETCONF can be conceptually partitioned into four layers: Layer Example +-------------+ +-----------------+ +----------------+ (4) | Content | | Configuration | | Notification | | | | data | | data | +-------------+ +-----------------+ +----------------+ | | | +-------------+ +-----------------+ | (3) | Operations | | | | | | | | | +-------------+ +-----------------+ | | | | +-------------+ +-----------------+ +----------------+ (2) | Messages | | , | | | | | | | | | +-------------+ +-----------------+ +----------------+ | | | +-------------+ +-----------------------------------------+ (1) | Secure | | SSH, TLS, BEEP/TLS, SOAP/HTTP/TLS, ... | | Transports | | | +-------------+ +-----------------------------------------+ 1. The Secure Transport layer provides a communication path between the client and server. NETCONF can be layered over any transport protocol that provides a set of basic requirements. Section 2 discusses these requirements. Enns, et al. Expires August 8, 2010 [Page 7] Internet-Draft NETCONF Protocol February 2010 2. The Messages layer provides a simple, transport-independent framing mechanism for encoding RPCs. Section 4 documents this protocol. 3. The Operations layer defines a set of base operations invoked as RPC methods with XML-encoded parameters. Section 7 details the list of base operations. 4. The Content layer is outside the scope of this document. Given the current proprietary nature of the configuration data being manipulated, the specification of this content depends on the NETCONF implementation. It is expected that a separate effort to specify a standard data definition language and standard content will be undertaken. 1.2. Capabilities A NETCONF capability is a set of functionality that supplements the base NETCONF specification. The capability is identified by a uniform resource identifier (URI). These URIs should follow the guidelines as described in Section 8. Capabilities augment the base operations of the device, describing both additional operations and the content allowed inside operations. The client can discover the server's capabilities and use any additional operations, parameters, and content defined by those capabilities. The capability definition may name one or more dependent capabilities. To support a capability, the server MUST support any capabilities upon which it depends. Section 8 defines the capabilities exchange that allows the client to discover the server's capabilities. Section 8 also lists the set of capabilities defined in this document. Additional capabilities can be defined at any time in external documents, allowing the set of capabilities to expand over time. Standards bodies may define standardized capabilities, and implementations may define proprietary ones. A capability URI MUST sufficiently distinguish the naming authority to avoid naming collisions. 1.3. Separation of Configuration and State Data The information that can be retrieved from a running system is separated into two classes, configuration data and state data. Configuration data is the set of writable data that is required to Enns, et al. Expires August 8, 2010 [Page 8] Internet-Draft NETCONF Protocol February 2010 transform a system from its initial default state into its current state. State data is the additional data on a system that is not configuration data such as read-only status information and collected statistics. When a device is performing configuration operations, a number of problems would arise if state data were included: o Comparisons of configuration data sets would be dominated by irrelevant entries such as different statistics. o Incoming data could contain nonsensical requests, such as attempts to write read-only data. o The data sets would be large. o Archived data could contain values for read-only data items, complicating the processing required to restore archived data. To account for these issues, the NETCONF protocol recognizes the difference between configuration data and state data and provides operations for each. The operation retrieves configuration data only, while the operation retrieves configuration and state data. Note that the NETCONF protocol is focused on the information required to get the device into its desired running state. The inclusion of other important, persistent data is implementation specific. For example, user files and databases are not treated as configuration data by the NETCONF protocol. If a local database of user authentication data is stored on the device, whether it is included in configuration data is an implementation-dependent matter. Enns, et al. Expires August 8, 2010 [Page 9] Internet-Draft NETCONF Protocol February 2010 2. Transport Protocol Requirements NETCONF uses an RPC-based communication paradigm. A client sends a series of one or more RPC request operations, which cause the server to respond with a corresponding series of RPC replies. The NETCONF protocol can be layered on any transport protocol that provides the required set of functionality. It is not bound to any particular transport protocol, but allows a mapping to define how it can be implemented over any specific protocol. The transport protocol MUST provide a mechanism to indicate the session type (client or server) to the NETCONF protocol layer. This section details the characteristics that NETCONF requires from the underlying transport protocol. 2.1. Connection-Oriented Operation NETCONF is connection-oriented, requiring a persistent connection between peers. This connection must provide reliable, sequenced data delivery. NETCONF connections are long-lived, persisting between protocol operations. This allows the client to make changes to the state of the connection that will persist for the lifetime of the connection. For example, authentication information specified for a connection remains in effect until the connection is closed. In addition, resources requested from the server for a particular connection MUST be automatically released when the connection closes, making failure recovery simpler and more robust. For example, when a lock is acquired by a client, the lock persists until either it is explicitly released or the server determines that the connection has been terminated. If a connection is terminated while the client holds a lock, the server can perform any appropriate recovery. The lock operation is further discussed in Section 7.5. 2.2. Authentication, Integrity, and Confidentiality NETCONF connections must provide authentication, data integrity, and confidentiality. NETCONF depends on the transport protocol for this capability. A NETCONF peer assumes that appropriate levels of security and confidentiality are provided independently of this document. For example, connections may be encrypted in TLS [11] or SSH [12], depending on the underlying protocol. Enns, et al. Expires August 8, 2010 [Page 10] Internet-Draft NETCONF Protocol February 2010 2.3. Authentication NETCONF connections must be authenticated. The transport protocol is responsible for authentication. The peer assumes that the connection's authentication information has been validated by the underlying protocol using sufficiently trustworthy mechanisms and that the peer's identity has been sufficiently proven. One goal of NETCONF is to provide a programmatic interface to the device that closely follows the functionality of the device's native interface. Therefore, it is expected that the underlying protocol uses existing authentication mechanisms defined by the device. For example, a device that supports RADIUS [13] should allow the use of RADIUS to authenticate NETCONF sessions. The authentication process should result in an identity whose permissions are known to the device. These permissions MUST be enforced during the remainder of the NETCONF session. 2.4. Mandatory Transport Protocol A NETCONF implementation MUST support the SSH transport protocol mapping [4]. Enns, et al. Expires August 8, 2010 [Page 11] Internet-Draft NETCONF Protocol February 2010 3. XML Considerations XML serves as the encoding format for NETCONF, allowing complex hierarchical data to be expressed in a text format that can be read, saved, and manipulated with both traditional text tools and tools specific to XML. All NETCONF messages MUST be well-formed XML, encoded in UTF-8. A NETCONF message MAY begin with an XML declaration (see section 2.8 of [1]). This section discusses a small number of XML-related considerations pertaining to NETCONF. 3.1. Namespace All NETCONF protocol elements are defined in the following namespace: urn:ietf:params:xml:ns:netconf:base:1.0 NETCONF capability names MUST be URIs [5]. NETCONF capabilities are discussed in Section 8. 3.2. No Document Type Declarations Document type declarations MUST NOT appear in NETCONF content. Enns, et al. Expires August 8, 2010 [Page 12] Internet-Draft NETCONF Protocol February 2010 4. RPC Model The NETCONF protocol uses an RPC-based communication model. NETCONF peers use and elements to provide transport protocol-independent framing of NETCONF requests and responses. The syntax and XML encoding of the Messages layer RPCs are formally defined in the XML schema in Appendix B. 4.1. Element The element is used to enclose a NETCONF request sent from the client to the server. The element has a mandatory attribute "message-id", which is an arbitrary string chosen by the sender of the RPC that will commonly encode a monotonically increasing integer. The receiver of the RPC does not decode or interpret this string but simply saves it to be used as a "message-id" attribute in any resulting message. For example: If additional attributes are present in an element, a NETCONF peer MUST return them unmodified in the element. This includes any "xmlns" attributes. The name and parameters of an RPC are encoded as the contents of the element. The name of the RPC is an element directly inside the element, and any parameters are encoded inside this element. The following example invokes a method called , which has two parameters, , with a value of "14", and , with a value of "fred": 14 fred Enns, et al. Expires August 8, 2010 [Page 13] Internet-Draft NETCONF Protocol February 2010 The following example invokes a method with a parameter of "27606-0100": 27606-0100 The following example invokes the NETCONF method with no parameters: 4.2. Element The message is sent in response to an operation. The element has a mandatory attribute "message-id", which is equal to the "message-id" attribute of the for which this is a response. A NETCONF peer MUST also return any additional attributes included in the element unmodified in the element. The response data is encoded as one or more child elements to the element. For example: The following element invokes the NETCONF method and includes an additional attribute called "user-id". Note that the "user-id" attribute is not in the NETCONF namespace. The returned element returns the "user-id" attribute, as well as the requested content. Enns, et al. Expires August 8, 2010 [Page 14] Internet-Draft NETCONF Protocol February 2010 4.3. Element The element is sent in messages if an error occurs during the processing of an request. If a server encounters multiple errors during the processing of an request, the MAY contain multiple elements. However, a server is not required to detect or report more than one element, if a request contains multiple errors. A server is not required to check for particular error conditions in a specific sequence. A server MUST return an element if any error conditions occur during processing and SHOULD return an element if any warning conditions occur during processing. A server MUST NOT return application-level- or data-model-specific error information in an element for which the client does not have sufficient access rights. The element includes the following information: error-type: Defines the conceptual layer that the error occurred. Enumeration. One of: * transport (layer: Secure Transport) * rpc (layer: Messages) * protocol (layer: Operations) Enns, et al. Expires August 8, 2010 [Page 15] Internet-Draft NETCONF Protocol February 2010 * application (layer: Content) error-tag: Contains a string identifying the error condition. See Appendix A for allowed values. error-severity: Contains a string identifying the error severity, as determined by the device. One of: * error * warning error-app-tag: Contains a string identifying the data-model-specific or implementation-specific error condition, if one exists. This element will not be present if no appropriate application error tag can be associated with a particular error condition. error-path: Contains the absolute XPath [2] expression identifying the element path to the node that is associated with the error being reported in a particular rpc-error element. This element will not be present if no appropriate payload element or data store node can be associated with a particular error condition. The XPath expression is interpreted in the following context: * The set of namespace declarations are those in scope on the rpc-error element. * The set of variable bindings is empty. * The function library is the core function library. The context node depends on the node associated with the error being reported: * If a payload element can be associated with the error, the context node is the rpc request's document node (i.e. the "rpc" element). * Otherwise, the context node is the root of all data models, i.e. the node which has the top-level nodes from all data models as children. error-message: Contains a string suitable for human display that describes the error condition. This element will not be present if no appropriate message is provided for a particular error condition. This element SHOULD include an xml:lang attribute as defined in [1] and discussed in [14]. Enns, et al. Expires August 8, 2010 [Page 16] Internet-Draft NETCONF Protocol February 2010 error-info: Contains protocol- or data-model-specific error content. This element will not be present if no such error content is provided for a particular error condition. The list in Appendix A defines any mandatory error-info content for each error. After any protocol-mandated content, a data model definition may mandate that certain application-layer error information be included in the error-info container. An implementation may include additional elements to provide extended and/or implementation- specific debugging information. Appendix A enumerates the standard NETCONF errors. Example: An error is returned if an element is received without a message-id attribute. Note that only in this case is it acceptable for the NETCONF peer to omit the message-id attribute in the element. rpc missing-attribute error message-id rpc The following illustrates the case of returning multiple elements. Note that the data models used in the examples in this section use the element to distinguish between multiple instances of the element. Enns, et al. Expires August 8, 2010 [Page 17] Internet-Draft NETCONF Protocol February 2010 application invalid-value error /t:top/t:interface[t:name="Ethernet0/0"]/t:mtu MTU value 25000 is not within range 256..9192 application invalid-value error /t:top/t:interface[t:name="Ethernet1/0"]/t:address/t:name Invalid IP address for interface Ethernet1/0 4.4. Element The element is sent in messages if no errors or warnings occurred during the processing of an request, and no data was returned from the operation. For example: 4.5. Pipelining NETCONF requests MUST be processed serially by the managed device. Additional requests MAY be sent before previous ones have been completed. The managed device MUST send responses only in the order the requests were received. Enns, et al. Expires August 8, 2010 [Page 18] Internet-Draft NETCONF Protocol February 2010 5. Configuration Model NETCONF provides an initial set of operations and a number of capabilities that can be used to extend the base. NETCONF peers exchange device capabilities when the session is initiated as described in Section 8.1. 5.1. Configuration Datastores NETCONF defines the existence of one or more configuration datastores and allows configuration operations on them. A configuration datastore is defined as the complete set of configuration data that is required to get a device from its initial default state into a desired operational state. The configuration datastore does not include state data or executive commands. Only the configuration datastore is present in the base model. Additional configuration datastores may be defined by capabilities. Such configuration datastores are available only on devices that advertise the capabilities. o Running: The complete configuration currently active on the network device. Only one configuration datastore of this type exists on the device, and it is always present. NETCONF protocol operations refer to this datastore using the element. The capabilities in Sections 8.3 and 8.7 define the and configuration datastores, respectively. 5.2. Data Modeling Data modeling and content issues are outside the scope of the NETCONF protocol. An assumption is made that the device's data model is well-known to the application and that both parties are aware of issues such as the layout, containment, keying, lookup, replacement, and management of the data, as well as any other constraints imposed by the data model. NETCONF carries configuration data inside the element that is specific to device's data model. The protocol treats the contents of that element as opaque data. The device uses capabilities to announce the set of data models that the device implements. The capability definition details the operation and constraints imposed by data model. Devices and managers may support multiple data models, including both standard and proprietary data models. Enns, et al. Expires August 8, 2010 [Page 19] Internet-Draft NETCONF Protocol February 2010 6. Subtree Filtering 6.1. Overview XML subtree filtering is a mechanism that allows an application to select particular XML subtrees to include in the for a or operation. A small set of filters for inclusion, simple content exact-match, and selection is provided, which allows some useful, but also very limited, selection mechanisms. The server does not need to utilize any data-model- specific semantics during processing, allowing for simple and centralized implementation strategies. Conceptually, a subtree filter is comprised of zero or more element subtrees, which represent the filter selection criteria. At each containment level within a subtree, the set of sibling nodes is logically processed by the server to determine if its subtree and path of elements to the root are included in the filter output. All elements present in a particular subtree within a filter must match associated nodes present in the server's conceptual data model. XML namespaces may be specified (via 'xmlns' declarations) within the filter data model. If they are, the declared namespace must first exactly match a namespace supported by the server. Note that prefix values for qualified namespaces are not relevant when comparing filter elements to elements in the underlying data model. Only data associated with a specified namespace will be included in the filter output. Each node specified in a subtree filter represents an inclusive filter. Only associated nodes in underlying data model(s) within the specified configuration datastore on the server are selected by the filter. A node must exactly match the namespace and hierarchy of elements given in the filter data, except that the filter absolute path name is adjusted to start from the layer below . Response messages contain only the subtrees selected by the filter. Any selection criteria that were present in the request, within a particular selected subtree, are also included in the response. Note that some elements expressed in the filter as leaf nodes will be expanded (i.e., subtrees included) in the filter output. Specific data instances are not duplicated in the response in the event that the request contains multiple filter subtree expressions that select the same data. Enns, et al. Expires August 8, 2010 [Page 20] Internet-Draft NETCONF Protocol February 2010 6.2. Subtree Filter Components A subtree filter is comprised of XML elements and their XML attributes. There are five types of components that may be present in a subtree filter: o Namespace Selection o Attribute Match Expressions o Containment Nodes o Selection Nodes o Content Match Nodes 6.2.1. Namespace Selection If namespaces are used, then the filter output will only include elements from the specified namespace. A namespace is considered to match (for filter purposes) if the content of the 'xmlns' attributes are the same in the filter and the underlying data model. Note that namespace selection cannot be used by itself. At least one element must be specified in the filter any elements to be included in the filter output. Example: In this example, the element is a selection node, and only this node and any child nodes (from the underlying data model) in the 'http://example.com/schema/1.2/config' namespace will be included in the filter output. 6.2.2. Attribute Match Expressions An attribute that appears in a subtree filter is part of an "attribute match expression". Any number of (unqualified or qualified) XML attributes may be present in any type of filter node. In addition to the selection criteria normally applicable to that node, the selected data must have matching values for every attribute specified in the node. If an element is not defined to include a specified attribute, then it is not selected in the filter output. Example: Enns, et al. Expires August 8, 2010 [Page 21] Internet-Draft NETCONF Protocol February 2010 In this example, the , and elements are containment nodes, the element is a selection node, and 'ifName' is an attribute match expression. Only 'interface' nodes in the 'http://example.com/schema/1.2/config' namespace that have an 'ifName' attribute with the value 'eth0' and occur within 'interfaces' nodes within 'top' nodes will be included in the filter output. 6.2.3. Containment Nodes Nodes that contain child elements within a subtree filter are called "containment nodes". Each child element can be any type of node, including another containment node. For each containment node specified in a subtree filter, all data model instances that exactly match the specified namespaces, element hierarchy, and any attribute match expressions are included in the filter output. Example: In this example, the element is a containment node. 6.2.4. Selection Nodes An empty leaf node within a filter is called a "selection node", and it represents an "explicit selection" filter on the underlying data model. Presence of any selection nodes within a set of sibling nodes will cause the filter to select the specified subtree(s) and suppress automatic selection of the entire set of sibling nodes in the underlying data model. For filtering purposes, an empty leaf node can be declared either with an empty tag (e.g., ) or with explicit start and end tags (e.g., ). Any whitespace characters are ignored in this form. Example: Enns, et al. Expires August 8, 2010 [Page 22] Internet-Draft NETCONF Protocol February 2010 In this example, the element is a containment node, and the element is a selection node. Only 'users' nodes in the 'http://example.com/schema/1.2/config' namespace that occur within a 'top' element that is the root of the configuration datastore will be included in the filter output. 6.2.5. Content Match Nodes A leaf node that contains simple content is called a "content match node". It is used to select some or all of its sibling nodes for filter output, and it represents an exact-match filter on the leaf node element content. The following constraints apply to content match nodes: o A content match node must not contain nested elements (i.e., must resolve to a simpleType in the XML Schema Definition (XSD)). o Multiple content match nodes (i.e., sibling nodes) are logically combined in an "AND" expression. o Filtering of mixed content is not supported. o Filtering of list content is not supported. o Filtering of whitespace-only content is not supported. o A content match node must contain non-whitespace characters. An empty element (e.g., ) will be interpreted as a selection node (e.g., ). o Leading and trailing whitespace characters are ignored, but any whitespace characters within a block of text characters are not ignored or modified. If all specified sibling content match nodes in a subtree filter expression are 'true', then the filter output nodes are selected in the following manner: o Each content match node in the sibling set is included in the filter output. Enns, et al. Expires August 8, 2010 [Page 23] Internet-Draft NETCONF Protocol February 2010 o If any containment nodes are present in the sibling set, then they are processed further and included if any nested filter criteria are also met. o If any selection nodes are present in the sibling set, then all of them are included in the filter output. o If any sibling nodes of the selection node are instance identifier components for a conceptual data structure (e.g., list key leaf), then they MAY also be included in the filter output. o Otherwise (i.e., there are no selection or containment nodes in the filter sibling set), all the nodes defined at this level in the underlying data model (and their subtrees, if any) are returned in the filter output. If any of the sibling content match node tests are 'false', then no further filter processing is performed on that sibling set, and none of the sibling subtrees are selected by the filter, including the content match node(s). Example: fred In this example, the and nodes are both containment nodes, and is a content match node. Since no sibling nodes of are specified (and therefore no containment or selection nodes), all of the sibling nodes of are returned in the filter output. Only 'user' nodes in the 'http://example.com/schema/1.2/config' namespace that match the element hierarchy and for which the element is equal to 'fred' will be included in the filter output. 6.3. Subtree Filter Processing The filter output (the set of selected nodes) is initially empty. Each subtree filter can contain one or more data model fragments, which represent portions of the data model that should be selected Enns, et al. Expires August 8, 2010 [Page 24] Internet-Draft NETCONF Protocol February 2010 (with all child nodes) in the filter output. Each subtree data fragment is compared by the server to the internal data models supported by the server. If the entire subtree data- fragment filter (starting from the root to the innermost element specified in the filter) exactly matches a corresponding portion of the supported data model, then that node and all its children are included in the result data. The server processes all nodes with the same parent node (sibling set) together, starting from the root to the leaf nodes. The root elements in the filter are considered in the same sibling set (assuming they are in the same namespace), even though they do not have a common parent. For each sibling set, the server determines which nodes are included (or potentially included) in the filter output, and which sibling subtrees are excluded (pruned) from the filter output. The server first determines which types of nodes are present in the sibling set and processes the nodes according to the rules for their type. If any nodes in the sibling set are selected, then the process is recursively applied to the sibling sets of each selected node. The algorithm continues until all sibling sets in all subtrees specified in the filter have been processed. 6.4. Subtree Filtering Examples 6.4.1. No Filter Leaving out the filter on the get operation returns the entire data model. Enns, et al. Expires August 8, 2010 [Page 25] Internet-Draft NETCONF Protocol February 2010 6.4.2. Empty Filter An empty filter will select nothing because no content match or selection nodes are present. This is not an error. The filter type attribute used in these examples is discussed further in Section 7.1. 6.4.3. Select the Entire Subtree The filter in this example contains one selection node (), so just that subtree is selected by the filter. This example represents the fully-populated data model in most of the filter examples that follow. In a real data model, the would not likely be returned with the list of users for a particular host or network. NOTE: The filtering and configuration examples used in this document appear in the namespace "http://example.com/schema/1.2/config". The root element of this namespace is . The element and its descendents represent an example configuration data model only. Enns, et al. Expires August 8, 2010 [Page 26] Internet-Draft NETCONF Protocol February 2010 root superuser Charlie Root 1 1 fred admin Fred Flintstone 2 2 barney admin Barney Rubble 2 3 The following filter request would have produced the same result, but only because the container defines one child element (). Enns, et al. Expires August 8, 2010 [Page 27] Internet-Draft NETCONF Protocol February 2010 6.4.4. Select All Elements within the Subtree This filter contains two containment nodes (, ) and one selection node (). All instances of the element in the same sibling set are selected in the filter output. The client may need to know that is used as an instance identifier in this particular data structure, but the server does not need to know that meta-data in order to process the request. Enns, et al. Expires August 8, 2010 [Page 28] Internet-Draft NETCONF Protocol February 2010 root fred barney 6.4.5. One Specific Entry This filter contains two containment nodes (, ) and one content match node (). All instances of the sibling set containing for which the value of equals "fred" are selected in the filter output. Enns, et al. Expires August 8, 2010 [Page 29] Internet-Draft NETCONF Protocol February 2010 fred fred admin Fred Flintstone 2 2 6.4.6. Specific Elements from a Specific Entry This filter contains two containment nodes (, ), one content match node (), and two selection nodes (, ). All instances of the and elements in the same sibling set containing for which the value of equals "fred" are selected in the filter output. The element is not included because the sibling set contains selection nodes. Enns, et al. Expires August 8, 2010 [Page 30] Internet-Draft NETCONF Protocol February 2010 fred fred admin Fred Flintstone 6.4.7. Multiple Subtrees This filter contains three subtrees (name=root, fred, barney). The "root" subtree filter contains two containment nodes (, ), one content match node (), and one selection node (). The subtree selection criteria is met, and just the company-info subtree for "root" is selected in the filter output. The "fred" subtree filter contains three containment nodes (, , ), one content match node (), and one selection node (). The subtree selection criteria is met, and just the element within the company-info subtree for "fred" is Enns, et al. Expires August 8, 2010 [Page 31] Internet-Draft NETCONF Protocol February 2010 selected in the filter output. The "barney" subtree filter contains three containment nodes (, , ), two content match nodes (, ), and one selection node (). The subtree selection criteria is not met because user "barney" is not a "superuser", and the entire subtree for "barney" (including its parent entry) is excluded from the filter output. root fred barney superuser root Enns, et al. Expires August 8, 2010 [Page 32] Internet-Draft NETCONF Protocol February 2010 1 1 fred 2 6.4.8. Elements with Attribute Naming In this example, the filter contains one containment node (), one attribute match expression (ifName), and one selection node (). All instances of the subtree that have an ifName attribute equal to "eth0" are selected in the filter output. The filter data elements and attributes must be qualified because the ifName attribute will not be considered part of the 'schema/1.2' namespace if it is unqualified. Enns, et al. Expires August 8, 2010 [Page 33] Internet-Draft NETCONF Protocol February 2010 45621 774344 If ifName were a child node instead of an attribute, then the following request would produce similar results. eth0 Enns, et al. Expires August 8, 2010 [Page 34] Internet-Draft NETCONF Protocol February 2010 7. Protocol Operations The NETCONF protocol provides a small set of low-level operations to manage device configurations and retrieve device state information. The base protocol provides operations to retrieve, configure, copy, and delete configuration datastores. Additional operations are provided, based on the capabilities advertised by the device. The base protocol includes the following protocol operations: o get o get-config o edit-config o copy-config o delete-config o lock o unlock o close-session o kill-session A protocol operation may fail for various reasons, including "operation not supported". An initiator should not assume that any operation will always succeed. The return values in any RPC reply should be checked for error responses. The syntax and XML encoding of the protocol operations are formally defined in the YANG module in Appendix C. The following sections describe the semantics of each protocol operation. 7.1. Description: Retrieve all or part of a specified configuration. Parameters: Enns, et al. Expires August 8, 2010 [Page 35] Internet-Draft NETCONF Protocol February 2010 source: Name of the configuration datastore being queried, such as . filter: This parameter identifies the portions of the device configuration 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 element containing a element with the results of the query. Negative Response: An element is included in the if the request cannot be completed for any reason. Example: To retrieve the entire subtree: Enns, et al. Expires August 8, 2010 [Page 36] Internet-Draft NETCONF Protocol February 2010 root superuser Charlie Root 1 1 If the configuration is available in multiple formats, such as XML and text, an XML namespace can be used to specify which format is desired. In the following example, the client uses a specific element () in a specific namespace to indicate to the server the desire to receive the configuration in an alternative format. The server may support any number of distinct formats or views into the configuration data, with the client using the parameter to select between them. Enns, et al. Expires August 8, 2010 [Page 37] Internet-Draft NETCONF Protocol February 2010 Section 6 contains additional examples of subtree filtering. 7.2. Description: The operation loads all or part of a specified configuration to the specified target configuration. This operation allows the new configuration to be expressed in several ways, such as using a local file, a remote file, or inline. If the target configuration does not exist, it will be created. If a NETCONF peer supports the :url capability (Section 8.8), the element can appear instead of the parameter. The device analyzes the source and target configurations and performs the requested changes. The target configuration is not necessarily replaced, as with the message. Instead, the target configuration is changed in accordance with the source's data and requested operations. If the operation contains multiple sub-operations which 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). Enns, et al. Expires August 8, 2010 [Page 38] Internet-Draft NETCONF Protocol February 2010 Attributes: operation: Elements in the subtree may contain an "operation" attribute. The attribute identifies the point in the configuration to perform the operation and MAY appear on multiple elements throughout the subtree. If the operation attribute is not specified, the configuration is merged into the configuration datastore. The operation attribute has one of the following values: merge: The configuration data identified by the element containing this attribute is merged with the configuration at the corresponding level in the configuration datastore identified by the target parameter. This is the default behavior. replace: The configuration data identified by the element containing this attribute replaces any related configuration in the configuration datastore identified by the target parameter. If no such configuration data exists in the configuration datastore, it is created. Unlike a 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 element is returned with an value of data-exists. delete: The configuration data identified by the element containing this attribute is deleted in the configuration datastore identified by the target parameter. Parameters: target: Name of the configuration datastore being edited, such as or . Enns, et al. Expires August 8, 2010 [Page 39] Internet-Draft NETCONF Protocol February 2010 default-operation: Selects the default operation (as described in the "operation" attribute) for this request. The default value for the default-operation parameter is "merge". The default-operation parameter is optional, but if provided, it must have one of the following values: merge: The configuration data in the 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 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 parameter, unless and until the incoming configuration data uses the "operation" attribute to request a different operation. If the configuration in the parameter contains data for which there is not a corresponding level in the target datastore, an is returned with an value of data-missing. Using "none" allows operations like "delete" to avoid unintentionally creating the parent hierarchy of the element to be deleted. test-option: The test-option element may be specified only if the device advertises the :validate capability (Section 8.6). The test-option element has one of the following values: test-then-set: Perform a validation test before attempting to set. If validation errors occur, do not perform the 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. Enns, et al. Expires August 8, 2010 [Page 40] Internet-Draft NETCONF Protocol February 2010 error-option: The error-option element has one of the following values: stop-on-error: Abort the edit-config operation on first error. This is the default error-option. continue-on-error: Continue to process configuration data on error; error is recorded, and negative response is generated if any errors occur. rollback-on-error: If an error condition occurs such that an error severity 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 is sent containing an element. Negative Response: An response is sent if the request cannot be completed for any reason. Example: The examples in this section utilize a simple data model, in which multiple instances of the 'interface' element may be present, and an instance is distinguished by the 'name' element within each 'interface' element. Set the MTU to 1500 on an interface named "Ethernet0/0" in the running configuration: Enns, et al. Expires August 8, 2010 [Page 41] Internet-Draft NETCONF Protocol February 2010 Ethernet0/0 1500 Add an interface named "Ethernet0/0" to the running configuration, replacing any previous interface with that name: Enns, et al. Expires August 8, 2010 [Page 42] Internet-Draft NETCONF Protocol February 2010 Ethernet0/0 1500
192.0.2.4 24
Delete the configuration for an interface named "Ethernet0/0" from the running configuration: Enns, et al. Expires August 8, 2010 [Page 43] Internet-Draft NETCONF Protocol February 2010 none Ethernet0/0 Delete interface 192.0.2.4 from an OSPF area (other interfaces configured in the same area are unaffected): Enns, et al. Expires August 8, 2010 [Page 44] Internet-Draft NETCONF Protocol February 2010 none 0.0.0.0 192.0.2.4 7.3. 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 element can appear as the or parameter. Even if it advertises the :writable-running capability, a device may choose not to support the configuration datastore as the parameter of a operation. A device may choose not to support remote-to-remote copy operations, where both the and parameters use the element. Enns, et al. Expires August 8, 2010 [Page 45] Internet-Draft NETCONF Protocol February 2010 If the source and target parameters identify the same URL or configuration datastore, an error MUST be returned with an error- tag containing invalid-value. Parameters: target: Name of the configuration datastore to use as the destination of the copy operation. source: Name of the configuration datastore to use as the source of the copy operation, or the element containing the complete configuration to copy. Positive Response: If the device was able to satisfy the request, an is sent that includes an element. Negative Response: An element is included within the if the request cannot be completed for any reason. Example: https://user@example.com:passphrase/cfg/new.txt Enns, et al. Expires August 8, 2010 [Page 46] Internet-Draft NETCONF Protocol February 2010 7.4. Description: Delete a configuration datastore. The configuration datastore cannot be deleted. If a NETCONF peer supports the :url capability (Section 8.8), the element can appear as the parameter. Parameters: target: Name of the configuration datastore to delete. Positive Response: If the device was able to satisfy the request, an is sent that includes an element. Negative Response: An element is included within the if the request cannot be completed for any reason. Example: 7.5. Enns, et al. Expires August 8, 2010 [Page 47] Internet-Draft NETCONF Protocol February 2010 Description: The lock operation allows the client to lock the configuration system of a device. Such locks are intended to be short-lived and allow a client to make a change without fear of interaction with other NETCONF clients, non-NETCONF clients (e.g., SNMP and command line interface (CLI) scripts), and human users. An attempt to lock the configuration MUST fail if an existing session or other entity holds a lock on any portion of the lock target. When the lock is acquired, the server MUST prevent any changes to the locked resource other than those requested by this session. SNMP and CLI requests to modify the resource MUST fail with an appropriate error. The duration of the lock is defined as beginning when the lock is acquired and lasting until either the lock is released or the NETCONF session closes. The session closure may be explicitly performed by the client, or implicitly performed by the server based on criteria such as failure of the underlying transport, or simple inactivity timeout. This criteria is dependent on the implementation and the underlying transport. The lock operation takes a mandatory parameter, target. The target parameter names the configuration that will be locked. When a lock is active, using the operation on the locked configuration and using the locked configuration as a target of the 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 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 either of the following conditions is true: * A lock is already held by any NETCONF session or another entity. * The target configuration is , it has already been modified, and these changes have not been committed or rolled back. Enns, et al. Expires August 8, 2010 [Page 48] Internet-Draft NETCONF Protocol February 2010 The server MUST respond with either an element or an . 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 is sent that contains an element. Negative Response: An element is included in the if the request cannot be completed for any reason. If the lock is already held, the element will be 'lock-denied' and the element will include the of the lock owner. If the lock is held by a non- NETCONF entity, a 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. Enns, et al. Expires August 8, 2010 [Page 49] Internet-Draft NETCONF Protocol February 2010 Example: The following example shows a failed attempt to acquire a lock when the lock is already in use. protocol lock-denied error Lock failed, lock is already held 454 7.6. Description: The unlock operation is used to release a configuration lock, previously obtained with the operation. An unlock operation will not succeed if any of the following conditions are true: * the specified lock is not currently active * the session issuing the operation is not the same session that obtained the lock The server MUST respond with either an element or an Enns, et al. Expires August 8, 2010 [Page 50] Internet-Draft NETCONF Protocol February 2010 . Parameters: target: Name of the configuration datastore to unlock. A NETCONF client is not permitted to unlock a configuration datastore that it did not lock. Positive Response: If the device was able to satisfy the request, an is sent that contains an element. Negative Response: An element is included in the if the request cannot be completed for any reason. Example: 7.7. Description: Retrieve running configuration and device state information. Parameters: Enns, et al. Expires August 8, 2010 [Page 51] Internet-Draft NETCONF Protocol February 2010 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. Positive Response: If the device was able to satisfy the request, an is sent. The section contains the appropriate subset. Negative Response: An element is included in the if the request cannot be completed for any reason. Example: Enns, et al. Expires August 8, 2010 [Page 52] Internet-Draft NETCONF Protocol February 2010 eth0 eth0 45621 774344 7.8. Description: Request graceful termination of a NETCONF session. When a NETCONF server receives a 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 request will be ignored. Positive Response: If the device was able to satisfy the request, an is sent that includes an element. Enns, et al. Expires August 8, 2010 [Page 53] Internet-Draft NETCONF Protocol February 2010 Negative Response: An element is included in the if the request cannot be completed for any reason. Example: 7.9. Description: Force the termination of a NETCONF session. When a NETCONF entity receives a 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 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 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. Enns, et al. Expires August 8, 2010 [Page 54] Internet-Draft NETCONF Protocol February 2010 Positive Response: If the device was able to satisfy the request, an is sent that includes an element. Negative Response: An element is included in the if the request cannot be completed for any reason. Example: 4 Enns, et al. Expires August 8, 2010 [Page 55] Internet-Draft NETCONF Protocol February 2010 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 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 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 element MUST include a element containing the session ID for this NETCONF session. A client sending the element MUST NOT include a element. A server receiving a element MUST NOT continue the NETCONF session. Similarly, a client that does not receive a element in the server's 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. Enns, et al. Expires August 8, 2010 [Page 56] Internet-Draft NETCONF Protocol February 2010 urn:ietf:params:netconf:base:1.0 urn:ietf:params:netconf:capability:startup:1.0 http://example.net/router/2.3/myfeature 4 Each peer sends its 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 configuration datastore. In other words, the device supports edit-config and copy-config operations where the 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 Enns, et al. Expires August 8, 2010 [Page 57] Internet-Draft NETCONF Protocol February 2010 8.2.5.1. The :writable-running capability modifies the operation to accept the element as a . 8.2.5.2. The :writable-running capability modifies the operation to accept the element as a . 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 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 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 operation. This operation reverts the contents of the candidate configuration to the contents of the running configuration. Enns, et al. Expires August 8, 2010 [Page 58] Internet-Draft NETCONF Protocol February 2010 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. 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 operation. The 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 operation, MUST fail with an value of 'in-use'. If the system does not have the :candidate capability, the operation is not available. Positive Response: If the device was able to satisfy the request, an is sent that contains an element. Enns, et al. Expires August 8, 2010 [Page 59] Internet-Draft NETCONF Protocol February 2010 Negative Response: An element is included in the if the request cannot be completed for any reason. Example: 8.3.4.2. If the client decides that the candidate configuration should not be committed, the operation can be used to revert the candidate configuration to the current running configuration. 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. , , , and The candidate configuration can be used as a source or target of any , , , or operation as a or parameter. The element is used to indicate the candidate configuration: Enns, et al. Expires August 8, 2010 [Page 60] Internet-Draft NETCONF Protocol February 2010 8.3.5.2. and The candidate configuration can be locked using the operation with the element as the parameter: Similarly, the candidate configuration is unlocked using the element as the parameter: 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 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 and parameters for the protocol operation. See Section 8.3 for further details on the 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 element. The confirming commit can itself include a parameter. Enns, et al. Expires August 8, 2010 [Page 61] Internet-Draft NETCONF Protocol February 2010 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 client 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. The :confirmed-commit capability allows 2 additional parameters to the operation. Enns, et al. Expires August 8, 2010 [Page 62] Internet-Draft NETCONF Protocol February 2010 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: 120 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 parameter to the 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 Enns, et al. Expires August 8, 2010 [Page 63] Internet-Draft NETCONF Protocol February 2010 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. The :rollback-on-error capability allows the 'rollback-on-error' value to the parameter on the operation. rollback-on-error Ethernet0/0 100000 8.6. Validate Capability 8.6.1. Description Validation consists of checking a complete configuration for syntactical and semantic errors before applying the configuration to Enns, et al. Expires August 8, 2010 [Page 64] Internet-Draft NETCONF Protocol February 2010 the device. If this capability is advertised, the device supports the protocol operation and checks at least for syntax errors. In addition, this capability supports the test-option parameter to the operation and, when it is provided, checks at least for syntax errors. This capability exists in two versions, 1.0 and 1.1. Version 1.1 contains all of version 1.0, and adds a new value, "test-only", to the test-option parameter. Servers SHOULD implement and advertise version 1.1, and MAY, for backwards compatibility, also advertise version 1.0. Note that both versions can be advertised at the same time. 8.6.2. Dependencies None. 8.6.3. Capability Identifier Version 1.0 of the :validate capability is identified by the following capability string: urn:ietf:params:netconf:capability:validate:1.0 Version 1.1 of the :validate capability is identified by the following capability string: urn:ietf:params:netconf:capability:validate:1.1 8.6.4. New Operations 8.6.4.1. Description: This protocol operation validates the contents of the specified configuration. Parameters: source: Name of the configuration datastore to validate, such as , or the element containing the complete configuration to validate. Enns, et al. Expires August 8, 2010 [Page 65] Internet-Draft NETCONF Protocol February 2010 Positive Response: If the device was able to satisfy the request, an is sent that contains an element. Negative Response: An element is included in the 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: 8.6.5. Modifications to Existing Operations 8.6.5.1. The :validate capability modifies the operation to accept the parameter. 8.7. Distinct Startup Capability 8.7.1. Description The device supports separate running and startup configuration datastores. The startup configuration is loaded by the device when it boots. Operations that affect the running configuration will not Enns, et al. Expires August 8, 2010 [Page 66] Internet-Draft NETCONF Protocol February 2010 be automatically copied to the startup configuration. An explicit operation from the to the 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 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 configuration datastore to arguments of several NETCONF operations. The server MUST support the following additional values: +--------------------+--------------------------+-------------------+ | Operation | Parameters | Notes | +--------------------+--------------------------+-------------------+ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | If :validate is | | | | advertised | | | | | | | | Resets the device | | | | to its factory | | | | defaults | +--------------------+--------------------------+-------------------+ Enns, et al. Expires August 8, 2010 [Page 67] Internet-Draft NETCONF Protocol February 2010 To save the startup configuration, use the copy-config operation to copy the configuration datastore to the configuration datastore. 8.8. URL Capability 8.8.1. Description The NETCONF peer has the ability to accept the element in and 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 Enns, et al. Expires August 8, 2010 [Page 68] Internet-Draft NETCONF Protocol February 2010 8.8.5.1. The :url capability modifies the operation to accept the element as an alternative to the parameter. 8.8.5.2. The :url capability modifies the operation to accept the element as the value of the and the parameters. 8.8.5.3. The :url capability modifies the operation to accept the element as the value of the parameters. 8.8.5.4. The :url capability modifies the operation to accept the element as the value of the 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 element. XPath is described in [2]. The data model used in the XPath expression is the same as that used in XPath 1.0 [2], with the same extension for root node children as used by XSLT 1.0 [10] (section 3.1). Specifically, it means that the root node may have any number of element nodes as its children. The XPath expression is evaluated in the following context: o The set of namespace declarations are those in scope on the filter element. o The set of variable bindings is defined by the data model. If no such variable bindings are defined, the set is empty. o The function library is the core function library, plus any functions defined by the data model. o The context node is the root node. The XPath expression MUST return a node set. If it does not return a Enns, et al. Expires August 8, 2010 [Page 69] Internet-Draft NETCONF Protocol February 2010 node set, the operation fails with an "invalid-value" error. The response message contains the subtrees selected by the filter expression. For each such subtree, the path from the data model root node down to the subtree, including any elements or attributes necessary to uniquely identify the subtree, are included in the response message. 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. and The :xpath capability modifies the and 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. The XPath result for the select expression MUST be a node-set. Each node in the node-set MUST correspond to a node in underlying data model. In order to properly identify each node, the following encoding rules are defined: o All ancestor nodes of the result node MUST be encoded first, so the element returned in the reply contains only fully- specified sub-trees, according to the underlying data model. o If any sibling or ancestor nodes of the result node are needed to identify a particular instance within a conceptual data structure, then these nodes MUST also be encoded in the response. Enns, et al. Expires August 8, 2010 [Page 70] Internet-Draft NETCONF Protocol February 2010 For example: fred 2 Enns, et al. Expires August 8, 2010 [Page 71] Internet-Draft NETCONF Protocol February 2010 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 secure transport layer (SSH, BEEP, 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 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 Enns, et al. Expires August 8, 2010 [Page 72] Internet-Draft NETCONF Protocol February 2010 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, to the startup or running configurations is clearly not a normal provisioning operation, whereas 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 configuration, user A must not be allowed to commit the 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 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. Enns, et al. Expires August 8, 2010 [Page 73] Internet-Draft NETCONF Protocol February 2010 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. Enns, et al. Expires August 8, 2010 [Page 74] Internet-Draft NETCONF Protocol February 2010 +--------------------+----------------------------------------------+ | 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 | | | urn:ietf:params:netconf:capability:validate: | | | 1.1 | | | | | :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. Enns, et al. Expires August 8, 2010 [Page 75] Internet-Draft NETCONF Protocol February 2010 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 persistence 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. Enns, et al. Expires August 8, 2010 [Page 76] Internet-Draft NETCONF Protocol February 2010 12. References 12.1. Normative References [1] Bray, T., Sperberg-McQueen, C., Paoli, J., and E. Maler, "Extensible Markup Language (XML) 1.0 (Second Edition)", World Wide Web Consortium FirstEdition REC-xml-20001006, October 2000, . [2] DeRose, S. and J. Clark, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath- 19991116, November 1999, . [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [4] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration Protocol over Secure SHell (SSH)", RFC 4742, December 2006. [5] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [6] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An IETF URN Sub-namespace for Registered Protocol Parameters", BCP 73, RFC 3553, June 2003. [7] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [8] Bjorklund, M., "YANG - A data modeling language for NETCONF", draft-ietf-netmod-yang-10 (work in progress), January 2010. [9] Schoenwaelder, J., "Common YANG Data Types", draft-ietf-netmod-yang-types-06 (work in progress), February 2010. 12.2. Informative References [10] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide Web Consortium Recommendation REC-xslt-19991116, November 1999, . [11] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.1", RFC 4346, April 2006. [12] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Protocol Enns, et al. Expires August 8, 2010 [Page 77] Internet-Draft NETCONF Protocol February 2010 Architecture", RFC 4251, January 2006. [13] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote Authentication Dial In User Service (RADIUS)", RFC 2865, June 2000. [14] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols", BCP 70, RFC 3470, January 2003. Enns, et al. Expires August 8, 2010 [Page 78] Internet-Draft NETCONF Protocol February 2010 Appendix A. NETCONF Error List This section is normative. For each error-tag, the valid error-type and error-severity values are listed, together with any mandatory error-info, if any. error-tag: in-use error-type: protocol, application error-severity: error error-info: none Description: The request requires a resource that already in use. error-tag: invalid-value error-type: protocol, application error-severity: error error-info: none Description: The request specifies an unacceptable value for one or more parameters. error-tag: too-big error-type: transport, rpc, protocol, application error-severity: error error-info: none Description: The request or response (that would be generated) is too large for the implementation to handle. error-tag: missing-attribute error-type: rpc, protocol, application error-severity: error error-info: : name of the missing attribute : name of the element that should contain the missing attribute Description: An expected attribute is missing. error-tag: bad-attribute error-type: rpc, protocol, application error-severity: error error-info: : name of the attribute w/ bad value : name of the element that contains the attribute with the bad value Description: An attribute value is not correct; e.g., wrong type, out of range, pattern mismatch. error-tag: unknown-attribute error-type: rpc, protocol, application error-severity: error error-info: : name of the unexpected attribute Enns, et al. Expires August 8, 2010 [Page 79] Internet-Draft NETCONF Protocol February 2010 : name of the element that contains the unexpected attribute Description: An unexpected attribute is present. error-tag: missing-element error-type: protocol, application error-severity: error error-info: : name of the missing element Description: An expected element is missing. error-tag: bad-element error-type: protocol, application error-severity: error error-info: : name of the element w/ bad value Description: An element value is not correct; e.g., wrong type, out of range, pattern mismatch. error-tag: unknown-element error-type: protocol, application error-severity: error error-info: : name of the unexpected element Description: An unexpected element is present. error-tag: unknown-namespace error-type: protocol, application error-severity: error error-info: : name of the element that contains the unexpected namespace : name of the unexpected namespace Description: An unexpected namespace is present. error-tag: access-denied error-type: protocol, application error-severity: error error-info: none Description: Access to the requested protocol operation, or data model is denied because authorization failed. error-tag: lock-denied error-type: protocol error-severity: error error-info: : session ID of session holding the requested lock, or zero to indicate a non-NETCONF entity holds the lock Description: Access to the requested lock is denied because the lock is currently held by another entity. error-tag: resource-denied Enns, et al. Expires August 8, 2010 [Page 80] Internet-Draft NETCONF Protocol February 2010 error-type: transport, rpc, protocol, application error-severity: error error-info: none Description: Request could not be completed because of insufficient resources. error-tag: rollback-failed error-type: protocol, application error-severity: error error-info: none Description: Request to rollback some configuration change (via rollback-on-error or discard-changes operations) was not completed for some reason. error-tag: data-exists error-type: application error-severity: error error-info: none Description: Request could not be completed because the relevant data model content already exists. For example, a 'create' operation was attempted on data that already exists. error-tag: data-missing error-type: application error-severity: error error-info: none Description: Request could not be completed because the relevant data model content does not exist. For example, a 'delete' operation was attempted on data that does not exist. error-tag: operation-not-supported error-type: protocol, application error-severity: error error-info: none Description: Request could not be completed because the requested operation is not supported by this implementation. error-tag: operation-failed error-type: rpc, protocol, application error-severity: error error-info: none Description: Request could not be completed because the requested operation failed for some reason not covered by any other error condition. error-tag: partial-operation Enns, et al. Expires August 8, 2010 [Page 81] Internet-Draft NETCONF Protocol February 2010 error-type: application error-severity: error error-info: : identifies an element in the data model for which the requested operation has been completed for that node and all its child nodes. This element can appear zero or more times in the container. : identifies an element in the data model for which the requested operation has failed for that node and all its child nodes. This element can appear zero or more times in the container. : identifies an element in the data model for which the requested operation was not attempted for that node and all its child nodes. This element can appear zero or more times in the container. Description: Some part of the requested operation failed or was not attempted for some reason. Full cleanup has not been performed (e.g., rollback not supported) by the server. The error-info container is used to identify which portions of the application data model content for which the requested operation has succeeded (), failed (), or not been attempted (). Enns, et al. Expires August 8, 2010 [Page 82] Internet-Draft NETCONF Protocol February 2010 Appendix B. XML Schema for NETCONF Messages Layer This section is normative. BEGIN This schema defines the syntax for the NETCONF Message layer messages 'hello', 'rpc', and 'rpc-reply'. This import accesses the xml: attribute groups for the xml:lang as declared on the error-message element. Enns, et al. Expires August 8, 2010 [Page 83] Internet-Draft NETCONF Protocol February 2010 Enns, et al. Expires August 8, 2010 [Page 84] Internet-Draft NETCONF Protocol February 2010 Enns, et al. Expires August 8, 2010 [Page 85] Internet-Draft NETCONF Protocol February 2010 END Enns, et al. Expires August 8, 2010 [Page 87] Internet-Draft NETCONF Protocol February 2010 Appendix C. YANG Module for NETCONF Protocol Operations This section is normative. BEGIN module ietf-netconf { namespace "urn:ietf:params:xml:ns:netconf:base:1.0"; prefix nc; import ietf-inet-types { prefix inet; } organization "IETF NETCONF (Network Configuration) Working Group"; contact "Send comments to the NETCONF WG mailing list. "; description "NETCONF Protocol Data Types and RPC methods. Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - Neither the name of Internet Society, IETF or IETF Trust, nor the names of specific contributors, may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND ANY EXPRESS OR IMPLIED Enns, et al. Expires August 8, 2010 [Page 88] Internet-Draft NETCONF Protocol February 2010 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This version of this YANG module is part of RFC XXXX; see the RFC itself for full legal notices."; // RFC Ed.: replace XXXX with actual RFC number and // remove this note reference "draft-ietf-netconf-rfc4741bis-01.txt"; revision 2010-02-04 { description "Initial revision"; reference "RFC XXXX: Network Configuration Protocol"; // RFC Ed.: replace XXXX with actual RFC number and // remove this note } extension get-filter-element-attributes { description "If this extension is present within the an 'anyxml' statement named 'filter', which must be conceptually defined within the RPC input section for the 'get' and 'get-config' RPC operations, then the following unqualified XML attribute is supported within the 'filter' element, within a 'get' or 'get-config' protocol operation: type : optional attribute with allowed value strings 'subtree' and 'xpath'. If missing, the default value is 'subtree'. If the xpath feature is supported, then the following unqualified XML attribute is also supported: Enns, et al. Expires August 8, 2010 [Page 89] Internet-Draft NETCONF Protocol February 2010 select: optional attribute containing a string representing an XPath expression. The 'type' attribute must be equal to 'xpath' if this attribute is present."; } // NETCONF capabilities defined as features feature writable-running { description "NETCONF :writable-running capability; If the server advertises the :writable-running capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled."; // RFC Ed.: replace XXXX with actual RFC number and // remove this note reference "RFC XXXX, section 8.2."; } feature candidate { description "NETCONF :candidate capability; If the server advertises the :candidate capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled."; reference "RFC XXXX, section 8.3."; } feature confirmed-commit { if-feature candidate; description "NETCONF :confirmed-commit capability; If the server advertises the :confirmed-commit capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled."; reference "RFC XXXX, section 8.4."; } feature rollback-on-error { description "NETCONF :rollback-on-error capability; If the server advertises the :rollback-on-error capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled."; Enns, et al. Expires August 8, 2010 [Page 90] Internet-Draft NETCONF Protocol February 2010 reference "RFC XXXX, section 8.5."; } feature validate { status "deprecated"; description "NETCONF :validate:1.0 capability; If the server advertises the :validate:1.0 capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled."; reference "RFC XXXX, section 8.6."; } feature validate-1.1 { description "NETCONF :validate:1.1 capability; If the server advertises the :validate:1.1 capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled."; reference "RFC XXXX, section 8.6."; } feature startup { description "NETCONF :startup capability; If the server advertises the :startup capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled."; reference "RFC XXXX, section 8.7."; } feature url { description "NETCONF :url capability; If the server advertises the :url capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled."; reference "RFC XXXX, section 8.8."; } feature xpath { description "NETCONF :xpath capability; If the server advertises the :xpath Enns, et al. Expires August 8, 2010 [Page 91] Internet-Draft NETCONF Protocol February 2010 capability for a session, then this feature must also be enabled for that session. Otherwise, this feature must not be enabled."; reference "RFC XXXX, section 8.9."; } // NETCONF Simple Types typedef session-id-type { type uint32 { range "1..max"; } description "NETCONF Session Id"; } typedef session-id-or-zero-type { type uint32; description "NETCONF Session Id or Zero to indicate none"; } // NETCONF Standard RPC Methods rpc get-config { description "Retrieve all or part of a specified configuration."; reference "RFC XXXX, section 7.1."; input { container source { description "Particular configuration to retrieve."; choice config-source { mandatory true; leaf candidate { if-feature candidate; type empty; } leaf running { type empty; } leaf startup { if-feature startup; type empty; Enns, et al. Expires August 8, 2010 [Page 92] Internet-Draft NETCONF Protocol February 2010 description "This is optional-to-implement on the server because not all servers will support filtering for this database."; } } } anyxml filter { description "Subtree or Xpath filter to use."; nc:get-filter-element-attributes; } } output { container data { presence "An empty data container indicates that the request did not produce any results."; description "Copy of the source database subset which matched the filter criteria (if any)."; } } } rpc edit-config { description "The 'edit-config' operation loads all or part of a specified configuration to the specified target configuration."; reference "RFC XXXX, section 7.2."; input { container target { description "Particular configuration to edit."; choice config-target { mandatory true; leaf candidate { if-feature candidate; type empty; } leaf running { if-feature writable-running; Enns, et al. Expires August 8, 2010 [Page 93] Internet-Draft NETCONF Protocol February 2010 type empty; } } } leaf default-operation { type enumeration { enum merge; enum replace; enum none; } default "merge"; } leaf test-option { if-feature validate; type enumeration { enum test-then-set; enum set; enum test-only { description "This value can only be used if the 'validate-1.1' feature is supported."; } } } leaf error-option { type enumeration { enum stop-on-error; enum continue-on-error; enum rollback-on-error { description "This value can only be used if the 'rollback-on-error' feature is supported."; } } default "stop-on-error"; } choice edit-content { mandatory true; anyxml config { description "Inline Config content: 'config' element. This is not full 'anyxml' because the element cannot directly contain a text node."; } Enns, et al. Expires August 8, 2010 [Page 94] Internet-Draft NETCONF Protocol February 2010 leaf url { if-feature url; type inet:uri; } } } } rpc copy-config { description "Create or replace an entire configuration datastore with the contents of another complete configuration datastore."; reference "RFC XXXX, section 7.3."; input { container target { description "Particular configuration to copy to."; choice config-target { mandatory true; leaf candidate { if-feature candidate; type empty; } leaf running { if-feature writable-running; type empty; description "This is optional-to-implement on the server."; } leaf startup { if-feature startup; type empty; } leaf url { if-feature url; type inet:uri; } } } container source { description "Particular configuration to copy from."; Enns, et al. Expires August 8, 2010 [Page 95] Internet-Draft NETCONF Protocol February 2010 choice config-source { mandatory true; leaf candidate { if-feature candidate; type empty; } leaf running { type empty; } leaf startup { if-feature startup; type empty; } leaf url { if-feature url; type inet:uri; } anyxml config { description "Inline Config content: 'config' element. Represents an entire 'stand-alone' configuration database, not a subset of the running database."; } } } } } rpc delete-config { description "Delete a configuration datastore."; reference "RFC XXXX, section 7.4."; input { container target { description "Particular configuration to delete."; choice config-target { mandatory true; leaf startup { if-feature startup; type empty; } Enns, et al. Expires August 8, 2010 [Page 96] Internet-Draft NETCONF Protocol February 2010 leaf url { if-feature url; type inet:uri; } } } } } rpc lock { description "The lock operation allows the client to lock the configuration system of a device."; reference "RFC XXXX, section 7.5."; input { container target { description "Particular configuration to lock"; choice config-target { mandatory true; leaf candidate { if-feature candidate; type empty; } leaf running { type empty; } leaf startup { if-feature startup; type empty; } } } } } rpc unlock { description "The unlock operation is used to release a configuration lock, previously obtained with the 'lock' operation."; reference "RFC XXXX, section 7.6."; input { Enns, et al. Expires August 8, 2010 [Page 97] Internet-Draft NETCONF Protocol February 2010 container target { description "Particular configuration to unlock."; choice config-target { mandatory true; leaf candidate { if-feature candidate; type empty; } leaf running { type empty; } leaf startup { if-feature startup; type empty; } } } } } rpc get { description "Retrieve running configuration and device state information."; reference "RFC XXXX, section 7.7."; input { anyxml filter { description "This parameter specifies the portion of the system configuration and state data to retrieve."; nc:get-filter-element-attributes; } } output { container data { presence "An empty data container indicates that the filter request did not match any results."; description "Copy of the 'running' database subset and/or state data which matched the filter criteria (if any)."; } } Enns, et al. Expires August 8, 2010 [Page 98] Internet-Draft NETCONF Protocol February 2010 } rpc close-session { description "Request graceful termination of a NETCONF session."; reference "RFC XXXX, section 7.8."; } rpc kill-session { description "Force the termination of a NETCONF session."; reference "RFC XXXX, section 7.9."; input { leaf session-id { type session-id-type; mandatory true; description "Particular session to kill."; } } } rpc commit { if-feature candidate; description "Commit the candidate configuration as the device's new current configuration"; reference "RFC XXXX, section 8.3.4.1."; input { leaf confirmed { if-feature confirmed-commit; type empty; reference "RFC XXXX, section 8.3.4.1."; } leaf confirm-timeout { if-feature confirmed-commit; type uint32 { range "1..max"; } units "seconds"; default "600"; // 10 minutes Enns, et al. Expires August 8, 2010 [Page 99] Internet-Draft NETCONF Protocol February 2010 reference "RFC XXXX, section 8.3.4.1."; } } } rpc discard-changes { if-feature candidate; description "Revert the candidate configuration to the current running configuration."; reference "RFC XXXX, section 8.3.4.2."; } rpc validate { if-feature validate; description "Validates the contents of the specified configuration."; reference "RFC XXXX, section 8.6.4.1."; input { container source { description "Particular configuration to validate."; choice config-source { mandatory true; leaf candidate { if-feature candidate; type empty; } leaf running { type empty; } leaf startup { if-feature startup; type empty; } leaf url { if-feature url; type inet:uri; } anyxml config { description Enns, et al. Expires August 8, 2010 [Page 100] Internet-Draft NETCONF Protocol February 2010 "Inline Config content: 'config' element. Represents an entire 'stand-alone' configuration database, not a subset of the running database."; } } } } } } END Enns, et al. Expires August 8, 2010 [Page 101] Internet-Draft NETCONF Protocol February 2010 Appendix D. Capability Template This section is non-normative. D.1. capability-name (template) D.1.1. Overview D.1.2. Dependencies D.1.3. Capability Identifier The {name} capability is identified by the following capability string: {capability uri} D.1.4. New Operations D.1.4.1. D.1.5. Modifications to Existing Operations D.1.5.1. If existing operations are not modified by this capability, this section may be omitted. D.1.6. Interactions with Other Capabilities If this capability does not interact with other capabilities, this section may be omitted. Enns, et al. Expires August 8, 2010 [Page 102] Internet-Draft NETCONF Protocol February 2010 Appendix E. Configuring Multiple Devices with NETCONF This section is non-normative. E.1. Operations on Individual Devices Consider the work involved in performing a configuration update against a single individual device. In making a change to the configuration, the application needs to build trust that its change has been made correctly and that it has not impacted the operation of the device. The application (and the application user) should feel confident that their change has not damaged the network. Protecting each individual device consists of a number of steps: o Acquiring the configuration lock. o Loading the update. o Validating the incoming configuration. o Checkpointing the running configuration. o Changing the running configuration. o Testing the new configuration. o Making the change permanent (if desired). o Releasing the configuration lock. Let's look at the details of each step. E.1.1. Acquiring the Configuration Lock A lock should be acquired to prevent simultaneous updates from multiple sources. If multiple sources are affecting the device, the application is hampered in both testing of its change to the configuration and in recovery should the update fail. Acquiring a short-lived lock is a simple defense to prevent other parties from introducing unrelated changes. The lock can be acquired using the operation. Enns, et al. Expires August 8, 2010 [Page 103] Internet-Draft NETCONF Protocol February 2010 E.1.2. Loading the Update The configuration can be loaded onto the device without impacting the running system. If the :url capability is supported and lists "file" as a supported scheme, incoming changes can be placed in a local file. file://incoming.conf If the :candidate capability is supported, the candidate configuration can be used. If the update fails, the user file can be deleted using the operation, or the candidate configuration can be reverted using the operation. Enns, et al. Expires August 8, 2010 [Page 104] Internet-Draft NETCONF Protocol February 2010 E.1.3. Validating the Incoming Configuration Before the incoming configuration is applied, validating it is often useful. Validation allows the application to gain confidence that the change will succeed and simplifies recovery if it does not. If the device supports the :url capability and lists "file" as a supported scheme, use the operation with the parameter set to the proper user file: file://incoming.conf If the device supports the :candidate capability, some validation will be performed as part of loading the incoming configuration into the candidate. For full validation, either pass the parameter during the step given above, or use the operation with the parameter set to . E.1.4. Checkpointing the Running Configuration The running configuration can be saved into a local file as a checkpoint before loading the new configuration. If the update fails, the configuration can be restored by reloading the checkpoint file. The checkpoint file can be created using the operation. Enns, et al. Expires August 8, 2010 [Page 105] Internet-Draft NETCONF Protocol February 2010 file://checkpoint.conf To restore the checkpoint file, reverse the source and target parameters. E.1.5. Changing the Running Configuration When the incoming configuration has been safely loaded onto the device and validated, it is ready to impact the running system. If the device supports the :url capability and lists "file" as a supported scheme, use the operation to merge the incoming configuration into the running configuration. file://incoming.conf If the device supports the :candidate capability, use the operation to set the running configuration to the candidate configuration. Use the parameter to allow automatic reversion to the original configuration if connectivity to the device fails. 120 Enns, et al. Expires August 8, 2010 [Page 106] Internet-Draft NETCONF Protocol February 2010 E.1.6. Testing the New Configuration Now that the incoming configuration has been integrated into the running configuration, the application needs to gain trust that the change has affected the device in the way intended without affecting it negatively. To gain this confidence, the application can run tests of the operational state of the device. The nature of the test is dependent on the nature of the change and is outside the scope of this document. Such tests may include reachability from the system running the application (using ping), changes in reachability to the rest of the network (by comparing the device's routing table), or inspection of the particular change (looking for operational evidence of the BGP peer that was just added). E.1.7. Making the Change Permanent When the configuration change is in place and the application has sufficient faith in the proper function of this change, the application should make the change permanent. If the device supports the :startup capability, the current configuration can be saved to the startup configuration by using the startup configuration as the target of the operation. If the device supports the :candidate capability and a confirmed commit was requested, the confirming commit must be sent before the timeout expires. Enns, et al. Expires August 8, 2010 [Page 107] Internet-Draft NETCONF Protocol February 2010 E.1.8. Releasing the Configuration Lock When the configuration update is complete, the lock must be released, allowing other applications access to the configuration. Use the operation to release the configuration lock. E.2. Operations on Multiple Devices When a configuration change requires updates across a number of devices, care should be taken to provide the required transaction semantics. The NETCONF protocol contains sufficient primitives upon which transaction-oriented operations can be built. Providing complete transactional semantics across multiple devices is prohibitively expensive, but the size and number of windows for failure scenarios can be reduced. There are two classes of multi-device operations. The first class allows the operation to fail on individual devices without requiring all devices to revert to their original state. The operation can be retried at a later time, or its failure simply reported to the user. An example of this class might be adding an NTP server. For this class of operations, failure avoidance and recovery are focused on the individual device. This means recovery of the device, reporting the failure, and perhaps scheduling another attempt. The second class is more interesting, requiring that the operation should complete on all devices or be fully reversed. The network should either be transformed into a new state or be reset to its original state. For example, a change to a VPN may require updates to a number of devices. Another example of this might be adding a class-of-service definition. Leaving the network in a state where only a portion of the devices have been updated with the new definition will lead to future failures when the definition is referenced. To give transactional semantics, the same steps used in single device operations listed above are used, but are performed in parallel across all devices. Configuration locks should be acquired on all Enns, et al. Expires August 8, 2010 [Page 108] Internet-Draft NETCONF Protocol February 2010 target devices and kept until all devices are updated and the changes made permanent. Configuration changes should be uploaded and validation performed across all devices. Checkpoints should be made on each device. Then the running configuration can be changed, tested, and made permanent. If any of these steps fail, the previous configurations can be restored on any devices upon which they were changed. After the changes have been completely implemented or completely discarded, the locks on each device can be released. Enns, et al. Expires August 8, 2010 [Page 109] Internet-Draft NETCONF Protocol February 2010 Appendix F. Changes from RFC 4741 This section lists major changes between this document and RFC 4741. TBD. Enns, et al. Expires August 8, 2010 [Page 110] Internet-Draft NETCONF Protocol February 2010 Authors' Addresses Rob Enns (editor) Juniper Networks 1194 North Mathilda Ave Sunnyvale, CA 94089 US Email: rpe@juniper.net Martin Bjorklund (editor) Tail-f Systems Email: mbj@tail-f.com Juergen Schoenwaelder (editor) Jacobs University Email: j.schoenwaelder@jacobs-university.de Andy Bierman (editor) InterWorking Labs Email: andyb@iwl.com Enns, et al. Expires August 8, 2010 [Page 111]