Internet Engineering Task Force (IETF) R. Enns, Ed.
Request for Comments: 6241 Juniper Networks
Obsoletes: 4741 M. Bjorklund, Ed.
Category: Standards Track Tail-f Systems
ISSN: 2070-1721 J. Schoenwaelder, Ed.
Jacobs University
A. Bierman, Ed.
Brocade
June 2011
Network Configuration Protocol (NETCONF)
Abstract
The Network Configuration Protocol (NETCONF) defined in this document
provides mechanisms to install, manipulate, and delete the
configuration of network devices. It uses an Extensible Markup
Language (XML)-based data encoding for the configuration data as well
as the protocol messages. The NETCONF protocol operations are
realized as remote procedure calls (RPCs). This document obsoletes
RFC 4741.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6241.
Enns, et al. Standards Track [Page 1]
RFC 6241 NETCONF Protocol June 2011
Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Enns, et al. Standards Track [Page 2]
RFC 6241 NETCONF Protocol June 2011
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7
1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 8
1.3. Capabilities . . . . . . . . . . . . . . . . . . . . . . 10
1.4. Separation of Configuration and State Data . . . . . . . 10
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 11
2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 11
2.2. Authentication, Integrity, and Confidentiality . . . . . 12
2.3. Mandatory Transport Protocol . . . . . . . . . . . . . . 12
3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 13
3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2. Document Type Declarations . . . . . . . . . . . . . . . 13
4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1. Element . . . . . . . . . . . . . . . . . . . . . . 13
4.2. Element . . . . . . . . . . . . . . . . . . . 15
4.3. Element . . . . . . . . . . . . . . . . . . . 16
4.4. Element . . . . . . . . . . . . . . . . . . . . . . 19
4.5. Pipelining . . . . . . . . . . . . . . . . . . . . . . . 19
5. Configuration Model . . . . . . . . . . . . . . . . . . . . . 19
5.1. Configuration Datastores . . . . . . . . . . . . . . . . 19
5.2. Data Modeling . . . . . . . . . . . . . . . . . . . . . . 20
6. Subtree Filtering . . . . . . . . . . . . . . . . . . . . . . 20
6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 20
6.2. Subtree Filter Components . . . . . . . . . . . . . . . . 21
6.2.1. Namespace Selection . . . . . . . . . . . . . . . . . 21
6.2.2. Attribute Match Expressions . . . . . . . . . . . . . 22
6.2.3. Containment Nodes . . . . . . . . . . . . . . . . . . 23
6.2.4. Selection Nodes . . . . . . . . . . . . . . . . . . . 23
6.2.5. Content Match Nodes . . . . . . . . . . . . . . . . . 24
6.3. Subtree Filter Processing . . . . . . . . . . . . . . . . 25
6.4. Subtree Filtering Examples . . . . . . . . . . . . . . . 26
6.4.1. No Filter . . . . . . . . . . . . . . . . . . . . . . 26
6.4.2. Empty Filter . . . . . . . . . . . . . . . . . . . . 26
6.4.3. Select the Entire Subtree . . . . . . . . . . 27
6.4.4. Select All Elements within the
Subtree . . . . . . . . . . . . . . . . . . . . . . . 29
6.4.5. One Specific Entry . . . . . . . . . . . . . . 30
6.4.6. Specific Elements from a Specific Entry . . . 31
6.4.7. Multiple Subtrees . . . . . . . . . . . . . . . . . . 32
6.4.8. Elements with Attribute Naming . . . . . . . . . . . 33
7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 35
7.1. . . . . . . . . . . . . . . . . . . . . . . 35
7.2. . . . . . . . . . . . . . . . . . . . . . . 37
7.3. . . . . . . . . . . . . . . . . . . . . . . 43
7.4. . . . . . . . . . . . . . . . . . . . . . 44
7.5. . . . . . . . . . . . . . . . . . . . . . . . . . 44
Enns, et al. Standards Track [Page 3]
RFC 6241 NETCONF Protocol June 2011
7.6. . . . . . . . . . . . . . . . . . . . . . . . . 47
7.7. . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7.8. . . . . . . . . . . . . . . . . . . . . . 49
7.9. . . . . . . . . . . . . . . . . . . . . . 50
8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 51
8.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 51
8.2. Writable-Running Capability . . . . . . . . . . . . . . . 53
8.2.1. Description . . . . . . . . . . . . . . . . . . . . . 53
8.2.2. Dependencies . . . . . . . . . . . . . . . . . . . . 53
8.2.3. Capability Identifier . . . . . . . . . . . . . . . . 53
8.2.4. New Operations . . . . . . . . . . . . . . . . . . . 53
8.2.5. Modifications to Existing Operations . . . . . . . . 53
8.3. Candidate Configuration Capability . . . . . . . . . . . 53
8.3.1. Description . . . . . . . . . . . . . . . . . . . . . 53
8.3.2. Dependencies . . . . . . . . . . . . . . . . . . . . 54
8.3.3. Capability Identifier . . . . . . . . . . . . . . . . 54
8.3.4. New Operations . . . . . . . . . . . . . . . . . . . 54
8.3.5. Modifications to Existing Operations . . . . . . . . 56
8.4. Confirmed Commit Capability . . . . . . . . . . . . . . . 57
8.4.1. Description . . . . . . . . . . . . . . . . . . . . . 57
8.4.2. Dependencies . . . . . . . . . . . . . . . . . . . . 58
8.4.3. Capability Identifier . . . . . . . . . . . . . . . . 58
8.4.4. New Operations . . . . . . . . . . . . . . . . . . . 59
8.4.5. Modifications to Existing Operations . . . . . . . . 60
8.5. Rollback-on-Error Capability . . . . . . . . . . . . . . 61
8.5.1. Description . . . . . . . . . . . . . . . . . . . . . 61
8.5.2. Dependencies . . . . . . . . . . . . . . . . . . . . 62
8.5.3. Capability Identifier . . . . . . . . . . . . . . . . 62
8.5.4. New Operations . . . . . . . . . . . . . . . . . . . 62
8.5.5. Modifications to Existing Operations . . . . . . . . 62
8.6. Validate Capability . . . . . . . . . . . . . . . . . . . 63
8.6.1. Description . . . . . . . . . . . . . . . . . . . . . 63
8.6.2. Dependencies . . . . . . . . . . . . . . . . . . . . 63
8.6.3. Capability Identifier . . . . . . . . . . . . . . . . 63
8.6.4. New Operations . . . . . . . . . . . . . . . . . . . 63
8.6.5. Modifications to Existing Operations . . . . . . . . 64
8.7. Distinct Startup Capability . . . . . . . . . . . . . . . 64
8.7.1. Description . . . . . . . . . . . . . . . . . . . . . 64
8.7.2. Dependencies . . . . . . . . . . . . . . . . . . . . 65
8.7.3. Capability Identifier . . . . . . . . . . . . . . . . 65
8.7.4. New Operations . . . . . . . . . . . . . . . . . . . 65
8.7.5. Modifications to Existing Operations . . . . . . . . 65
8.8. URL Capability . . . . . . . . . . . . . . . . . . . . . 66
8.8.1. Description . . . . . . . . . . . . . . . . . . . . . 66
8.8.2. Dependencies . . . . . . . . . . . . . . . . . . . . 66
8.8.3. Capability Identifier . . . . . . . . . . . . . . . . 66
8.8.4. New Operations . . . . . . . . . . . . . . . . . . . 66
8.8.5. Modifications to Existing Operations . . . . . . . . 66
Enns, et al. Standards Track [Page 4]
RFC 6241 NETCONF Protocol June 2011
8.9. XPath Capability . . . . . . . . . . . . . . . . . . . . 67
8.9.1. Description . . . . . . . . . . . . . . . . . . . . . 67
8.9.2. Dependencies . . . . . . . . . . . . . . . . . . . . 68
8.9.3. Capability Identifier . . . . . . . . . . . . . . . . 68
8.9.4. New Operations . . . . . . . . . . . . . . . . . . . 68
8.9.5. Modifications to Existing Operations . . . . . . . . 68
9. Security Considerations . . . . . . . . . . . . . . . . . . . 69
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 71
10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 71
10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 71
10.3. NETCONF YANG Module . . . . . . . . . . . . . . . . . . . 72
10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 72
11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 73
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 73
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 74
13.1. Normative References . . . . . . . . . . . . . . . . . . 74
13.2. Informative References . . . . . . . . . . . . . . . . . 75
Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 76
Appendix B. XML Schema for NETCONF Messages Layer . . . . . . . 80
Appendix C. YANG Module for NETCONF Protocol Operations . . . . 85
Appendix D. Capability Template . . . . . . . . . . . . . . . . 105
D.1. capability-name (template) . . . . . . . . . . . . . . . 105
D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 105
D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 105
D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 105
D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 105
D.1.5. Modifications to Existing Operations . . . . . . . . 105
D.1.6. Interactions with Other Capabilities . . . . . . . . 105
Appendix E. Configuring Multiple Devices with NETCONF . . . . . 106
E.1. Operations on Individual Devices . . . . . . . . . . . . 106
E.1.1. Acquiring the Configuration Lock . . . . . . . . . . 106
E.1.2. Checkpointing the Running Configuration . . . . . . . 107
E.1.3. Loading and Validating the Incoming Configuration . . 108
E.1.4. Changing the Running Configuration . . . . . . . . . 108
E.1.5. Testing the New Configuration . . . . . . . . . . . . 109
E.1.6. Making the Change Permanent . . . . . . . . . . . . . 109
E.1.7. Releasing the Configuration Lock . . . . . . . . . . 110
E.2. Operations on Multiple Devices . . . . . . . . . . . . . 111
Appendix F. Changes from RFC 4741 . . . . . . . . . . . . . . . 112
Enns, et al. Standards Track [Page 5]
RFC 6241 NETCONF Protocol June 2011
1. Introduction
The NETCONF protocol defines a simple mechanism through which a
network device can be managed, configuration data information can be
retrieved, and new configuration data can be uploaded and
manipulated. The protocol allows the device to expose a full, formal
application programming interface (API). Applications can use this
straightforward API to send and receive full and partial
configuration data sets.
The NETCONF protocol uses a remote procedure call (RPC) paradigm. A
client encodes an RPC in XML [W3C.REC-xml-20001006] and sends it to a
server using a secure, connection-oriented session. The server
responds with a reply encoded in XML. The contents of both the
request and the response are fully described in XML DTDs or XML
schemas, or both, allowing both parties to recognize the syntax
constraints imposed on the exchange.
A key aspect of NETCONF is that it allows the functionality of the
management protocol to closely mirror the native functionality of the
device. This reduces implementation costs and allows timely access
to new features. In addition, applications can access both the
syntactic and semantic content of the device's native user interface.
NETCONF allows a client to discover the set of protocol extensions
supported by a server. These "capabilities" permit the client to
adjust its behavior to take advantage of the features exposed by the
device. The capability definitions can be easily extended in a
noncentralized manner. Standard and non-standard capabilities can be
defined with semantic and syntactic rigor. Capabilities are
discussed in Section 8.
The NETCONF protocol is a building block in a system of automated
configuration. XML is the lingua franca of interchange, providing a
flexible but fully specified encoding mechanism for hierarchical
content. NETCONF can be used in concert with XML-based
transformation technologies, such as XSLT [W3C.REC-xslt-19991116], to
provide a system for automated generation of full and partial
configurations. The system can query one or more databases for data
about networking topologies, links, policies, customers, and
services. This data can be transformed using one or more XSLT
scripts from a task-oriented, vendor-independent data schema into a
form that is specific to the vendor, product, operating system, and
software release. The resulting data can be passed to the device
using the NETCONF protocol.
Enns, et al. Standards Track [Page 6]
RFC 6241 NETCONF Protocol June 2011
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
1.1. Terminology
o candidate configuration datastore: A configuration datastore that
can be manipulated without impacting the device's current
configuration and that can be committed to the running
configuration datastore. Not all devices support a candidate
configuration datastore.
o capability: A functionality that supplements the base NETCONF
specification.
o client: Invokes protocol operations on a server. In addition, a
client can subscribe to receive notifications from a server.
o configuration data: The set of writable data that is required to
transform a system from its initial default state into its current
state.
o datastore: A conceptual place to store and access information. A
datastore might be implemented, for example, using files, a
database, flash memory locations, or combinations thereof.
o configuration datastore: The datastore holding the complete set of
configuration data that is required to get a device from its
initial default state into a desired operational state.
o message: A protocol element sent over a session. Messages are
well-formed XML documents.
o notification: A server-initiated message indicating that a certain
event has been recognized by the server.
o protocol operation: A specific remote procedure call, as used
within the NETCONF protocol.
o remote procedure call (RPC): Realized by exchanging and
messages.
o running configuration datastore: A configuration datastore holding
the complete configuration currently active on the device. The
running configuration datastore always exists.
o server: Executes protocol operations invoked by a client. In
addition, a server can send notifications to a client.
Enns, et al. Standards Track [Page 7]
RFC 6241 NETCONF Protocol June 2011
o session: Client and server exchange messages using a secure,
connection-oriented session.
o startup configuration datastore: The configuration datastore
holding the configuration loaded by the device when it boots.
Only present on devices that separate the startup configuration
datastore from the running configuration datastore.
o state data: The additional data on a system that is not
configuration data such as read-only status information and
collected statistics.
o user: The authenticated identity of the client. The authenticated
identity of a client is commonly referred to as the NETCONF
username.
1.2. Protocol Overview
NETCONF uses a simple RPC-based mechanism to facilitate communication
between a client and a server. The client can be a script or
application typically running as part of a network manager. The
server is typically a network device. The terms "device" and
"server" are used interchangeably in this document, as are "client"
and "application".
A NETCONF session is the logical connection between a network
administrator or network configuration application and a network
device. A device MUST support at least one NETCONF session and
SHOULD support multiple sessions. Global configuration attributes
can be changed during any authorized session, and the effects are
visible in all sessions. Session-specific attributes affect only the
session in which they are changed.
NETCONF can be conceptually partitioned into four layers as shown in
Figure 1.
Enns, et al. Standards Track [Page 8]
RFC 6241 NETCONF Protocol June 2011
Layer Example
+-------------+ +-----------------+ +----------------+
(4) | Content | | Configuration | | Notification |
| | | data | | data |
+-------------+ +-----------------+ +----------------+
| | |
+-------------+ +-----------------+ |
(3) | Operations | | | |
| | | | |
+-------------+ +-----------------+ |
| | |
+-------------+ +-----------------+ +----------------+
(2) | Messages | | , | | |
| | | | | |
+-------------+ +-----------------+ +----------------+
| | |
+-------------+ +-----------------------------------------+
(1) | Secure | | SSH, TLS, BEEP/TLS, SOAP/HTTP/TLS, ... |
| Transport | | |
+-------------+ +-----------------------------------------+
Figure 1: NETCONF Protocol Layers
(1) The Secure Transport layer provides a communication path between
the client and server. NETCONF can be layered over any
transport protocol that provides a set of basic requirements.
Section 2 discusses these requirements.
(2) The Messages layer provides a simple, transport-independent
framing mechanism for encoding RPCs and notifications.
Section 4 documents the RPC messages, and [RFC5717] documents
notifications.
(3) The Operations layer defines a set of base protocol operations
invoked as RPC methods with XML-encoded parameters. Section 7
details the list of base protocol operations.
(4) The Content layer is outside the scope of this document. It is
expected that separate efforts to standardize NETCONF data
models will be undertaken.
The YANG data modeling language [RFC6020] has been developed for
specifying NETCONF data models and protocol operations, covering the
Operations and the Content layers of Figure 1.
Enns, et al. Standards Track [Page 9]
RFC 6241 NETCONF Protocol June 2011
1.3. Capabilities
A NETCONF capability is a set of functionality that supplements the
base NETCONF specification. The capability is identified by a
uniform resource identifier (URI) [RFC3986].
Capabilities augment the base operations of the device, describing
both additional operations and the content allowed inside operations.
The client can discover the server's capabilities and use any
additional operations, parameters, and content defined by those
capabilities.
The capability definition might name one or more dependent
capabilities. To support a capability, the server MUST support any
capabilities upon which it depends.
Section 8 defines the capabilities exchange that allows the client to
discover the server's capabilities. Section 8 also lists the set of
capabilities defined in this document.
Additional capabilities can be defined at any time in external
documents, allowing the set of capabilities to expand over time.
Standards bodies can define standardized capabilities, and
implementations can define proprietary ones. A capability URI MUST
sufficiently distinguish the naming authority to avoid naming
collisions.
1.4. Separation of Configuration and State Data
The information that can be retrieved from a running system is
separated into two classes, configuration data and state data.
Configuration data is the set of writable data that is required to
transform a system from its initial default state into its current
state. State data is the additional data on a system that is not
configuration data such as read-only status information and collected
statistics. When a device is performing configuration operations, a
number of problems would arise if state data were included:
o Comparisons of configuration data sets would be dominated by
irrelevant entries such as different statistics.
o Incoming data could contain nonsensical requests, such as attempts
to write read-only data.
o The data sets would be large.
o Archived data could contain values for read-only data items,
complicating the processing required to restore archived data.
Enns, et al. Standards Track [Page 10]
RFC 6241 NETCONF Protocol June 2011
To account for these issues, the NETCONF protocol recognizes the
difference between configuration data and state data and provides
operations for each. The 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.
For example, if a local database of user authentication data is
stored on the device, it is an implementation-dependent matter
whether it is included in configuration data.
2. Transport Protocol Requirements
NETCONF uses an RPC-based communication paradigm. A client sends a
series of one or more RPC request messages, which cause the server to
respond with a corresponding series of RPC reply messages.
The NETCONF protocol can be layered on any transport protocol that
provides the required set of functionality. It is not bound to any
particular transport protocol, but allows a mapping to define how it
can be implemented over any specific protocol.
The transport protocol MUST provide a mechanism to indicate the
session type (client or server) to the NETCONF protocol layer.
This section details the characteristics that NETCONF requires from
the underlying transport protocol.
2.1. Connection-Oriented Operation
NETCONF is connection-oriented, requiring a persistent connection
between peers. This connection MUST provide reliable, sequenced data
delivery. NETCONF connections are long-lived, persisting between
protocol operations.
In addition, resources requested from the server for a particular
connection MUST be automatically released when the connection closes,
making failure recovery simpler and more robust. For example, when a
lock is acquired by a client, the lock persists until either it is
explicitly released or the server determines that the connection has
been terminated. If a connection is terminated while the client
holds a lock, the server can perform any appropriate recovery. The
operation is further discussed in Section 7.5.
Enns, et al. Standards Track [Page 11]
RFC 6241 NETCONF Protocol June 2011
2.2. Authentication, Integrity, and Confidentiality
NETCONF connections MUST provide authentication, data integrity,
confidentiality, and replay protection. NETCONF depends on the
transport protocol for this capability. A NETCONF peer assumes that
appropriate levels of security and confidentiality are provided
independently of this document. For example, connections could be
encrypted using Transport Layer Security (TLS) [RFC5246] or Secure
Shell (SSH) [RFC4251], depending on the underlying protocol.
NETCONF connections MUST be authenticated. The transport protocol is
responsible for authentication of the server to the client and
authentication of the client to the server. A NETCONF peer assumes
that the connection's authentication information has been validated
by the underlying transport protocol using sufficiently trustworthy
mechanisms and that the peer's identity has been sufficiently proven.
One goal of NETCONF is to provide a programmatic interface to the
device that closely follows the functionality of the device's native
interface. Therefore, it is expected that the underlying protocol
uses existing authentication mechanisms available on the device. For
example, a NETCONF server on a device that supports RADIUS [RFC2865]
might allow the use of RADIUS to authenticate NETCONF sessions.
The authentication process MUST result in an authenticated client
identity whose permissions are known to the server. The
authenticated identity of a client is commonly referred to as the
NETCONF username. The username is a string of characters that match
the "Char" production from Section 2.2 of [W3C.REC-xml-20001006].
The algorithm used to derive the username is transport protocol
specific and in addition specific to the authentication mechanism
used by the transport protocol. The transport protocol MUST provide
a username to be used by the other NETCONF layers.
The access permissions of a given client, identified by its NETCONF
username, are part of the configuration of the NETCONF server. These
permissions MUST be enforced during the remainder of the NETCONF
session. The details of how access control is configured is outside
the scope of this document.
2.3. Mandatory Transport Protocol
A NETCONF implementation MUST support the SSH transport protocol
mapping [RFC6242].
Enns, et al. Standards Track [Page 12]
RFC 6241 NETCONF Protocol June 2011
3. XML Considerations
XML serves as the encoding format for NETCONF, allowing complex
hierarchical data to be expressed in a text format that can be read,
saved, and manipulated with both traditional text tools and tools
specific to XML.
All NETCONF messages MUST be well-formed XML, encoded in UTF-8
[RFC3629]. If a peer receives an message that is not well-
formed XML or not encoded in UTF-8, it SHOULD reply with a
"malformed-message" error. If a reply cannot be sent for any reason,
the server MUST terminate the session.
A NETCONF message MAY begin with an XML declaration (see Section 2.8
of [W3C.REC-xml-20001006]).
This section discusses a small number of XML-related considerations
pertaining to NETCONF.
3.1. Namespace
All NETCONF protocol elements are defined in the following namespace:
urn:ietf:params:xml:ns:netconf:base:1.0
NETCONF capability names MUST be URIs [RFC3986]. NETCONF
capabilities are discussed in Section 8.
3.2. Document Type Declarations
Document type declarations (see Section 2.8 of
[W3C.REC-xml-20001006]) MUST NOT appear in NETCONF content.
4. RPC Model
The NETCONF protocol uses an RPC-based communication model. NETCONF
peers use and elements to provide transport-
protocol-independent framing of NETCONF requests and responses.
The syntax and XML encoding of the Messages-layer RPCs are formally
defined in the XML schema in Appendix B.
4.1. Element
The element is used to enclose a NETCONF request sent from the
client to the server.
Enns, et al. Standards Track [Page 13]
RFC 6241 NETCONF Protocol June 2011
The element has a mandatory attribute "message-id", which is a
string chosen by the sender of the RPC that will commonly encode a
monotonically increasing integer. The receiver of the RPC does not
decode or interpret this string but simply saves it to be used as a
"message-id" attribute in any resulting message. The
sender MUST ensure that the "message-id" value is normalized
according to the XML attribute value normalization rules defined in
[W3C.REC-xml-20001006] if the sender wants the string to be returned
unmodified. For example:
If additional attributes are present in an element, a NETCONF
peer MUST return them unmodified in the element. This
includes any "xmlns" attributes.
The name and parameters of an RPC are encoded as the contents of the
element. The name of the RPC is an element directly inside the
element, and any parameters are encoded inside this element.
The following example invokes a method called , which
has two parameters, , with a value of "14", and
, with a value of "fred":
14fred
The following example invokes a method with a
parameter of "27606-0100":
27606-0100
Enns, et al. Standards Track [Page 14]
RFC 6241 NETCONF Protocol June 2011
The following example invokes the NETCONF method with no
parameters:
4.2. Element
The message is sent in response to an message.
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 server MUST also return any additional attributes included
in the element unmodified in the element.
The response data is encoded as one or more child elements to the
element.
For example:
The following element invokes the NETCONF method and
includes an additional attribute called "user-id". Note that the
"user-id" attribute is not in the NETCONF namespace. The returned
element returns the "user-id" attribute, as well as the
requested content.
Enns, et al. Standards Track [Page 15]
RFC 6241 NETCONF Protocol June 2011
4.3. Element
The element is sent in messages if an error
occurs during the processing of an request.
If a server encounters multiple errors during the processing of an
request, the MAY contain multiple
elements. However, a server is not required to detect or report more
than one element, if a request contains multiple errors.
A server is not required to check for particular error conditions in
a specific sequence. A server MUST return an element if
any error conditions occur during processing.
A server MUST NOT return application-level- or data-model-specific
error information in an element for which the client does
not have sufficient access rights.
The element includes the following information:
error-type: Defines the conceptual layer that the error occurred.
Enumeration. One of:
* transport (layer: Secure Transport)
* rpc (layer: Messages)
* protocol (layer: Operations)
* application (layer: Content)
error-tag: Contains a string identifying the error condition. See
Appendix A for allowed values.
error-severity: Contains a string identifying the error severity, as
determined by the device. One of:
* error
* warning
Note that there are no values defined in this document
that utilize the "warning" enumeration. This is reserved for
future use.
error-app-tag: Contains a string identifying the data-model-specific
or implementation-specific error condition, if one exists. This
element will not be present if no appropriate application error-
tag can be associated with a particular error condition. If a
Enns, et al. Standards Track [Page 16]
RFC 6241 NETCONF Protocol June 2011
data-model-specific and an implementation-specific error-app-tag
both exist, then the data-model-specific value MUST be used by the
server.
error-path: Contains the absolute XPath [W3C.REC-xpath-19991116]
expression identifying the element path to the node that is
associated with the error being reported in a particular
element. This element will not be present if no
appropriate payload element or datastore node can be associated
with a particular error condition.
The XPath expression is interpreted in the following context:
* The set of namespace declarations are those in scope on the
element.
* The set of variable bindings is empty.
* The function library is the core function library.
The context node depends on the node associated with the error
being reported:
* If a payload element can be associated with the error, the
context node is the rpc request's document node (i.e., the
element).
* Otherwise, the context node is the root of all data models,
i.e., the node that has the top-level nodes from all data
models as children.
error-message: Contains a string suitable for human display that
describes the error condition. This element will not be present
if no appropriate message is provided for a particular error
condition. This element SHOULD include an "xml:lang" attribute as
defined in [W3C.REC-xml-20001006] and discussed in [RFC3470].
error-info: Contains protocol- or data-model-specific error content.
This element will not be present if no such error content is
provided for a particular error condition. The list in Appendix A
defines any mandatory error-info content for each error. After
any protocol-mandated content, a data model definition MAY mandate
that certain application-layer error information be included in
the error-info container. An implementation MAY include
additional elements to provide extended and/or implementation-
specific debugging information.
Appendix A enumerates the standard NETCONF errors.
Enns, et al. Standards Track [Page 17]
RFC 6241 NETCONF Protocol June 2011
Example: An error is returned if an 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.
rpcmissing-attributeerrormessage-idrpc
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.
applicationinvalid-valueerror
/t:top/t:interface[t:name="Ethernet0/0"]/t:mtu
MTU value 25000 is not within range 256..9192
application
Enns, et al. Standards Track [Page 18]
RFC 6241 NETCONF Protocol June 2011
invalid-valueerror
/t:top/t:interface[t:name="Ethernet1/0"]/t:address/t:name
Invalid IP address for interface Ethernet1/0
4.4. Element
The element is sent in messages if no errors or
warnings occurred during the processing of an request, and no
data was returned from the operation. For example:
4.5. Pipelining
NETCONF requests MUST be processed serially by the managed
device. Additional requests MAY be sent before previous ones
have been completed. The managed device MUST send responses only in
the order the requests were received.
5. Configuration Model
NETCONF provides an initial set of operations and a number of
capabilities that can be used to extend the base. NETCONF peers
exchange device capabilities when the session is initiated as
described in Section 8.1.
5.1. Configuration Datastores
NETCONF defines the existence of one or more configuration datastores
and allows configuration operations on them. A configuration
datastore is defined as the complete set of configuration data that
is required to get a device from its initial default state into a
desired operational state. The configuration datastore does not
include state data or executive commands.
Enns, et al. Standards Track [Page 19]
RFC 6241 NETCONF Protocol June 2011
The running configuration datastore holds the complete configuration
currently active on the network device. Only one configuration
datastore of this type exists on the device, and it is always
present. NETCONF protocol operations refer to this datastore using
the element.
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.
The capabilities in Sections 8.3 and 8.7 define the and
configuration datastores, respectively.
5.2. Data Modeling
Data modeling and content issues are outside the scope of the NETCONF
protocol. An assumption is made that the device's data model is
well-known to the application and that both parties are aware of
issues such as the layout, containment, keying, lookup, replacement,
and management of the data, as well as any other constraints imposed
by the data model.
NETCONF carries configuration data inside the element that
is specific to the device's data model. The protocol treats the
contents of that element as opaque data. The device uses
capabilities to announce the set of data models that the device
implements. The capability definition details the operation and
constraints imposed by data model.
Devices and managers can support multiple data models, including both
standard and proprietary data models.
6. Subtree Filtering
6.1. Overview
XML subtree filtering is a mechanism that allows an application to
select particular XML subtrees to include in the for a
or operation. A small set of filters for
inclusion, simple content exact-match, and selection is provided,
which allows some useful, but also very limited, selection
mechanisms. The server does not need to utilize any data-model-
specific semantics during processing, allowing for simple and
centralized implementation strategies.
Enns, et al. Standards Track [Page 20]
RFC 6241 NETCONF Protocol June 2011
Conceptually, a subtree filter is comprised of zero or more element
subtrees, which represent the filter selection criteria. At each
containment level within a subtree, the set of sibling nodes is
logically processed by the server to determine if its subtree and
path of elements to the root are included in the filter output.
Each node specified in a subtree filter represents an inclusive
filter. Only associated nodes in underlying data model(s) within the
specified datastore on the server are selected by the filter. A node
is selected if it matches the selection criteria and hierarchy of
elements given in the filter data, except that the filter absolute
path name is adjusted to start from the layer below .
Response messages contain only the subtrees selected by the filter.
Any selection criteria that were present in the request, within a
particular selected subtree, are also included in the response. Note
that some elements expressed in the filter as leaf nodes will be
expanded (i.e., subtrees included) in the filter output. Specific
data instances are not duplicated in the response in the event that
the request contains multiple filter subtree expressions that select
the same data.
6.2. Subtree Filter Components
A subtree filter is comprised of XML elements and their XML
attributes. There are five types of components that can be present
in a subtree filter:
o Namespace Selection
o Attribute Match Expressions
o Containment Nodes
o Selection Nodes
o Content Match Nodes
6.2.1. Namespace Selection
A namespace is considered to match (for filter purposes) if the XML
namespace associated with a particular node within the
element is the same as in the underlying data model. Note that
namespace selection cannot be used by itself. At least one element
MUST be specified in the filter if any elements are to be included in
the filter output.
Enns, et al. Standards Track [Page 21]
RFC 6241 NETCONF Protocol June 2011
An XML namespace wildcard mechanism is defined for subtree filtering.
If an element within the element is not qualified by a
namespace (e.g., xmlns=""), then the server MUST evaluate all the XML
namespaces it supports, when processing that subtree filter node.
This wildcard mechanism is not applicable to XML attributes.
Note that prefix values for qualified namespaces are not relevant
when comparing filter elements to elements in the underlying data
model.
Example:
In this example, the element is a selection node, and only this
node in the "http://example.com/schema/1.2/config" namespace and any
child nodes (from the underlying data model) will be included in the
filter output.
6.2.2. Attribute Match Expressions
An attribute that appears in a subtree filter is part of an
"attribute match expression". Any number of (unqualified or
qualified) XML attributes MAY be present in any type of filter node.
In addition to the selection criteria normally applicable to that
node, the selected data MUST have matching values for every attribute
specified in the node. If an element is not defined to include a
specified attribute, then it is not selected in the filter output.
Example:
In this example, the and elements are containment
nodes, the element is a selection node, and "ifName" is
an attribute match expression. Only "interface" nodes in the
"http://example.com/schema/1.2/config" namespace that have an
"ifName" attribute with the value "eth0" and occur within
"interfaces" nodes within "top" nodes will be included in the filter
output.
Enns, et al. Standards Track [Page 22]
RFC 6241 NETCONF Protocol June 2011
6.2.3. Containment Nodes
Nodes that contain child elements within a subtree filter are called
"containment nodes". Each child element can be any type of node,
including another containment node. For each containment node
specified in a subtree filter, all data model instances that exactly
match the specified namespaces, element hierarchy, and any attribute
match expressions are included in the filter output.
Example:
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
element that is the root of the configuration datastore will be
included in the filter output.
Enns, et al. Standards Track [Page 23]
RFC 6241 NETCONF Protocol June 2011
6.2.5. Content Match Nodes
A leaf node that contains simple content is called a "content match
node". It is used to select some or all of its sibling nodes for
filter output, and it represents an exact-match filter on the leaf
node element content. The following constraints apply to content
match nodes:
o A content match node MUST NOT contain nested elements.
o Multiple content match nodes (i.e., sibling nodes) are logically
combined in an "AND" expression.
o Filtering of mixed content is not supported.
o Filtering of list content is not supported.
o Filtering of whitespace-only content is not supported.
o A content match node MUST contain non-whitespace characters. An
empty element (e.g., ) 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 If any sibling nodes of the selection node are instance identifier
components for a conceptual data structure (e.g., list key leaf),
then they MAY also be included in the filter output.
Enns, et al. Standards Track [Page 24]
RFC 6241 NETCONF Protocol June 2011
o Otherwise (i.e., there are no selection or containment nodes in
the filter sibling set), all the nodes defined at this level in
the underlying data model (and their subtrees, if any) are
returned in the filter output.
If any of the sibling content match node tests are "false", then no
further filter processing is performed on that sibling set, and none
of the sibling subtrees are selected by the filter, including the
content match node(s).
Example:
fred
In this example, the and nodes are both containment
nodes, and is a content match node. Since no sibling nodes of
are specified (and therefore no containment or selection
nodes), all of the sibling nodes of are returned in the filter
output. Only "user" nodes in the
"http://example.com/schema/1.2/config" namespace that match the
element hierarchy and for which the element is equal to "fred"
will be included in the filter output.
6.3. Subtree Filter Processing
The filter output (the set of selected nodes) is initially empty.
Each subtree filter can contain one or more data model fragments,
which represent portions of the data model that will be selected
(with all child nodes) in the filter output.
Each subtree data fragment is compared by the server to the internal
data models supported by the server. If the entire subtree data-
fragment filter (starting from the root to the innermost element
specified in the filter) exactly matches a corresponding portion of
the supported data model, then that node and all its children are
included in the result data.
The server processes all nodes with the same parent node (sibling
set) together, starting from the root to the leaf nodes. The root
Enns, et al. Standards Track [Page 25]
RFC 6241 NETCONF Protocol June 2011
elements in the filter are considered in the same sibling set
(assuming they are in the same namespace), even though they do not
have a common parent.
For each sibling set, the server determines which nodes are included
(or potentially included) in the filter output, and which sibling
subtrees are excluded (pruned) from the filter output. The server
first determines which types of nodes are present in the sibling set
and processes the nodes according to the rules for their type. If
any nodes in the sibling set are selected, then the process is
recursively applied to the sibling sets of each selected node. The
algorithm continues until all sibling sets in all subtrees specified
in the filter have been processed.
6.4. Subtree Filtering Examples
6.4.1. No Filter
Leaving out the filter on the operation returns the entire data
model.
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
element's "type" attribute used in these examples is discussed
further in Section 7.1.
Enns, et al. Standards Track [Page 26]
RFC 6241 NETCONF Protocol June 2011
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.
rootsuperuserCharlie Root11
Enns, et al. Standards Track [Page 27]
RFC 6241 NETCONF Protocol June 2011
fredadminFred Flintstone22barneyadminBarney Rubble23
The following filter request would have produced the same result, but
only because the container defines one child element
().
Enns, et al. Standards Track [Page 28]
RFC 6241 NETCONF Protocol June 2011
6.4.4. Select All Elements within the Subtree
This filter contains two containment nodes (, ) and one
selection node (). All instances of the element in the
same sibling set are selected in the filter output. The client might
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.
rootfredbarney
Enns, et al. Standards Track [Page 29]
RFC 6241 NETCONF Protocol June 2011
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.
fredfredadminFred Flintstone22
Enns, et al. Standards Track [Page 30]
RFC 6241 NETCONF Protocol June 2011
6.4.6. Specific Elements from a Specific Entry
This filter contains two containment nodes (, ), one
content match node (), and two selection nodes (,
). All instances of the and elements
in the same sibling set containing for which the value of
equals "fred" are selected in the filter output. The
element is not included because the sibling set
contains selection nodes.
fredfredadminFred Flintstone
Enns, et al. Standards Track [Page 31]
RFC 6241 NETCONF Protocol June 2011
6.4.7. Multiple Subtrees
This filter contains three subtrees (name=root, fred, barney).
The "root" subtree filter contains two containment nodes (,
), one content match node (), and one selection node
(). The subtree selection criteria are met, and just
the company-info subtree for "root" is selected in the filter output.
The "fred" subtree filter contains three containment nodes (,
, ), one content match node (), and one
selection node (). The subtree selection criteria are 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 selection node (). The subtree selection
criteria are 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.
rootfredbarneysuperuser
Enns, et al. Standards Track [Page 32]
RFC 6241 NETCONF Protocol June 2011
root11fred2
6.4.8. Elements with Attribute Naming
In this example, the filter contains one containment node
(), one attribute match expression ("ifName"), and one
selection node (). All instances of the
subtree that have an "ifName" attribute equal to "eth0" are selected
in the filter output. The filter data elements and attributes are
qualified because the "ifName" attribute will not be considered part
of the "schema/1.2" namespace if it is unqualified.
Enns, et al. Standards Track [Page 33]
RFC 6241 NETCONF Protocol June 2011
45621774344
If "ifName" were a child node instead of an attribute, then the
following request would produce similar results.
eth0
Enns, et al. Standards Track [Page 34]
RFC 6241 NETCONF Protocol June 2011
7. Protocol Operations
The NETCONF protocol provides a small set of low-level operations to
manage device configurations and retrieve device state information.
The base protocol provides operations to retrieve, configure, copy,
and delete configuration datastores. Additional operations are
provided, based on the capabilities advertised by the device.
The base protocol includes the following protocol operations:
o get
o get-config
o edit-config
o copy-config
o delete-config
o lock
o unlock
o close-session
o kill-session
A protocol operation can fail for various reasons, including
"operation not supported". An initiator SHOULD NOT assume that any
operation will always succeed. The return values in any RPC reply
SHOULD be checked for error responses.
The syntax and XML encoding of the protocol operations are formally
defined in the YANG module in Appendix C. The following sections
describe the semantics of each protocol operation.
7.1.
Description: Retrieve all or part of a specified configuration
datastore.
Parameters:
source: Name of the configuration datastore being queried, such
as .
Enns, et al. Standards Track [Page 35]
RFC 6241 NETCONF Protocol June 2011
filter: This parameter identifies the portions of the device
configuration datastore to retrieve. If this parameter is not
present, the entire configuration is returned.
The element MAY optionally contain a "type" attribute.
This attribute indicates the type of filtering syntax used
within the 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 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:
rootsuperuserCharlie Root
Enns, et al. Standards Track [Page 36]
RFC 6241 NETCONF Protocol June 2011
11
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 datastore.
This operation allows the new configuration to be expressed in
several ways, such as using a local file, a remote file, or
inline. If the target configuration datastore does not exist, it
will be created.
If a NETCONF peer supports the :url capability (Section 8.8), the
element can appear instead of the parameter.
The device analyzes the source and target configurations and
performs the requested changes. The target configuration is not
necessarily replaced, as with the message. Instead,
the target configuration is changed in accordance with the
source's data and requested operations.
If the operation contains multiple sub-operations
that apply to the same conceptual node in the underlying data
model, then the result of the operation is undefined (i.e.,
outside the scope of the NETCONF protocol).
Attributes:
operation: Elements in the subtree MAY contain an
"operation" attribute, which belongs to the NETCONF namespace
defined in Section 3.1. The attribute identifies the point in
the configuration to perform the operation and MAY appear on
multiple elements throughout the subtree.
If the "operation" attribute is not specified, the
configuration is merged into the configuration datastore.
Enns, et al. Standards Track [Page 37]
RFC 6241 NETCONF Protocol June 2011
The "operation" attribute has one of the following values:
merge: The configuration data identified by the element
containing this attribute is merged with the configuration
at the corresponding level in the configuration datastore
identified by the parameter. This is the default
behavior.
replace: The configuration data identified by the element
containing this attribute replaces any related configuration
in the configuration datastore identified by the
parameter. If no such configuration data exists in the
configuration datastore, it is created. Unlike a
operation, which replaces the entire target
configuration, only the configuration actually present in
the parameter is affected.
create: The configuration data identified by the element
containing this attribute is added to the configuration if
and only if the configuration data does not already exist in
the configuration datastore. If the configuration data
exists, an element is returned with an
value of "data-exists".
delete: The configuration data identified by the element
containing this attribute is deleted from the configuration
if and only if the configuration data currently exists in
the configuration datastore. If the configuration data does
not exist, an element is returned with an
value of "data-missing".
remove: The configuration data identified by the element
containing this attribute is deleted from the configuration
if the configuration data currently exists in the
configuration datastore. If the configuration data does not
exist, the "remove" operation is silently ignored by the
server.
Parameters:
target: Name of the configuration datastore being edited, such as
or .
default-operation: Selects the default operation (as described in
the "operation" attribute) for this request. The
default value for the parameter is "merge".
Enns, et al. Standards Track [Page 38]
RFC 6241 NETCONF Protocol June 2011
The parameter is optional, but if provided,
it has one of the following values:
merge: The configuration data in the parameter is
merged with the configuration at the corresponding level in
the target datastore. This is the default behavior.
replace: The configuration data in the parameter
completely replaces the configuration in the target
datastore. This is useful for loading previously saved
configuration data.
none: The target datastore is unaffected by the configuration
in the parameter, unless and until the incoming
configuration data uses the "operation" attribute to request
a different operation. If the configuration in the
parameter contains data for which there is not a
corresponding level in the target datastore, an
is returned with an value of data-missing.
Using "none" allows operations like "delete" to avoid
unintentionally creating the parent hierarchy of the element
to be deleted.
test-option: The element MAY be specified only if
the device advertises the :validate:1.1 capability
(Section 8.6).
The element has one of the following values:
test-then-set: Perform a validation test before attempting to
set. If validation errors occur, do not perform the
operation. This is the default test-option.
set: Perform a set without a validation test first.
test-only: Perform only the validation test, without
attempting to set.
error-option: The element has one of the following
values:
stop-on-error: Abort the operation on first
error. This is the default error-option.
continue-on-error: Continue to process configuration data on
error; error is recorded, and negative response is generated
if any errors occur.
Enns, et al. Standards Track [Page 39]
RFC 6241 NETCONF Protocol June 2011
rollback-on-error: If an error condition occurs such that an
error severity element is generated, the server
will stop processing the operation and restore
the specified configuration to its complete state at the
start of this operation. This option requires
the server to support the :rollback-on-error capability
described in Section 8.5.
config: A hierarchy of configuration data as defined by one of
the device's data models. The contents MUST be placed in an
appropriate namespace, to allow the device to detect the
appropriate data model, and the contents MUST follow the
constraints of that data model, as defined by its capability
definition. Capabilities are discussed in Section 8.
Positive Response: If the device was able to satisfy the request, an
is sent containing an element.
Negative Response: An response is sent if the request
cannot be completed for any reason.
Example: The examples in this section utilize a simple
data model, in which multiple instances of the element
can be present, and an instance is distinguished by the
element within each element.
Set the MTU to 1500 on an interface named "Ethernet0/0" in the
running configuration:
Ethernet0/01500
Enns, et al. Standards Track [Page 40]
RFC 6241 NETCONF Protocol June 2011
Add an interface named "Ethernet0/0" to the running configuration,
replacing any previous interface with that name:
Ethernet0/01500192.0.2.424
Delete the configuration for an interface named "Ethernet0/0" from
the running configuration:
noneEthernet0/0
Enns, et al. Standards Track [Page 41]
RFC 6241 NETCONF Protocol June 2011
Delete interface 192.0.2.4 from an OSPF area (other interfaces
configured in the same area are unaffected):
none0.0.0.0192.0.2.4
Enns, et al. Standards Track [Page 42]
RFC 6241 NETCONF Protocol June 2011
7.3.
Description: Create or replace an entire configuration datastore
with the contents of another complete configuration datastore. If
the target datastore exists, it is overwritten. Otherwise, a new
one is created, if allowed.
If a NETCONF peer supports the :url capability (Section 8.8), the
element can appear as the or parameter.
Even if it advertises the :writable-running capability, a device
MAY choose not to support the configuration datastore
as the parameter of a operation. A device
MAY choose not to support remote-to-remote copy operations, where
both the and parameters use the element.
If the and 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 operation.
source: Name of the configuration datastore to use as the source
of the operation, or the element
containing the complete configuration to copy.
Positive Response: If the device was able to satisfy the request, an
is sent that includes an element.
Negative Response: An element is included within the
if the request cannot be completed for any reason.
Example:
https://user:password@example.com/cfg/new.txt
Enns, et al. Standards Track [Page 43]
RFC 6241 NETCONF Protocol June 2011
7.4.
Description: Delete a configuration datastore. The
configuration datastore cannot be deleted.
If a NETCONF peer supports the :url capability (Section 8.8), the
element can appear as the parameter.
Parameters:
target: Name of the configuration datastore to delete.
Positive Response: If the device was able to satisfy the request, an
is sent that includes an element.
Negative Response: An element is included within the
if the request cannot be completed for any reason.
Example:
7.5.
Description: The operation allows the client to lock the
entire configuration datastore system of a device. Such locks are
intended to be short-lived and allow a client to make a change
without fear of interaction with other NETCONF clients, non-
NETCONF clients (e.g., SNMP and command line interface (CLI)
scripts), and human users.
Enns, et al. Standards Track [Page 44]
RFC 6241 NETCONF Protocol June 2011
An attempt to lock the configuration datastore MUST fail if an
existing session or other entity holds a lock on any portion of
the lock target.
When the lock is acquired, the server MUST prevent any changes to
the locked resource other than those requested by this session.
SNMP and CLI requests to modify the resource MUST fail with an
appropriate error.
The duration of the lock is defined as beginning when the lock is
acquired and lasting until either the lock is released or the
NETCONF session closes. The session closure can be explicitly
performed by the client, or implicitly performed by the server
based on criteria such as failure of the underlying transport,
simple inactivity timeout, or detection of abusive behavior on the
part of the client. These criteria are dependent on the
implementation and the underlying transport.
The operation takes a mandatory parameter, . The
parameter names the configuration datastore that will be
locked. When a lock is active, using the operation
on the locked configuration datastore and using the locked
configuration as a target of the operation will be
disallowed by any other NETCONF session. Additionally, the system
will ensure that these locked configuration resources will not be
modified by other non-NETCONF management operations such as SNMP
and CLI. The operation can be used to force the
release of a lock owned by another NETCONF session. It is beyond
the scope of this document to define how to break locks held by
other entities.
A lock MUST NOT be granted if any of the following conditions is
true:
* A lock is already held by any NETCONF session or another
entity.
* The target configuration is , it has already been
modified, and these changes have not been committed or rolled
back.
* The target configuration is , and another NETCONF
session has an ongoing confirmed commit (Section 8.4).
The server MUST respond with either an element or an
.
Enns, et al. Standards Track [Page 45]
RFC 6241 NETCONF Protocol June 2011
A lock will be released by the system if the session holding the
lock is terminated for any reason.
Parameters:
target: Name of the configuration datastore to lock.
Positive Response: If the device was able to satisfy the request, an
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
