diff options
Diffstat (limited to 'doc/rfc/rfc6241.txt')
| -rw-r--r-- | doc/rfc/rfc6241.txt | 6331 |
1 files changed, 6331 insertions, 0 deletions
diff --git a/doc/rfc/rfc6241.txt b/doc/rfc/rfc6241.txt new file mode 100644 index 0000000..5df2c58 --- /dev/null +++ b/doc/rfc/rfc6241.txt @@ -0,0 +1,6331 @@ + + + + + + +Internet Engineering Task Force (IETF) R. Enns, Ed. +Request for Comments: 6241 Juniper Networks +Obsoletes: 4741 M. Bjorklund, Ed. +Category: Standards Track Tail-f Systems +ISSN: 2070-1721 J. Schoenwaelder, Ed. + Jacobs University + A. Bierman, Ed. + Brocade + June 2011 + + + Network Configuration Protocol (NETCONF) + +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 (RPCs). This document obsoletes + RFC 4741. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6241. + + + + + + + + + + + + + + + +Enns, et al. Standards Track [Page 1] + +RFC 6241 NETCONF Protocol June 2011 + + +Copyright Notice + + Copyright (c) 2011 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 Simplified 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. Standards Track [Page 2] + +RFC 6241 NETCONF Protocol June 2011 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 + 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 + 1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 8 + 1.3. Capabilities . . . . . . . . . . . . . . . . . . . . . . 10 + 1.4. Separation of Configuration and State Data . . . . . . . 10 + 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 11 + 2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 11 + 2.2. Authentication, Integrity, and Confidentiality . . . . . 12 + 2.3. Mandatory Transport Protocol . . . . . . . . . . . . . . 12 + 3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 13 + 3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 13 + 3.2. Document Type Declarations . . . . . . . . . . . . . . . 13 + 4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 4.1. <rpc> Element . . . . . . . . . . . . . . . . . . . . . . 13 + 4.2. <rpc-reply> Element . . . . . . . . . . . . . . . . . . . 15 + 4.3. <rpc-error> Element . . . . . . . . . . . . . . . . . . . 16 + 4.4. <ok> Element . . . . . . . . . . . . . . . . . . . . . . 19 + 4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 19 + 5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 19 + 5.1. Configuration Datastores . . . . . . . . . . . . . . . . 19 + 5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 20 + 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 . . . . . . . . . . . . . 22 + 6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 23 + 6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 23 + 6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 24 + 6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 25 + 6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 26 + 6.4.1. No Filter . . . . . . . . . . . . . . . . . . . . . . 26 + 6.4.2. Empty Filter . . . . . . . . . . . . . . . . . . . . 26 + 6.4.3. Select the Entire <users> Subtree . . . . . . . . . . 27 + 6.4.4. Select All <name> Elements within the <users> + Subtree . . . . . . . . . . . . . . . . . . . . . . . 29 + 6.4.5. One Specific <user> Entry . . . . . . . . . . . . . . 30 + 6.4.6. Specific Elements from a Specific <user> Entry . . . 31 + 6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 32 + 6.4.8. Elements with Attribute Naming . . . . . . . . . . . 33 + 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 35 + 7.1. <get-config> . . . . . . . . . . . . . . . . . . . . . . 35 + 7.2. <edit-config> . . . . . . . . . . . . . . . . . . . . . . 37 + 7.3. <copy-config> . . . . . . . . . . . . . . . . . . . . . . 43 + 7.4. <delete-config> . . . . . . . . . . . . . . . . . . . . . 44 + 7.5. <lock> . . . . . . . . . . . . . . . . . . . . . . . . . 44 + + + +Enns, et al. Standards Track [Page 3] + +RFC 6241 NETCONF Protocol June 2011 + + + 7.6. <unlock> . . . . . . . . . . . . . . . . . . . . . . . . 47 + 7.7. <get> . . . . . . . . . . . . . . . . . . . . . . . . . . 48 + 7.8. <close-session> . . . . . . . . . . . . . . . . . . . . . 49 + 7.9. <kill-session> . . . . . . . . . . . . . . . . . . . . . 50 + 8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 51 + 8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 51 + 8.2. Writable-Running Capability . . . . . . . . . . . . . . . 53 + 8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 53 + 8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 53 + 8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 53 + 8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 53 + 8.2.5. Modifications to Existing Operations . . . . . . . . 53 + 8.3. Candidate Configuration Capability . . . . . . . . . . . 53 + 8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 53 + 8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 54 + 8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 54 + 8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 54 + 8.3.5. Modifications to Existing Operations . . . . . . . . 56 + 8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 57 + 8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 57 + 8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 58 + 8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 58 + 8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 59 + 8.4.5. Modifications to Existing Operations . . . . . . . . 60 + 8.5. Rollback-on-Error Capability . . . . . . . . . . . . . . 61 + 8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 61 + 8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 62 + 8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 62 + 8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 62 + 8.5.5. Modifications to Existing Operations . . . . . . . . 62 + 8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 63 + 8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 63 + 8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 63 + 8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 63 + 8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 63 + 8.6.5. Modifications to Existing Operations . . . . . . . . 64 + 8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 64 + 8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 64 + 8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 65 + 8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 65 + 8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 65 + 8.7.5. Modifications to Existing Operations . . . . . . . . 65 + 8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 66 + 8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 66 + 8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 66 + 8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 66 + 8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 66 + 8.8.5. Modifications to Existing Operations . . . . . . . . 66 + + + +Enns, et al. Standards Track [Page 4] + +RFC 6241 NETCONF Protocol June 2011 + + + 8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 67 + 8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 67 + 8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 68 + 8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 68 + 8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 68 + 8.9.5. Modifications to Existing Operations . . . . . . . . 68 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 69 + 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 71 + 10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 71 + 10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 71 + 10.3. NETCONF YANG Module . . . . . . . . . . . . . . . . . . . 72 + 10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 72 + 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 73 + 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 73 + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 74 + 13.1. Normative References . . . . . . . . . . . . . . . . . . 74 + 13.2. Informative References . . . . . . . . . . . . . . . . . 75 + Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 76 + Appendix B. XML Schema for NETCONF Messages Layer . . . . . . . 80 + Appendix C. YANG Module for NETCONF Protocol Operations . . . . 85 + Appendix D. Capability Template . . . . . . . . . . . . . . . . 105 + D.1. capability-name (template) . . . . . . . . . . . . . . . 105 + D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 105 + D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 105 + D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 105 + D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 105 + D.1.5. Modifications to Existing Operations . . . . . . . . 105 + D.1.6. Interactions with Other Capabilities . . . . . . . . 105 + Appendix E. Configuring Multiple Devices with NETCONF . . . . . 106 + E.1. Operations on Individual Devices . . . . . . . . . . . . 106 + E.1.1. Acquiring the Configuration Lock . . . . . . . . . . 106 + E.1.2. Checkpointing the Running Configuration . . . . . . . 107 + E.1.3. Loading and Validating the Incoming Configuration . . 108 + E.1.4. Changing the Running Configuration . . . . . . . . . 108 + E.1.5. Testing the New Configuration . . . . . . . . . . . . 109 + E.1.6. Making the Change Permanent . . . . . . . . . . . . . 109 + E.1.7. Releasing the Configuration Lock . . . . . . . . . . 110 + E.2. Operations on Multiple Devices . . . . . . . . . . . . . 111 + Appendix F. Changes from RFC 4741 . . . . . . . . . . . . . . . 112 + + + + + + + + + + + + +Enns, et al. Standards Track [Page 5] + +RFC 6241 NETCONF Protocol June 2011 + + +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 [W3C.REC-xml-20001006] 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 [W3C.REC-xslt-19991116], 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. + + + + + + +Enns, et al. Standards Track [Page 6] + +RFC 6241 NETCONF Protocol June 2011 + + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + +1.1. Terminology + + o candidate configuration datastore: A configuration datastore that + can be manipulated without impacting the device's current + configuration and that can be committed to the running + configuration datastore. Not all devices support a candidate + configuration datastore. + + o capability: A functionality that supplements the base NETCONF + specification. + + o client: Invokes protocol operations on a server. In addition, a + client can subscribe to receive notifications from a server. + + o configuration data: The set of writable data that is required to + transform a system from its initial default state into its current + state. + + o datastore: A conceptual place to store and access information. A + datastore might be implemented, for example, using files, a + database, flash memory locations, or combinations thereof. + + o configuration datastore: The datastore holding the complete set of + configuration data that is required to get a device from its + initial default state into a desired operational state. + + o message: A protocol element sent over a session. Messages are + well-formed XML documents. + + o notification: A server-initiated message indicating that a certain + event has been recognized by the server. + + o protocol operation: A specific remote procedure call, as used + within the NETCONF protocol. + + o remote procedure call (RPC): Realized by exchanging <rpc> and + <rpc-reply> messages. + + o running configuration datastore: A configuration datastore holding + the complete configuration currently active on the device. The + running configuration datastore always exists. + + o server: Executes protocol operations invoked by a client. In + addition, a server can send notifications to a client. + + + +Enns, et al. Standards Track [Page 7] + +RFC 6241 NETCONF Protocol June 2011 + + + o session: Client and server exchange messages using a secure, + connection-oriented session. + + o startup configuration datastore: The configuration datastore + holding the configuration loaded by the device when it boots. + Only present on devices that separate the startup configuration + datastore from the running configuration datastore. + + o state data: The additional data on a system that is not + configuration data such as read-only status information and + collected statistics. + + o user: The authenticated identity of the client. The authenticated + identity of a client is commonly referred to as the NETCONF + username. + +1.2. 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 as shown in + Figure 1. + + + + + + + + + + + + + + + + +Enns, et al. Standards Track [Page 8] + +RFC 6241 NETCONF Protocol June 2011 + + + Layer Example + +-------------+ +-----------------+ +----------------+ + (4) | Content | | Configuration | | Notification | + | | | data | | data | + +-------------+ +-----------------+ +----------------+ + | | | + +-------------+ +-----------------+ | + (3) | Operations | | <edit-config> | | + | | | | | + +-------------+ +-----------------+ | + | | | + +-------------+ +-----------------+ +----------------+ + (2) | Messages | | <rpc>, | | <notification> | + | | | <rpc-reply> | | | + +-------------+ +-----------------+ +----------------+ + | | | + +-------------+ +-----------------------------------------+ + (1) | Secure | | SSH, TLS, BEEP/TLS, SOAP/HTTP/TLS, ... | + | Transport | | | + +-------------+ +-----------------------------------------+ + + Figure 1: NETCONF Protocol Layers + + (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. + + (2) The Messages layer provides a simple, transport-independent + framing mechanism for encoding RPCs and notifications. + Section 4 documents the RPC messages, and [RFC5717] documents + notifications. + + (3) The Operations layer defines a set of base protocol operations + invoked as RPC methods with XML-encoded parameters. Section 7 + details the list of base protocol operations. + + (4) The Content layer is outside the scope of this document. It is + expected that separate efforts to standardize NETCONF data + models will be undertaken. + + The YANG data modeling language [RFC6020] has been developed for + specifying NETCONF data models and protocol operations, covering the + Operations and the Content layers of Figure 1. + + + + + + + +Enns, et al. Standards Track [Page 9] + +RFC 6241 NETCONF Protocol June 2011 + + +1.3. 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) [RFC3986]. + + 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 might 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 can define standardized capabilities, and + implementations can define proprietary ones. A capability URI MUST + sufficiently distinguish the naming authority to avoid naming + collisions. + +1.4. 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 + 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. + + + +Enns, et al. Standards Track [Page 10] + +RFC 6241 NETCONF Protocol June 2011 + + + To account for these issues, the NETCONF protocol recognizes the + difference between configuration data and state data and provides + operations for each. The <get-config> operation retrieves + configuration data only, while the <get> 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. + + For example, if a local database of user authentication data is + stored on the device, it is an implementation-dependent matter + whether it is included in configuration data. + +2. Transport Protocol Requirements + + NETCONF uses an RPC-based communication paradigm. A client sends a + series of one or more RPC request messages, which cause the server to + respond with a corresponding series of RPC reply messages. + + 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. + + 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. + + + +Enns, et al. Standards Track [Page 11] + +RFC 6241 NETCONF Protocol June 2011 + + +2.2. Authentication, Integrity, and Confidentiality + + NETCONF connections MUST provide authentication, data integrity, + confidentiality, and replay protection. 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 could be + encrypted using Transport Layer Security (TLS) [RFC5246] or Secure + Shell (SSH) [RFC4251], depending on the underlying protocol. + + NETCONF connections MUST be authenticated. The transport protocol is + responsible for authentication of the server to the client and + authentication of the client to the server. A NETCONF peer assumes + that the connection's authentication information has been validated + by the underlying transport 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 available on the device. For + example, a NETCONF server on a device that supports RADIUS [RFC2865] + might allow the use of RADIUS to authenticate NETCONF sessions. + + The authentication process MUST result in an authenticated client + identity whose permissions are known to the server. The + authenticated identity of a client is commonly referred to as the + NETCONF username. The username is a string of characters that match + the "Char" production from Section 2.2 of [W3C.REC-xml-20001006]. + The algorithm used to derive the username is transport protocol + specific and in addition specific to the authentication mechanism + used by the transport protocol. The transport protocol MUST provide + a username to be used by the other NETCONF layers. + + The access permissions of a given client, identified by its NETCONF + username, are part of the configuration of the NETCONF server. These + permissions MUST be enforced during the remainder of the NETCONF + session. The details of how access control is configured is outside + the scope of this document. + +2.3. Mandatory Transport Protocol + + A NETCONF implementation MUST support the SSH transport protocol + mapping [RFC6242]. + + + + + + + +Enns, et al. Standards Track [Page 12] + +RFC 6241 NETCONF Protocol June 2011 + + +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 + [RFC3629]. If a peer receives an <rpc> message that is not well- + formed XML or not encoded in UTF-8, it SHOULD reply with a + "malformed-message" error. If a reply cannot be sent for any reason, + the server MUST terminate the session. + + A NETCONF message MAY begin with an XML declaration (see Section 2.8 + of [W3C.REC-xml-20001006]). + + 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 [RFC3986]. NETCONF + capabilities are discussed in Section 8. + +3.2. Document Type Declarations + + Document type declarations (see Section 2.8 of + [W3C.REC-xml-20001006]) MUST NOT appear in NETCONF content. + +4. RPC Model + + The NETCONF protocol uses an RPC-based communication model. NETCONF + peers use <rpc> and <rpc-reply> 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. <rpc> Element + + The <rpc> element is used to enclose a NETCONF request sent from the + client to the server. + + + + + +Enns, et al. Standards Track [Page 13] + +RFC 6241 NETCONF Protocol June 2011 + + + The <rpc> element has a mandatory attribute "message-id", which is a + 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 <rpc-reply> message. The + sender MUST ensure that the "message-id" value is normalized + according to the XML attribute value normalization rules defined in + [W3C.REC-xml-20001006] if the sender wants the string to be returned + unmodified. For example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <some-method> + <!-- method parameters here... --> + </some-method> + </rpc> + + If additional attributes are present in an <rpc> element, a NETCONF + peer MUST return them unmodified in the <rpc-reply> element. This + includes any "xmlns" attributes. + + The name and parameters of an RPC are encoded as the contents of the + <rpc> element. The name of the RPC is an element directly inside the + <rpc> element, and any parameters are encoded inside this element. + + The following example invokes a method called <my-own-method>, which + has two parameters, <my-first-parameter>, with a value of "14", and + <another-parameter>, with a value of "fred": + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <my-own-method xmlns="http://example.net/me/my-own/1.0"> + <my-first-parameter>14</my-first-parameter> + <another-parameter>fred</another-parameter> + </my-own-method> + </rpc> + + The following example invokes a <rock-the-house> method with a + <zip-code> parameter of "27606-0100": + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <rock-the-house xmlns="http://example.net/rock/1.0"> + <zip-code>27606-0100</zip-code> + </rock-the-house> + </rpc> + + + + + +Enns, et al. Standards Track [Page 14] + +RFC 6241 NETCONF Protocol June 2011 + + + The following example invokes the NETCONF <get> method with no + parameters: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get/> + </rpc> + +4.2. <rpc-reply> Element + + The <rpc-reply> message is sent in response to an <rpc> message. + + The <rpc-reply> element has a mandatory attribute "message-id", which + is equal to the "message-id" attribute of the <rpc> for which this is + a response. + + A NETCONF server MUST also return any additional attributes included + in the <rpc> element unmodified in the <rpc-reply> element. + + The response data is encoded as one or more child elements to the + <rpc-reply> element. + + For example: + + The following <rpc> element invokes the NETCONF <get> method and + includes an additional attribute called "user-id". Note that the + "user-id" attribute is not in the NETCONF namespace. The returned + <rpc-reply> element returns the "user-id" attribute, as well as the + requested content. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" + xmlns:ex="http://example.net/content/1.0" + ex:user-id="fred"> + <get/> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" + xmlns:ex="http://example.net/content/1.0" + ex:user-id="fred"> + <data> + <!-- contents here... --> + </data> + </rpc-reply> + + + + + + +Enns, et al. Standards Track [Page 15] + +RFC 6241 NETCONF Protocol June 2011 + + +4.3. <rpc-error> Element + + The <rpc-error> element is sent in <rpc-reply> messages if an error + occurs during the processing of an <rpc> request. + + If a server encounters multiple errors during the processing of an + <rpc> request, the <rpc-reply> MAY contain multiple <rpc-error> + elements. However, a server is not required to detect or report more + than one <rpc-error> 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 <rpc-error> element if + any error conditions occur during processing. + + A server MUST NOT return application-level- or data-model-specific + error information in an <rpc-error> element for which the client does + not have sufficient access rights. + + The <rpc-error> 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) + + * 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 + + Note that there are no <error-tag> values defined in this document + that utilize the "warning" enumeration. This is reserved for + future use. + + 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. If a + + + +Enns, et al. Standards Track [Page 16] + +RFC 6241 NETCONF Protocol June 2011 + + + data-model-specific and an implementation-specific error-app-tag + both exist, then the data-model-specific value MUST be used by the + server. + + error-path: Contains the absolute XPath [W3C.REC-xpath-19991116] + 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 datastore 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 that 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 [W3C.REC-xml-20001006] and discussed in [RFC3470]. + + 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. + + + +Enns, et al. Standards Track [Page 17] + +RFC 6241 NETCONF Protocol June 2011 + + + Example: An error is returned if an <rpc> 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 <rpc-reply> element. + + <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get-config> + <source> + <running/> + </source> + </get-config> + </rpc> + + <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <rpc-error> + <error-type>rpc</error-type> + <error-tag>missing-attribute</error-tag> + <error-severity>error</error-severity> + <error-info> + <bad-attribute>message-id</bad-attribute> + <bad-element>rpc</bad-element> + </error-info> + </rpc-error> + </rpc-reply> + + The following <rpc-reply> illustrates the case of returning multiple + <rpc-error> elements. + + Note that the data models used in the examples in this section use + the <name> element to distinguish between multiple instances of the + <interface> element. + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" + xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0"> + <rpc-error> + <error-type>application</error-type> + <error-tag>invalid-value</error-tag> + <error-severity>error</error-severity> + <error-path xmlns:t="http://example.com/schema/1.2/config"> + /t:top/t:interface[t:name="Ethernet0/0"]/t:mtu + </error-path> + <error-message xml:lang="en"> + MTU value 25000 is not within range 256..9192 + </error-message> + </rpc-error> + <rpc-error> + <error-type>application</error-type> + + + +Enns, et al. Standards Track [Page 18] + +RFC 6241 NETCONF Protocol June 2011 + + + <error-tag>invalid-value</error-tag> + <error-severity>error</error-severity> + <error-path xmlns:t="http://example.com/schema/1.2/config"> + /t:top/t:interface[t:name="Ethernet1/0"]/t:address/t:name + </error-path> + <error-message xml:lang="en"> + Invalid IP address for interface Ethernet1/0 + </error-message> + </rpc-error> + </rpc-reply> + +4.4. <ok> Element + + The <ok> element is sent in <rpc-reply> messages if no errors or + warnings occurred during the processing of an <rpc> request, and no + data was returned from the operation. For example: + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + +4.5. Pipelining + + NETCONF <rpc> requests MUST be processed serially by the managed + device. Additional <rpc> requests MAY be sent before previous ones + have been completed. The managed device MUST send responses only in + the order the requests were received. + +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. + + + + + + + +Enns, et al. Standards Track [Page 19] + +RFC 6241 NETCONF Protocol June 2011 + + + The running configuration datastore holds 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 <running> element. + + Only the <running> 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. + + The capabilities in Sections 8.3 and 8.7 define the <candidate> and + <startup> 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 <config> element that + is specific to the 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 can support multiple data models, including both + standard and proprietary data models. + +6. Subtree Filtering + +6.1. Overview + + XML subtree filtering is a mechanism that allows an application to + select particular XML subtrees to include in the <rpc-reply> for a + <get> or <get-config> operation. A small set of filters for + inclusion, simple content exact-match, and selection is provided, + which allows some useful, but also very limited, selection + mechanisms. The server does not need to utilize any data-model- + specific semantics during processing, allowing for simple and + centralized implementation strategies. + + + + + + +Enns, et al. Standards Track [Page 20] + +RFC 6241 NETCONF Protocol June 2011 + + + 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. + + Each node specified in a subtree filter represents an inclusive + filter. Only associated nodes in underlying data model(s) within the + specified datastore on the server are selected by the filter. A node + is selected if it matches the selection criteria and hierarchy of + elements given in the filter data, except that the filter absolute + path name is adjusted to start from the layer below <filter>. + + Response messages contain only the subtrees selected by the filter. + Any selection criteria that were present in the request, within a + particular selected subtree, are also included in the response. Note + that some elements expressed in the filter as leaf nodes will be + expanded (i.e., subtrees included) in the filter output. Specific + data instances are not duplicated in the response in the event that + the request contains multiple filter subtree expressions that select + the same data. + +6.2. Subtree Filter Components + + A subtree filter is comprised of XML elements and their XML + attributes. There are five types of components that can 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 + + A namespace is considered to match (for filter purposes) if the XML + namespace associated with a particular node within the <filter> + element is the same as in the underlying data model. Note that + namespace selection cannot be used by itself. At least one element + MUST be specified in the filter if any elements are to be included in + the filter output. + + + + + +Enns, et al. Standards Track [Page 21] + +RFC 6241 NETCONF Protocol June 2011 + + + An XML namespace wildcard mechanism is defined for subtree filtering. + If an element within the <filter> element is not qualified by a + namespace (e.g., xmlns=""), then the server MUST evaluate all the XML + namespaces it supports, when processing that subtree filter node. + This wildcard mechanism is not applicable to XML attributes. + + Note that prefix values for qualified namespaces are not relevant + when comparing filter elements to elements in the underlying data + model. + + Example: + + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"/> + </filter> + + In this example, the <top> element is a selection node, and only this + node in the "http://example.com/schema/1.2/config" namespace and any + child nodes (from the underlying data model) will be included in the + filter output. + +6.2.2. Attribute Match Expressions + + An attribute that appears in a subtree filter is part of an + "attribute match expression". Any number of (unqualified or + qualified) XML attributes MAY be present in any type of filter node. + In addition to the selection criteria normally applicable to that + node, the selected data MUST have matching values for every attribute + specified in the node. If an element is not defined to include a + specified attribute, then it is not selected in the filter output. + + Example: + + <filter type="subtree"> + <t:top xmlns:t="http://example.com/schema/1.2/config"> + <t:interfaces> + <t:interface t:ifName="eth0"/> + </t:interfaces> + </t:top> + </filter> + + In this example, the <top> and <interfaces> elements are containment + nodes, the <interface> 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. + + + +Enns, et al. Standards Track [Page 22] + +RFC 6241 NETCONF Protocol June 2011 + + +6.2.3. Containment Nodes + + Nodes that contain child elements within a subtree filter are called + "containment nodes". Each child element can be any type of node, + including another containment node. For each containment node + specified in a subtree filter, all data model instances that exactly + match the specified namespaces, element hierarchy, and any attribute + match expressions are included in the filter output. + + Example: + + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"> + <users/> + </top> + </filter> + + In this example, the <top> element is a containment node. + +6.2.4. Selection Nodes + + An empty leaf node within a filter is called a "selection node", and + it represents an "explicit selection" filter on the underlying data + model. Presence of any selection nodes within a set of sibling nodes + will cause the filter to select the specified subtree(s) and suppress + automatic selection of the entire set of sibling nodes in the + underlying data model. For filtering purposes, an empty leaf node + can be declared either with an empty tag (e.g., <foo/>) or with + explicit start and end tags (e.g., <foo> </foo>). Any whitespace + characters are ignored in this form. + + Example: + + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"> + <users/> + </top> + </filter> + + In this example, the <top> element is a containment node, and the + <users> element is a selection node. Only "users" nodes in the + "http://example.com/schema/1.2/config" namespace that occur within a + <top> element that is the root of the configuration datastore will be + included in the filter output. + + + + + + + +Enns, et al. Standards Track [Page 23] + +RFC 6241 NETCONF Protocol June 2011 + + +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. + + o Multiple content match nodes (i.e., sibling nodes) are logically + combined in an "AND" expression. + + o Filtering of mixed content is not supported. + + o Filtering of list content is not supported. + + o Filtering of whitespace-only content is not supported. + + o A content match node MUST contain non-whitespace characters. An + empty element (e.g., <foo></foo>) will be interpreted as a + selection node (e.g., <foo/>). + + o Leading and trailing whitespace characters are ignored, but any + whitespace characters within a block of text characters are not + ignored or modified. + + If all specified sibling content match nodes in a subtree filter + expression are "true", then the filter output nodes are selected in + the following manner: + + o Each content match node in the sibling set is included in the + filter output. + + o If any containment nodes are present in the sibling set, then they + are processed further and included if any nested filter criteria + are also met. + + o If any selection nodes are present in the sibling set, then all of + them are included in the filter output. + + o 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. + + + + + + + +Enns, et al. Standards Track [Page 24] + +RFC 6241 NETCONF Protocol June 2011 + + + o Otherwise (i.e., there are no selection or containment nodes in + the filter sibling set), all the nodes defined at this level in + the underlying data model (and their subtrees, if any) are + returned in the filter output. + + If any of the sibling content match node tests are "false", then no + further filter processing is performed on that sibling set, and none + of the sibling subtrees are selected by the filter, including the + content match node(s). + + Example: + + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>fred</name> + </user> + </users> + </top> + </filter> + + In this example, the <users> and <user> nodes are both containment + nodes, and <name> is a content match node. Since no sibling nodes of + <name> are specified (and therefore no containment or selection + nodes), all of the sibling nodes of <name> are returned in the filter + output. Only "user" nodes in the + "http://example.com/schema/1.2/config" namespace that match the + element hierarchy and for which the <name> element is equal to "fred" + will be included in the filter output. + +6.3. Subtree Filter Processing + + The filter output (the set of selected nodes) is initially empty. + + Each subtree filter can contain one or more data model fragments, + which represent portions of the data model that will be selected + (with all child nodes) in the filter output. + + Each subtree data fragment is compared by the server to the internal + data models supported by the server. If the entire subtree data- + fragment filter (starting from the root to the innermost element + specified in the filter) exactly matches a corresponding portion of + the supported data model, then that node and all its children are + included in the result data. + + The server processes all nodes with the same parent node (sibling + set) together, starting from the root to the leaf nodes. The root + + + +Enns, et al. Standards Track [Page 25] + +RFC 6241 NETCONF Protocol June 2011 + + + elements in the filter are considered in the same sibling set + (assuming they are in the same namespace), even though they do not + have a common parent. + + For each sibling set, the server determines which nodes are included + (or potentially included) in the filter output, and which sibling + subtrees are excluded (pruned) from the filter output. The server + first determines which types of nodes are present in the sibling set + and processes the nodes according to the rules for their type. If + any nodes in the sibling set are selected, then the process is + recursively applied to the sibling sets of each selected node. The + algorithm continues until all sibling sets in all subtrees specified + in the filter have been processed. + +6.4. Subtree Filtering Examples + +6.4.1. No Filter + + Leaving out the filter on the <get> operation returns the entire data + model. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get/> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + <!-- ... entire set of data returned ... --> + </data> + </rpc-reply> + +6.4.2. Empty Filter + + An empty filter will select nothing because no content match or + selection nodes are present. This is not an error. The <filter> + element's "type" attribute used in these examples is discussed + further in Section 7.1. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get> + <filter type="subtree"> + </filter> + </get> + </rpc> + + + + +Enns, et al. Standards Track [Page 26] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + </data> + </rpc-reply> + +6.4.3. Select the Entire <users> Subtree + + The filter in this example contains one selection node (<users>), so + just that subtree is selected by the filter. This example represents + the fully populated <users> data model in most of the filter examples + that follow. In a real data model, the <company-info> would not + likely be returned with the list of users for a particular host or + network. + + NOTE: The filtering and configuration examples used in this document + appear in the namespace "http://example.com/schema/1.2/config". The + root element of this namespace is <top>. The <top> element and its + descendents represent an example configuration data model only. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get-config> + <source> + <running/> + </source> + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"> + <users/> + </top> + </filter> + </get-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>root</name> + <type>superuser</type> + <full-name>Charlie Root</full-name> + <company-info> + <dept>1</dept> + <id>1</id> + </company-info> + </user> + + + +Enns, et al. Standards Track [Page 27] + +RFC 6241 NETCONF Protocol June 2011 + + + <user> + <name>fred</name> + <type>admin</type> + <full-name>Fred Flintstone</full-name> + <company-info> + <dept>2</dept> + <id>2</id> + </company-info> + </user> + <user> + <name>barney</name> + <type>admin</type> + <full-name>Barney Rubble</full-name> + <company-info> + <dept>2</dept> + <id>3</id> + </company-info> + </user> + </users> + </top> + </data> + </rpc-reply> + + The following filter request would have produced the same result, but + only because the container <users> defines one child element + (<user>). + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get-config> + <source> + <running/> + </source> + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user/> + </users> + </top> + </filter> + </get-config> + </rpc> + + + + + + + + + +Enns, et al. Standards Track [Page 28] + +RFC 6241 NETCONF Protocol June 2011 + + +6.4.4. Select All <name> Elements within the <users> Subtree + + This filter contains two containment nodes (<users>, <user>) and one + selection node (<name>). All instances of the <name> element in the + same sibling set are selected in the filter output. The client might + need to know that <name> is used as an instance identifier in this + particular data structure, but the server does not need to know that + meta-data in order to process the request. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get-config> + <source> + <running/> + </source> + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name/> + </user> + </users> + </top> + </filter> + </get-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>root</name> + </user> + <user> + <name>fred</name> + </user> + <user> + <name>barney</name> + </user> + </users> + </top> + </data> + </rpc-reply> + + + + + + +Enns, et al. Standards Track [Page 29] + +RFC 6241 NETCONF Protocol June 2011 + + +6.4.5. One Specific <user> Entry + + This filter contains two containment nodes (<users>, <user>) and one + content match node (<name>). All instances of the sibling set + containing <name> for which the value of <name> equals "fred" are + selected in the filter output. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get-config> + <source> + <running/> + </source> + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>fred</name> + </user> + </users> + </top> + </filter> + </get-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>fred</name> + <type>admin</type> + <full-name>Fred Flintstone</full-name> + <company-info> + <dept>2</dept> + <id>2</id> + </company-info> + </user> + </users> + </top> + </data> + </rpc-reply> + + + + + + + + +Enns, et al. Standards Track [Page 30] + +RFC 6241 NETCONF Protocol June 2011 + + +6.4.6. Specific Elements from a Specific <user> Entry + + This filter contains two containment nodes (<users>, <user>), one + content match node (<name>), and two selection nodes (<type>, + <full-name>). All instances of the <type> and <full-name> elements + in the same sibling set containing <name> for which the value of + <name> equals "fred" are selected in the filter output. The + <company-info> element is not included because the sibling set + contains selection nodes. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get-config> + <source> + <running/> + </source> + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>fred</name> + <type/> + <full-name/> + </user> + </users> + </top> + </filter> + </get-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>fred</name> + <type>admin</type> + <full-name>Fred Flintstone</full-name> + </user> + </users> + </top> + </data> + </rpc-reply> + + + + + + + +Enns, et al. Standards Track [Page 31] + +RFC 6241 NETCONF Protocol June 2011 + + +6.4.7. Multiple Subtrees + + This filter contains three subtrees (name=root, fred, barney). + + The "root" subtree filter contains two containment nodes (<users>, + <user>), one content match node (<name>), and one selection node + (<company-info>). The subtree selection criteria are met, and just + the company-info subtree for "root" is selected in the filter output. + + The "fred" subtree filter contains three containment nodes (<users>, + <user>, <company-info>), one content match node (<name>), and one + selection node (<id>). The subtree selection criteria are met, and + just the <id> element within the company-info subtree for "fred" is + selected in the filter output. + + The "barney" subtree filter contains three containment nodes + (<users>, <user>, <company-info>), two content match nodes (<name>, + <type>), and one selection node (<dept>). The subtree selection + criteria are not met because user "barney" is not a "superuser", and + the entire subtree for "barney" (including its parent <user> entry) + is excluded from the filter output. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get-config> + <source> + <running/> + </source> + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>root</name> + <company-info/> + </user> + <user> + <name>fred</name> + <company-info> + <id/> + </company-info> + </user> + <user> + <name>barney</name> + <type>superuser</type> + <company-info> + <dept/> + </company-info> + </user> + + + +Enns, et al. Standards Track [Page 32] + +RFC 6241 NETCONF Protocol June 2011 + + + </users> + </top> + </filter> + </get-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>root</name> + <company-info> + <dept>1</dept> + <id>1</id> + </company-info> + </user> + <user> + <name>fred</name> + <company-info> + <id>2</id> + </company-info> + </user> + </users> + </top> + </data> + </rpc-reply> + +6.4.8. Elements with Attribute Naming + + In this example, the filter contains one containment node + (<interfaces>), one attribute match expression ("ifName"), and one + selection node (<interface>). All instances of the <interface> + subtree that have an "ifName" attribute equal to "eth0" are selected + in the filter output. The filter data elements and attributes are + qualified because the "ifName" attribute will not be considered part + of the "schema/1.2" namespace if it is unqualified. + + + + + + + + + + + + + +Enns, et al. Standards Track [Page 33] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get> + <filter type="subtree"> + <t:top xmlns:t="http://example.com/schema/1.2/stats"> + <t:interfaces> + <t:interface t:ifName="eth0"/> + </t:interfaces> + </t:top> + </filter> + </get> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + <t:top xmlns:t="http://example.com/schema/1.2/stats"> + <t:interfaces> + <t:interface t:ifName="eth0"> + <t:ifInOctets>45621</t:ifInOctets> + <t:ifOutOctets>774344</t:ifOutOctets> + </t:interface> + </t:interfaces> + </t:top> + </data> + </rpc-reply> + + If "ifName" were a child node instead of an attribute, then the + following request would produce similar results. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get> + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/stats"> + <interfaces> + <interface> + <ifName>eth0</ifName> + </interface> + </interfaces> + </top> + </filter> + </get> + </rpc> + + + + + + + +Enns, et al. Standards Track [Page 34] + +RFC 6241 NETCONF Protocol June 2011 + + +7. Protocol Operations + + The NETCONF protocol provides a small set of low-level operations to + manage device configurations and retrieve device state information. + The base protocol provides operations to retrieve, configure, copy, + and delete configuration datastores. Additional operations are + provided, based on the capabilities advertised by the device. + + The base protocol includes the following protocol operations: + + o get + + o get-config + + o edit-config + + o copy-config + + o delete-config + + o lock + + o unlock + + o close-session + + o kill-session + + A protocol operation can fail for various reasons, including + "operation not supported". An initiator SHOULD NOT assume that any + operation will always succeed. The return values in any RPC reply + SHOULD be checked for error responses. + + The syntax and XML encoding of the protocol operations are formally + defined in the YANG module in Appendix C. The following sections + describe the semantics of each protocol operation. + +7.1. <get-config> + + Description: Retrieve all or part of a specified configuration + datastore. + + Parameters: + + source: Name of the configuration datastore being queried, such + as <running/>. + + + + + +Enns, et al. Standards Track [Page 35] + +RFC 6241 NETCONF Protocol June 2011 + + + filter: This parameter identifies the portions of the device + configuration datastore to retrieve. If this parameter is not + present, the entire configuration is returned. + + The <filter> element MAY optionally contain a "type" attribute. + This attribute indicates the type of filtering syntax used + within the <filter> element. The default filtering mechanism + in NETCONF is referred to as subtree filtering and is described + in Section 6. The value "subtree" explicitly identifies this + type of filtering. + + If the NETCONF peer supports the :xpath capability + (Section 8.9), the value "xpath" MAY be used to indicate that + the "select" attribute on the <filter> element contains an + XPath expression. + + Positive Response: If the device can satisfy the request, the server + sends an <rpc-reply> element containing a <data> element with the + results of the query. + + Negative Response: An <rpc-error> element is included in the + <rpc-reply> if the request cannot be completed for any reason. + + Example: To retrieve the entire <users> subtree: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get-config> + <source> + <running/> + </source> + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/config"> + <users/> + </top> + </filter> + </get-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>root</name> + <type>superuser</type> + <full-name>Charlie Root</full-name> + + + +Enns, et al. Standards Track [Page 36] + +RFC 6241 NETCONF Protocol June 2011 + + + <company-info> + <dept>1</dept> + <id>1</id> + </company-info> + </user> + <!-- additional <user> elements appear here... --> + </users> + </top> + </data> + </rpc-reply> + + Section 6 contains additional examples of subtree filtering. + +7.2. <edit-config> + + Description: + + The <edit-config> operation loads all or part of a specified + configuration to the specified target configuration datastore. + This operation allows the new configuration to be expressed in + several ways, such as using a local file, a remote file, or + inline. If the target configuration datastore does not exist, it + will be created. + + If a NETCONF peer supports the :url capability (Section 8.8), the + <url> element can appear instead of the <config> parameter. + + The device analyzes the source and target configurations and + performs the requested changes. The target configuration is not + necessarily replaced, as with the <copy-config> message. Instead, + the target configuration is changed in accordance with the + source's data and requested operations. + + If the <edit-config> operation contains multiple sub-operations + that apply to the same conceptual node in the underlying data + model, then the result of the operation is undefined (i.e., + outside the scope of the NETCONF protocol). + + Attributes: + + operation: Elements in the <config> subtree MAY contain an + "operation" attribute, which belongs to the NETCONF namespace + defined in Section 3.1. The attribute identifies the point in + the configuration to perform the operation and MAY appear on + multiple elements throughout the <config> subtree. + + If the "operation" attribute is not specified, the + configuration is merged into the configuration datastore. + + + +Enns, et al. Standards Track [Page 37] + +RFC 6241 NETCONF Protocol June 2011 + + + The "operation" attribute has one of the following values: + + merge: The configuration data identified by the element + containing this attribute is merged with the configuration + at the corresponding level in the configuration datastore + identified by the <target> parameter. This is the default + behavior. + + replace: The configuration data identified by the element + containing this attribute replaces any related configuration + in the configuration datastore identified by the <target> + parameter. If no such configuration data exists in the + configuration datastore, it is created. Unlike a + <copy-config> operation, which replaces the entire target + configuration, only the configuration actually present in + the <config> parameter is affected. + + create: The configuration data identified by the element + containing this attribute is added to the configuration if + and only if the configuration data does not already exist in + the configuration datastore. If the configuration data + exists, an <rpc-error> element is returned with an + <error-tag> value of "data-exists". + + delete: The configuration data identified by the element + containing this attribute is deleted from the configuration + if and only if the configuration data currently exists in + the configuration datastore. If the configuration data does + not exist, an <rpc-error> element is returned with an + <error-tag> value of "data-missing". + + remove: The configuration data identified by the element + containing this attribute is deleted from the configuration + if the configuration data currently exists in the + configuration datastore. If the configuration data does not + exist, the "remove" operation is silently ignored by the + server. + + Parameters: + + target: Name of the configuration datastore being edited, such as + <running/> or <candidate/>. + + default-operation: Selects the default operation (as described in + the "operation" attribute) for this <edit-config> request. The + default value for the <default-operation> parameter is "merge". + + + + + +Enns, et al. Standards Track [Page 38] + +RFC 6241 NETCONF Protocol June 2011 + + + The <default-operation> parameter is optional, but if provided, + it has one of the following values: + + merge: The configuration data in the <config> parameter is + merged with the configuration at the corresponding level in + the target datastore. This is the default behavior. + + replace: The configuration data in the <config> parameter + completely replaces the configuration in the target + datastore. This is useful for loading previously saved + configuration data. + + none: The target datastore is unaffected by the configuration + in the <config> parameter, unless and until the incoming + configuration data uses the "operation" attribute to request + a different operation. If the configuration in the <config> + parameter contains data for which there is not a + corresponding level in the target datastore, an <rpc-error> + is returned with an <error-tag> value of data-missing. + Using "none" allows operations like "delete" to avoid + unintentionally creating the parent hierarchy of the element + to be deleted. + + test-option: The <test-option> element MAY be specified only if + the device advertises the :validate:1.1 capability + (Section 8.6). + + The <test-option> element has one of the following values: + + test-then-set: Perform a validation test before attempting to + set. If validation errors occur, do not perform the + <edit-config> operation. This is the default test-option. + + set: Perform a set without a validation test first. + + test-only: Perform only the validation test, without + attempting to set. + + error-option: The <error-option> element has one of the following + values: + + stop-on-error: Abort the <edit-config> operation on first + error. This is the default error-option. + + continue-on-error: Continue to process configuration data on + error; error is recorded, and negative response is generated + if any errors occur. + + + + +Enns, et al. Standards Track [Page 39] + +RFC 6241 NETCONF Protocol June 2011 + + + rollback-on-error: If an error condition occurs such that an + error severity <rpc-error> element is generated, the server + will stop processing the <edit-config> operation and restore + the specified configuration to its complete state at the + start of this <edit-config> operation. This option requires + the server to support the :rollback-on-error capability + described in Section 8.5. + + config: A hierarchy of configuration data as defined by one of + the device's data models. The contents MUST be placed in an + appropriate namespace, to allow the device to detect the + appropriate data model, and the contents MUST follow the + constraints of that data model, as defined by its capability + definition. Capabilities are discussed in Section 8. + + Positive Response: If the device was able to satisfy the request, an + <rpc-reply> is sent containing an <ok> element. + + Negative Response: An <rpc-error> response is sent if the request + cannot be completed for any reason. + + Example: The <edit-config> examples in this section utilize a simple + data model, in which multiple instances of the <interface> element + can be present, and an instance is distinguished by the <name> + element within each <interface> element. + + Set the MTU to 1500 on an interface named "Ethernet0/0" in the + running configuration: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <edit-config> + <target> + <running/> + </target> + <config> + <top xmlns="http://example.com/schema/1.2/config"> + <interface> + <name>Ethernet0/0</name> + <mtu>1500</mtu> + </interface> + </top> + </config> + </edit-config> + </rpc> + + + + + + +Enns, et al. Standards Track [Page 40] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + + Add an interface named "Ethernet0/0" to the running configuration, + replacing any previous interface with that name: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <edit-config> + <target> + <running/> + </target> + <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0"> + <top xmlns="http://example.com/schema/1.2/config"> + <interface xc:operation="replace"> + <name>Ethernet0/0</name> + <mtu>1500</mtu> + <address> + <name>192.0.2.4</name> + <prefix-length>24</prefix-length> + </address> + </interface> + </top> + </config> + </edit-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + + Delete the configuration for an interface named "Ethernet0/0" from + the running configuration: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <edit-config> + <target> + <running/> + </target> + <default-operation>none</default-operation> + <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0"> + <top xmlns="http://example.com/schema/1.2/config"> + <interface xc:operation="delete"> + <name>Ethernet0/0</name> + + + +Enns, et al. Standards Track [Page 41] + +RFC 6241 NETCONF Protocol June 2011 + + + </interface> + </top> + </config> + </edit-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + + Delete interface 192.0.2.4 from an OSPF area (other interfaces + configured in the same area are unaffected): + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <edit-config> + <target> + <running/> + </target> + <default-operation>none</default-operation> + <config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0"> + <top xmlns="http://example.com/schema/1.2/config"> + <protocols> + <ospf> + <area> + <name>0.0.0.0</name> + <interfaces> + <interface xc:operation="delete"> + <name>192.0.2.4</name> + </interface> + </interfaces> + </area> + </ospf> + </protocols> + </top> + </config> + </edit-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + + + + + + + +Enns, et al. Standards Track [Page 42] + +RFC 6241 NETCONF Protocol June 2011 + + +7.3. <copy-config> + + Description: Create or replace an entire configuration datastore + with the contents of another complete configuration datastore. If + the target datastore exists, it is overwritten. Otherwise, a new + one is created, if allowed. + + If a NETCONF peer supports the :url capability (Section 8.8), the + <url> element can appear as the <source> or <target> parameter. + + Even if it advertises the :writable-running capability, a device + MAY choose not to support the <running/> configuration datastore + as the <target> parameter of a <copy-config> operation. A device + MAY choose not to support remote-to-remote copy operations, where + both the <source> and <target> parameters use the <url> element. + If the <source> and <target> parameters identify the same URL or + configuration datastore, an error MUST be returned with an error- + tag containing "invalid-value". + + Parameters: + + target: Name of the configuration datastore to use as the + destination of the <copy-config> operation. + + source: Name of the configuration datastore to use as the source + of the <copy-config> operation, or the <config> element + containing the complete configuration to copy. + + Positive Response: If the device was able to satisfy the request, an + <rpc-reply> is sent that includes an <ok> element. + + Negative Response: An <rpc-error> element is included within the + <rpc-reply> if the request cannot be completed for any reason. + + Example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <copy-config> + <target> + <running/> + </target> + <source> + <url>https://user:password@example.com/cfg/new.txt</url> + </source> + </copy-config> + </rpc> + + + + +Enns, et al. Standards Track [Page 43] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + +7.4. <delete-config> + + Description: Delete a configuration datastore. The <running> + configuration datastore cannot be deleted. + + If a NETCONF peer supports the :url capability (Section 8.8), the + <url> element can appear as the <target> parameter. + + Parameters: + + target: Name of the configuration datastore to delete. + + Positive Response: If the device was able to satisfy the request, an + <rpc-reply> is sent that includes an <ok> element. + + Negative Response: An <rpc-error> element is included within the + <rpc-reply> if the request cannot be completed for any reason. + + Example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <delete-config> + <target> + <startup/> + </target> + </delete-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + +7.5. <lock> + + Description: The <lock> operation allows the client to lock the + entire configuration datastore system of a device. Such locks are + intended to be short-lived and allow a client to make a change + without fear of interaction with other NETCONF clients, non- + NETCONF clients (e.g., SNMP and command line interface (CLI) + scripts), and human users. + + + + +Enns, et al. Standards Track [Page 44] + +RFC 6241 NETCONF Protocol June 2011 + + + An attempt to lock the configuration datastore MUST fail if an + existing session or other entity holds a lock on any portion of + the lock target. + + When the lock is acquired, the server MUST prevent any changes to + the locked resource other than those requested by this session. + SNMP and CLI requests to modify the resource MUST fail with an + appropriate error. + + The duration of the lock is defined as beginning when the lock is + acquired and lasting until either the lock is released or the + NETCONF session closes. The session closure can be explicitly + performed by the client, or implicitly performed by the server + based on criteria such as failure of the underlying transport, + simple inactivity timeout, or detection of abusive behavior on the + part of the client. These criteria are dependent on the + implementation and the underlying transport. + + The <lock> operation takes a mandatory parameter, <target>. The + <target> parameter names the configuration datastore that will be + locked. When a lock is active, using the <edit-config> operation + on the locked configuration datastore and using the locked + configuration as a target of the <copy-config> operation will be + disallowed by any other NETCONF session. Additionally, the system + will ensure that these locked configuration resources will not be + modified by other non-NETCONF management operations such as SNMP + and CLI. The <kill-session> operation can be used to force the + release of a lock owned by another NETCONF session. It is beyond + the scope of this document to define how to break locks held by + other entities. + + A lock MUST NOT be granted if any of the following conditions is + true: + + * A lock is already held by any NETCONF session or another + entity. + + * The target configuration is <candidate>, it has already been + modified, and these changes have not been committed or rolled + back. + + * The target configuration is <running>, and another NETCONF + session has an ongoing confirmed commit (Section 8.4). + + The server MUST respond with either an <ok> element or an + <rpc-error>. + + + + + +Enns, et al. Standards Track [Page 45] + +RFC 6241 NETCONF Protocol June 2011 + + + A lock will be released by the system if the session holding the + lock is terminated for any reason. + + Parameters: + + target: Name of the configuration datastore to lock. + + Positive Response: If the device was able to satisfy the request, an + <rpc-reply> is sent that contains an <ok> element. + + Negative Response: An <rpc-error> element is included in the + <rpc-reply> if the request cannot be completed for any reason. + + If the lock is already held, the <error-tag> element will be + "lock-denied" and the <error-info> element will include the + <session-id> of the lock owner. If the lock is held by a non- + NETCONF entity, a <session-id> of 0 (zero) is included. Note that + any other entity performing a lock on even a partial piece of a + target will prevent a NETCONF lock (which is global) from being + obtained on that target. + + Example: The following example shows a successful acquisition of a + lock. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <lock> + <target> + <running/> + </target> + </lock> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> <!-- lock succeeded --> + </rpc-reply> + + Example: The following example shows a failed attempt to acquire a + lock when the lock is already in use. + + + + + + + + + + + +Enns, et al. Standards Track [Page 46] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <lock> + <target> + <running/> + </target> + </lock> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <rpc-error> <!-- lock failed --> + <error-type>protocol</error-type> + <error-tag>lock-denied</error-tag> + <error-severity>error</error-severity> + <error-message> + Lock failed, lock is already held + </error-message> + <error-info> + <session-id>454</session-id> + <!-- lock is held by NETCONF session 454 --> + </error-info> + </rpc-error> + </rpc-reply> + +7.6. <unlock> + + Description: The <unlock> operation is used to release a + configuration lock, previously obtained with the <lock> operation. + + An <unlock> operation will not succeed if either of the following + conditions is true: + + * The specified lock is not currently active. + + * The session issuing the <unlock> operation is not the same + session that obtained the lock. + + The server MUST respond with either an <ok> element or an + <rpc-error>. + + Parameters: + + target: Name of the configuration datastore to unlock. + + A NETCONF client is not permitted to unlock a configuration + datastore that it did not lock. + + + + +Enns, et al. Standards Track [Page 47] + +RFC 6241 NETCONF Protocol June 2011 + + + Positive Response: If the device was able to satisfy the request, an + <rpc-reply> is sent that contains an <ok> element. + + Negative Response: An <rpc-error> element is included in the + <rpc-reply> if the request cannot be completed for any reason. + + Example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <unlock> + <target> + <running/> + </target> + </unlock> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + +7.7. <get> + + Description: Retrieve running configuration and device state + information. + + Parameters: + + filter: This parameter specifies the portion of the system + configuration and state data to retrieve. If this parameter is + not present, all the device configuration and state information + is returned. + + The <filter> element MAY optionally contain a "type" attribute. + This attribute indicates the type of filtering syntax used + within the <filter> element. The default filtering mechanism + in NETCONF is referred to as subtree filtering and is described + in Section 6. The value "subtree" explicitly identifies this + type of filtering. + + If the NETCONF peer supports the :xpath capability + (Section 8.9), the value "xpath" MAY be used to indicate that + the "select" attribute of the <filter> element contains an + XPath expression. + + + + + + +Enns, et al. Standards Track [Page 48] + +RFC 6241 NETCONF Protocol June 2011 + + + Positive Response: If the device was able to satisfy the request, an + <rpc-reply> is sent. The <data> section contains the appropriate + subset. + + Negative Response: An <rpc-error> element is included in the + <rpc-reply> if the request cannot be completed for any reason. + + Example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get> + <filter type="subtree"> + <top xmlns="http://example.com/schema/1.2/stats"> + <interfaces> + <interface> + <ifName>eth0</ifName> + </interface> + </interfaces> + </top> + </filter> + </get> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + <top xmlns="http://example.com/schema/1.2/stats"> + <interfaces> + <interface> + <ifName>eth0</ifName> + <ifInOctets>45621</ifInOctets> + <ifOutOctets>774344</ifOutOctets> + </interface> + </interfaces> + </top> + </data> + </rpc-reply> + +7.8. <close-session> + + Description: Request graceful termination of a NETCONF session. + + When a NETCONF server receives a <close-session> request, it will + gracefully close the session. The server will release any locks + and resources associated with the session and gracefully close any + associated connections. Any NETCONF requests received after a + <close-session> request will be ignored. + + + +Enns, et al. Standards Track [Page 49] + +RFC 6241 NETCONF Protocol June 2011 + + + Positive Response: If the device was able to satisfy the request, an + <rpc-reply> is sent that includes an <ok> element. + + Negative Response: An <rpc-error> element is included in the + <rpc-reply> if the request cannot be completed for any reason. + + Example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <close-session/> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + +7.9. <kill-session> + + Description: Force the termination of a NETCONF session. + + When a NETCONF entity receives a <kill-session> request for an + open session, it will abort any operations currently in process, + release any locks and resources associated with the session, and + close any associated connections. + + If a NETCONF server receives a <kill-session> request while + processing a confirmed commit (Section 8.4), it MUST restore the + configuration to its state before the confirmed commit was issued. + + Otherwise, the <kill-session> operation does not roll back + configuration or other device state modifications made by the + entity holding the lock. + + Parameters: + + session-id: Session identifier of the NETCONF session to be + terminated. If this value is equal to the current session ID, + an "invalid-value" error is returned. + + Positive Response: If the device was able to satisfy the request, an + <rpc-reply> is sent that includes an <ok> element. + + Negative Response: An <rpc-error> element is included in the + <rpc-reply> if the request cannot be completed for any reason. + + + + + +Enns, et al. Standards Track [Page 50] + +RFC 6241 NETCONF Protocol June 2011 + + + Example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <kill-session> + <session-id>4</session-id> + </kill-session> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + +8. Capabilities + + This section defines a set of capabilities that a client or a server + MAY implement. Each peer advertises its capabilities by sending them + during an initial capabilities exchange. Each peer needs to + understand only those capabilities that it might use and MUST ignore + any capability received from the other peer that it does not require + or does not understand. + + Additional capabilities can be defined using the template in + Appendix D. Future capability definitions can be published as + standards by standards bodies or published as proprietary extensions. + + A NETCONF capability is identified with a URI. The base capabilities + are defined using URNs following the method described in RFC 3553 + [RFC3553]. Capabilities defined in this document have the following + format: + + urn:ietf:params:netconf:capability:{name}:1.x + + where {name} is the name of the capability. Capabilities are often + referenced in discussions and email using the shorthand :{name}, or + :{name}:{version} if the capability exists in multiple versions. For + example, the foo capability would have the formal name + "urn:ietf:params:netconf:capability:foo:1.0" and be called ":foo". + The shorthand form MUST NOT be used inside the protocol. + +8.1. Capabilities Exchange + + Capabilities are advertised in messages sent by each peer during + session establishment. When the NETCONF session is opened, each peer + (both client and server) MUST send a <hello> element containing a + list of that peer's capabilities. Each peer MUST send at least the + + + + +Enns, et al. Standards Track [Page 51] + +RFC 6241 NETCONF Protocol June 2011 + + + base NETCONF capability, "urn:ietf:params:netconf:base:1.1". A peer + MAY include capabilities for previous NETCONF versions, to indicate + that it supports multiple protocol versions. + + Both NETCONF peers MUST verify that the other peer has advertised a + common protocol version. When comparing protocol version capability + URIs, only the base part is used, in the event any parameters are + encoded at the end of the URI string. If no protocol version + capability in common is found, the NETCONF peer MUST NOT continue the + session. If more than one protocol version URI in common is present, + then the highest numbered (most recent) protocol version MUST be used + by both peers. + + A server sending the <hello> element MUST include a <session-id> + element containing the session ID for this NETCONF session. A client + sending the <hello> element MUST NOT include a <session-id> element. + + A server receiving a <hello> message with a <session-id> element MUST + terminate the NETCONF session. Similarly, a client that does not + receive a <session-id> element in the server's <hello> message MUST + terminate the NETCONF session (without first sending a + <close-session>). + + In the following example, a server advertises the base NETCONF + capability, one NETCONF capability defined in the base NETCONF + document, and one implementation-specific capability. + + <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <capabilities> + <capability> + urn:ietf:params:netconf:base:1.1 + </capability> + <capability> + urn:ietf:params:netconf:capability:startup:1.0 + </capability> + <capability> + http://example.net/router/2.3/myfeature + </capability> + </capabilities> + <session-id>4</session-id> + </hello> + + Each peer sends its <hello> element simultaneously as soon as the + connection is open. A peer MUST NOT wait to receive the capability + set from the other side before sending its own set. + + + + + + +Enns, et al. Standards Track [Page 52] + +RFC 6241 NETCONF Protocol June 2011 + + +8.2. Writable-Running Capability + +8.2.1. Description + + The :writable-running capability indicates that the device supports + direct writes to the <running> configuration datastore. In other + words, the device supports <edit-config> and <copy-config> operations + where the <running> configuration is the target. + +8.2.2. Dependencies + + None. + +8.2.3. Capability Identifier + + The :writable-running capability is identified by the following + capability string: + + urn:ietf:params:netconf:capability:writable-running:1.0 + +8.2.4. New Operations + + None. + +8.2.5. Modifications to Existing Operations + +8.2.5.1. <edit-config> + + The :writable-running capability modifies the <edit-config> operation + to accept the <running> element as a <target>. + +8.2.5.2. <copy-config> + + The :writable-running capability modifies the <copy-config> operation + to accept the <running> element as a <target>. + +8.3. Candidate Configuration Capability + +8.3.1. Description + + The candidate configuration capability, :candidate, indicates that + the device supports a candidate configuration datastore, which is + used to hold configuration data that can be manipulated without + impacting the device's current configuration. The candidate + configuration is a full configuration data set that serves as a work + place for creating and manipulating configuration data. Additions, + deletions, and changes can be made to this data to construct the + + + + +Enns, et al. Standards Track [Page 53] + +RFC 6241 NETCONF Protocol June 2011 + + + desired configuration data. A <commit> operation MAY be performed at + any time that causes the device's running configuration to be set to + the value of the candidate configuration. + + The <commit> operation effectively sets the running configuration to + the current contents of the candidate configuration. While it could + be modeled as a simple copy, it is done as a distinct operation for a + number of reasons. In keeping high-level concepts as first-class + operations, we allow developers to see more clearly both what the + client is requesting and what the server must perform. This keeps + the intentions more obvious, the special cases less complex, and the + interactions between operations more straightforward. For example, + the :confirmed-commit:1.1 capability (Section 8.4) would make no + sense as a "copy confirmed" operation. + + The candidate configuration can be shared among multiple sessions. + Unless a client has specific information that the candidate + configuration is not shared, it MUST assume that other sessions are + able to modify the candidate configuration at the same time. It is + therefore prudent for a client to lock the candidate configuration + before modifying it. + + The client can discard any uncommitted changes to the candidate + configuration by executing the <discard-changes> operation. This + operation reverts the contents of the candidate configuration to the + contents of the running configuration. + +8.3.2. Dependencies + + None. + +8.3.3. Capability Identifier + + The :candidate capability is identified by the following capability + string: + + urn:ietf:params:netconf:capability:candidate:1.0 + +8.3.4. New Operations + +8.3.4.1. <commit> + + Description: + + When the candidate configuration's content is complete, the + configuration data can be committed, publishing the data set to + the rest of the device and requesting the device to conform to + the behavior described in the new configuration. + + + +Enns, et al. Standards Track [Page 54] + +RFC 6241 NETCONF Protocol June 2011 + + + To commit the candidate configuration as the device's new + current configuration, use the <commit> operation. + + The <commit> operation instructs the device to implement the + configuration data contained in the candidate configuration. + If the device is unable to commit all of the changes in the + candidate configuration datastore, then the running + configuration MUST remain unchanged. If the device does + succeed in committing, the running configuration MUST be + updated with the contents of the candidate configuration. + + If the running or candidate configuration is currently locked + by a different session, the <commit> operation MUST fail with + an <error-tag> value of "in-use". + + If the system does not have the :candidate capability, the + <commit> operation is not available. + + Positive Response: + + If the device was able to satisfy the request, an <rpc-reply> + is sent that contains an <ok> element. + + Negative Response: + + An <rpc-error> element is included in the <rpc-reply> if the + request cannot be completed for any reason. + + Example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <commit/> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + +8.3.4.2. <discard-changes> + + If the client decides that the candidate configuration is not to be + committed, the <discard-changes> operation can be used to revert the + candidate configuration to the current running configuration. + + + + + + +Enns, et al. Standards Track [Page 55] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <discard-changes/> + </rpc> + + This operation discards any uncommitted changes by resetting the + candidate configuration with the content of the running + configuration. + +8.3.5. Modifications to Existing Operations + +8.3.5.1. <get-config>, <edit-config>, <copy-config>, and <validate> + + The candidate configuration can be used as a source or target of any + <get-config>, <edit-config>, <copy-config>, or <validate> operation + as a <source> or <target> parameter. The <candidate> element is used + to indicate the candidate configuration: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get-config> + <source> + <candidate/> + </source> + </get-config> + </rpc> + +8.3.5.2. <lock> and <unlock> + + The candidate configuration can be locked using the <lock> operation + with the <candidate> element as the <target> parameter: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <lock> + <target> + <candidate/> + </target> + </lock> + </rpc> + + Similarly, the candidate configuration is unlocked using the + <candidate> element as the <target> parameter: + + + + + + + + +Enns, et al. Standards Track [Page 56] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <unlock> + <target> + <candidate/> + </target> + </unlock> + </rpc> + + When a client fails with outstanding changes to the candidate + configuration, recovery can be difficult. To facilitate easy + recovery, any outstanding changes are discarded when the lock is + released, whether explicitly with the <unlock> operation or + implicitly from session failure. + +8.4. Confirmed Commit Capability + +8.4.1. Description + + The :confirmed-commit:1.1 capability indicates that the server will + support the <cancel-commit> operation and the <confirmed>, + <confirm-timeout>, <persist>, and <persist-id> parameters for the + <commit> operation. See Section 8.3 for further details on the + <commit> operation. + + A confirmed <commit> operation MUST be reverted if a confirming + commit is not issued within the timeout period (by default 600 + seconds = 10 minutes). The confirming commit is a <commit> operation + without the <confirmed> parameter. The timeout period can be + adjusted with the <confirm-timeout> parameter. If a follow-up + confirmed <commit> operation is issued before the timer expires, the + timer is reset to the new value (600 seconds by default). Both the + confirming commit and a follow-up confirmed <commit> operation MAY + introduce additional changes to the configuration. + + If the <persist> element is not given in the confirmed commit + operation, any follow-up commit and the confirming commit MUST be + issued on the same session that issued the confirmed commit. If the + <persist> element is given in the confirmed <commit> operation, a + follow-up commit and the confirming commit can be given on any + session, and they MUST include a <persist-id> element with a value + equal to the given value of the <persist> element. + + If the server also advertises the :startup capability, a + <copy-config> from running to startup is also necessary to save the + changes to startup. + + + + + +Enns, et al. Standards Track [Page 57] + +RFC 6241 NETCONF Protocol June 2011 + + + If the session issuing the confirmed commit is terminated for any + reason before the confirm timeout expires, the server MUST restore + the configuration to its state before the confirmed commit was + issued, unless the confirmed commit also included a <persist> + element. + + If the device reboots for any reason before the confirm timeout + expires, the server MUST restore the configuration to its state + before the confirmed commit was issued. + + If a confirming commit is not issued, the device will revert its + configuration to the state prior to the issuance of the confirmed + commit. To cancel a confirmed commit and revert changes without + waiting for the confirm timeout to expire, the client can explicitly + restore the configuration to its state before the confirmed commit + was issued, by using the <cancel-commit> operation. + + For shared configurations, this feature can cause other configuration + changes (for example, via other NETCONF sessions) to be inadvertently + altered or removed, unless the configuration locking feature is used + (in other words, the lock is obtained before the <edit-config> + operation is started). Therefore, it is strongly suggested that in + order to use this feature with shared configuration datastores, + configuration locking SHOULD also be used. + + Version 1.0 of this capability was defined in [RFC4741]. Version 1.1 + is defined in this document, and extends version 1.0 by adding a new + operation, <cancel-commit>, and two new optional parameters, + <persist> and <persist-id>. For backwards compatibility with old + clients, servers conforming to this specification MAY advertise + version 1.0 in addition to version 1.1. + +8.4.2. Dependencies + + The :confirmed-commit:1.1 capability is only relevant if the + :candidate capability is also supported. + +8.4.3. Capability Identifier + + The :confirmed-commit:1.1 capability is identified by the following + capability string: + + urn:ietf:params:netconf:capability:confirmed-commit:1.1 + + + + + + + + +Enns, et al. Standards Track [Page 58] + +RFC 6241 NETCONF Protocol June 2011 + + +8.4.4. New Operations + +8.4.4.1. <cancel-commit> + + Description: + + Cancels an ongoing confirmed commit. If the <persist-id> + parameter is not given, the <cancel-commit> operation MUST be + issued on the same session that issued the confirmed commit. + + Parameters: + + persist-id: + + Cancels a persistent confirmed commit. The value MUST be + equal to the value given in the <persist> parameter to the + <commit> operation. If the value does not match, the + operation fails with an "invalid-value" error. + + Positive Response: + + If the device was able to satisfy the request, an <rpc-reply> + is sent that contains an <ok> element. + + Negative Response: + + An <rpc-error> element is included in the <rpc-reply> if the + request cannot be completed for any reason. + + Example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <commit> + <confirmed/> + </commit> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + + <rpc message-id="102" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <cancel-commit/> + </rpc> + + + + +Enns, et al. Standards Track [Page 59] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc-reply message-id="102" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + +8.4.5. Modifications to Existing Operations + +8.4.5.1. <commit> + + The :confirmed-commit:1.1 capability allows 4 additional parameters + to the <commit> operation. + + Parameters: + + confirmed: + + Perform a confirmed <commit> operation. + + confirm-timeout: + + Timeout period for confirmed commit, in seconds. If + unspecified, the confirm timeout defaults to 600 seconds. + + persist: + + Make the confirmed commit survive a session termination, and + set a token on the ongoing confirmed commit. + + persist-id: + + Used to issue a follow-up confirmed commit or a confirming + commit from any session, with the token from the previous + <commit> operation. + + Example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <commit> + <confirmed/> + <confirm-timeout>120</confirm-timeout> + </commit> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + + + +Enns, et al. Standards Track [Page 60] + +RFC 6241 NETCONF Protocol June 2011 + + + Example: + + <!-- start a persistent confirmed-commit --> + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <commit> + <confirmed/> + <persist>IQ,d4668</persist> + </commit> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + + <!-- confirm the persistent confirmed-commit, + possibly from another session --> + <rpc message-id="102" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <commit> + <persist-id>IQ,d4668</persist-id> + </commit> + </rpc> + + <rpc-reply message-id="102" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + +8.5. Rollback-on-Error Capability + +8.5.1. Description + + This capability indicates that the server will support the + "rollback-on-error" value in the <error-option> parameter to the + <edit-config> operation. + + For shared configurations, this feature can cause other configuration + changes (for example, via other NETCONF sessions) to be inadvertently + altered or removed, unless the configuration locking feature is used + (in other words, the lock is obtained before the <edit-config> + operation is started). Therefore, it is strongly suggested that in + order to use this feature with shared configuration datastores, + configuration locking also be used. + + + + + + +Enns, et al. Standards Track [Page 61] + +RFC 6241 NETCONF Protocol June 2011 + + +8.5.2. Dependencies + + None. + +8.5.3. Capability Identifier + + The :rollback-on-error capability is identified by the following + capability string: + + urn:ietf:params:netconf:capability:rollback-on-error:1.0 + +8.5.4. New Operations + + None. + +8.5.5. Modifications to Existing Operations + +8.5.5.1. <edit-config> + + The :rollback-on-error capability allows the "rollback-on-error" + value to the <error-option> parameter on the <edit-config> operation. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <edit-config> + <target> + <running/> + </target> + <error-option>rollback-on-error</error-option> + <config> + <top xmlns="http://example.com/schema/1.2/config"> + <interface> + <name>Ethernet0/0</name> + <mtu>100000</mtu> + </interface> + </top> + </config> + </edit-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + + + + + + + +Enns, et al. Standards Track [Page 62] + +RFC 6241 NETCONF Protocol June 2011 + + +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 + the device. + + If this capability is advertised, the device supports the <validate> + protocol operation and checks at least for syntax errors. In + addition, this capability supports the <test-option> parameter to the + <edit-config> operation and, when it is provided, checks at least for + syntax errors. + + Version 1.0 of this capability was defined in [RFC4741]. Version 1.1 + is defined in this document, and extends version 1.0 by adding a new + value, "test-only", to the <test-option> parameter of the + <edit-config> operation. For backwards compatibility with old + clients, servers conforming to this specification MAY advertise + version 1.0 in addition to version 1.1. + +8.6.2. Dependencies + + None. + +8.6.3. Capability Identifier + + The :validate:1.1 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. <validate> + + Description: + + This protocol operation validates the contents of the specified + configuration. + + Parameters: + + source: + + Name of the configuration datastore to validate, such as + <candidate>, or the <config> element containing the complete + configuration to validate. + + + +Enns, et al. Standards Track [Page 63] + +RFC 6241 NETCONF Protocol June 2011 + + + Positive Response: + + If the device was able to satisfy the request, an <rpc-reply> + is sent that contains an <ok> element. + + Negative Response: + + An <rpc-error> element is included in the <rpc-reply> if the + request cannot be completed for any reason. + + A <validate> operation can fail for a number of reasons, such + as syntax errors, missing parameters, references to undefined + configuration data, or any other violations of rules + established by the underlying data model. + + Example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <validate> + <source> + <candidate/> + </source> + </validate> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <ok/> + </rpc-reply> + +8.6.5. Modifications to Existing Operations + +8.6.5.1. <edit-config> + + The :validate:1.1 capability modifies the <edit-config> operation to + accept the <test-option> 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 + be automatically copied to the startup configuration. An explicit + <copy-config> operation from the <running> to the <startup> is used + to update the startup configuration to the current contents of the + + + +Enns, et al. Standards Track [Page 64] + +RFC 6241 NETCONF Protocol June 2011 + + + running configuration. NETCONF protocol operations refer to the + startup datastore using the <startup> element. + +8.7.2. Dependencies + + None. + +8.7.3. Capability Identifier + + The :startup capability is identified by the following capability + string: + + urn:ietf:params:netconf:capability:startup:1.0 + +8.7.4. New Operations + + None. + +8.7.5. Modifications to Existing Operations + +8.7.5.1. General + + The :startup capability adds the <startup/> configuration datastore + to arguments of several NETCONF operations. The server MUST support + the following additional values: + + +--------------------+--------------------------+-------------------+ + | Operation | Parameters | Notes | + +--------------------+--------------------------+-------------------+ + | <get-config> | <source> | | + | | | | + | <copy-config> | <source> <target> | | + | | | | + | <lock> | <target> | | + | | | | + | <unlock> | <target> | | + | | | | + | <validate> | <source> | If :validate:1.1 | + | | | is advertised | + | | | | + | <delete-config> | <target> | Resets the device | + | | | to its factory | + | | | defaults | + +--------------------+--------------------------+-------------------+ + + To save the startup configuration, use the <copy-config> operation to + copy the <running> configuration datastore to the <startup> + configuration datastore. + + + +Enns, et al. Standards Track [Page 65] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <copy-config> + <target> + <startup/> + </target> + <source> + <running/> + </source> + </copy-config> + </rpc> + +8.8. URL Capability + +8.8.1. Description + + The NETCONF peer has the ability to accept the <url> element in + <source> and <target> parameters. The capability is further + identified by URL arguments indicating the URL schemes supported. + +8.8.2. Dependencies + + None. + +8.8.3. Capability Identifier + + The :url capability is identified by the following capability string: + + urn:ietf:params:netconf:capability:url:1.0?scheme={name,...} + + The :url capability URI MUST contain a "scheme" argument assigned a + comma-separated list of scheme names indicating which schemes the + NETCONF peer supports. For example: + + urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file + +8.8.4. New Operations + + None. + +8.8.5. Modifications to Existing Operations + +8.8.5.1. <edit-config> + + The :url capability modifies the <edit-config> operation to accept + the <url> element as an alternative to the <config> parameter. + + + + + +Enns, et al. Standards Track [Page 66] + +RFC 6241 NETCONF Protocol June 2011 + + + The file that the url refers to contains the configuration data + hierarchy to be modified, encoded in XML under the element <config> + in the "urn:ietf:params:xml:ns:netconf:base:1.0" namespace. + +8.8.5.2. <copy-config> + + The :url capability modifies the <copy-config> operation to accept + the <url> element as the value of the <source> and the <target> + parameters. + + The file that the url refers to contains the complete datastore, + encoded in XML under the element <config> in the + "urn:ietf:params:xml:ns:netconf:base:1.0" namespace. + +8.8.5.3. <delete-config> + + The :url capability modifies the <delete-config> operation to accept + the <url> element as the value of the <target> parameters. + +8.8.5.4. <validate> + + The :url capability modifies the <validate> operation to accept the + <url> element as the value of the <source> parameter. + +8.9. XPath Capability + +8.9.1. Description + + The XPath capability indicates that the NETCONF peer supports the use + of XPath expressions in the <filter> element. XPath is described in + [W3C.REC-xpath-19991116]. + + The data model used in the XPath expression is the same as that used + in XPath 1.0 [W3C.REC-xpath-19991116], with the same extension for + root node children as used by XSLT 1.0 ([W3C.REC-xslt-19991116], + 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. + + + +Enns, et al. Standards Track [Page 67] + +RFC 6241 NETCONF Protocol June 2011 + + + o The context node is the root node. + + The XPath expression MUST return a node set. If it does not return a + 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. Specific data instances are not duplicated in the + response. + +8.9.2. Dependencies + + None. + +8.9.3. Capability Identifier + + The :xpath capability is identified by the following capability + string: + + urn:ietf:params:netconf:capability:xpath:1.0 + +8.9.4. New Operations + + None. + +8.9.5. Modifications to Existing Operations + +8.9.5.1. <get-config> and <get> + + The :xpath capability modifies the <get> and <get-config> operations + to accept the value "xpath" in the "type" attribute of the <filter> + element. When the "type" attribute is set to "xpath", a "select" + attribute MUST be present on the <filter> element. The "select" + attribute will be treated as an XPath expression and used to filter + the returned data. The <filter> element itself MUST be empty in this + case. + + The XPath result for the select expression MUST be a node-set. Each + node in the node-set MUST correspond to a node in the 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 <data> element returned in the reply contains only fully + specified subtrees, according to the underlying data model. + + + + +Enns, et al. Standards Track [Page 68] + +RFC 6241 NETCONF Protocol June 2011 + + + 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. + + For example: + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <get-config> + <source> + <running/> + </source> + <!-- get the user named fred --> + <filter xmlns:t="http://example.com/schema/1.2/config" + type="xpath" + select="/t:top/t:users/t:user[t:name='fred']"/> + </get-config> + </rpc> + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <data> + <top xmlns="http://example.com/schema/1.2/config"> + <users> + <user> + <name>fred</name> + <company-info> + <id>2</id> + </company-info> + </user> + </users> + </top> + </data> + </rpc-reply> + +9. Security Considerations + + This section provides security considerations for the base NETCONF + message layer and the base operations of the NETCONF protocol. + Security considerations for the NETCONF transports are provided in + the transport documents, and security considerations for the content + manipulated by NETCONF can be found in the documents defining data + models. + + This document does not specify an authorization scheme, as such a + scheme will likely be tied to a meta-data model or a data model. + Implementors SHOULD provide a comprehensive authorization scheme with + NETCONF. + + + +Enns, et al. Standards Track [Page 69] + +RFC 6241 NETCONF Protocol June 2011 + + + Authorization of individual users via the NETCONF server may or may + not map 1:1 to other interfaces. First, the data models might be + incompatible. Second, it could be desirable to authorize based on + mechanisms available in the Secure Transport layer (e.g., SSH, Blocks + Extensible Exchange Protocol (BEEP), etc.). + + In addition, operations on configurations could have unintended + consequences if those operations are also not guarded by the global + lock on the files or objects being operated upon. For instance, if + the running configuration is not locked, a partially complete access + list could be committed from the candidate configuration unbeknownst + to the owner of the lock of the candidate configuration, leading to + either an insecure or inaccessible device. + + Configuration information is by its very nature sensitive. Its + transmission in the clear and without integrity checking leaves + devices open to classic eavesdropping and false data injection + 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 provides 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 can be exchanged in the form of + configuration information, which is all the more reason to ensure the + security of the connection. + + That having been said, it is important to recognize that some + operations are clearly more sensitive by nature than others. For + instance, <copy-config> to the startup or running configurations is + clearly not a normal provisioning operation, whereas <edit-config> + is. Such global operations MUST disallow the changing of information + + + +Enns, et al. Standards Track [Page 70] + +RFC 6241 NETCONF Protocol June 2011 + + + that an individual does not have authorization to perform. For + example, if user A is not allowed to configure an IP address on an + interface but user B has configured an IP address on an interface in + the <candidate> configuration, user A MUST NOT be allowed to commit + the <candidate> configuration. + + Similarly, just because someone says "go write a configuration + through the URL capability at a particular place", this does not mean + that an element will do it without proper authorization. + + The <lock> operation will demonstrate that NETCONF is intended for + use by systems that have at least some trust of the administrator. + As specified in this document, it is possible to lock portions of a + configuration that a principal might not otherwise have access to. + After all, the entire configuration is locked. To mitigate this + problem, there are two approaches. It is possible to kill another + NETCONF session programmatically from within NETCONF if one knows the + session identifier of the offending session. The other possible way + to break a lock is to provide a function within the device's native + user interface. These two mechanisms suffer from a race condition + that could be ameliorated by removing the offending user from an + Authentication, Authorization, and Accounting (AAA) server. However, + such a solution is not useful in all deployment scenarios, such as + those where SSH public/private key pairs are used. + +10. IANA Considerations + +10.1. NETCONF XML Namespace + + This document registers a URI for the NETCONF XML namespace in the + IETF XML registry [RFC3688]. + + IANA has updated the following URI to reference this document. + + 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 [RFC3688]. + + IANA has updated the following URI to reference this document. + + URI: urn:ietf:params:xml:schema:netconf + + + +Enns, et al. Standards Track [Page 71] + +RFC 6241 NETCONF Protocol June 2011 + + + Registrant Contact: The IESG. + + XML: Appendix B of this document. + +10.3. NETCONF YANG Module + + This document registers a YANG module in the YANG Module Names + registry [RFC6020]. + + name: ietf-netconf + namespace: urn:ietf:params:xml:ns:netconf:base:1.0 + prefix: nc + reference: RFC 6241 + +10.4. NETCONF Capability URNs + + IANA has created and now maintains a registry "Network Configuration + Protocol (NETCONF) Capability URNs" that allocates NETCONF capability + identifiers. Additions to the registry require IETF Standards + Action. + + IANA has updated the allocations of the following capabilities to + reference this document. + + Index + Capability Identifier + ------------------------ + + :writable-running + urn:ietf:params:netconf:capability:writable-running:1.0 + + :candidate + urn:ietf:params:netconf:capability:candidate:1.0 + + :rollback-on-error + urn:ietf:params:netconf:capability:rollback-on-error:1.0 + + :startup + urn:ietf:params:netconf:capability:startup:1.0 + + :url + urn:ietf:params:netconf:capability:url:1.0 + + :xpath + urn:ietf:params:netconf:capability:xpath:1.0 + + + + + + +Enns, et al. Standards Track [Page 72] + +RFC 6241 NETCONF Protocol June 2011 + + + IANA has added the following capabilities to the registry: + + Index + Capability Identifier + ------------------------ + + :base:1.1 + urn:ietf:params:netconf:base:1.1 + + :confirmed-commit:1.1 + urn:ietf:params:netconf:capability:confirmed-commit:1.1 + + :validate:1.1 + urn:ietf:params:netconf:capability:validate:1.1 + +11. Contributors + + In addition to the editors, this document was written by: + + Ken Crozier, Cisco Systems + + Ted Goddard, IceSoft + + Eliot Lear, Cisco Systems + + Phil Shafer, Juniper Networks + + Steve Waldbusser + + Margaret Wasserman, Painless Security, LLC + +12. Acknowledgements + + 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, Glenn Waters, David Perkins, Weijing Chen, Simon Leinen, + Keith Allen, Dave Harrington, Ladislav Lhotka, Tom Petch, and Kent + Watsen for all of their valuable advice. + + + + + + + + + + + +Enns, et al. Standards Track [Page 73] + +RFC 6241 NETCONF Protocol June 2011 + + +13. References + +13.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An + IETF URN Sub-namespace for Registered Protocol + Parameters", BCP 73, RFC 3553, June 2003. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + January 2004. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [RFC5717] Lengyel, B. and M. Bjorklund, "Partial Lock Remote + Procedure Call (RPC) for NETCONF", RFC 5717, + December 2009. + + [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the + Network Configuration Protocol (NETCONF)", RFC 6020, + October 2010. + + [RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, + October 2010. + + [RFC6242] Wasserman, M., "Using the NETCONF Configuration Protocol + over Secure Shell (SSH)", RFC 6242, June 2011. + + [W3C.REC-xml-20001006] + Sperberg-McQueen, C., Bray, T., Paoli, J., and E. Maler, + "Extensible Markup Language (XML) 1.0 (Second Edition)", + World Wide Web Consortium REC-xml-20001006, October 2000, + <http://www.w3.org/TR/2000/REC-xml-20001006>. + + [W3C.REC-xpath-19991116] + DeRose, S. and J. Clark, "XML Path Language (XPath) + Version 1.0", World Wide Web Consortium + Recommendation REC-xpath-19991116, November 1999, + <http://www.w3.org/TR/1999/REC-xpath-19991116>. + + + + + +Enns, et al. Standards Track [Page 74] + +RFC 6241 NETCONF Protocol June 2011 + + +13.2. Informative References + + [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, + "Remote Authentication Dial In User Service (RADIUS)", + RFC 2865, June 2000. + + [RFC3470] 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. + + [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) + Protocol Architecture", RFC 4251, January 2006. + + [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, + December 2006. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, August 2008. + + [W3C.REC-xslt-19991116] + Clark, J., "XSL Transformations (XSLT) Version 1.0", World + Wide Web Consortium Recommendation REC-xslt-19991116, + November 1999, + <http://www.w3.org/TR/1999/REC-xslt-19991116>. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Enns, et al. Standards Track [Page 75] + +RFC 6241 NETCONF Protocol June 2011 + + +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 is 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: <bad-attribute> : name of the missing attribute + <bad-element> : name of the element that is supposed + to contain the missing attribute + Description: An expected attribute is missing. + + error-tag: bad-attribute + error-type: rpc, protocol, application + error-severity: error + error-info: <bad-attribute> : name of the attribute w/ bad value + <bad-element> : 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. + + + + + + + +Enns, et al. Standards Track [Page 76] + +RFC 6241 NETCONF Protocol June 2011 + + + error-tag: unknown-attribute + error-type: rpc, protocol, application + error-severity: error + error-info: <bad-attribute> : name of the unexpected attribute + <bad-element> : 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: <bad-element> : name of the missing element + Description: An expected element is missing. + + error-tag: bad-element + error-type: protocol, application + error-severity: error + error-info: <bad-element> : 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: <bad-element> : name of the unexpected element + Description: An unexpected element is present. + + error-tag: unknown-namespace + error-type: protocol, application + error-severity: error + error-info: <bad-element> : name of the element that contains + the unexpected namespace + <bad-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. + + + + + + + + + + +Enns, et al. Standards Track [Page 77] + +RFC 6241 NETCONF Protocol June 2011 + + + error-tag: lock-denied + error-type: protocol + error-severity: error + error-info: <session-id> : 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 + 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 roll back 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. + + + +Enns, et al. Standards Track [Page 78] + +RFC 6241 NETCONF Protocol June 2011 + + + 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 + error-type: application + error-severity: error + error-info: <ok-element> : 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 + <error-info> container. + + <err-element> : 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 + <error-info> container. + + <noop-element> : 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 + <error-info> container. + + Description: This error-tag is obsolete, and SHOULD NOT be sent + by servers conforming to this document. + + 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 (<ok-element>), failed (<bad-element>), + or not been attempted (<noop-element>). + + + + + + + + + + + +Enns, et al. Standards Track [Page 79] + +RFC 6241 NETCONF Protocol June 2011 + + + error-tag: malformed-message + error-type: rpc + error-severity: error + error-info: none + Description: A message could not be handled because it failed to + be parsed correctly. For example, the message is not + well-formed XML or it uses an invalid character set. + + This error-tag is new in :base:1.1 and MUST NOT be + sent to old clients. + +Appendix B. XML Schema for NETCONF Messages Layer + + This section is normative. + + <CODE BEGINS> file "netconf.xsd" + + <?xml version="1.0" encoding="UTF-8"?> + <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" + targetNamespace="urn:ietf:params:xml:ns:netconf:base:1.0" + elementFormDefault="qualified" + attributeFormDefault="unqualified" + xml:lang="en" + version="1.1"> + + <xs:annotation> + <xs:documentation> + This schema defines the syntax for the NETCONF Messages layer + messages 'hello', 'rpc', and 'rpc-reply'. + </xs:documentation> + </xs:annotation> + + <!-- + import standard XML definitions + --> + <xs:import namespace="http://www.w3.org/XML/1998/namespace" + schemaLocation="http://www.w3.org/2001/xml.xsd"> + <xs:annotation> + <xs:documentation> + This import accesses the xml: attribute groups for the + xml:lang as declared on the error-message element. + </xs:documentation> + </xs:annotation> + </xs:import> + <!-- + message-id attribute + --> + + + +Enns, et al. Standards Track [Page 80] + +RFC 6241 NETCONF Protocol June 2011 + + + <xs:simpleType name="messageIdType"> + <xs:restriction base="xs:string"> + <xs:maxLength value="4095"/> + </xs:restriction> + </xs:simpleType> + <!-- + Types used for session-id + --> + <xs:simpleType name="SessionId"> + <xs:restriction base="xs:unsignedInt"> + <xs:minInclusive value="1"/> + </xs:restriction> + </xs:simpleType> + <xs:simpleType name="SessionIdOrZero"> + <xs:restriction base="xs:unsignedInt"/> + </xs:simpleType> + <!-- + <rpc> element + --> + <xs:complexType name="rpcType"> + <xs:sequence> + <xs:element ref="rpcOperation"/> + </xs:sequence> + <xs:attribute name="message-id" type="messageIdType" + use="required"/> + <!-- + Arbitrary attributes can be supplied with <rpc> element. + --> + <xs:anyAttribute processContents="lax"/> + </xs:complexType> + <xs:element name="rpc" type="rpcType"/> + <!-- + data types and elements used to construct rpc-errors + --> + <xs:simpleType name="ErrorType"> + <xs:restriction base="xs:string"> + <xs:enumeration value="transport"/> + <xs:enumeration value="rpc"/> + <xs:enumeration value="protocol"/> + <xs:enumeration value="application"/> + </xs:restriction> + </xs:simpleType> + <xs:simpleType name="ErrorTag"> + <xs:restriction base="xs:string"> + <xs:enumeration value="in-use"/> + <xs:enumeration value="invalid-value"/> + <xs:enumeration value="too-big"/> + <xs:enumeration value="missing-attribute"/> + + + +Enns, et al. Standards Track [Page 81] + +RFC 6241 NETCONF Protocol June 2011 + + + <xs:enumeration value="bad-attribute"/> + <xs:enumeration value="unknown-attribute"/> + <xs:enumeration value="missing-element"/> + <xs:enumeration value="bad-element"/> + <xs:enumeration value="unknown-element"/> + <xs:enumeration value="unknown-namespace"/> + <xs:enumeration value="access-denied"/> + <xs:enumeration value="lock-denied"/> + <xs:enumeration value="resource-denied"/> + <xs:enumeration value="rollback-failed"/> + <xs:enumeration value="data-exists"/> + <xs:enumeration value="data-missing"/> + <xs:enumeration value="operation-not-supported"/> + <xs:enumeration value="operation-failed"/> + <xs:enumeration value="partial-operation"/> + <xs:enumeration value="malformed-message"/> + </xs:restriction> + </xs:simpleType> + <xs:simpleType name="ErrorSeverity"> + <xs:restriction base="xs:string"> + <xs:enumeration value="error"/> + <xs:enumeration value="warning"/> + </xs:restriction> + </xs:simpleType> + <xs:complexType name="errorInfoType"> + <xs:sequence> + <xs:choice> + <xs:element name="session-id" type="SessionIdOrZero"/> + <xs:sequence minOccurs="0" maxOccurs="unbounded"> + <xs:sequence> + <xs:element name="bad-attribute" type="xs:QName" + minOccurs="0" maxOccurs="1"/> + <xs:element name="bad-element" type="xs:QName" + minOccurs="0" maxOccurs="1"/> + <xs:element name="ok-element" type="xs:QName" + minOccurs="0" maxOccurs="1"/> + <xs:element name="err-element" type="xs:QName" + minOccurs="0" maxOccurs="1"/> + <xs:element name="noop-element" type="xs:QName" + minOccurs="0" maxOccurs="1"/> + <xs:element name="bad-namespace" type="xs:string" + minOccurs="0" maxOccurs="1"/> + </xs:sequence> + </xs:sequence> + </xs:choice> + <!-- elements from any other namespace are also allowed + to follow the NETCONF elements --> + <xs:any namespace="##other" processContents="lax" + + + +Enns, et al. Standards Track [Page 82] + +RFC 6241 NETCONF Protocol June 2011 + + + minOccurs="0" maxOccurs="unbounded"/> + </xs:sequence> + </xs:complexType> + <xs:complexType name="rpcErrorType"> + <xs:sequence> + <xs:element name="error-type" type="ErrorType"/> + <xs:element name="error-tag" type="ErrorTag"/> + <xs:element name="error-severity" type="ErrorSeverity"/> + <xs:element name="error-app-tag" type="xs:string" + minOccurs="0"/> + <xs:element name="error-path" type="xs:string" minOccurs="0"/> + <xs:element name="error-message" minOccurs="0"> + <xs:complexType> + <xs:simpleContent> + <xs:extension base="xs:string"> + <xs:attribute ref="xml:lang" use="optional"/> + </xs:extension> + </xs:simpleContent> + </xs:complexType> + </xs:element> + <xs:element name="error-info" type="errorInfoType" + minOccurs="0"/> + </xs:sequence> + </xs:complexType> + <!-- + operation attribute used in <edit-config> + --> + <xs:simpleType name="editOperationType"> + <xs:restriction base="xs:string"> + <xs:enumeration value="merge"/> + <xs:enumeration value="replace"/> + <xs:enumeration value="create"/> + <xs:enumeration value="delete"/> + <xs:enumeration value="remove"/> + </xs:restriction> + </xs:simpleType> + <xs:attribute name="operation" type="editOperationType"/> + <!-- + <rpc-reply> element + --> + <xs:complexType name="rpcReplyType"> + <xs:choice> + <xs:element name="ok"/> + <xs:sequence> + <xs:element ref="rpc-error" + minOccurs="0" maxOccurs="unbounded"/> + <xs:element ref="rpcResponse" + minOccurs="0" maxOccurs="unbounded"/> + + + +Enns, et al. Standards Track [Page 83] + +RFC 6241 NETCONF Protocol June 2011 + + + </xs:sequence> + </xs:choice> + <xs:attribute name="message-id" type="messageIdType" + use="optional"/> + <!-- + Any attributes supplied with <rpc> element must be returned + on <rpc-reply>. + --> + <xs:anyAttribute processContents="lax"/> + </xs:complexType> + <xs:element name="rpc-reply" type="rpcReplyType"/> + <!-- + <rpc-error> element + --> + <xs:element name="rpc-error" type="rpcErrorType"/> + <!-- + rpcOperationType: used as a base type for all + NETCONF operations + --> + <xs:complexType name="rpcOperationType"/> + <xs:element name="rpcOperation" type="rpcOperationType" + abstract="true"/> + <!-- + rpcResponseType: used as a base type for all + NETCONF responses + --> + <xs:complexType name="rpcResponseType"/> + <xs:element name="rpcResponse" type="rpcResponseType" + abstract="true"/> + <!-- + <hello> element + --> + <xs:element name="hello"> + <xs:complexType> + <xs:sequence> + <xs:element name="capabilities"> + <xs:complexType> + <xs:sequence> + <xs:element name="capability" type="xs:anyURI" + maxOccurs="unbounded"/> + </xs:sequence> + </xs:complexType> + </xs:element> + <xs:element name="session-id" type="SessionId" + minOccurs="0"/> + + + + + + +Enns, et al. Standards Track [Page 84] + +RFC 6241 NETCONF Protocol June 2011 + + + </xs:sequence> + </xs:complexType> + </xs:element> + </xs:schema> + + <CODE ENDS> + +Appendix C. YANG Module for NETCONF Protocol Operations + + This section is normative. + + The ietf-netconf YANG module imports typedefs from [RFC6021]. + + <CODE BEGINS> file "ietf-netconf@2011-06-01.yang" + + module ietf-netconf { + + // the namespace for NETCONF XML definitions is unchanged + // from RFC 4741, which this document replaces + 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 + "WG Web: <http://tools.ietf.org/wg/netconf/> + WG List: <netconf@ietf.org> + + WG Chair: Bert Wijnen + <bertietf@bwijnen.net> + + WG Chair: Mehmet Ersue + <mehmet.ersue@nsn.com> + + Editor: Martin Bjorklund + <mbj@tail-f.com> + + Editor: Juergen Schoenwaelder + <j.schoenwaelder@jacobs-university.de> + + Editor: Andy Bierman + <andy.bierman@brocade.com>"; + + + +Enns, et al. Standards Track [Page 85] + +RFC 6241 NETCONF Protocol June 2011 + + + description + "NETCONF Protocol Data Types and Protocol Operations. + + Copyright (c) 2011 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, is permitted pursuant to, and subject + to the license terms contained in, the Simplified BSD License + set forth in Section 4.c of the IETF Trust's Legal Provisions + Relating to IETF Documents + (http://trustee.ietf.org/license-info). + + This version of this YANG module is part of RFC 6241; see + the RFC itself for full legal notices."; + revision 2011-06-01 { + description + "Initial revision"; + reference + "RFC 6241: Network Configuration Protocol"; + } + + extension get-filter-element-attributes { + description + "If this extension is present within an 'anyxml' + statement named 'filter', which must be conceptually + defined within the RPC input section for the <get> + and <get-config> protocol 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: + + 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 { + + + +Enns, et al. Standards Track [Page 86] + +RFC 6241 NETCONF Protocol June 2011 + + + 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."; + reference "RFC 6241, 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 6241, Section 8.3"; + } + + feature confirmed-commit { + if-feature candidate; + description + "NETCONF :confirmed-commit:1.1 capability; + If the server advertises the :confirmed-commit: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 6241, 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."; + reference "RFC 6241, Section 8.5"; + } + + feature validate { + 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."; + + + +Enns, et al. Standards Track [Page 87] + +RFC 6241 NETCONF Protocol June 2011 + + + reference "RFC 6241, 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 6241, 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 6241, Section 8.8"; + } + + feature xpath { + description + "NETCONF :xpath capability; + If the server advertises the :xpath + capability for a session, then this feature must + also be enabled for that session. Otherwise, + this feature must not be enabled."; + reference "RFC 6241, 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"; + } + + + +Enns, et al. Standards Track [Page 88] + +RFC 6241 NETCONF Protocol June 2011 + + + typedef error-tag-type { + type enumeration { + enum in-use { + description + "The request requires a resource that + already is in use."; + } + enum invalid-value { + description + "The request specifies an unacceptable value for one + or more parameters."; + } + enum too-big { + description + "The request or response (that would be generated) is + too large for the implementation to handle."; + } + enum missing-attribute { + description + "An expected attribute is missing."; + } + enum bad-attribute { + description + "An attribute value is not correct; e.g., wrong type, + out of range, pattern mismatch."; + } + enum unknown-attribute { + description + "An unexpected attribute is present."; + } + enum missing-element { + description + "An expected element is missing."; + } + enum bad-element { + description + "An element value is not correct; e.g., wrong type, + out of range, pattern mismatch."; + } + enum unknown-element { + description + "An unexpected element is present."; + } + enum unknown-namespace { + description + "An unexpected namespace is present."; + } + enum access-denied { + + + +Enns, et al. Standards Track [Page 89] + +RFC 6241 NETCONF Protocol June 2011 + + + description + "Access to the requested protocol operation or + data model is denied because authorization failed."; + } + enum lock-denied { + description + "Access to the requested lock is denied because the + lock is currently held by another entity."; + } + enum resource-denied { + description + "Request could not be completed because of + insufficient resources."; + } + enum rollback-failed { + description + "Request to roll back some configuration change (via + rollback-on-error or <discard-changes> operations) + was not completed for some reason."; + + } + enum data-exists { + 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."; + } + enum data-missing { + 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."; + } + enum operation-not-supported { + description + "Request could not be completed because the requested + operation is not supported by this implementation."; + } + enum operation-failed { + description + "Request could not be completed because the requested + operation failed for some reason not covered by + any other error condition."; + } + enum partial-operation { + description + + + +Enns, et al. Standards Track [Page 90] + +RFC 6241 NETCONF Protocol June 2011 + + + "This error-tag is obsolete, and SHOULD NOT be sent + by servers conforming to this document."; + } + enum malformed-message { + description + "A message could not be handled because it failed to + be parsed correctly. For example, the message is not + well-formed XML or it uses an invalid character set."; + } + } + description "NETCONF Error Tag"; + reference "RFC 6241, Appendix A"; + } + + typedef error-severity-type { + type enumeration { + enum error { + description "Error severity"; + } + enum warning { + description "Warning severity"; + } + } + description "NETCONF Error Severity"; + reference "RFC 6241, Section 4.3"; + } + + typedef edit-operation-type { + type enumeration { + enum merge { + description + "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."; + } + enum replace { + description + "The configuration data identified by the element + containing this attribute replaces any related + configuration in the configuration datastore + identified by the target parameter. If no such + configuration data exists in the configuration + datastore, it is created. Unlike a + <copy-config> operation, which replaces the + entire target configuration, only the configuration + actually present in the config parameter is affected."; + + + +Enns, et al. Standards Track [Page 91] + +RFC 6241 NETCONF Protocol June 2011 + + + } + enum create { + description + "The configuration data identified by the element + containing this attribute is added to the + configuration if and only if the configuration + data does not already exist in the configuration + datastore. If the configuration data exists, an + <rpc-error> element is returned with an + <error-tag> value of 'data-exists'."; + } + enum delete { + description + "The configuration data identified by the element + containing this attribute is deleted from the + configuration if and only if the configuration + data currently exists in the configuration + datastore. If the configuration data does not + exist, an <rpc-error> element is returned with + an <error-tag> value of 'data-missing'."; + } + enum remove { + description + "The configuration data identified by the element + containing this attribute is deleted from the + configuration if the configuration + data currently exists in the configuration + datastore. If the configuration data does not + exist, the 'remove' operation is silently ignored + by the server."; + } + } + default "merge"; + description "NETCONF 'operation' attribute values"; + reference "RFC 6241, Section 7.2"; + } + + // NETCONF Standard Protocol Operations + + rpc get-config { + description + "Retrieve all or part of a specified configuration."; + + reference "RFC 6241, Section 7.1"; + + input { + container source { + description + + + +Enns, et al. Standards Track [Page 92] + +RFC 6241 NETCONF Protocol June 2011 + + + "Particular configuration to retrieve."; + + choice config-source { + mandatory true; + description + "The configuration to retrieve."; + leaf candidate { + if-feature candidate; + type empty; + description + "The candidate configuration is the config source."; + } + leaf running { + type empty; + description + "The running configuration is the config source."; + } + leaf startup { + if-feature startup; + type empty; + description + "The startup configuration is the config source. + This is optional-to-implement on the server because + not all servers will support filtering for this + datastore."; + } + } + } + + anyxml filter { + description + "Subtree or XPath filter to use."; + nc:get-filter-element-attributes; + } + } + + output { + anyxml data { + description + "Copy of the source datastore subset that matched + the filter criteria (if any). An empty data container + indicates that the request did not produce any results."; + } + } + } + + rpc edit-config { + description + + + +Enns, et al. Standards Track [Page 93] + +RFC 6241 NETCONF Protocol June 2011 + + + "The <edit-config> operation loads all or part of a specified + configuration to the specified target configuration."; + + reference "RFC 6241, Section 7.2"; + + input { + container target { + description + "Particular configuration to edit."; + + choice config-target { + mandatory true; + description + "The configuration target."; + + leaf candidate { + if-feature candidate; + type empty; + description + "The candidate configuration is the config target."; + } + leaf running { + if-feature writable-running; + type empty; + description + "The running configuration is the config source."; + } + } + } + + leaf default-operation { + type enumeration { + enum merge { + description + "The default operation is merge."; + } + enum replace { + description + "The default operation is replace."; + } + enum none { + description + "There is no default operation."; + } + } + default "merge"; + description + "The default operation to use."; + + + +Enns, et al. Standards Track [Page 94] + +RFC 6241 NETCONF Protocol June 2011 + + + } + + leaf test-option { + if-feature validate; + type enumeration { + enum test-then-set { + description + "The server will test and then set if no errors."; + } + enum set { + description + "The server will set without a test first."; + } + + enum test-only { + description + "The server will only test and not set, even + if there are no errors."; + } + } + default "test-then-set"; + description + "The test option to use."; + } + + leaf error-option { + type enumeration { + enum stop-on-error { + description + "The server will stop on errors."; + } + enum continue-on-error { + description + "The server may continue on errors."; + } + enum rollback-on-error { + description + "The server will roll back on errors. + This value can only be used if the 'rollback-on-error' + feature is supported."; + } + } + default "stop-on-error"; + description + "The error option to use."; + } + + choice edit-content { + + + +Enns, et al. Standards Track [Page 95] + +RFC 6241 NETCONF Protocol June 2011 + + + mandatory true; + description + "The content for the edit operation."; + + anyxml config { + description + "Inline Config content."; + } + leaf url { + if-feature url; + type inet:uri; + description + "URL-based config content."; + } + } + } + } + + rpc copy-config { + description + "Create or replace an entire configuration datastore with the + contents of another complete configuration datastore."; + + reference "RFC 6241, Section 7.3"; + + input { + container target { + description + "Particular configuration to copy to."; + + choice config-target { + mandatory true; + description + "The configuration target of the copy operation."; + + leaf candidate { + if-feature candidate; + type empty; + description + "The candidate configuration is the config target."; + } + leaf running { + if-feature writable-running; + type empty; + description + "The running configuration is the config target. + This is optional-to-implement on the server."; + } + + + +Enns, et al. Standards Track [Page 96] + +RFC 6241 NETCONF Protocol June 2011 + + + leaf startup { + if-feature startup; + type empty; + description + "The startup configuration is the config target."; + } + leaf url { + if-feature url; + type inet:uri; + description + "The URL-based configuration is the config target."; + } + } + } + + container source { + description + "Particular configuration to copy from."; + + choice config-source { + mandatory true; + description + "The configuration source for the copy operation."; + + leaf candidate { + if-feature candidate; + type empty; + description + "The candidate configuration is the config source."; + } + leaf running { + type empty; + description + "The running configuration is the config source."; + } + leaf startup { + if-feature startup; + type empty; + description + "The startup configuration is the config source."; + } + leaf url { + if-feature url; + type inet:uri; + description + "The URL-based configuration is the config source."; + } + anyxml config { + + + +Enns, et al. Standards Track [Page 97] + +RFC 6241 NETCONF Protocol June 2011 + + + description + "Inline Config content: <config> element. Represents + an entire configuration datastore, not + a subset of the running datastore."; + } + } + } + } + } + + rpc delete-config { + description + "Delete a configuration datastore."; + + reference "RFC 6241, Section 7.4"; + + input { + container target { + description + "Particular configuration to delete."; + + choice config-target { + mandatory true; + description + "The configuration target to delete."; + + leaf startup { + if-feature startup; + type empty; + description + "The startup configuration is the config target."; + } + leaf url { + if-feature url; + type inet:uri; + description + "The URL-based configuration is the config target."; + } + } + } + } + } + + rpc lock { + description + "The lock operation allows the client to lock the configuration + system of a device."; + + + + +Enns, et al. Standards Track [Page 98] + +RFC 6241 NETCONF Protocol June 2011 + + + reference "RFC 6241, Section 7.5"; + + input { + container target { + description + "Particular configuration to lock."; + + choice config-target { + mandatory true; + description + "The configuration target to lock."; + + leaf candidate { + if-feature candidate; + type empty; + description + "The candidate configuration is the config target."; + } + leaf running { + type empty; + description + "The running configuration is the config target."; + } + leaf startup { + if-feature startup; + type empty; + description + "The startup configuration is the config target."; + } + } + } + } + } + + rpc unlock { + description + "The unlock operation is used to release a configuration lock, + previously obtained with the 'lock' operation."; + + reference "RFC 6241, Section 7.6"; + + input { + container target { + description + "Particular configuration to unlock."; + + choice config-target { + mandatory true; + + + +Enns, et al. Standards Track [Page 99] + +RFC 6241 NETCONF Protocol June 2011 + + + description + "The configuration target to unlock."; + + leaf candidate { + if-feature candidate; + type empty; + description + "The candidate configuration is the config target."; + } + leaf running { + type empty; + description + "The running configuration is the config target."; + } + leaf startup { + if-feature startup; + type empty; + description + "The startup configuration is the config target."; + } + } + } + } + } + + rpc get { + description + "Retrieve running configuration and device state information."; + + reference "RFC 6241, 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 { + anyxml data { + description + "Copy of the running datastore subset and/or state + data that matched the filter criteria (if any). + An empty data container indicates that the request did not + produce any results."; + } + + + +Enns, et al. Standards Track [Page 100] + +RFC 6241 NETCONF Protocol June 2011 + + + } + } + + rpc close-session { + description + "Request graceful termination of a NETCONF session."; + + reference "RFC 6241, Section 7.8"; + } + + rpc kill-session { + description + "Force the termination of a NETCONF session."; + + reference "RFC 6241, 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 6241, Section 8.3.4.1"; + + input { + leaf confirmed { + if-feature confirmed-commit; + type empty; + description + "Requests a confirmed commit."; + reference "RFC 6241, Section 8.3.4.1"; + } + + leaf confirm-timeout { + if-feature confirmed-commit; + type uint32 { + range "1..max"; + + + +Enns, et al. Standards Track [Page 101] + +RFC 6241 NETCONF Protocol June 2011 + + + } + units "seconds"; + default "600"; // 10 minutes + description + "The timeout interval for a confirmed commit."; + reference "RFC 6241, Section 8.3.4.1"; + } + + leaf persist { + if-feature confirmed-commit; + type string; + description + "This parameter is used to make a confirmed commit + persistent. A persistent confirmed commit is not aborted + if the NETCONF session terminates. The only way to abort + a persistent confirmed commit is to let the timer expire, + or to use the <cancel-commit> operation. + + The value of this parameter is a token that must be given + in the 'persist-id' parameter of <commit> or + <cancel-commit> operations in order to confirm or cancel + the persistent confirmed commit. + + The token should be a random string."; + reference "RFC 6241, Section 8.3.4.1"; + } + + leaf persist-id { + if-feature confirmed-commit; + type string; + description + "This parameter is given in order to commit a persistent + confirmed commit. The value must be equal to the value + given in the 'persist' parameter to the <commit> operation. + If it does not match, the operation fails with an + 'invalid-value' error."; + reference "RFC 6241, Section 8.3.4.1"; + } + + } + } + + rpc discard-changes { + if-feature candidate; + + description + "Revert the candidate configuration to the current + running configuration."; + + + +Enns, et al. Standards Track [Page 102] + +RFC 6241 NETCONF Protocol June 2011 + + + reference "RFC 6241, Section 8.3.4.2"; + } + + rpc cancel-commit { + if-feature confirmed-commit; + description + "This operation is used to cancel an ongoing confirmed commit. + If the confirmed commit is persistent, the parameter + 'persist-id' must be given, and it must match the value of the + 'persist' parameter."; + reference "RFC 6241, Section 8.4.4.1"; + + input { + leaf persist-id { + type string; + description + "This parameter is given in order to cancel a persistent + confirmed commit. The value must be equal to the value + given in the 'persist' parameter to the <commit> operation. + If it does not match, the operation fails with an + 'invalid-value' error."; + } + } + } + + rpc validate { + if-feature validate; + + description + "Validates the contents of the specified configuration."; + + reference "RFC 6241, Section 8.6.4.1"; + + input { + container source { + description + "Particular configuration to validate."; + + choice config-source { + mandatory true; + description + "The configuration source to validate."; + + leaf candidate { + if-feature candidate; + type empty; + description + "The candidate configuration is the config source."; + + + +Enns, et al. Standards Track [Page 103] + +RFC 6241 NETCONF Protocol June 2011 + + + } + leaf running { + type empty; + description + "The running configuration is the config source."; + } + leaf startup { + if-feature startup; + type empty; + description + "The startup configuration is the config source."; + } + leaf url { + if-feature url; + type inet:uri; + description + "The URL-based configuration is the config source."; + } + anyxml config { + description + "Inline Config content: <config> element. Represents + an entire configuration datastore, not + a subset of the running datastore."; + } + } + } + } + } + + } + + <CODE ENDS> + + + + + + + + + + + + + + + + + + + +Enns, et al. Standards Track [Page 104] + +RFC 6241 NETCONF Protocol June 2011 + + +Appendix D. Capability Template + + This non-normative section defines a template that can be used to + define protocol capabilities. Data models written in YANG usually do + not need to define protocol capabilities since the usage of YANG + automatically leads to a capability announcing the data model and any + optional portions of the data model, so called features in YANG + terminology. The capabilities template is intended to be used in + cases where the YANG mechanisms are not powerful enough (e.g., for + handling parameterized features) or a different data modeling + language is used. + +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. <op-name> + +D.1.5. Modifications to Existing Operations + +D.1.5.1. <op-name> + + 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. Standards Track [Page 105] + +RFC 6241 NETCONF Protocol June 2011 + + +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 Checkpointing the running configuration. + + o Loading and validating the incoming 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 if the update fails. Acquiring a + short-lived lock is a simple defense to prevent other parties from + introducing unrelated changes. + + The lock can be acquired using the <lock> operation. + + + + + + + + + + +Enns, et al. Standards Track [Page 106] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <lock> + <target> + <running/> + </target> + </lock> + </rpc> + + If the :candidate capability is supported, the candidate + configuration should be locked. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <lock> + <target> + <candidate/> + </target> + </lock> + </rpc> + +E.1.2. 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 <copy-config> operation. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <copy-config> + <target> + <url>file://checkpoint.conf</url> + </target> + <source> + <running/> + </source> + </copy-config> + </rpc> + + To restore the checkpoint file, reverse the <source> and <target> + parameters. + + + + + + + +Enns, et al. Standards Track [Page 107] + +RFC 6241 NETCONF Protocol June 2011 + + +E.1.3. Loading and Validating the Incoming Configuration + + If the :candidate capability is supported, the configuration can be + loaded onto the device without impacting the running system. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <edit-config> + <target> + <candidate/> + </target> + <config> + <!-- place incoming configuration changes here --> + </config> + </edit-config> + </rpc> + + If the device supports the :validate:1.1 capability, it will by + default validate the incoming configuration when it is loaded into + the candidate. To avoid this validation, pass the <test-option> + parameter with the value "set". Full validation can be requested + with the <validate> operation. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <validate> + <source> + <candidate/> + </source> + </validate> + </rpc> + +E.1.4. 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 :candidate capability, use the <commit> + operation to set the running configuration to the candidate + configuration. Use the <confirmed> parameter to allow automatic + reversion to the original configuration if connectivity to the device + fails. + + + + + + + + + +Enns, et al. Standards Track [Page 108] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <commit> + <confirmed/> + <confirm-timeout>120</confirm-timeout> + </commit> + </rpc> + + If the candidate is not supported by the device, the incoming + configuration change is loaded directly into running. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <edit-config> + <target> + <running/> + </target> + <config> + <!-- place incoming configuration changes here --> + </config> + </edit-config> + </rpc> + +E.1.5. 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.6. 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 is expected to 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 <copy-config> operation. + + + +Enns, et al. Standards Track [Page 109] + +RFC 6241 NETCONF Protocol June 2011 + + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <copy-config> + <target> + <startup/> + </target> + <source> + <running/> + </source> + </copy-config> + </rpc> + + If the device supports the :candidate capability and a confirmed + commit was requested, the confirming commit must be sent before the + timeout expires. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <commit/> + </rpc> + +E.1.7. Releasing the Configuration Lock + + When the configuration update is complete, the lock must be released, + allowing other applications access to the configuration. + + Use the <unlock> operation to release the configuration lock. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <unlock> + <target> + <running/> + </target> + </unlock> + </rpc> + + If the :candidate capability is supported, the candidate + configuration should be unlocked. + + <rpc message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <unlock> + <target> + <candidate/> + </target> + </unlock> + </rpc> + + + +Enns, et al. Standards Track [Page 110] + +RFC 6241 NETCONF Protocol June 2011 + + +E.2. Operations on Multiple Devices + + When a configuration change requires updates across a number of + devices, care needs to 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 + 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. Standards Track [Page 111] + +RFC 6241 NETCONF Protocol June 2011 + + +Appendix F. Changes from RFC 4741 + + This section lists major changes between this document and RFC 4741. + + o Added the "malformed-message" error-tag. + + o Added "remove" enumeration value to the "operation" attribute. + + o Obsoleted the "partial-operation" error-tag enumeration value. + + o Added <persist> and <persist-id> parameters to the <commit> + operation. + + o Updated the base protocol URI and clarified the <hello> message + exchange to select and identify the base protocol version in use + for a particular session. + + o Added a YANG module to model the operations and removed the + operation layer from the XSD. + + o Clarified lock behavior for the candidate datastore. + + o Clarified the error response server requirements for the "delete" + enumeration value of the "operation" attribute. + + o Added a namespace wildcarding mechanism for subtree filtering. + + o Added a "test-only" value for the <test-option> parameter to the + <edit-config> operation. + + o Added a <cancel-commit> operation. + + o Introduced a NETCONF username and a requirement for transport + protocols to explain how a username is derived. + + + + + + + + + + + + + + + + + +Enns, et al. Standards Track [Page 112] + +RFC 6241 NETCONF Protocol June 2011 + + +Authors' Addresses + + Rob Enns (editor) + Juniper Networks + + EMail: rob.enns@gmail.com + + + 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) + Brocade + + EMail: andy.bierman@brocade.com + + + + + + + + + + + + + + + + + + + + + + + + + + + +Enns, et al. Standards Track [Page 113] + |