From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc4741.txt | 5323 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 5323 insertions(+) create mode 100644 doc/rfc/rfc4741.txt (limited to 'doc/rfc/rfc4741.txt') diff --git a/doc/rfc/rfc4741.txt b/doc/rfc/rfc4741.txt new file mode 100644 index 0000000..6568e42 --- /dev/null +++ b/doc/rfc/rfc4741.txt @@ -0,0 +1,5323 @@ + + + + + + +Network Working Group R. Enns, Ed. +Request for Comments: 4741 Juniper Networks +Category: Standards Track December 2006 + + + NETCONF Configuration Protocol + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The IETF Trust (2006). + +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 on top of a simple Remote Procedure Call (RPC) layer. + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 1] + +RFC 4741 NETCONF Protocol December 2006 + + +Table of Contents + + 1. Introduction ....................................................5 + 1.1. Protocol Overview ..........................................6 + 1.2. Capabilities ...............................................7 + 1.3. Separation of Configuration and State Data .................7 + 2. Transport Protocol Requirements .................................8 + 2.1. Connection-Oriented Operation ..............................9 + 2.2. Authentication, Integrity, and Confidentiality .............9 + 2.3. Authentication .............................................9 + 2.4. Mandatory Transport Protocol ..............................10 + 3. XML Considerations .............................................10 + 3.1. Namespace .................................................10 + 3.2. No Document Type Declarations .............................10 + 4. RPC Model ......................................................10 + 4.1. Element .............................................10 + 4.2. Element .......................................12 + 4.3. Element .......................................12 + 4.4. Element ..............................................16 + 4.5. Pipelining ................................................16 + 5. Configuration Model ............................................16 + 5.1. Configuration Datastores ..................................16 + 5.2. Data Modeling .............................................17 + 6. Subtree Filtering ..............................................17 + 6.1. Overview ..................................................17 + 6.2. Subtree Filter Components .................................18 + 6.2.1. Namespace Selection ................................18 + 6.2.2. Attribute Match Expressions ........................19 + 6.2.3. Containment Nodes ..................................19 + 6.2.4. Selection Nodes ....................................20 + 6.2.5. Content Match Nodes ................................20 + 6.3. Subtree Filter Processing .................................22 + 6.4. Subtree Filtering Examples ................................22 + 6.4.1. No Filter ..........................................22 + 6.4.2. Empty Filter .......................................23 + 6.4.3. Select the Entire Subtree ..................23 + 6.4.4. Select All Elements within the + Subtree ....................................25 + 6.4.5. One Specific Entry ..........................26 + 6.4.6. Specific Elements from a Specific Entry .....27 + 6.4.7. Multiple Subtrees ..................................28 + 6.4.8. Elements with Attribute Naming .....................29 + 7. Protocol Operations ............................................31 + 7.1. ..............................................31 + 7.2. .............................................34 + 7.3. .............................................39 + 7.4. ...........................................41 + 7.5. ....................................................42 + + + +Enns Standards Track [Page 2] + +RFC 4741 NETCONF Protocol December 2006 + + + 7.6. ..................................................44 + 7.7. .....................................................45 + 7.8. ...........................................47 + 7.9. ............................................48 + 8. Capabilities ...................................................49 + 8.1. Capabilities Exchange .....................................49 + 8.2. Writable-Running Capability ...............................50 + 8.2.1. Description ........................................50 + 8.2.2. Dependencies .......................................50 + 8.2.3. Capability Identifier ..............................50 + 8.2.4. New Operations .....................................51 + 8.2.5. Modifications to Existing Operations ...............51 + 8.3. Candidate Configuration Capability ........................51 + 8.3.1. Description ........................................51 + 8.3.2. Dependencies .......................................52 + 8.3.3. Capability Identifier ..............................52 + 8.3.4. New Operations .....................................52 + 8.3.5. Modifications to Existing Operations ...............53 + 8.4. Confirmed Commit Capability ...............................55 + 8.4.1. Description ........................................55 + 8.4.2. Dependencies .......................................55 + 8.4.3. Capability Identifier ..............................56 + 8.4.4. New Operations .....................................56 + 8.4.5. Modifications to Existing Operations ...............56 + 8.5. Rollback on Error Capability ..............................57 + 8.5.1. Description ........................................57 + 8.5.2. Dependencies .......................................57 + 8.5.3. Capability Identifier ..............................57 + 8.5.4. New Operations .....................................57 + 8.5.5. Modifications to Existing Operations ...............57 + 8.6. Validate Capability .......................................58 + 8.6.1. Description ........................................58 + 8.6.2. Dependencies .......................................58 + 8.6.3. Capability Identifier ..............................58 + 8.6.4. New Operations .....................................58 + 8.7. Distinct Startup Capability ...............................60 + 8.7.1. Description ........................................60 + 8.7.2. Dependencies .......................................60 + 8.7.3. Capability Identifier ..............................60 + 8.7.4. New Operations .....................................60 + 8.7.5. Modifications to Existing Operations ...............60 + 8.8. URL Capability ............................................61 + 8.8.1. Description ........................................61 + 8.8.2. Dependencies .......................................61 + 8.8.3. Capability Identifier ..............................62 + 8.8.4. New Operations .....................................62 + 8.8.5. Modifications to Existing Operations ...............62 + + + + +Enns Standards Track [Page 3] + +RFC 4741 NETCONF Protocol December 2006 + + + 8.9. XPath Capability ..........................................63 + 8.9.1. Description ........................................63 + 8.9.2. Dependencies .......................................63 + 8.9.3. Capability Identifier ..............................63 + 8.9.4. New Operations .....................................63 + 8.9.5. Modifications to Existing Operations ...............63 + 9. Security Considerations ........................................64 + 10. IANA Considerations ...........................................66 + 10.1. NETCONF XML Namespace ....................................66 + 10.2. NETCONF XML Schema .......................................66 + 10.3. NETCONF Capability URNs ..................................66 + 11. Authors and Acknowledgements ..................................68 + 12. References ....................................................68 + 12.1. Normative References .....................................68 + 12.2. Informative References ...................................69 + Appendix A. NETCONF Error List ....................................70 + Appendix B. XML Schema for NETCONF RPC and Protocol Operations ....74 + Appendix C. Capability Template ...................................86 + C.1. capability-name (template) ................................86 + C.1.1. Overview ...........................................86 + C.1.2. Dependencies .......................................86 + C.1.3. Capability Identifier ..............................86 + C.1.4. New Operations .....................................86 + C.1.5. Modifications to Existing Operations ...............86 + C.1.6. Interactions with Other Capabilities ...............86 + Appendix D. Configuring Multiple Devices with NETCONF ............87 + D.1. Operations on Individual Devices ..........................87 + D.1.1. Acquiring the Configuration Lock ...................87 + D.1.2. Loading the Update .................................88 + D.1.3. Validating the Incoming Configuration ..............89 + D.1.4. Checkpointing the Running Configuration ............89 + D.1.5. Changing the Running Configuration .................90 + D.1.6. Testing the New Configuration ......................91 + D.1.7. Making the Change Permanent ........................91 + D.1.8. Releasing the Configuration Lock ...................92 + D.2. Operations on Multiple Devices ............................92 + Appendix E. Deferred Features .....................................93 + + + + + + + + + + + + + + +Enns Standards Track [Page 4] + +RFC 4741 NETCONF Protocol December 2006 + + +1. Introduction + + The NETCONF protocol defines a simple mechanism through which a + network device can be managed, configuration data information can be + retrieved, and new configuration data can be uploaded and + manipulated. The protocol allows the device to expose a full, formal + application programming interface (API). Applications can use this + straightforward API to send and receive full and partial + configuration data sets. + + The NETCONF protocol uses a remote procedure call (RPC) paradigm. A + client encodes an RPC in XML [1] and sends it to a server using a + secure, connection-oriented session. The server responds with a + reply encoded in XML. The contents of both the request and the + response are fully described in XML DTDs or XML schemas, or both, + allowing both parties to recognize the syntax constraints imposed on + the exchange. + + A key aspect of NETCONF is that it allows the functionality of the + management protocol to closely mirror the native functionality of the + device. This reduces implementation costs and allows timely access + to new features. In addition, applications can access both the + syntactic and semantic content of the device's native user interface. + + NETCONF allows a client to discover the set of protocol extensions + supported by a server. These "capabilities" permit the client to + adjust its behavior to take advantage of the features exposed by the + device. The capability definitions can be easily extended in a + noncentralized manner. Standard and non-standard capabilities can be + defined with semantic and syntactic rigor. Capabilities are + discussed in Section 8. + + The NETCONF protocol is a building block in a system of automated + configuration. XML is the lingua franca of interchange, providing a + flexible but fully specified encoding mechanism for hierarchical + content. NETCONF can be used in concert with XML-based + transformation technologies, such as XSLT [8], 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 Standards Track [Page 5] + +RFC 4741 NETCONF Protocol December 2006 + + + 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 [3]. + +1.1. Protocol Overview + + NETCONF uses a simple RPC-based mechanism to facilitate communication + between a client and a server. The client can be a script or + application typically running as part of a network manager. The + server is typically a network device. The terms "device" and + "server" are used interchangeably in this document, as are "client" + and "application". + + A NETCONF session is the logical connection between a network + administrator or network configuration application and a network + device. A device MUST support at least one NETCONF session and + SHOULD support multiple sessions. Global configuration attributes + can be changed during any authorized session, and the effects are + visible in all sessions. Session-specific attributes affect only the + session in which they are changed. + + NETCONF can be conceptually partitioned into four layers: + + Layer Example + +-------------+ +-----------------------------+ + (4) | Content | | Configuration data | + +-------------+ +-----------------------------+ + | | + +-------------+ +-----------------------------+ + (3) | Operations | | , | + +-------------+ +-----------------------------+ + | | + +-------------+ +-----------------------------+ + (2) | RPC | | , | + +-------------+ +-----------------------------+ + | | + +-------------+ +-----------------------------+ + (1) | Transport | | BEEP, SSH, SSL, console | + | Protocol | | | + +-------------+ +-----------------------------+ + + 1. The transport protocol 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 RPC layer provides a simple, transport-independent framing + mechanism for encoding RPCs. Section 4 documents this protocol. + + + +Enns Standards Track [Page 6] + +RFC 4741 NETCONF Protocol December 2006 + + + 3. The operations layer defines a set of base operations invoked as + RPC methods with XML-encoded parameters. Section 7 details the + list of base operations. + + 4. The content layer is outside the scope of this document. Given + the current proprietary nature of the configuration data being + manipulated, the specification of this content depends on the + NETCONF implementation. It is expected that a separate effort to + specify a standard data definition language and standard content + will be undertaken. + +1.2. Capabilities + + A NETCONF capability is a set of functionality that supplements the + base NETCONF specification. The capability is identified by a + uniform resource identifier (URI). These URIs should follow the + guidelines as described in Section 8. + + Capabilities augment the base operations of the device, describing + both additional operations and the content allowed inside operations. + The client can discover the server's capabilities and use any + additional operations, parameters, and content defined by those + capabilities. + + The capability definition may name one or more dependent + capabilities. To support a capability, the server MUST support any + capabilities upon which it depends. + + Section 8 defines the capabilities exchange that allows the client to + discover the server's capabilities. Section 8 also lists the set of + capabilities defined in this document. + + Additional capabilities can be defined at any time in external + documents, allowing the set of capabilities to expand over time. + Standards bodies may define standardized capabilities, and + implementations may define proprietary ones. A capability URI MUST + sufficiently distinguish the naming authority to avoid naming + collisions. + +1.3. Separation of Configuration and State Data + + The information that can be retrieved from a running system is + separated into two classes, configuration data and state data. + Configuration data is the set of writable data that is required to + transform a system from its initial default state into its current + state. State data is the additional data on a system that is not + + + + + +Enns Standards Track [Page 7] + +RFC 4741 NETCONF Protocol December 2006 + + + configuration data such as read-only status information and collected + statistics. When a device is performing configuration operations, a + number of problems would arise if state data were included: + + o Comparisons of configuration data sets would be dominated by + irrelevant entries such as different statistics. + + o Incoming data could contain nonsensical requests, such as attempts + to write read-only data. + + o The data sets would be large. + + o Archived data could contain values for read-only data items, + complicating the processing required to restore archived data. + + To account for these issues, the NETCONF protocol recognizes the + difference between configuration data and state data and provides + operations for each. The operation retrieves + configuration data only, while the operation retrieves + configuration and state data. + + Note that the NETCONF protocol is focused on the information required + to get the device into its desired running state. The inclusion of + other important, persistent data is implementation specific. For + example, user files and databases are not treated as configuration + data by the NETCONF protocol. + + If a local database of user authentication data is stored on the + device, whether it is included in configuration data is an + implementation-dependent matter. + +2. Transport Protocol Requirements + + NETCONF uses an RPC-based communication paradigm. A client sends a + series of one or more RPC request operations, which cause the server + to respond with a corresponding series of RPC replies. + + The NETCONF protocol can be layered on any transport protocol that + provides the required set of functionality. It is not bound to any + particular transport protocol, but allows a mapping to define how it + can be implemented over any specific protocol. + + The transport protocol MUST provide a mechanism to indicate the + session type (client or server) to the NETCONF protocol layer. + + This section details the characteristics that NETCONF requires from + the underlying transport protocol. + + + + +Enns Standards Track [Page 8] + +RFC 4741 NETCONF Protocol December 2006 + + +2.1. Connection-Oriented Operation + + NETCONF is connection-oriented, requiring a persistent connection + between peers. This connection must provide reliable, sequenced data + delivery. + + NETCONF connections are long-lived, persisting between protocol + operations. This allows the client to make changes to the state of + the connection that will persist for the lifetime of the connection. + For example, authentication information specified for a connection + remains in effect until the connection is closed. + + In addition, resources requested from the server for a particular + connection MUST be automatically released when the connection closes, + making failure recovery simpler and more robust. For example, when a + lock is acquired by a client, the lock persists until either it is + explicitly released or the server determines that the connection has + been terminated. If a connection is terminated while the client + holds a lock, the server can perform any appropriate recovery. The + lock operation is further discussed in Section 7.5. + +2.2. Authentication, Integrity, and Confidentiality + + NETCONF connections must provide authentication, data integrity, and + confidentiality. NETCONF depends on the transport protocol for this + capability. A NETCONF peer assumes that appropriate levels of + security and confidentiality are provided independently of this + document. For example, connections may be encrypted in TLS [9] or + SSH [10], depending on the underlying protocol. + +2.3. Authentication + + NETCONF connections must be authenticated. The transport protocol is + responsible for authentication. The peer assumes that the + connection's authentication information has been validated by the + underlying protocol using sufficiently trustworthy mechanisms and + that the peer's identity has been sufficiently proven. + + One goal of NETCONF is to provide a programmatic interface to the + device that closely follows the functionality of the device's native + interface. Therefore, it is expected that the underlying protocol + uses existing authentication mechanisms defined by the device. For + example, a device that supports RADIUS [11] should allow the use of + RADIUS to authenticate NETCONF sessions. + + The authentication process should result in an identity whose + permissions are known to the device. These permissions MUST be + enforced during the remainder of the NETCONF session. + + + +Enns Standards Track [Page 9] + +RFC 4741 NETCONF Protocol December 2006 + + +2.4. Mandatory Transport Protocol + + A NETCONF implementation MUST support the SSH transport protocol + mapping [4]. + +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. + + This section discusses a small number of XML-related considerations + pertaining to NETCONF. + +3.1. Namespace + + All NETCONF protocol elements are defined in the following namespace: + + urn:ietf:params:xml:ns:netconf:base:1.0 + + NETCONF capability names MUST be URIs [5]. NETCONF capabilities are + discussed in Section 8. + +3.2. No Document Type Declarations + + Document type declarations MUST NOT appear in NETCONF content. + +4. RPC Model + + The NETCONF protocol uses an RPC-based communication model. NETCONF + peers use and elements to provide transport + protocol-independent framing of NETCONF requests and responses. + +4.1. Element + + The element is used to enclose a NETCONF request sent from the + client to the server. + + The element has a mandatory attribute "message-id", which is an + arbitrary string chosen by the sender of the RPC that will commonly + encode a monotonically increasing integer. The receiver of the RPC + does not decode or interpret this string but simply saves it to be + used as a "message-id" attribute in any resulting + message. For example: + + + + + + +Enns Standards Track [Page 10] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + If additional attributes are present in an element, a NETCONF + peer MUST return them unmodified in the element. + + The name and parameters of an RPC are encoded as the contents of the + element. The name of the RPC is an element directly inside the + element, and any parameters are encoded inside this element. + + The following example invokes a method called , which + has two parameters, , with a value of "14", and + , with a value of "fred": + + + + 14 + fred + + + + The following example invokes a method with a + parameter of "27606-0100": + + + + 27606-0100 + + + + The following example invokes the NETCONF method with no + parameters: + + + + + + + + + + + + +Enns Standards Track [Page 11] + +RFC 4741 NETCONF Protocol December 2006 + + +4.2. Element + + The message is sent in response to an operation. + + The element has a mandatory attribute "message-id", which + is equal to the "message-id" attribute of the for which this is + a response. + + A NETCONF peer MUST also return any additional attributes included in + the element unmodified in the element. + + The response name and response data are encoded as the contents of + the element. The name of the reply is an element + directly inside the element, and any data is encoded + inside this element. + + For example: + + The following element invokes the NETCONF method and + includes an additional attribute called "user-id". Note that the + "user-id" attribute is not in the NETCONF namespace. The returned + element returns the "user-id" attribute, as well as the + requested content. + + + + + + + + + + + +4.3. Element + + The element is sent in messages if an error + occurs during the processing of an request. + + If a server encounters multiple errors during the processing of an + request, the MAY contain multiple + elements. However, a server is not required to detect or report more + + + +Enns Standards Track [Page 12] + +RFC 4741 NETCONF Protocol December 2006 + + + than one element, if a request contains multiple errors. + A server is not required to check for particular error conditions in + a specific sequence. A server MUST return an element if + any error conditions occur during processing and SHOULD return an + element if any warning conditions occur during + processing. + + A server MUST NOT return application-level- or data-model-specific + error information in an element for which the client does + not have sufficient access rights. + + The element includes the following information: + + error-type: Defines the conceptual layer that the error occurred. + Enumeration. One of: + + * transport + + * rpc + + * protocol + + * application + + error-tag: Contains a string identifying the error condition. See + Appendix A for allowed values. + + error-severity: Contains a string identifying the error severity, as + determined by the device. One of: + + * error + + * warning + + error-app-tag: Contains a string identifying the data-model-specific + or implementation-specific error condition, if one exists. This + element will not be present if no appropriate application error + tag can be associated with a particular error condition. + + error-path: Contains the absolute XPath [2] expression identifying + the element path to the node that is associated with the error + being reported in a particular rpc-error element. This element + will not be present if no appropriate payload element can be + associated with a particular error condition, or if the + 'bad-element' QString returned in the 'error-info' container is + sufficient to identify the node associated with the error. When + + + + + +Enns Standards Track [Page 13] + +RFC 4741 NETCONF Protocol December 2006 + + + the XPath expression is interpreted, the set of namespace + declarations are those in scope on the rpc-error element, + including the default namespace. + + error-message: Contains a string suitable for human display that + describes the error condition. This element will not be present + if no appropriate message is provided for a particular error + condition. This element SHOULD include an xml:lang attribute as + defined in [1] and discussed in [12]. + + error-info: Contains protocol- or data-model-specific error content. + This element will not be present if no such error content is + provided for a particular error condition. The list in Appendix A + defines any mandatory error-info content for each error. After + any protocol-mandated content, a data model definition may mandate + that certain application-layer error information be included in + the error-info container. An implementation may include + additional elements to provide extended and/or implementation- + specific debugging information. + + Appendix A enumerates the standard NETCONF errors. + + Example: + + An error is returned if an element is received without a + message-id attribute. Note that only in this case is it + acceptable for the NETCONF peer to omit the message-id attribute + in the element. + + + + + + + + + + + + rpc + missing-attribute + error + + message-id + rpc + + + + + + +Enns Standards Track [Page 14] + +RFC 4741 NETCONF Protocol December 2006 + + + The following illustrates the case of returning + multiple elements. + + Note that the data models used in the examples in this section use + the element to distinguish between multiple instances of + the element. + + + + application + invalid-value + error + + MTU value 25000 is not within range 256..9192 + + + + + Ethernet0/0 + 25000 + + + + + + application + invalid-value + error + + Invalid IP address for interface Ethernet1/0 + + + + + Ethernet1/0 +
+ 1.4 + 24 +
+ + + + + + + + + + +Enns Standards Track [Page 15] + +RFC 4741 NETCONF Protocol December 2006 + + +4.4. Element + + The element is sent in messages if no errors or + warnings occurred during the processing of an request. For + example: + + + + + +4.5. Pipelining + + NETCONF requests MUST be processed serially by the managed + device. Additional requests MAY be sent before previous ones + have been completed. The managed device MUST send responses only in + the order the requests were received. + +5. Configuration Model + + NETCONF provides an initial set of operations and a number of + capabilities that can be used to extend the base. NETCONF peers + exchange device capabilities when the session is initiated as + described in Section 8.1. + +5.1. Configuration Datastores + + NETCONF defines the existence of one or more configuration datastores + and allows configuration operations on them. A configuration + datastore is defined as the complete set of configuration data that + is required to get a device from its initial default state into a + desired operational state. The configuration datastore does not + include state data or executive commands. + + Only the configuration datastore is present in the base + model. Additional configuration datastores may be defined by + capabilities. Such configuration datastores are available only on + devices that advertise the capabilities. + + o Running: The complete configuration currently active on the + network device. Only one configuration datastore of this type + exists on the device, and it is always present. NETCONF protocol + operations refer to this datastore using the element. + + The capabilities in Sections 8.3 and 8.7 define the and + configuration datastores, respectively. + + + + + +Enns Standards Track [Page 16] + +RFC 4741 NETCONF Protocol December 2006 + + +5.2. Data Modeling + + Data modeling and content issues are outside the scope of the NETCONF + protocol. An assumption is made that the device's data model is + well-known to the application and that both parties are aware of + issues such as the layout, containment, keying, lookup, replacement, + and management of the data, as well as any other constraints imposed + by the data model. + + NETCONF carries configuration data inside the element that + is specific to device's data model. The protocol treats the contents + of that element as opaque data. The device uses capabilities to + announce the set of data models that the device implements. The + capability definition details the operation and constraints imposed + by data model. + + Devices and managers may support multiple data models, including both + standard and proprietary data models. + +6. Subtree Filtering + +6.1. Overview + + XML subtree filtering is a mechanism that allows an application to + select particular XML subtrees to include in the for a + or operation. A small set of filters for + inclusion, simple content exact-match, and selection is provided, + which allows some useful, but also very limited, selection + mechanisms. The agent does not need to utilize any data-model- + specific semantics during processing, allowing for simple and + centralized implementation strategies. + + Conceptually, a subtree filter is comprised of zero or more element + subtrees, which represent the filter selection criteria. At each + containment level within a subtree, the set of sibling nodes is + logically processed by the server to determine if its subtree and + path of elements to the root are included in the filter output. + + All elements present in a particular subtree within a filter must + match associated nodes present in the server's conceptual data model. + XML namespaces may be specified (via 'xmlns' declarations) within the + filter data model. If they are, the declared namespace must first + exactly match a namespace supported by the server. Note that prefix + values for qualified namespaces are not relevant when comparing + filter elements to elements in the underlying data model. Only data + associated with a specified namespace will be included in the filter + output. + + + + +Enns Standards Track [Page 17] + +RFC 4741 NETCONF Protocol December 2006 + + + Each node specified in a subtree filter represents an inclusive + filter. Only associated nodes in underlying data model(s) within the + specified configuration datastore on the server are selected by the + filter. A node must exactly match the namespace and hierarchy of + elements given in the filter data, except that the filter absolute + path name is adjusted to start from the layer below . + + Response messages contain only the subtrees selected by the filter. + Any selection criteria that were present in the request, within a + particular selected subtree, are also included in the response. Note + that some elements expressed in the filter as leaf nodes will be + expanded (i.e., subtrees included) in the filter output. Specific + data instances are not duplicated in the response in the event that + the request contains multiple filter subtree expressions that select + the same data. + +6.2. Subtree Filter Components + + A subtree filter is comprised of XML elements and their XML + attributes. There are five types of components that may be present + in a subtree filter: + + o Namespace Selection + + o Attribute Match Expressions + + o Containment Nodes + + o Selection Nodes + + o Content Match Nodes + +6.2.1. Namespace Selection + + If namespaces are used, then the filter output will only include + elements from the specified namespace. A namespace is considered to + match (for filter purposes) if the content of the 'xmlns' attributes + are the same in the filter and the underlying data model. Note that + namespace selection cannot be used by itself. At least one element + must be specified in the filter any elements to be included in the + filter output. + + Example: + + + + + + + + +Enns Standards Track [Page 18] + +RFC 4741 NETCONF Protocol December 2006 + + + In this example, the element is a selection node, and only this + node and any child nodes (from the underlying data model) in the + 'http://example.com/schema/1.2/config' namespace will be included in + the filter output. + +6.2.2. Attribute Match Expressions + + An attribute that appears in a subtree filter is part of an + "attribute match expression". Any number of (unqualified or + qualified) XML attributes may be present in any type of filter node. + In addition to the selection criteria normally applicable to that + node, the selected data must have matching values for every attribute + specified in the node. If an element is not defined to include a + specified attribute, then it is not selected in the filter output. + + Example: + + + + + + + + + + In this example, the , , and elements + are containment nodes, and 'ifName' is an attribute match expression. + Only 'interface' nodes in the 'http://example.com/schema/1.2/config' + namespace that have an 'ifName' attribute with the value 'eth0' and + occur within 'interfaces' nodes within 'top' nodes will be included + in the filter output. + +6.2.3. Containment Nodes + + Nodes that contain child elements within a subtree filter are called + "containment nodes". Each child element can be any type of node, + including another containment node. For each containment node + specified in a subtree filter, all data model instances that exactly + match the specified namespaces, element hierarchy, and any attribute + match expressions are included in the filter output. + + Example: + + + + + + + + + +Enns Standards Track [Page 19] + +RFC 4741 NETCONF Protocol December 2006 + + + In this example, the element is a containment node. + +6.2.4. Selection Nodes + + An empty leaf node within a filter is called a "selection node", and + it represents an "explicit selection" filter on the underlying data + model. Presence of any selection nodes within a set of sibling nodes + will cause the filter to select the specified subtree(s) and suppress + automatic selection of the entire set of sibling nodes in the + underlying data model. For filtering purposes, an empty leaf node + can be declared either with an empty tag (e.g., ) or with + explicit start and end tags (e.g., ). Any whitespace + characters are ignored in this form. + + Example: + + + + + + + + In this example, the element is a containment node, and the + element is a selection node. Only 'users' nodes in the + 'http://example.com/schema/1.2/config' namespace that occur within a + 'top' element that is the root of the configuration datastore will be + included in the filter output. + +6.2.5. Content Match Nodes + + A leaf node that contains simple content is called a "content match + node". It is used to select some or all of its sibling nodes for + filter output, and it represents an exact-match filter on the leaf + node element content. The following constraints apply to content + match nodes: + + o A content match node must not contain nested elements (i.e., must + resolve to a simpleType in the XML Schema Definition (XSD)). + + o Multiple content match nodes (i.e., sibling nodes) are logically + combined in an "AND" expression. + + o Filtering of mixed content is not supported. + + o Filtering of list content is not supported. + + o Filtering of whitespace-only content is not supported. + + + + +Enns Standards Track [Page 20] + +RFC 4741 NETCONF Protocol December 2006 + + + o A content match node must contain non-whitespace characters. An + empty element (e.g., ) will be interpreted as a + selection node (e.g., ). + + o Leading and trailing whitespace characters are ignored, but any + whitespace characters within a block of text characters are not + ignored or modified. + + If all specified sibling content match nodes in a subtree filter + expression are 'true', then the filter output nodes are selected in + the following manner: + + o Each content match node in the sibling set is included in the + filter output. + + 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 Otherwise (i.e., there are no selection or containment nodes in + the filter sibling set), all the nodes defined at this level in + the underlying data model (and their subtrees, if any) are + returned in the filter output. + + If any of the sibling content match node tests are 'false', then no + further filter processing is performed on that sibling set, and none + of the sibling subtrees are selected by the filter, including the + content match node(s). + + Example: + + + + + + fred + + + + + + In this example, the and nodes are both containment + nodes, and is a content match node. Since no sibling nodes of + are specified (and therefore no containment or selection + nodes), all of the sibling nodes of are returned in the filter + + + +Enns Standards Track [Page 21] + +RFC 4741 NETCONF Protocol December 2006 + + + output. Only 'user' nodes in the + 'http://example.com/schema/1.2/config' namespace that match the + element hierarchy and for which the element is equal to 'fred' + will be included in the filter output. + +6.3. Subtree Filter Processing + + The filter output (the set of selected nodes) is initially empty. + + Each subtree filter can contain one or more data model fragments, + which represent portions of the data model that should be selected + (with all child nodes) in the filter output. + + Each subtree data fragment is compared by the server to the internal + data models supported by the server. If the entire subtree data- + fragment filter (starting from the root to the innermost element + specified in the filter) exactly matches a corresponding portion of + the supported data model, then that node and all its children are + included in the result data. + + The server processes all nodes with the same parent node (sibling + set) together, starting from the root to the leaf nodes. The root + elements in the filter are considered in the same sibling set + (assuming they are in the same namespace), even though they do not + have a common parent. + + For each sibling set, the server determines which nodes are included + (or potentially included) in the filter output, and which sibling + subtrees are excluded (pruned) from the filter output. The server + first determines which types of nodes are present in the sibling set + and processes the nodes according to the rules for their type. If + any nodes in the sibling set are selected, then the process is + recursively applied to the sibling sets of each selected node. The + algorithm continues until all sibling sets in all subtrees specified + in the filter have been processed. + +6.4. Subtree Filtering Examples + +6.4.1. No Filter + + Leaving out the filter on the get operation returns the entire data + model. + + + + + + + + +Enns Standards Track [Page 22] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + +6.4.2. Empty Filter + + An empty filter will select nothing because no content match or + selection nodes are present. This is not an error. The filter type + attribute used in these examples is discussed further in Section 7.1. + + + + + + + + + + + + + +6.4.3. Select the Entire Subtree + + The filter in this example contains one selection node (), so + just that subtree is selected by the filter. This example represents + the fully-populated data model in most of the filter examples + that follow. In a real data model, the would not + likely be returned with the list of users for a particular host or + network. + + NOTE: The filtering and configuration examples used in this document + appear in the namespace "http://example.com/schema/1.2/config". The + root element of this namespace is . The element and its + descendents represent an example configuration data model only. + + + + + + + + + + +Enns Standards Track [Page 23] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + root + superuser + Charlie Root + + 1 + 1 + + + + fred + admin + Fred Flintstone + + 2 + 2 + + + + barney + admin + Barney Rubble + + 2 + 3 + + + + + + + + The following filter request would have produced the same result, but + only because the container defines one child element + (). + + + + +Enns Standards Track [Page 24] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + + + +6.4.4. Select All Elements within the Subtree + + This filter contains two containment nodes (, ) and one + selector node (). All instances of the element in the + same sibling set are selected in the filter output. The manager may + need to know that is used as an instance identifier in this + particular data structure, but the server does not need to know that + meta-data in order to process the request. + + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 25] + +RFC 4741 NETCONF Protocol December 2006 + + + + root + + + fred + + + barney + + + + + + +6.4.5. One Specific Entry + + This filter contains two containment nodes (, ) and one + content match node (). All instances of the sibling set + containing for which the value of equals "fred" are + selected in the filter output. + + + + + + + + + + + fred + + + + + + + + + + + + + fred + admin + Fred Flintstone + + + +Enns Standards Track [Page 26] + +RFC 4741 NETCONF Protocol December 2006 + + + + 2 + 2 + + + + + + + +6.4.6. Specific Elements from a Specific Entry + + This filter contains two containment nodes (, ), one + content match node (), and two selector nodes (, + ). All instances of the and elements + in the same sibling set containing for which the value of + equals "fred" are selected in the filter output. The + element is not included because the sibling set + contains selection nodes. + + + + + + + + + + + fred + + + + + + + + + + + + + + + fred + admin + + + +Enns Standards Track [Page 27] + +RFC 4741 NETCONF Protocol December 2006 + + + Fred Flintstone + + + + + + +6.4.7. Multiple Subtrees + + This filter contains three subtrees (name=root, fred, barney). + + The "root" subtree filter contains two containment nodes (, + ), one content match node (), and one selector node + (). The subtree selection criteria is met, and just + the company-info subtree for "root" is selected in the filter output. + + The "fred" subtree filter contains three containment nodes (, + , ), one content match node (), and one + selector node (). The subtree selection criteria is met, and + just the element within the company-info subtree for "fred" is + selected in the filter output. + + The "barney" subtree filter contains three containment nodes + (, , ), two content match nodes (, + ), and one selector node (). The subtree selection + criteria is not met because user "barney" is not a "superuser", and + the entire subtree for "barney" (including its parent entry) + is excluded from the filter output. + + + + + + + + + + + root + + + + fred + + + + + + + +Enns Standards Track [Page 28] + +RFC 4741 NETCONF Protocol December 2006 + + + + barney + superuser + + + + + + + + + + + + + + + + root + + 1 + 1 + + + + fred + + 2 + + + + + + + +6.4.8. Elements with Attribute Naming + + In this example, the filter contains one containment node + (), one attribute match expression (ifName), and one + selector node (). All instances of the + subtree that have an ifName attribute equal to "eth0" are selected in + the filter output. The filter data elements and attributes must be + qualified because the ifName attribute will not be considered part of + the 'schema/1.2' namespace if it is unqualified. + + + + + + +Enns Standards Track [Page 29] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + + + + + + 45621 + 774344 + + + + + + + If ifName were a child node instead of an attribute, then the + following request would produce similar results. + + + + + + + + eth0 + + + + + + + + + + + + + +Enns Standards Track [Page 30] + +RFC 4741 NETCONF Protocol December 2006 + + +7. Protocol Operations + + The NETCONF protocol provides a small set of low-level operations to + manage device configurations and retrieve device state information. + The base protocol provides operations to retrieve, configure, copy, + and delete configuration datastores. Additional operations are + provided, based on the capabilities advertised by the device. + + The base protocol includes the following protocol operations: + + o get + + o get-config + + o edit-config + + o copy-config + + o delete-config + + o lock + + o unlock + + o close-session + + o kill-session + + A protocol operation may fail for various reasons, including + "operation not supported". An initiator should not assume that any + operation will always succeed. The return values in any RPC reply + should be checked for error responses. + + The syntax and XML encoding of the protocol operations are formally + defined in the XML schema in Appendix B. The following sections + describe the semantics of each protocol operation. + +7.1. + + Description: + + Retrieve all or part of a specified configuration. + + + + + + + + + +Enns Standards Track [Page 31] + +RFC 4741 NETCONF Protocol December 2006 + + + Parameters: + + source: + + Name of the configuration datastore being queried, such as + . + + filter: + + The filter element identifies the portions of the device + configuration to retrieve. If this element is unspecified, the + entire configuration is returned. + + The filter element may optionally contain a "type" attribute. + This attribute indicates the type of filtering syntax used + within the filter element. The default filtering mechanism in + NETCONF is referred to as subtree filtering and is described in + Section 6. The value "subtree" explicitly identifies this type + of filtering. + + If the NETCONF peer supports the :xpath capability + (Section 8.9), the value "xpath" may be used to indicate that + the select attribute on the filter element contains an XPath + expression. + + Positive Response: + + If the device can satisfy the request, the server sends an + element containing a element with the results + of the query. + + Negative Response: + + An element is included in the if the + request cannot be completed for any reason. + + Example: To retrieve the entire subtree: + + + + + + + + + + + + + +Enns Standards Track [Page 32] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + root + superuser + Charlie Root + + 1 + 1 + + + + + + + + + If the configuration is available in multiple formats, such as XML + and text, an XML namespace can be used to specify which format is + desired. In the following example, the client uses a specific + element () in a specific namespace to indicate to the + server the desire to receive the configuration in an alternative + format. The server may support any number of distinct formats or + views into the configuration data, with the client using the + parameter to select between them. + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 33] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + Section 6 contains additional examples of subtree filtering. + +7.2. + + Description: + + The operation loads all or part of a specified + configuration to the specified target configuration. This + operation allows the new configuration to be expressed in several + ways, such as using a local file, a remote file, or inline. If + the target configuration does not exist, it will be created. If a + NETCONF peer supports the :url capability (Section 8.8), the + element can appear instead of the parameter and should + identify a local configuration file. + + The device analyzes the source and target configurations and + performs the requested changes. The target configuration is not + necessarily replaced, as with the message. Instead, + the target configuration is changed in accordance with the + source's data and requested operations. + + Attributes: + + operation: + + Elements in the subtree may contain an "operation" + attribute. The attribute identifies the point in the + configuration to perform the operation and MAY appear on + multiple elements throughout the subtree. + + If the operation attribute is not specified, the configuration + is merged into the configuration datastore. + + The operation attribute has one of the following values: + + merge: The configuration data identified by the element + containing this attribute is merged with the configuration + at the corresponding level in the configuration datastore + identified by the target parameter. This is the default + behavior. + + + + +Enns Standards Track [Page 34] + +RFC 4741 NETCONF Protocol December 2006 + + + replace: The configuration data identified by the element + containing this attribute replaces any related configuration + in the configuration datastore identified by the target + parameter. Unlike a operation, which replaces + the entire target configuration, only the configuration + actually present in the config parameter is affected. + + create: The configuration data identified by the element + containing this attribute is added to the configuration if + and only if the configuration data does not already exist on + the device. If the configuration data exists, an + element is returned with an value of + data-exists. + + delete: The configuration data identified by the element + containing this attribute is deleted in the configuration + datastore identified by the target parameter. + + Parameters: + + target: + + Name of the configuration datastore being edited, such as + or . + + default-operation: + + Selects the default operation (as described in the "operation" + attribute) for this request. The default value + for the default-operation parameter is "merge". + + The default-operation parameter is optional, but if provided, + it must have one of the following values: + + merge: The configuration data in the parameter is + merged with the configuration at the corresponding level in + the target datastore. This is the default behavior. + + replace: The configuration data in the parameter + completely replaces the configuration in the target + datastore. This is useful for loading previously saved + configuration data. + + none: The target datastore is unaffected by the configuration + in the parameter, unless and until the incoming + configuration data uses the "operation" attribute to request + a different operation. If the configuration in the + parameter contains data for which there is not a + + + +Enns Standards Track [Page 35] + +RFC 4741 NETCONF Protocol December 2006 + + + corresponding level in the target datastore, an + is returned with an value of data-missing. + Using "none" allows operations like "delete" to avoid + unintentionally creating the parent hierarchy of the element + to be deleted. + + test-option: + + The test-option element may be specified only if the device + advertises the :validate capability (Section 8.6). + + The test-option element has one of the following values: + + test-then-set: Perform a validation test before attempting to + set. If validation errors occur, do not perform the + operation. This is the default test-option. + + set: Perform a set without a validation test first. + + error-option: + + The error-option element has one of the following values: + + stop-on-error: Abort the edit-config operation on first error. + This is the default error-option. + + continue-on-error: Continue to process configuration data on + error; error is recorded, and negative response is generated + if any errors occur. + + rollback-on-error: If an error condition occurs such that an + error severity element is generated, the server + will stop processing the edit-config operation and restore + the specified configuration to its complete state at the + start of this edit-config operation. This option requires + the server to support the :rollback-on-error capability + described in Section 8.5. + + config: + + A hierarchy of configuration data as defined by one of the + device's data models. The contents MUST be placed in an + appropriate namespace, to allow the device to detect the + appropriate data model, and the contents MUST follow the + constraints of that data model, as defined by its capability + definition. Capabilities are discussed in Section 8. + + + + + +Enns Standards Track [Page 36] + +RFC 4741 NETCONF Protocol December 2006 + + + Positive Response: + + If the device was able to satisfy the request, an is + sent containing an element. + + Negative Response: + + An response is sent if the request cannot be completed + for any reason. + + Example: + + The examples in this section utilize a simple data + model, in which multiple instances of the 'interface' element may + be present, and an instance is distinguished by the 'name' element + within each 'interface' element. + + Set the MTU to 1500 on an interface named "Ethernet0/0" in the + running configuration: + + + + + + + + + + Ethernet0/0 + 1500 + + + + + + + + + + + Add an interface named "Ethernet0/0" to the running configuration, + replacing any previous interface with that name: + + + + + + +Enns Standards Track [Page 37] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + Ethernet0/0 + 1500 +
+ 192.0.2.4 + 24 +
+ + + + + + + + + + + Delete the configuration for an interface named "Ethernet0/0" from + the running configuration: + + + + + + + none + + + + Ethernet0/0 + + + + + + + + + + + + + +Enns Standards Track [Page 38] + +RFC 4741 NETCONF Protocol December 2006 + + + Delete interface 192.0.2.4 from an OSPF area (other interfaces + configured in the same area are unaffected): + + + + + + + none + + + + + + 0.0.0.0 + + + 192.0.2.4 + + + + + + + + + + + + + + +7.3. + + Description: + + Create or replace an entire configuration datastore with the + contents of another complete configuration datastore. If the + target datastore exists, it is overwritten. Otherwise, a new one + is created, if allowed. + + If a NETCONF peer supports the :url capability (Section 8.8), the + element can appear as the or parameter. + + Even if it advertises the :writable-running capability, a device + may choose not to support the configuration datastore + + + +Enns Standards Track [Page 39] + +RFC 4741 NETCONF Protocol December 2006 + + + as the parameter of a operation. A device + may choose not to support remote-to-remote copy operations, where + both the and parameters use the element. + + If the source and target parameters identify the same URL or + configuration datastore, an error MUST be returned with an error- + tag containing invalid-value. + + Parameters: + + target: + + Name of the configuration datastore to use as the destination + of the copy operation. + + source: + + Name of the configuration datastore to use as the source of the + copy operation or the element containing the + configuration subtree to copy. + + Positive Response: + + If the device was able to satisfy the request, an is + sent that includes an element. + + Negative Response: + + An element is included within the if the + request cannot be completed for any reason. + + Example: + + + + + + + + https://user@example.com:passphrase/cfg/new.txt + + + + + + + + + + +Enns Standards Track [Page 40] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + +7.4. + + Description: + + Delete a configuration datastore. The configuration + datastore cannot be deleted. + + If a NETCONF peer supports the :url capability (Section 8.8), the + element can appear as the parameter. + + Parameters: + + target: + + Name of the configuration datastore to delete. + + Positive Response: + + If the device was able to satisfy the request, an is + sent that includes an element. + + Negative Response: + + An element is included within the if the + request cannot be completed for any reason. + + Example: + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 41] + +RFC 4741 NETCONF Protocol December 2006 + + +7.5. + + Description: + + The lock operation allows the client to lock the configuration + system of a device. Such locks are intended to be short-lived and + allow a client to make a change without fear of interaction with + other NETCONF clients, non-NETCONF clients (e.g., SNMP and command + line interface (CLI) scripts), and human users. + + An attempt to lock the configuration MUST fail if an existing + session or other entity holds a lock on any portion of the lock + target. + + When the lock is acquired, the server MUST prevent any changes to + the locked resource other than those requested by this session. + SNMP and CLI requests to modify the resource MUST fail with an + appropriate error. + + The duration of the lock is defined as beginning when the lock is + acquired and lasting until either the lock is released or the + NETCONF session closes. The session closure may be explicitly + performed by the client, or implicitly performed by the server + based on criteria such as failure of the underlying transport, or + simple inactivity timeout. This criteria is dependent on the + implementation and the underlying transport. + + The lock operation takes a mandatory parameter, target. The + target parameter names the configuration that will be locked. + When a lock is active, using the operation on the + locked configuration and using the locked configuration as a + target of the operation will be disallowed by any + other NETCONF session. Additionally, the system will ensure that + these locked configuration resources will not be modified by other + non-NETCONF management operations such as SNMP and CLI. The + message (at the RPC layer) can be used to force the + release of a lock owned by another NETCONF session. It is beyond + the scope of this document to define how to break locks held by + other entities. + + A lock MUST not be granted if either of the following conditions + is true: + + * A lock is already held by any NETCONF session or another + entity. + + + + + + +Enns Standards Track [Page 42] + +RFC 4741 NETCONF Protocol December 2006 + + + * The target configuration is , it has already been + modified, and these changes have not been committed or rolled + back. + + The server MUST respond with either an element or an + . + + A lock will be released by the system if the session holding the + lock is terminated for any reason. + + Parameters: + + target: + + Name of the configuration datastore to lock. + + Positive Response: + + If the device was able to satisfy the request, an is + sent that contains an element. + + Negative Response: + + An element is included in the if the + request cannot be completed for any reason. + + If the lock is already held, the element will be + 'lock-denied' and the element will include the + of the lock owner. If the lock is held by a non- + NETCONF entity, a of 0 (zero) is included. Note that + any other entity performing a lock on even a partial piece of a + target will prevent a NETCONF lock (which is global) from being + obtained on that target. + + Example: + + The following example shows a successful acquisition of a lock. + + + + + + + + + + + + + +Enns Standards Track [Page 43] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + Example: + + The following example shows a failed attempt to acquire a lock + when the lock is already in use. + + + + + + + + + + + + + protocol + lock-denied + error + + Lock failed, lock is already held + + + 454 + + + + + +7.6. + + Description: + + The unlock operation is used to release a configuration lock, + previously obtained with the operation. + + An unlock operation will not succeed if any of the following + conditions are true: + + * the specified lock is not currently active + + + + +Enns Standards Track [Page 44] + +RFC 4741 NETCONF Protocol December 2006 + + + * the session issuing the operation is not the same + session that obtained the lock + + The server MUST respond with either an element or an + . + + Parameters: + + target: + + Name of the configuration datastore to unlock. + + A NETCONF client is not permitted to unlock a configuration + datastore that it did not lock. + + Positive Response: + + If the device was able to satisfy the request, an is + sent that contains an element. + + Negative Response: + + An element is included in the if the + request cannot be completed for any reason. + + Example: + + + + + + + + + + + + + +7.7. + + Description: + + Retrieve running configuration and device state information. + + + + + +Enns Standards Track [Page 45] + +RFC 4741 NETCONF Protocol December 2006 + + + Parameters: + + filter: + + This parameter specifies the portion of the system + configuration and state data to retrieve. If this parameter is + empty, all the device configuration and state information is + returned. + + The filter element may optionally contain a 'type' attribute. + This attribute indicates the type of filtering syntax used + within the filter element. The default filtering mechanism in + NETCONF is referred to as subtree filtering and is described in + Section 6. The value 'subtree' explicitly identifies this type + of filtering. + + If the NETCONF peer supports the :xpath capability + (Section 8.9), the value "xpath" may be used to indicate that + the select attribute of the filter element contains an XPath + expression. + + Positive Response: + + If the device was able to satisfy the request, an is + sent. The section contains the appropriate subset. + + Negative Response: + + An element is included in the if the + request cannot be completed for any reason. + + Example: + + + + + + + + eth0 + + + + + + + + + + +Enns Standards Track [Page 46] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + eth0 + 45621 + 774344 + + + + + + +7.8. + + Description: + + Request graceful termination of a NETCONF session. + + When a NETCONF server receives a request, it will + gracefully close the session. The server will release any locks + and resources associated with the session and gracefully close any + associated connections. Any NETCONF requests received after a + request will be ignored. + + Positive Response: + + If the device was able to satisfy the request, an is + sent that includes an element. + + Negative Response: + + An element is included in the if the + request cannot be completed for any reason. + + Example: + + + + + + + + + + + +Enns Standards Track [Page 47] + +RFC 4741 NETCONF Protocol December 2006 + + +7.9. + + Description: + + Force the termination of a NETCONF session. + + When a NETCONF entity receives a request for an + open session, it will abort any operations currently in process, + release any locks and resources associated with the session, and + close any associated connections. + + If a NETCONF server receives a request while + processing a confirmed commit (Section 8.4), it must restore the + configuration to its state before the confirmed commit was issued. + + Otherwise, the operation does not roll back + configuration or other device state modifications made by the + entity holding the lock. + + Parameters: + + session-id: + + Session identifier of the NETCONF session to be terminated. If + this value is equal to the current session ID, an + 'invalid-value' error is returned. + + Positive Response: + + If the device was able to satisfy the request, an is + sent that includes an element. + + Negative Response: + + An element is included in the if the + request cannot be completed for any reason. + + Example: + + + + 4 + + + + + + + + +Enns Standards Track [Page 48] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + +8. Capabilities + + This section defines a set of capabilities that a client or a server + MAY implement. Each peer advertises its capabilities by sending them + during an initial capabilities exchange. Each peer needs to + understand only those capabilities that it might use and MUST ignore + any capability received from the other peer that it does not require + or does not understand. + + Additional capabilities can be defined using the template in + Appendix C. Future capability definitions may be published as + standards by standards bodies or published as proprietary extensions. + + A NETCONF capability is identified with a URI. The base capabilities + are defined using URNs following the method described in RFC 3553 + [6]. Capabilities defined in this document have the following + format: + + urn:ietf:params:netconf:capability:{name}:1.0 + + where {name} is the name of the capability. Capabilities are often + referenced in discussions and email using the shorthand :{name}. For + example, the foo capability would have the formal name + "urn:ietf:params:netconf:capability:foo:1.0" and be called ":foo". + The shorthand form MUST NOT be used inside the protocol. + +8.1. Capabilities Exchange + + Capabilities are advertised in messages sent by each peer during + session establishment. When the NETCONF session is opened, each peer + (both client and server) MUST send a element containing a + list of that peer's capabilities. Each peer MUST send at least the + base NETCONF capability, "urn:ietf:params:netconf:base:1.0". + + A server sending the element MUST include a + element containing the session ID for this NETCONF session. A client + sending the element MUST NOT include a element. + + A server receiving a element MUST NOT continue the + NETCONF session. Similarly, a client that does not receive a + element in the server's message MUST NOT + continue the NETCONF session. In both cases, the underlying + transport should be closed. + + + +Enns Standards Track [Page 49] + +RFC 4741 NETCONF Protocol December 2006 + + + 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. + + + + + urn:ietf:params:netconf:base:1.0 + + + urn:ietf:params:netconf:capability:startup:1.0 + + + http://example.net/router/2.3/myfeature + + + 4 + + + Each peer sends its element simultaneously as soon as the + connection is open. A peer MUST NOT wait to receive the capability + set from the other side before sending its own set. + +8.2. Writable-Running Capability + +8.2.1. Description + + The :writable-running capability indicates that the device supports + direct writes to the configuration datastore. In other + words, the device supports edit-config and copy-config operations + where the configuration is the target. + +8.2.2. Dependencies + + None. + +8.2.3. Capability Identifier + + The :writable-running capability is identified by the following + capability string: + + urn:ietf:params:netconf:capability:writable-running:1.0 + + + + + + + + + +Enns Standards Track [Page 50] + +RFC 4741 NETCONF Protocol December 2006 + + +8.2.4. New Operations + + None. + +8.2.5. Modifications to Existing Operations + +8.2.5.1. + + The :writable-running capability modifies the operation + to accept the element as a . + +8.2.5.2. + + The :writable-running capability modifies the operation + to accept the element as a . + +8.3. Candidate Configuration Capability + +8.3.1. Description + + The candidate configuration capability, :candidate, indicates that + the device supports a candidate configuration datastore, which is + used to hold configuration data that can be manipulated without + impacting the device's current configuration. The candidate + configuration is a full configuration data set that serves as a work + place for creating and manipulating configuration data. Additions, + deletions, and changes may be made to this data to construct the + desired configuration data. A operation may be performed at + any time that causes the device's running configuration to be set to + the value of the candidate configuration. + + The operation effectively sets the running configuration to + the current contents of the candidate configuration. While it could + be modeled as a simple copy, it is done as a distinct operation for a + number of reasons. In keeping high-level concepts as first class + operations, we allow developers to see more clearly both what the + client is requesting and what the server must perform. This keeps + the intentions more obvious, the special cases less complex, and the + interactions between operations more straightforward. For example, + the :confirmed-commit capability (Section 8.4) would make no sense as + a "copy confirmed" operation. + + The candidate configuration may be shared among multiple sessions. + Unless a client has specific information that the candidate + configuration is not shared, it must assume that other sessions may + be able to modify the candidate configuration at the same time. It + is therefore prudent for a client to lock the candidate configuration + before modifying it. + + + +Enns Standards Track [Page 51] + +RFC 4741 NETCONF Protocol December 2006 + + + The client can discard any uncommitted changes to the candidate + configuration by executing the operation. This + operation reverts the contents of the candidate configuration to the + contents of the running configuration. + +8.3.2. Dependencies + + None. + +8.3.3. Capability Identifier + + The :candidate capability is identified by the following capability + string: + + urn:ietf:params:netconf:capability:candidate:1.0 + +8.3.4. New Operations + +8.3.4.1. + + Description: + + When a candidate configuration's content is complete, the + configuration data can be committed, publishing the data set to + the rest of the device and requesting the device to conform to + the behavior described in the new configuration. + + To commit the candidate configuration as the device's new + current configuration, use the operation. + + The operation instructs the device to implement the + configuration data contained in the candidate configuration. + If the device is unable to commit all of the changes in the + candidate configuration datastore, then the running + configuration MUST remain unchanged. If the device does + succeed in committing, the running configuration MUST be + updated with the contents of the candidate configuration. + + If the system does not have the :candidate capability, the + operation is not available. + + Positive Response: + + If the device was able to satisfy the request, an + is sent that contains an element. + + + + + + +Enns Standards Track [Page 52] + +RFC 4741 NETCONF Protocol December 2006 + + + Negative Response: + + An element is included in the if the + request cannot be completed for any reason. + + Example: + + + + + + + + + +8.3.4.2. + + If the client decides that the candidate configuration should not be + committed, the operation can be used to revert the + candidate configuration to the current running configuration. + + + + + + This operation discards any uncommitted changes by resetting the + candidate configuration with the content of the running + configuration. + +8.3.5. Modifications to Existing Operations + +8.3.5.1. , , , and + + The candidate configuration can be used as a source or target of any + , , , or operation + as a or parameter. The element is used + to indicate the candidate configuration: + + + + + + + + + + + +Enns Standards Track [Page 53] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + +8.3.5.2. and + + The candidate configuration can be locked using the operation + with the element as the parameter: + + + + + + + + + + Similarly, the candidate configuration is unlocked using the + element as the parameter: + + + + + + + + + + When a client fails with outstanding changes to the candidate + configuration, recovery can be difficult. To facilitate easy + recovery, any outstanding changes are discarded when the lock is + released, whether explicitly with the operation or + implicitly from session failure. + + + + + + + + + + + +Enns Standards Track [Page 54] + +RFC 4741 NETCONF Protocol December 2006 + + +8.4. Confirmed Commit Capability + +8.4.1. Description + + The :confirmed-commit capability indicates that the server will + support the and parameters for the + protocol operation. See Section 8.3 for further details on + the operation. + + A confirmed commit operation MUST be reverted if a follow-up commit + (called the "confirming commit") is not issued within 600 seconds (10 + minutes). The timeout period can be adjusted with the + element. The confirming commit can itself include + a parameter. + + If the session issuing the confirmed commit is terminated for any + reason before the confirm timeout expires, the server MUST restore + the configuration to its state before the confirmed commit was + issued. + + If the device reboots for any reason before the confirm timeout + expires, the server MUST restore the configuration to its state + before the confirmed commit was issued. + + If a confirming commit is not issued, the device will revert its + configuration to the state prior to the issuance of the confirmed + commit. Note that any commit operation, including a commit which + introduces additional changes to the configuration, will serve as a + confirming commit. Thus to cancel a confirmed commit and revert + changes without waiting for the confirm timeout to expire, the + manager can explicitly restore the configuration to its state before + the confirmed commit was issued. + + For shared configurations, this feature can cause other configuration + changes (for example, via other NETCONF sessions) to be inadvertently + altered or removed, unless the configuration locking feature is used + (in other words, the lock is obtained before the edit-config + operation is started). Therefore, it is strongly suggested that in + order to use this feature with shared configuration databases, + configuration locking should also be used. + +8.4.2. Dependencies + + The :confirmed-commit capability is only relevant if the :candidate + capability is also supported. + + + + + + +Enns Standards Track [Page 55] + +RFC 4741 NETCONF Protocol December 2006 + + +8.4.3. Capability Identifier + + The :confirmed-commit capability is identified by the following + capability string: + + urn:ietf:params:netconf:capability:confirmed-commit:1.0 + +8.4.4. New Operations + + None. + +8.4.5. Modifications to Existing Operations + +8.4.5.1. + + The :confirmed-commit capability allows 2 additional parameters to + the operation. + + Parameters: + + confirmed: + + Perform a confirmed commit operation. + + confirm-timeout: + + Timeout period for confirmed commit, in seconds. If + unspecified, the confirm timeout defaults to 600 seconds. + + Example: + + + + + 120 + + + + + + + + + + + + + + +Enns Standards Track [Page 56] + +RFC 4741 NETCONF Protocol December 2006 + + +8.5. Rollback on Error Capability + +8.5.1. Description + + This capability indicates that the server will support the + 'rollback-on-error' value in the parameter to the + operation. + + For shared configurations, this feature can cause other configuration + changes (for example, via other NETCONF sessions) to be inadvertently + altered or removed, unless the configuration locking feature is used + (in other words, the lock is obtained before the edit-config + operation is started). Therefore, it is strongly suggested that in + order to use this feature with shared configuration databases, + configuration locking also be used. + +8.5.2. Dependencies + + None + +8.5.3. Capability Identifier + + The :rollback-on-error capability is identified by the following + capability string: + + urn:ietf:params:netconf:capability:rollback-on-error:1.0 + +8.5.4. New Operations + + None. + +8.5.5. Modifications to Existing Operations + +8.5.5.1. + + The :rollback-on-error capability allows the 'rollback-on-error' + value to the parameter on the operation. + + + + + + + + rollback-on-error + + + + + +Enns Standards Track [Page 57] + +RFC 4741 NETCONF Protocol December 2006 + + + + Ethernet0/0 + 100000 + + + + + + + + + + +8.6. Validate Capability + +8.6.1. Description + + Validation consists of checking a candidate configuration for + syntactical and semantic errors before applying the configuration to + the device. + + If this capability is advertised, the device supports the + protocol operation and checks at least for syntax errors. In + addition, this capability supports the test-option parameter to the + operation and, when it is provided, checks at least for + syntax errors. + +8.6.2. Dependencies + + None. + +8.6.3. Capability Identifier + + The :validate capability is identified by the following capability + string: + + urn:ietf:params:netconf:capability:validate:1.0 + +8.6.4. New Operations + +8.6.4.1. + + Description: + + This protocol operation validates the contents of the specified + configuration. + + + + +Enns Standards Track [Page 58] + +RFC 4741 NETCONF Protocol December 2006 + + + Parameters: + + source: + + Name of the configuration datastore being validated, such as + or the element containing the + configuration subtree to validate. + + Positive Response: + + If the device was able to satisfy the request, an + is sent that contains an element. + + Negative Response: + + An element is included in the if the + request cannot be completed for any reason. + + A validate operation can fail for any of the following reasons: + + + Syntax errors + + + Missing parameters + + + References to undefined configuration data + + Example: + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 59] + +RFC 4741 NETCONF Protocol December 2006 + + +8.7. Distinct Startup Capability + +8.7.1. Description + + The device supports separate running and startup configuration + datastores. Operations that affect the running configuration will + not be automatically copied to the startup configuration. An + explicit operation from the to the + must be invoked to update the startup configuration to the current + contents of the running configuration. NETCONF protocol operations + refer to the startup datastore using the element. + +8.7.2. Dependencies + + None. + +8.7.3. Capability Identifier + + The :startup capability is identified by the following capability + string: + + urn:ietf:params:netconf:capability:startup:1.0 + +8.7.4. New Operations + + None. + +8.7.5. Modifications to Existing Operations + +8.7.5.1. General + + The :startup capability adds the configuration datastore + to arguments of several NETCONF operations. The server MUST support + the following additional values: + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 60] + +RFC 4741 NETCONF Protocol December 2006 + + + +--------------------+--------------------------+-------------------+ + | Operation | Parameters | Notes | + +--------------------+--------------------------+-------------------+ + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | If :validate is | + | | | advertised | + +--------------------+--------------------------+-------------------+ + + To save the startup configuration, use the copy-config operation to + copy the configuration datastore to the + configuration datastore. + + + + + + + + + + + + +8.8. URL Capability + +8.8.1. Description + + The NETCONF peer has the ability to accept the element in + and parameters. The capability is further + identified by URL arguments indicating the URL schemes supported. + +8.8.2. Dependencies + + None. + + + + + + + + + +Enns Standards Track [Page 61] + +RFC 4741 NETCONF Protocol December 2006 + + +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. + + The :url capability modifies the operation to accept + the element as an alternative to the parameter. If + the element is specified, then it should identify a local + configuration file. + +8.8.5.2. + + The :url capability modifies the operation to accept + the element as the value of the and the + parameters. + +8.8.5.3. + + The :url capability modifies the operation to accept + the element as the value of the parameters. If this + parameter contains a URL, then it should identify a local + configuration file. + +8.8.5.4. + + The :url capability modifies the operation to accept the + element as the value of the parameter. + + + + + + + + + +Enns Standards Track [Page 62] + +RFC 4741 NETCONF Protocol December 2006 + + +8.9. XPath Capability + +8.9.1. Description + + The XPath capability indicates that the NETCONF peer supports the use + of XPath expressions in the element. XPath is described in + [2]. + + The XPath expression must return a node-set. + + The XPath expression is evaluated in a context where the context node + is the root node, and the set of namespace declarations are those in + scope on the filter element, including the default namespace. + +8.9.2. Dependencies + + None. + +8.9.3. Capability Identifier + + The :xpath capability is identified by the following capability + string: + + urn:ietf:params:netconf:capability:xpath:1.0 + +8.9.4. New Operations + + None. + +8.9.5. Modifications to Existing Operations + +8.9.5.1. and + + The :xpath capability modifies the and operations + to accept the value "xpath" in the type attribute of the filter + element. When the type attribute is set to "xpath", a select + attribute MUST be present on the filter element. The select + attribute will be treated as an XPath expression and used to filter + the returned data. The filter element itself MUST be empty in this + case. + + For example: + + + + + + + + +Enns Standards Track [Page 63] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + +9. Security Considerations + + This document does not specify an authorization scheme, as such a + scheme should be tied to a meta-data model or a data model. + Implementors SHOULD provide a comprehensive authorization scheme with + NETCONF. + + Authorization of individual users via the NETCONF server may or may + not map 1:1 to other interfaces. First, the data models may be + incompatible. Second, it may be desirable to authorize based on + mechanisms available in the transport protocol layer (TELNET, SSH, + etc). + + In addition, operations on configurations may have unintended + consequences if those operations are also not guarded by the global + lock on the files or objects being operated upon. For instance, a + partially complete access list could be committed from a candidate + configuration unbeknownst to the owner of the lock of the candidate + configuration, leading to either an insecure or inaccessible device + if the lock on the candidate configuration does not also apply to the + operation when applied to it. + + Configuration information is by its very nature sensitive. Its + transmission in the clear and without integrity checking leaves + devices open to classic eavesdropping attacks. Configuration + information often contains passwords, user names, service + descriptions, and topological information, all of which are + sensitive. Because of this, this protocol should be implemented + carefully with adequate attention to all manner of attack one might + expect to experience with other management interfaces. + + The protocol, therefore, must minimally support options for both + confidentiality and authentication. It is anticipated that the + underlying protocol (SSH, BEEP, etc) will provide for both + confidentiality and authentication, as is required. It is further + expected that the identity of each end of a NETCONF session will be + available to the other in order to determine authorization for any + given request. One could also easily envision additional + information, such as transport and encryption methods, being made + available for purposes of authorization. NETCONF itself provide no + means to re-authenticate, much less authenticate. All such actions + occur at lower layers. + + + +Enns Standards Track [Page 64] + +RFC 4741 NETCONF Protocol December 2006 + + + Different environments may well allow different rights prior to and + then after authentication. Thus, an authorization model is not + specified in this document. When an operation is not properly + authorized, a simple "access denied" is sufficient. Note that + authorization information may be exchanged in the form of + configuration information, which is all the more reason to ensure the + security of the connection. + + That having been said, it is important to recognize that some + operations are clearly more sensitive by nature than others. For + instance, to the startup or running configurations is + clearly not a normal provisioning operation, whereas + is. Such global operations MUST disallow the changing of information + that an individual does not have authorization to perform. For + example, if a user A is not allowed to configure an IP address on an + interface but user B has configured an IP address on an interface in + the configuration, user A must not be allowed to commit + the configuration. + + Similarly, just because someone says "go write a configuration + through the URL capability at a particular place", this does not mean + that an element should do it without proper authorization. + + The operation will demonstrate that NETCONF is intended for + use by systems that have at least some trust of the administrator. + As specified in this document, it is possible to lock portions of a + configuration that a principal might not otherwise have access to. + After all, the entire configuration is locked. To mitigate this + problem, there are two approaches. It is possible to kill another + NETCONF session programmatically from within NETCONF if one knows the + session identifier of the offending session. The other possible way + to break a lock is to provide an function within the device's native + user interface. These two mechanisms suffer from a race condition + that may be ameliorated by removing the offending user from an AAA + server. However, such a solution is not useful in all deployment + scenarios, such as those where SSH public/private key pairs are used. + + + + + + + + + + + + + + + +Enns Standards Track [Page 65] + +RFC 4741 NETCONF Protocol December 2006 + + +10. IANA Considerations + +10.1. NETCONF XML Namespace + + This document registers a URI for the NETCONF XML namespace in the + IETF XML registry [7]. + + Following the format in RFC 3688, IANA has made the following + registration. + + URI: urn:ietf:params:xml:ns:netconf:base:1.0 + + Registrant Contact: The IESG. + + XML: N/A, the requested URI is an XML namespace. + +10.2. NETCONF XML Schema + + This document registers a URI for the NETCONF XML schema in the IETF + XML registry [7]. + + Following the format in RFC 3688, IANA has made the following + registration. + + URI: urn:ietf:params:xml:schema:netconf + + Registrant Contact: The IESG. + + XML: Appendix B of this document. + +10.3. NETCONF Capability URNs + + This document creates a registry that allocates NETCONF capability + identifiers. Additions to the registry require IETF Standards + Action. + + The initial content of the registry contains the capability URNs + defined in Section 8. + + Following the guidelines in RFC 3553 [6], IANA assigned a NETCONF + sub-namespace as follows: + + Registry name: netconf + + Specification: Section 8 of this document. + + Repository: The following table. + + + + +Enns Standards Track [Page 66] + +RFC 4741 NETCONF Protocol December 2006 + + + +--------------------+----------------------------------------------+ + | Index | Capability Identifier | + +--------------------+----------------------------------------------+ + | :writable-running | urn:ietf:params:netconf:capability:writable- | + | | running:1.0 | + | | | + | :candidate | urn:ietf:params:netconf:capability:candidate | + | | :1.0 | + | | | + | :confirmed-commit | urn:ietf:params:netconf:capability:confirmed | + | | -commit:1.0 | + | | | + | :rollback-on-error | urn:ietf:params:netconf:capability:rollback- | + | | on-error:1.0 | + | | | + | :validate | urn:ietf:params:netconf:capability:validate: | + | | 1.0 | + | | | + | :startup | urn:ietf:params:netconf:capability:startup:1 | + | | .0 | + | | | + | :url | urn:ietf:params:netconf:capability:url:1.0 | + | | | + | :xpath | urn:ietf:params:netconf:capability:xpath:1.0 | + +--------------------+----------------------------------------------+ + + Index value: The capability name. + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 67] + +RFC 4741 NETCONF Protocol December 2006 + + +11. Authors and Acknowledgements + + This document was written by: + + Andy Bierman + + Ken Crozier, Cisco Systems + + Rob Enns, Juniper Networks + + Ted Goddard, IceSoft + + Eliot Lear, Cisco Systems + + Phil Shafer, Juniper Networks + + Steve Waldbusser + + Margaret Wasserman, ThingMagic + + The authors would like to acknowledge the members of the NETCONF + working group. In particular, we would like to thank Wes Hardaker + for his persistance and patience in assisting us with security + considerations. We would also like to thank Randy Presuhn, Sharon + Chisholm, Juergen Schoenwalder, Glenn Waters, David Perkins, Weijing + Chen, Simon Leinen, Keith Allen, and Dave Harrington for all of their + valuable advice. + +12. References + +12.1. Normative References + + [1] Sperberg-McQueen, C., Paoli, J., Maler, E., and T. Bray, + "Extensible Markup Language (XML) 1.0 (Second Edition)", World + Wide Web Consortium, http://www.w3.org/TR/2000/REC-xml-20001006, + October 2000. + + [2] Clark, J. and S. DeRose, "XML Path Language (XPath) Version + 1.0", World Wide Web Consortium Recommendation, + http://www.w3.org/TR/1999/REC-xpath-19991116, November 1999. + + [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [4] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration + Protocol over Secure SHell (SSH)", RFC 4742, December 2006. + + + + + +Enns Standards Track [Page 68] + +RFC 4741 NETCONF Protocol December 2006 + + + [5] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, + January 2005. + + [6] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An IETF + URN Sub-namespace for Registered Protocol Parameters", BCP 73, + RFC 3553, June 2003. + + [7] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + January 2004. + +12.2. Informative References + + [8] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide + Web Consortium Recommendation, http://www.w3.org/TR/1999/REC- + xslt-19991116, November 1999. + + [9] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) + Protocol Version 1.1", RFC 4346, April 2006. + + [10] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Protocol + Architecture", RFC 4251, January 2006. + + [11] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote + Authentication Dial In User Service (RADIUS)", RFC 2865, + June 2000. + + [12] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the + Use of Extensible Markup Language (XML) within IETF Protocols", + BCP 70, RFC 3470, January 2003. + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 69] + +RFC 4741 NETCONF Protocol December 2006 + + +Appendix A. NETCONF Error List + + Tag: in-use + Error-type: protocol, application + Severity: error + Error-info: none + Description: The request requires a resource that already in use. + + Tag: invalid-value + Error-type: protocol, application + Severity: error + Error-info: none + Description: The request specifies an unacceptable value for one + or more parameters. + + Tag: too-big + Error-type: transport, rpc, protocol, application + Severity: error + Error-info: none + Description: The request or response (that would be generated) is too + large for the implementation to handle. + + Tag: missing-attribute + Error-type: rpc, protocol, application + Severity: error + Error-info: : name of the missing attribute + : name of the element that should + contain the missing attribute + Description: An expected attribute is missing. + + Tag: bad-attribute + Error-type: rpc, protocol, application + Severity: error + Error-info: : name of the attribute w/ bad value + : name of the element that contains + the attribute with the bad value + Description: An attribute value is not correct; e.g., wrong type, + out of range, pattern mismatch. + + Tag: unknown-attribute + Error-type: rpc, protocol, application + Severity: error + Error-info: : name of the unexpected attribute + : name of the element that contains + the unexpected attribute + Description: An unexpected attribute is present. + + + + + +Enns Standards Track [Page 70] + +RFC 4741 NETCONF Protocol December 2006 + + + Tag: missing-element + Error-type: rpc, protocol, application + Severity: error + Error-info: : name of the missing element + Description: An expected element is missing. + + Tag: bad-element + Error-type: rpc, protocol, application + Severity: error + Error-info: : name of the element w/ bad value + Description: An element value is not correct; e.g., wrong type, + out of range, pattern mismatch. + + Tag: unknown-element + Error-type: rpc, protocol, application + Severity: error + Error-info: : name of the unexpected element + Description: An unexpected element is present. + + Tag: unknown-namespace + Error-type: rpc, protocol, application + Severity: error + Error-info: : name of the element that contains + the unexpected namespace + : name of the unexpected namespace + Description: An unexpected namespace is present. + + Tag: access-denied + Error-type: rpc, protocol, application + Severity: error + Error-info: none + Description: Access to the requested RPC, protocol operation, + or data model is denied because authorization failed. + + Tag: lock-denied + Error-type: protocol + Severity: error + Error-info: : session ID of session holding the + requested lock, or zero to indicate a non-NETCONF + entity holds the lock + Description: Access to the requested lock is denied because the + lock is currently held by another entity. + + + + + + + + + +Enns Standards Track [Page 71] + +RFC 4741 NETCONF Protocol December 2006 + + + Tag: resource-denied + Error-type: transport, rpc, protocol, application + Severity: error + Error-info: none + Description: Request could not be completed because of insufficient + resources. + + Tag: rollback-failed + Error-type: protocol, application + Severity: error + Error-info: none + Description: Request to rollback some configuration change (via + rollback-on-error or discard-changes operations) was + not completed for some reason. + + Tag: data-exists + Error-type: application + 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. + + Tag: data-missing + Error-type: application + Severity: error + Error-info: none + Description: Request could not be completed because the relevant + data model content does not exist. For example, + a 'replace' or 'delete' operation was attempted on + data that does not exist. + + Tag: operation-not-supported + Error-type: rpc, protocol, application + Severity: error + Error-info: none + Description: Request could not be completed because the requested + operation is not supported by this implementation. + + Tag: operation-failed + Error-type: rpc, protocol, application + 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. + + + + +Enns Standards Track [Page 72] + +RFC 4741 NETCONF Protocol December 2006 + + + Tag: partial-operation + Error-type: application + Severity: error + Error-info: : identifies an element in the data model + for which the requested operation has been completed + for that node and all its child nodes. This element + can appear zero or more times in the + container. + + : identifies an element in the data model + for which the requested operation has failed for that + node and all its child nodes. This element + can appear zero or more times in the + container. + + : identifies an element in the data model + for which the requested operation was not attempted for + that node and all its child nodes. This element + can appear zero or more times in the + container. + Description: Some part of the requested operation failed or was + not attempted for some reason. Full cleanup has + not been performed (e.g., rollback not supported) + by the server. The error-info container is used + to identify which portions of the application + data model content for which the requested operation + has succeeded (), failed (), + or not been attempted (). + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 73] + +RFC 4741 NETCONF Protocol December 2006 + + +Appendix B. XML Schema for NETCONF RPC and Protocol Operations + + BEGIN + + + + + + + + This import accesses the xml: attribute groups for the + xml:lang as declared on the error-message element. + + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 74] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 75] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 76] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Use of the rollback-on-error value requires + the :rollback-on-error capability. + + + + + + + + +Enns Standards Track [Page 77] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + + + + + + + + + + + Use of the xpath value requires the :xpath capability. + + + + + + + + + + + + + + + + +Enns Standards Track [Page 78] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + The startup datastore can be used only if the :startup + capability is advertised. The candidate datastore can + be used only if the :candidate datastore is advertised. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 79] + +RFC 4741 NETCONF Protocol December 2006 + + + + + Use of the url element requires the :url capability. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 80] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + Use of the test-option element requires the + :validate capability. Use of the url element + requires the :url capability. + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 81] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 82] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + + + + + + + + + The validate operation requires the :validate capability. + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 83] + +RFC 4741 NETCONF Protocol December 2006 + + + + + The commit operation requires the :candidate capability. + + + + + + + + Use of the confirmed and confirm-timeout elements + requires the :confirmed-commit capability. + + + + + + + + + + + + + + The discard-changes operation requires the + :candidate capability. + + + + + + + + + + + + + + + +Enns Standards Track [Page 84] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + END + + + + + + + + + + + +Enns Standards Track [Page 85] + +RFC 4741 NETCONF Protocol December 2006 + + +Appendix C. Capability Template + +C.1. capability-name (template) + +C.1.1. Overview + +C.1.2. Dependencies + +C.1.3. Capability Identifier + + The {name} capability is identified by the following capability + string: + + {capability uri} + +C.1.4. New Operations + +C.1.4.1. + +C.1.5. Modifications to Existing Operations + +C.1.5.1. + + If existing operations are not modified by this capability, this + section may be omitted. + +C.1.6. Interactions with Other Capabilities + + If this capability does not interact with other capabilities, this + section may be omitted. + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 86] + +RFC 4741 NETCONF Protocol December 2006 + + +Appendix D. Configuring Multiple Devices with NETCONF + +D.1. Operations on Individual Devices + + Consider the work involved in performing a configuration update + against a single individual device. In making a change to the + configuration, the application needs to build trust that its change + has been made correctly and that it has not impacted the operation of + the device. The application (and the application user) should feel + confident that their change has not damaged the network. + + Protecting each individual device consists of a number of steps: + + o Acquiring the configuration lock. + + o Loading the update. + + o Validating the incoming configuration. + + o Checkpointing the running configuration. + + o Changing the running configuration. + + o Testing the new configuration. + + o Making the change permanent (if desired). + + o Releasing the configuration lock. + + Let's look at the details of each step. + +D.1.1. Acquiring the Configuration Lock + + A lock should be acquired to prevent simultaneous updates from + multiple sources. If multiple sources are affecting the device, the + application is hampered in both testing of its change to the + configuration and in recovery should the update fail. Acquiring a + short-lived lock is a simple defense to prevent other parties from + introducing unrelated changes. + + The lock can be acquired using the operation. + + + + + + + + + +Enns Standards Track [Page 87] + +RFC 4741 NETCONF Protocol December 2006 + + + + + +D.1.2. Loading the Update + + The configuration can be loaded onto the device without impacting the + running system. If the :url capability is supported and lists "file" + as a supported scheme, incoming changes can be placed in a local + file. + + + + + file://incoming.conf + + + + + + + + + + If the :candidate capability is supported, the candidate + configuration can be used. + + + + + + + + + + + + + If the update fails, the user file can be deleted using the + operation, or the candidate configuration can be + reverted using the operation. + + + + + + + + + +Enns Standards Track [Page 88] + +RFC 4741 NETCONF Protocol December 2006 + + +D.1.3. Validating the Incoming Configuration + + Before the incoming configuration is applied, validating it is often + useful. Validation allows the application to gain confidence that + the change will succeed and simplifies recovery if it does not. + + If the device supports the :url capability and lists "file" as a + supported scheme, use the operation with the + parameter set to the proper user file: + + + + + file://incoming.conf + + + + + If the device supports the :candidate capability, some validation + will be performed as part of loading the incoming configuration into + the candidate. For full validation, either pass the + parameter during the step given above, or use the + operation with the parameter set to . + + + + + + + + + +D.1.4. Checkpointing the Running Configuration + + The running configuration can be saved into a local file as a + checkpoint before loading the new configuration. If the update + fails, the configuration can be restored by reloading the checkpoint + file. + + The checkpoint file can be created using the operation. + + + + + file://checkpoint.conf + + + +Enns Standards Track [Page 89] + +RFC 4741 NETCONF Protocol December 2006 + + + + + + + + + + To restore the checkpoint file, reverse the source and target + parameters. + +D.1.5. Changing the Running Configuration + + When the incoming configuration has been safely loaded onto the + device and validated, it is ready to impact the running system. + + If the device supports the :url capability and lists "file" as a + supported scheme, use the operation to merge the + incoming configuration into the running configuration. + + + + + + + + file://incoming.conf + + + + + If the device supports the :candidate capability, use the + operation to set the running configuration to the candidate + configuration. Use the parameter to allow automatic + reversion to the original configuration if connectivity to the device + fails. + + + + + 120 + + + + + + + + + +Enns Standards Track [Page 90] + +RFC 4741 NETCONF Protocol December 2006 + + +D.1.6. Testing the New Configuration + + Now that the incoming configuration has been integrated into the + running configuration, the application needs to gain trust that the + change has affected the device in the way intended without affecting + it negatively. + + To gain this confidence, the application can run tests of the + operational state of the device. The nature of the test is dependent + on the nature of the change and is outside the scope of this + document. Such tests may include reachability from the system + running the application (using ping), changes in reachability to the + rest of the network (by comparing the device's routing table), or + inspection of the particular change (looking for operational evidence + of the BGP peer that was just added). + +D.1.7. Making the Change Permanent + + When the configuration change is in place and the application has + sufficient faith in the proper function of this change, the + application should make the change permanent. + + If the device supports the :startup capability, the current + configuration can be saved to the startup configuration by using the + startup configuration as the target of the operation. + + + + + + + + + + + + + If the device supports the :candidate capability and a confirmed + commit was requested, the confirming commit must be sent before the + timeout expires. + + + + + + + + + +Enns Standards Track [Page 91] + +RFC 4741 NETCONF Protocol December 2006 + + +D.1.8. Releasing the Configuration Lock + + When the configuration update is complete, the lock must be released, + allowing other applications access to the configuration. + + Use the operation to release the configuration lock. + + + + + + + + + +D.2. Operations on Multiple Devices + + When a configuration change requires updates across a number of + devices, care should be taken to provide the required transaction + semantics. The NETCONF protocol contains sufficient primitives upon + which transaction-oriented operations can be built. Providing + complete transactional semantics across multiple devices is + prohibitively expensive, but the size and number of windows for + failure scenarios can be reduced. + + There are two classes of multi-device operations. The first class + allows the operation to fail on individual devices without requiring + all devices to revert to their original state. The operation can be + retried at a later time, or its failure simply reported to the user. + An example of this class might be adding an NTP server. For this + class of operations, failure avoidance and recovery are focused on + the individual device. This means recovery of the device, reporting + the failure, and perhaps scheduling another attempt. + + The second class is more interesting, requiring that the operation + should complete on all devices or be fully reversed. The network + should either be transformed into a new state or be reset to its + original state. For example, a change to a VPN may require updates + to a number of devices. Another example of this might be adding a + class-of-service definition. Leaving the network in a state where + only a portion of the devices have been updated with the new + definition will lead to future failures when the definition is + referenced. + + To give transactional semantics, the same steps used in single device + operations listed above are used, but are performed in parallel + across all devices. Configuration locks should be acquired on all + + + +Enns Standards Track [Page 92] + +RFC 4741 NETCONF Protocol December 2006 + + + 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. + +Appendix E. Deferred Features + + The following features have been deferred until a future revision of + this document. + + o Granular locking of configuration objects. + + o Named configuration files/datastores. + + o Support for multiple NETCONF channels. + + o Asynchronous notifications. + + o Explicit protocol support for rollback of configuration changes to + prior versions. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 93] + +RFC 4741 NETCONF Protocol December 2006 + + +Editor's Address + + Rob Enns + Juniper Networks + 1194 North Mathilda Ave + Sunnyvale, CA 94089 + US + + EMail: rpe@juniper.net + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Enns Standards Track [Page 94] + +RFC 4741 NETCONF Protocol December 2006 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, + AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT + THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY + IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR + PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + +Enns Standards Track [Page 95] + -- cgit v1.2.3